clipp.h

Go to the documentation of this file.

/*****************************************************************************
 *
 * CLIPP - command line interfaces for modern C++
 *
 * released under MIT license
 *
 * (c) 2017 André Müller; [email protected]
 *
 *****************************************************************************/
 
#ifndef AM_CLIPP_H__
#define AM_CLIPP_H__
 
#include <cstring>
#include <string>
#include <cstdlib>
#include <cstring>
#include <cctype>
#include <cmath>
#include <memory>
#include <vector>
#include <limits>
#include <stack>
#include <algorithm>
#include <sstream>
#include <utility>
#include <iterator>
#include <functional>
 
 
/*************************************************************************/
namespace clipp {
 
 
 
/*****************************************************************************
 *
 * basic constants and datatype definitions
 *
 *****************************************************************************/
using arg_index = int;
 
using arg_string = std::string;
using doc_string = std::string;
 
using arg_list = std::vector<arg_string>;
 
 
 
/*************************************************************************/
enum class tri : char { no, yes, either };
 
inline constexpr bool operator == (tri t, bool b) noexcept {
 return b ? t != tri::no : t != tri::yes;
}
inline constexpr bool operator == (bool b, tri t) noexcept { return (t == b); }
inline constexpr bool operator != (tri t, bool b) noexcept { return !(t == b); }
inline constexpr bool operator != (bool b, tri t) noexcept { return !(t == b); }
 
 
 
/*************************************************************************/
class subrange {
public:
 using size_type = arg_string::size_type;
 
 explicit constexpr
 subrange() noexcept :
 at_{arg_string::npos}, length_{0}
 {}
 
 explicit constexpr
 subrange(size_type pos, size_type len) noexcept :
 at_{pos}, length_{len}
 {}
 
 constexpr size_type at() const noexcept { return at_; }
 constexpr size_type length() const noexcept { return length_; }
 
 constexpr bool prefix() const noexcept {
 return at_ == 0 && length_ > 0;
 }
 
 constexpr explicit operator bool () const noexcept {
 return at_ != arg_string::npos && length_ > 0;
 }
 
private:
 size_type at_;
 size_type length_;
};
 
 
 
/*************************************************************************/
using match_predicate = std::function<bool(const arg_string&)>;
using match_function = std::function<subrange(const arg_string&)>;
 
 
 
 
 
 
/*************************************************************************/
namespace traits {
 
/*************************************************************************/
template<class Fn, class Ret, class... Args>
constexpr auto
check_is_callable(int) -> decltype(
 std::declval<Fn>()(std::declval<Args>()...),
 std::integral_constant<bool,
 std::is_same<Ret,typename std::result_of<Fn(Args...)>::type>::value>{} );
 
template<class,class,class...>
constexpr auto
check_is_callable(long) -> std::false_type;
 
template<class Fn, class Ret>
constexpr auto
check_is_callable_without_arg(int) -> decltype(
 std::declval<Fn>()(),
 std::integral_constant<bool,
 std::is_same<Ret,typename std::result_of<Fn()>::type>::value>{} );
 
template<class,class>
constexpr auto
check_is_callable_without_arg(long) -> std::false_type;
 
 
 
template<class Fn, class... Args>
constexpr auto
check_is_void_callable(int) -> decltype(
 std::declval<Fn>()(std::declval<Args>()...), std::true_type{});
 
template<class,class,class...>
constexpr auto
check_is_void_callable(long) -> std::false_type;
 
template<class Fn>
constexpr auto
check_is_void_callable_without_arg(int) -> decltype(
 std::declval<Fn>()(), std::true_type{});
 
template<class>
constexpr auto
check_is_void_callable_without_arg(long) -> std::false_type;
 
 
 
template<class Fn, class Ret>
struct is_callable;
 
 
template<class Fn, class Ret, class... Args>
struct is_callable<Fn, Ret(Args...)> :
 decltype(check_is_callable<Fn,Ret,Args...>(0))
{};
 
template<class Fn, class Ret>
struct is_callable<Fn,Ret()> :
 decltype(check_is_callable_without_arg<Fn,Ret>(0))
{};
 
 
template<class Fn, class... Args>
struct is_callable<Fn, void(Args...)> :
 decltype(check_is_void_callable<Fn,Args...>(0))
{};
 
template<class Fn>
struct is_callable<Fn,void()> :
 decltype(check_is_void_callable_without_arg<Fn>(0))
{};
 
 
 
/*************************************************************************/
template<class T>
constexpr auto
check_is_input_range(int) -> decltype(
 begin(std::declval<T>()), end(std::declval<T>()),
 std::true_type{});
 
template<class T>
constexpr auto
check_is_input_range(char) -> decltype(
 std::begin(std::declval<T>()), std::end(std::declval<T>()),
 std::true_type{});
 
template<class>
constexpr auto
check_is_input_range(long) -> std::false_type;
 
template<class T>
struct is_input_range :
 decltype(check_is_input_range<T>(0))
{};
 
 
 
/*************************************************************************/
template<class T>
constexpr auto
check_has_size_getter(int) ->
 decltype(std::declval<T>().size(), std::true_type{});
 
template<class>
constexpr auto
check_has_size_getter(long) -> std::false_type;
 
template<class T>
struct has_size_getter :
 decltype(check_has_size_getter<T>(0))
{};
 
} // namespace traits
 
 
 
 
 
 
/*************************************************************************/
namespace detail {
 
 
/*************************************************************************/
inline bool
fwd_to_unsigned_int(const char*& s)
{
 if(!s) return false;
 for(; std::isspace(*s); ++s);
 if(!s[0] || s[0] == '-') return false;
 if(s[0] == '-') return false;
 return true;
}
 
 
/*************************************************************************/
template<class T, class V, bool = (sizeof(V) > sizeof(T))>
struct limits_clamped {
 static T from(const V& v) {
 if(v > V(std::numeric_limits<T>::max())) {
 return std::numeric_limits<T>::max();
 }
 if(v < V(std::numeric_limits<T>::lowest())) {
 return std::numeric_limits<T>::lowest();
 }
 return T(v);
 }
};
 
template<class T, class V>
struct limits_clamped<T,V,false> {
 static T from(const V& v) { return T(v); }
};
 
 
/*************************************************************************/
template<class T, class V>
inline T clamped_on_limits(const V& v) {
 return limits_clamped<T,V>::from(v);
}
 
 
 
 
/*************************************************************************/
template<class T>
struct make;
 
template<>
struct make<bool> {
 static inline bool from(const char* s) {
 if(!s) return false;
 return static_cast<bool>(s);
 }
};
 
template<>
struct make<unsigned char> {
 static inline unsigned char from(const char* s) {
 if(!fwd_to_unsigned_int(s)) return (0);
 return clamped_on_limits<unsigned char>(std::strtoull(s,nullptr,10));
 }
};
 
template<>
struct make<unsigned short int> {
 static inline unsigned short int from(const char* s) {
 if(!fwd_to_unsigned_int(s)) return (0);
 return clamped_on_limits<unsigned short int>(std::strtoull(s,nullptr,10));
 }
};
 
template<>
struct make<unsigned int> {
 static inline unsigned int from(const char* s) {
 if(!fwd_to_unsigned_int(s)) return (0);
 return clamped_on_limits<unsigned int>(std::strtoull(s,nullptr,10));
 }
};
 
template<>
struct make<unsigned long int> {
 static inline unsigned long int from(const char* s) {
 if(!fwd_to_unsigned_int(s)) return (0);
 return clamped_on_limits<unsigned long int>(std::strtoull(s,nullptr,10));
 }
};
 
template<>
struct make<unsigned long long int> {
 static inline unsigned long long int from(const char* s) {
 if(!fwd_to_unsigned_int(s)) return (0);
 return clamped_on_limits<unsigned long long int>(std::strtoull(s,nullptr,10));
 }
};
 
template<>
struct make<char> {
 static inline char from(const char* s) {
 //parse as single character?
 const auto n = std::strlen(s);
 if(n == 1) return s[0];
 //parse as integer
 return clamped_on_limits<char>(std::strtoll(s,nullptr,10));
 }
};
 
template<>
struct make<short int> {
 static inline short int from(const char* s) {
 return clamped_on_limits<short int>(std::strtoll(s,nullptr,10));
 }
};
 
template<>
struct make<int> {
 static inline int from(const char* s) {
 return clamped_on_limits<int>(std::strtoll(s,nullptr,10));
 }
};
 
template<>
struct make<long int> {
 static inline long int from(const char* s) {
 return clamped_on_limits<long int>(std::strtoll(s,nullptr,10));
 }
};
 
template<>
struct make<long long int> {
 static inline long long int from(const char* s) {
 return (std::strtoll(s,nullptr,10));
 }
};
 
template<>
struct make<float> {
 static inline float from(const char* s) {
 return (std::strtof(s,nullptr));
 }
};
 
template<>
struct make<double> {
 static inline double from(const char* s) {
 return (std::strtod(s,nullptr));
 }
};
 
template<>
struct make<long double> {
 static inline long double from(const char* s) {
 return (std::strtold(s,nullptr));
 }
};
 
template<>
struct make<std::string> {
 static inline std::string from(const char* s) {
 return std::string(s);
 }
};
 
 
 
/*************************************************************************/
template<class T, class V = T>
class assign_value
{
public:
 template<class X>
 explicit constexpr
 assign_value(T& target, X&& value) noexcept :
 t_{std::addressof(target)}, v_{std::forward<X>(value)}
 {}
 
 void operator () () const {
 if(t_) *t_ = v_;
 }
 
private:
 T* t_;
 V v_;
};
 
 
 
/*************************************************************************/
class flip_bool
{
public:
 explicit constexpr
 flip_bool(bool& target) noexcept :
 b_{&target}
 {}
 
 void operator () () const {
 if(b_) *b_ = !*b_;
 }
 
private:
 bool* b_;
};
 
 
 
/*************************************************************************/
template<class T>
class increment
{
public:
 explicit constexpr
 increment(T& target) noexcept : t_{std::addressof(target)} {}
 
 void operator () () const {
 if(t_) ++(*t_);
 }
 
private:
 T* t_;
};
 
 
 
/*************************************************************************/
template<class T>
class decrement
{
public:
 explicit constexpr
 decrement(T& target) noexcept : t_{std::addressof(target)} {}
 
 void operator () () const {
 if(t_) --(*t_);
 }
 
private:
 T* t_;
};
 
 
 
/*************************************************************************/
template<class T>
class increment_by
{
public:
 explicit constexpr
 increment_by(T& target, T by) noexcept :
 t_{std::addressof(target)}, by_{std::move(by)}
 {}
 
 void operator () () const {
 if(t_) (*t_) += by_;
 }
 
private:
 T* t_;
 T by_;
};
 
 
 
 
/*************************************************************************/
template<class T>
class map_arg_to
{
public:
 explicit constexpr
 map_arg_to(T& target) noexcept : t_{std::addressof(target)} {}
 
 void operator () (const char* s) const {
 if(t_ && s && (std::strlen(s) > 0))
 *t_ = detail::make<T>::from(s);
 }
 
private:
 T* t_;
};
 
 
//-------------------------------------------------------------------
template<class T>
class map_arg_to<std::vector<T>>
{
public:
 map_arg_to(std::vector<T>& target): t_{std::addressof(target)} {}
 
 void operator () (const char* s) const {
 if(t_ && s) t_->push_back(detail::make<T>::from(s));
 }
 
private:
 std::vector<T>* t_;
};
 
 
//-------------------------------------------------------------------
template<>
class map_arg_to<bool>
{
public:
 map_arg_to(bool& target): t_{&target} {}
 
 void operator () (const char* s) const {
 if(t_ && s) *t_ = true;
 }
 
private:
 bool* t_;
};
 
 
} // namespace detail
 
 
 
 
 
 
/*************************************************************************/
namespace str {
 
 
/*************************************************************************/
template<class T>
T make(const arg_string& s)
{
 return detail::make<T>::from(s);
}
 
 
 
/*************************************************************************/
template<class C, class T, class A>
inline void
trimr(std::basic_string<C,T,A>& s)
{
 if(s.empty()) return;
 
 s.erase(
 std::find_if_not(s.rbegin(), s.rend(),
 [](char c) { return std::isspace(c);} ).base(),
 s.end() );
}
 
 
/*************************************************************************/
template<class C, class T, class A>
inline void
triml(std::basic_string<C,T,A>& s)
{
 if(s.empty()) return;
 
 s.erase(
 s.begin(),
 std::find_if_not(s.begin(), s.end(),
 [](char c) { return std::isspace(c);})
 );
}
 
 
/*************************************************************************/
template<class C, class T, class A>
inline void
trim(std::basic_string<C,T,A>& s)
{
 triml(s);
 trimr(s);
}
 
 
/*************************************************************************/
template<class C, class T, class A>
inline void
remove_ws(std::basic_string<C,T,A>& s)
{
 if(s.empty()) return;
 
 s.erase(std::remove_if(s.begin(), s.end(),
 [](char c) { return std::isspace(c); }),
 s.end() );
}
 
 
/*************************************************************************/
template<class C, class T, class A>
inline bool
has_prefix(const std::basic_string<C,T,A>& subject,
 const std::basic_string<C,T,A>& prefix)
{
 if(prefix.size() > subject.size()) return false;
 return subject.find(prefix) == 0;
}
 
 
/*************************************************************************/
template<class C, class T, class A>
inline bool
has_postfix(const std::basic_string<C,T,A>& subject,
 const std::basic_string<C,T,A>& postfix)
{
 if(postfix.size() > subject.size()) return false;
 return (subject.size() - postfix.size()) == subject.find(postfix);
}
 
 
 
/*************************************************************************/
template<class InputRange>
auto
longest_common_prefix(const InputRange& strs)
 -> typename std::decay<decltype(*begin(strs))>::type
{
 static_assert(traits::is_input_range<InputRange>(),
 "parameter must satisfy the InputRange concept");
 
 static_assert(traits::has_size_getter<
 typename std::decay<decltype(*begin(strs))>::type>(),
 "elements of input range must have a ::size() member function");
 
 using std::begin;
 using std::end;
 
 using item_t = typename std::decay<decltype(*begin(strs))>::type;
 using str_size_t = typename std::decay<decltype(begin(strs)->size())>::type;
 
 const auto n = size_t(distance(begin(strs), end(strs)));
 if(n < 1) return item_t("");
 if(n == 1) return *begin(strs);
 
 //length of shortest string
 auto m = std::min_element(begin(strs), end(strs),
 [](const item_t& a, const item_t& b) {
 return a.size() < b.size(); })->size();
 
 //check each character until we find a mismatch
 for(str_size_t i = 0; i < m; ++i) {
 for(str_size_t j = 1; j < n; ++j) {
 if(strs[j][i] != strs[j-1][i])
 return strs[0].substr(0, i);
 }
 }
 return strs[0].substr(0, m);
}
 
 
 
/*************************************************************************/
template<class C, class T, class A, class InputRange>
subrange
longest_substring_match(const std::basic_string<C,T,A>& arg,
 const InputRange& substrings)
{
 using string_t = std::basic_string<C,T,A>;
 
 static_assert(traits::is_input_range<InputRange>(),
 "parameter must satisfy the InputRange concept");
 
 static_assert(std::is_same<string_t,
 typename std::decay<decltype(*begin(substrings))>::type>(),
 "substrings must have same type as 'arg'");
 
 auto i = string_t::npos;
 auto n = string_t::size_type(0);
 for(const auto& s : substrings) {
 auto j = arg.find(s);
 if(j != string_t::npos && s.size() > n) {
 i = j;
 n = s.size();
 }
 }
 return subrange{i,n};
}
 
 
 
/*************************************************************************/
template<class C, class T, class A, class InputRange>
subrange
longest_prefix_match(const std::basic_string<C,T,A>& arg,
 const InputRange& prefixes)
{
 using string_t = std::basic_string<C,T,A>;
 using s_size_t = typename string_t::size_type;
 
 static_assert(traits::is_input_range<InputRange>(),
 "parameter must satisfy the InputRange concept");
 
 static_assert(std::is_same<string_t,
 typename std::decay<decltype(*begin(prefixes))>::type>(),
 "prefixes must have same type as 'arg'");
 
 auto i = string_t::npos;
 auto n = s_size_t(0);
 for(const auto& s : prefixes) {
 auto j = arg.find(s);
 if(j == 0 && s.size() > n) {
 i = 0;
 n = s.size();
 }
 }
 return subrange{i,n};
}
 
 
 
/*************************************************************************/
template<class C, class T, class A>
inline subrange
substring_match(const std::basic_string<C,T,A>& subject,
 const std::basic_string<C,T,A>& query)
{
 if(subject.empty() || query.empty()) return subrange{};
 auto i = subject.find(query);
 if(i == std::basic_string<C,T,A>::npos) return subrange{};
 return subrange{i,query.size()};
}
 
 
 
/*************************************************************************/
template<class C, class T, class A>
subrange
first_number_match(std::basic_string<C,T,A> s,
 C digitSeparator = C(','),
 C decimalPoint = C('.'),
 C exponential = C('e'))
{
 using string_t = std::basic_string<C,T,A>;
 
 str::trim(s);
 if(s.empty()) return subrange{};
 
 auto i = s.find_first_of("0123456789+-");
 if(i == string_t::npos) {
 i = s.find(decimalPoint);
 if(i == string_t::npos) return subrange{};
 }
 
 bool point = false;
 bool sep = false;
 auto exp = string_t::npos;
 auto j = i + 1;
 for(; j < s.size(); ++j) {
 if(s[j] == digitSeparator) {
 if(!sep) sep = true; else break;
 }
 else {
 sep = false;
 if(s[j] == decimalPoint) {
 //only one decimal point before exponent allowed
 if(!point && exp == string_t::npos) point = true; else break;
 }
 else if(std::tolower(s[j]) == std::tolower(exponential)) {
 //only one exponent separator allowed
 if(exp == string_t::npos) exp = j; else break;
 }
 else if(exp != string_t::npos && (exp+1) == j) {
 //only sign or digit after exponent separator
 if(s[j] != '+' && s[j] != '-' && !std::isdigit(s[j])) break;
 }
 else if(!std::isdigit(s[j])) {
 break;
 }
 }
 }
 
 //if length == 1 then must be a digit
 if(j-i == 1 && !std::isdigit(s[i])) return subrange{};
 
 return subrange{i,j-i};
}
 
 
 
/*************************************************************************/
template<class C, class T, class A>
subrange
first_integer_match(std::basic_string<C,T,A> s,
 C digitSeparator = C(','))
{
 using string_t = std::basic_string<C,T,A>;
 
 str::trim(s);
 if(s.empty()) return subrange{};
 
 auto i = s.find_first_of("0123456789+-");
 if(i == string_t::npos) return subrange{};
 
 bool sep = false;
 auto j = i + 1;
 for(; j < s.size(); ++j) {
 if(s[j] == digitSeparator) {
 if(!sep) sep = true; else break;
 }
 else {
 sep = false;
 if(!std::isdigit(s[j])) break;
 }
 }
 
 //if length == 1 then must be a digit
 if(j-i == 1 && !std::isdigit(s[i])) return subrange{};
 
 return subrange{i,j-i};
}
 
 
 
/*************************************************************************/
template<class C, class T, class A>
bool represents_number(const std::basic_string<C,T,A>& candidate,
 C digitSeparator = C(','),
 C decimalPoint = C('.'),
 C exponential = C('e'))
{
 const auto match = str::first_number_match(candidate, digitSeparator,
 decimalPoint, exponential);
 
 return (match && match.length() == candidate.size());
}
 
 
 
/*************************************************************************/
template<class C, class T, class A>
bool represents_integer(const std::basic_string<C,T,A>& candidate,
 C digitSeparator = C(','))
{
 const auto match = str::first_integer_match(candidate, digitSeparator);
 return (match && match.length() == candidate.size());
}
 
} // namespace str
 
 
 
 
 
 
/*************************************************************************/
template<class T, class V>
inline detail::assign_value<T,V>
set(T& target, V value) {
 return detail::assign_value<T>{target, std::move(value)};
}
 
 
 
/*************************************************************************/
template<class T>
inline detail::map_arg_to<T>
set(T& target) {
 return detail::map_arg_to<T>{target};
}
 
 
 
/*************************************************************************/
inline detail::assign_value<bool>
set(bool& target) {
 return detail::assign_value<bool>{target,true};
}
 
/*************************************************************************/
inline detail::assign_value<bool>
unset(bool& target) {
 return detail::assign_value<bool>{target,false};
}
 
/*************************************************************************/
inline detail::flip_bool
flip(bool& b) {
 return detail::flip_bool(b);
}
 
 
 
 
 
/*************************************************************************/
template<class T>
inline detail::increment<T>
increment(T& target) {
 return detail::increment<T>{target};
}
 
/*************************************************************************/
template<class T>
inline detail::increment_by<T>
increment(T& target, T by) {
 return detail::increment_by<T>{target, std::move(by)};
}
 
/*************************************************************************/
template<class T>
inline detail::decrement<T>
decrement(T& target) {
 return detail::decrement<T>{target};
}
 
 
 
 
 
 
/*************************************************************************/
namespace detail {
 
 
/*************************************************************************/
template<class Derived>
class action_provider
{
private:
 //---------------------------------------------------------------
 using simple_action = std::function<void()>;
 using arg_action = std::function<void(const char*)>;
 using index_action = std::function<void(int)>;
 
 //-----------------------------------------------------
 class simple_action_adapter {
 public:
 simple_action_adapter() = default;
 simple_action_adapter(const simple_action& a): action_(a) {}
 simple_action_adapter(simple_action&& a): action_(std::move(a)) {}
 void operator() (const char*) const { action_(); }
 void operator() (int) const { action_(); }
 private:
 simple_action action_;
 };
 
 
public:
 //---------------------------------------------------------------
 Derived&
 call(arg_action a) {
 argActions_.push_back(std::move(a));
 return *static_cast<Derived*>(this);
 }
 
 Derived&
 call(simple_action a) {
 argActions_.push_back(simple_action_adapter(std::move(a)));
 return *static_cast<Derived*>(this);
 }
 
 Derived& operator () (arg_action a) { return call(std::move(a)); }
 
 Derived& operator () (simple_action a) { return call(std::move(a)); }
 
 
 //---------------------------------------------------------------
 template<class Target>
 Derived&
 set(Target& t) {
 return call(clipp::set(t));
 }
 
 template<class Target, class Value>
 Derived&
 set(Target& t, Value&& v) {
 return call(clipp::set(t, std::forward<Value>(v)));
 }
 
 
 //---------------------------------------------------------------
 Derived&
 if_repeated(simple_action a) {
 repeatActions_.push_back(simple_action_adapter{std::move(a)});
 return *static_cast<Derived*>(this);
 }
 Derived&
 if_repeated(index_action a) {
 repeatActions_.push_back(std::move(a));
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 Derived&
 if_missing(simple_action a) {
 missingActions_.push_back(simple_action_adapter{std::move(a)});
 return *static_cast<Derived*>(this);
 }
 Derived&
 if_missing(index_action a) {
 missingActions_.push_back(std::move(a));
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 Derived&
 if_blocked(simple_action a) {
 blockedActions_.push_back(simple_action_adapter{std::move(a)});
 return *static_cast<Derived*>(this);
 }
 Derived&
 if_blocked(index_action a) {
 blockedActions_.push_back(std::move(a));
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 Derived&
 if_conflicted(simple_action a) {
 conflictActions_.push_back(simple_action_adapter{std::move(a)});
 return *static_cast<Derived*>(this);
 }
 Derived&
 if_conflicted(index_action a) {
 conflictActions_.push_back(std::move(a));
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 template<class T, class... Ts>
 Derived&
 target(T&& t, Ts&&... ts) {
 target(std::forward<T>(t));
 target(std::forward<Ts>(ts)...);
 return *static_cast<Derived*>(this);
 }
 
 template<class T, class = typename std::enable_if<
 !std::is_fundamental<typename std::decay<T>::type>() &&
 (traits::is_callable<T,void()>() ||
 traits::is_callable<T,void(const char*)>() )
 >::type>
 Derived&
 target(T&& t) {
 call(std::forward<T>(t));
 return *static_cast<Derived*>(this);
 }
 
 template<class T, class = typename std::enable_if<
 std::is_fundamental<typename std::decay<T>::type>() ||
 (!traits::is_callable<T,void()>() &&
 !traits::is_callable<T,void(const char*)>() )
 >::type>
 Derived&
 target(T& t) {
 set(t);
 return *static_cast<Derived*>(this);
 }
 
 //TODO remove ugly empty param list overload
 Derived&
 target() {
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 template<class Target>
 inline friend Derived&
 operator << (Target&& t, Derived& p) {
 p.target(std::forward<Target>(t));
 return p;
 }
 template<class Target>
 inline friend Derived&&
 operator << (Target&& t, Derived&& p) {
 p.target(std::forward<Target>(t));
 return std::move(p);
 }
 
 //-----------------------------------------------------
 template<class Target>
 inline friend Derived&
 operator >> (Derived& p, Target&& t) {
 p.target(std::forward<Target>(t));
 return p;
 }
 template<class Target>
 inline friend Derived&&
 operator >> (Derived&& p, Target&& t) {
 p.target(std::forward<Target>(t));
 return std::move(p);
 }
 
 
 //---------------------------------------------------------------
 void execute_actions(const arg_string& arg) const {
 int i = 0;
 for(const auto& a : argActions_) {
 ++i;
 a(arg.c_str());
 }
 }
 
 void notify_repeated(arg_index idx) const {
 for(const auto& a : repeatActions_) a(idx);
 }
 void notify_missing(arg_index idx) const {
 for(const auto& a : missingActions_) a(idx);
 }
 void notify_blocked(arg_index idx) const {
 for(const auto& a : blockedActions_) a(idx);
 }
 void notify_conflict(arg_index idx) const {
 for(const auto& a : conflictActions_) a(idx);
 }
 
private:
 //---------------------------------------------------------------
 std::vector<arg_action> argActions_;
 std::vector<index_action> repeatActions_;
 std::vector<index_action> missingActions_;
 std::vector<index_action> blockedActions_;
 std::vector<index_action> conflictActions_;
};
 
 
 
 
 
 
/*************************************************************************/
template<class Derived>
class token
{
public:
 //---------------------------------------------------------------
 using doc_string = clipp::doc_string;
 
 
 //---------------------------------------------------------------
 const doc_string& doc() const noexcept {
 return doc_;
 }
 
 Derived& doc(const doc_string& txt) {
 doc_ = txt;
 return *static_cast<Derived*>(this);
 }
 
 Derived& doc(doc_string&& txt) {
 doc_ = std::move(txt);
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 bool repeatable() const noexcept {
 return repeatable_;
 }
 
 Derived& repeatable(bool yes) noexcept {
 repeatable_ = yes;
 return *static_cast<Derived*>(this);
 }
 
 
 //---------------------------------------------------------------
 bool blocking() const noexcept {
 return blocking_;
 }
 
 Derived& blocking(bool yes) noexcept {
 blocking_ = yes;
 return *static_cast<Derived*>(this);
 }
 
 
private:
 //---------------------------------------------------------------
 doc_string doc_;
 bool repeatable_ = false;
 bool blocking_ = false;
};
 
 
 
 
/*************************************************************************/
template<class T>
inline T&
operator % (doc_string docstr, token<T>& p)
{
 return p.doc(std::move(docstr));
}
//---------------------------------------------------------
template<class T>
inline T&&
operator % (doc_string docstr, token<T>&& p)
{
 return std::move(p.doc(std::move(docstr)));
}
 
//---------------------------------------------------------
template<class T>
inline T&
operator % (token<T>& p, doc_string docstr)
{
 return p.doc(std::move(docstr));
}
//---------------------------------------------------------
template<class T>
inline T&&
operator % (token<T>&& p, doc_string docstr)
{
 return std::move(p.doc(std::move(docstr)));
}
 
 
 
 
/*************************************************************************/
template<class T>
inline T&
doc(doc_string docstr, token<T>& p)
{
 return p.doc(std::move(docstr));
}
//---------------------------------------------------------
template<class T>
inline T&&
doc(doc_string docstr, token<T>&& p)
{
 return std::move(p.doc(std::move(docstr)));
}
 
 
 
} // namespace detail
 
 
 
/*************************************************************************/
namespace match {
 
 
/*************************************************************************/
inline bool
any(const arg_string&) { return true; }
 
/*************************************************************************/
inline bool
none(const arg_string&) { return false; }
 
 
 
/*************************************************************************/
inline bool
nonempty(const arg_string& s) {
 return !s.empty();
}
 
 
 
/*************************************************************************/
inline bool
alphanumeric(const arg_string& s) {
 if(s.empty()) return false;
 return std::all_of(s.begin(), s.end(), [](char c) {return std::isalnum(c); });
}
 
 
 
/*************************************************************************/
inline bool
alphabetic(const arg_string& s) {
 return std::all_of(s.begin(), s.end(), [](char c) {return std::isalpha(c); });
}
 
 
 
/*************************************************************************/
class numbers
{
public:
 explicit
 numbers(char decimalPoint = '.',
 char digitSeparator = ' ',
 char exponentSeparator = 'e')
 :
 decpoint_{decimalPoint}, separator_{digitSeparator},
 exp_{exponentSeparator}
 {}
 
 subrange operator () (const arg_string& s) const {
 return str::first_number_match(s, separator_, decpoint_, exp_);
 }
 
private:
 char decpoint_;
 char separator_;
 char exp_;
};
 
 
 
/*************************************************************************/
class integers {
public:
 explicit
 integers(char digitSeparator = ' '): separator_{digitSeparator} {}
 
 subrange operator () (const arg_string& s) const {
 return str::first_integer_match(s, separator_);
 }
 
private:
 char separator_;
};
 
 
 
/*************************************************************************/
class positive_integers {
public:
 explicit
 positive_integers(char digitSeparator = ' '): separator_{digitSeparator} {}
 
 subrange operator () (const arg_string& s) const {
 auto match = str::first_integer_match(s, separator_);
 if(!match) return subrange{};
 if(s[match.at()] == '-') return subrange{};
 return match;
 }
 
private:
 char separator_;
};
 
 
 
/*************************************************************************/
class substring
{
public:
 explicit
 substring(arg_string str): str_{std::move(str)} {}
 
 subrange operator () (const arg_string& s) const {
 return str::substring_match(s, str_);
 }
 
private:
 arg_string str_;
};
 
 
 
/*************************************************************************/
class prefix {
public:
 explicit
 prefix(arg_string p): prefix_{std::move(p)} {}
 
 bool operator () (const arg_string& s) const {
 return s.find(prefix_) == 0;
 }
 
private:
 arg_string prefix_;
};
 
 
 
/*************************************************************************/
class prefix_not {
public:
 explicit
 prefix_not(arg_string p): prefix_{std::move(p)} {}
 
 bool operator () (const arg_string& s) const {
 return s.find(prefix_) != 0;
 }
 
private:
 arg_string prefix_;
};
 
 
using noprefix = prefix_not;
 
 
 
/*************************************************************************/
class length {
public:
 explicit
 length(std::size_t exact):
 min_{exact}, max_{exact}
 {}
 
 explicit
 length(std::size_t min, std::size_t max):
 min_{min}, max_{max}
 {}
 
 bool operator () (const arg_string& s) const {
 return s.size() >= min_ && s.size() <= max_;
 }
 
private:
 std::size_t min_;
 std::size_t max_;
};
 
 
/*************************************************************************/
inline length min_length(std::size_t min)
{
 return length{min, arg_string::npos-1};
}
 
/*************************************************************************/
inline length max_length(std::size_t max)
{
 return length{0, max};
}
 
 
} // namespace match
 
 
 
 
 
/*************************************************************************/
class parameter :
 public detail::token<parameter>,
 public detail::action_provider<parameter>
{
 class predicate_adapter {
 public:
 explicit
 predicate_adapter(match_predicate pred): match_{std::move(pred)} {}
 
 subrange operator () (const arg_string& arg) const {
 return match_(arg) ? subrange{0,arg.size()} : subrange{};
 }
 
 private:
 match_predicate match_;
 };
 
public:
 //---------------------------------------------------------------
 parameter():
 flags_{},
 matcher_{predicate_adapter{match::none}},
 label_{}, required_{false}
 {}
 
 template<class... Strings>
 explicit
 parameter(arg_string str, Strings&&... strs):
 flags_{},
 matcher_{predicate_adapter{match::none}},
 label_{}, required_{false}
 {
 add_flags(std::move(str), std::forward<Strings>(strs)...);
 }
 
 explicit
 parameter(const arg_list& flaglist):
 flags_{},
 matcher_{predicate_adapter{match::none}},
 label_{}, required_{false}
 {
 add_flags(flaglist);
 }
 
 //-----------------------------------------------------
 explicit
 parameter(match_predicate filter):
 flags_{},
 matcher_{predicate_adapter{std::move(filter)}},
 label_{}, required_{false}
 {}
 
 explicit
 parameter(match_function filter):
 flags_{},
 matcher_{std::move(filter)},
 label_{}, required_{false}
 {}
 
 
 //---------------------------------------------------------------
 bool
 required() const noexcept {
 return required_;
 }
 
 parameter&
 required(bool yes) noexcept {
 required_ = yes;
 return *this;
 }
 
 
 //---------------------------------------------------------------
 const doc_string&
 label() const {
 return label_;
 }
 
 parameter&
 label(const doc_string& lbl) {
 label_ = lbl;
 return *this;
 }
 
 parameter&
 label(doc_string&& lbl) {
 label_ = lbl;
 return *this;
 }
 
 
 //---------------------------------------------------------------
 subrange
 match(const arg_string& arg) const
 {
 if(arg.empty()) return subrange{};
 
 if(flags_.empty()) {
 return matcher_(arg);
 }
 else {
 if(std::find(flags_.begin(), flags_.end(), arg) != flags_.end()) {
 return subrange{0,arg.size()};
 }
 return str::longest_prefix_match(arg, flags_);
 }
 }
 
 
 //---------------------------------------------------------------
 const arg_list&
 flags() const noexcept {
 return flags_;
 }
 
 const match_function&
 matcher() const noexcept {
 return matcher_;
 }
 
 
 //---------------------------------------------------------------
 inline friend parameter&
 with_prefix(const arg_string& prefix, parameter& p)
 {
 if(prefix.empty() || p.flags().empty()) return p;
 
 for(auto& f : p.flags_) {
 if(f.find(prefix) != 0) f.insert(0, prefix);
 }
 return p;
 }
 
 
 inline friend parameter&
 with_prefixes_short_long(
 const arg_string& shortpfx, const arg_string& longpfx,
 parameter& p)
 {
 if(shortpfx.empty() && longpfx.empty()) return p;
 if(p.flags().empty()) return p;
 
 for(auto& f : p.flags_) {
 if(f.size() == 1) {
 if(f.find(shortpfx) != 0) f.insert(0, shortpfx);
 } else {
 if(f.find(longpfx) != 0) f.insert(0, longpfx);
 }
 }
 return p;
 }
 
private:
 //---------------------------------------------------------------
 void add_flags(arg_string str) {
 //empty flags are not allowed
 str::remove_ws(str);
 if(!str.empty()) flags_.push_back(std::move(str));
 }
 
 //---------------------------------------------------------------
 void add_flags(const arg_list& strs) {
 if(strs.empty()) return;
 flags_.reserve(flags_.size() + strs.size());
 for(const auto& s : strs) add_flags(s);
 }
 
 template<class String1, class String2, class... Strings>
 void
 add_flags(String1&& s1, String2&& s2, Strings&&... ss) {
 flags_.reserve(2 + sizeof...(ss));
 add_flags(std::forward<String1>(s1));
 add_flags(std::forward<String2>(s2), std::forward<Strings>(ss)...);
 }
 
 arg_list flags_;
 match_function matcher_;
 doc_string label_;
 bool required_ = false;
};
 
 
 
 
/*************************************************************************/
template<class String, class... Strings>
inline parameter
command(String&& flag, Strings&&... flags)
{
 return parameter{std::forward<String>(flag), std::forward<Strings>(flags)...}
 .required(true).blocking(true).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class String, class... Strings>
inline parameter
required(String&& flag, Strings&&... flags)
{
 return parameter{std::forward<String>(flag), std::forward<Strings>(flags)...}
 .required(true).blocking(false).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class String, class... Strings>
inline parameter
option(String&& flag, Strings&&... flags)
{
 return parameter{std::forward<String>(flag), std::forward<Strings>(flags)...}
 .required(false).blocking(false).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
value(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::nonempty}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(false);
}
 
template<class Filter, class... Targets, class = typename std::enable_if<
 traits::is_callable<Filter,bool(const char*)>::value ||
 traits::is_callable<Filter,subrange(const char*)>::value>::type>
inline parameter
value(Filter&& filter, doc_string label, Targets&&... tgts)
{
 return parameter{std::forward<Filter>(filter)}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
values(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::nonempty}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(true);
}
 
template<class Filter, class... Targets, class = typename std::enable_if<
 traits::is_callable<Filter,bool(const char*)>::value ||
 traits::is_callable<Filter,subrange(const char*)>::value>::type>
inline parameter
values(Filter&& filter, doc_string label, Targets&&... tgts)
{
 return parameter{std::forward<Filter>(filter)}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_value(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::nonempty}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(false);
}
 
template<class Filter, class... Targets, class = typename std::enable_if<
 traits::is_callable<Filter,bool(const char*)>::value ||
 traits::is_callable<Filter,subrange(const char*)>::value>::type>
inline parameter
opt_value(Filter&& filter, doc_string label, Targets&&... tgts)
{
 return parameter{std::forward<Filter>(filter)}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_values(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::nonempty}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(true);
}
 
template<class Filter, class... Targets, class = typename std::enable_if<
 traits::is_callable<Filter,bool(const char*)>::value ||
 traits::is_callable<Filter,subrange(const char*)>::value>::type>
inline parameter
opt_values(Filter&& filter, doc_string label, Targets&&... tgts)
{
 return parameter{std::forward<Filter>(filter)}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
word(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::alphanumeric}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
words(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::alphanumeric}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_word(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::alphanumeric}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_words(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::alphanumeric}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
number(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::numbers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
numbers(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::numbers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_number(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::numbers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_numbers(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::numbers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
integer(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::integers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
integers(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::integers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(true).blocking(true).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_integer(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::integers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(false);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
opt_integers(const doc_string& label, Targets&&... tgts)
{
 return parameter{match::integers{}}
 .label(label)
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(true);
}
 
 
 
/*************************************************************************/
template<class... Targets>
inline parameter
any_other(Targets&&... tgts)
{
 return parameter{match::any}
 .target(std::forward<Targets>(tgts)...)
 .required(false).blocking(false).repeatable(true);
}
 
 
 
 
/*************************************************************************/
class group :
 public detail::token<group>
{
 //---------------------------------------------------------------
 template<class Param, class Group>
 struct child_t {
 enum class type : char {param, group};
 public:
 
 explicit
 child_t(const Param& v) : m_{v}, type_{type::param} {}
 child_t( Param&& v) noexcept : m_{std::move(v)}, type_{type::param} {}
 
 explicit
 child_t(const Group& g) : m_{g}, type_{type::group} {}
 child_t( Group&& g) noexcept : m_{std::move(g)}, type_{type::group} {}
 
 child_t(const child_t& src): type_{src.type_} {
 switch(type_) {
 default:
 case type::param: new(&m_)data{src.m_.param}; break;
 case type::group: new(&m_)data{src.m_.group}; break;
 }
 }
 
 child_t(child_t&& src) noexcept : type_{src.type_} {
 switch(type_) {
 default:
 case type::param: new(&m_)data{std::move(src.m_.param)}; break;
 case type::group: new(&m_)data{std::move(src.m_.group)}; break;
 }
 }
 
 child_t& operator = (const child_t& src) {
 destroy_content();
 type_ = src.type_;
 switch(type_) {
 default:
 case type::param: new(&m_)data{src.m_.param}; break;
 case type::group: new(&m_)data{src.m_.group}; break;
 }
 return *this;
 }
 
 child_t& operator = (child_t&& src) noexcept {
 destroy_content();
 type_ = src.type_;
 switch(type_) {
 default:
 case type::param: new(&m_)data{std::move(src.m_.param)}; break;
 case type::group: new(&m_)data{std::move(src.m_.group)}; break;
 }
 return *this;
 }
 
 ~child_t() {
 destroy_content();
 }
 
 const doc_string&
 doc() const noexcept {
 switch(type_) {
 default:
 case type::param: return m_.param.doc();
 case type::group: return m_.group.doc();
 }
 }
 
 bool blocking() const noexcept {
 switch(type_) {
 case type::param: return m_.param.blocking();
 case type::group: return m_.group.blocking();
 default: return false;
 }
 }
 bool repeatable() const noexcept {
 switch(type_) {
 case type::param: return m_.param.repeatable();
 case type::group: return m_.group.repeatable();
 default: return false;
 }
 }
 bool required() const noexcept {
 switch(type_) {
 case type::param: return m_.param.required();
 case type::group:
 return (m_.group.exclusive() && m_.group.all_required() ) ||
 (!m_.group.exclusive() && m_.group.any_required() );
 default: return false;
 }
 }
 bool exclusive() const noexcept {
 switch(type_) {
 case type::group: return m_.group.exclusive();
 case type::param:
 default: return false;
 }
 }
 std::size_t param_count() const noexcept {
 switch(type_) {
 case type::group: return m_.group.param_count();
 case type::param:
 default: return std::size_t(1);
 }
 }
 std::size_t depth() const noexcept {
 switch(type_) {
 case type::group: return m_.group.depth();
 case type::param:
 default: return std::size_t(0);
 }
 }
 
 void execute_actions(const arg_string& arg) const {
 switch(type_) {
 default:
 case type::group: return;
 case type::param: m_.param.execute_actions(arg); break;
 }
 
 }
 
 void notify_repeated(arg_index idx) const {
 switch(type_) {
 default:
 case type::group: return;
 case type::param: m_.param.notify_repeated(idx); break;
 }
 }
 void notify_missing(arg_index idx) const {
 switch(type_) {
 default:
 case type::group: return;
 case type::param: m_.param.notify_missing(idx); break;
 }
 }
 void notify_blocked(arg_index idx) const {
 switch(type_) {
 default:
 case type::group: return;
 case type::param: m_.param.notify_blocked(idx); break;
 }
 }
 void notify_conflict(arg_index idx) const {
 switch(type_) {
 default:
 case type::group: return;
 case type::param: m_.param.notify_conflict(idx); break;
 }
 }
 
 bool is_param() const noexcept { return type_ == type::param; }
 bool is_group() const noexcept { return type_ == type::group; }
 
 Param& as_param() noexcept { return m_.param; }
 Group& as_group() noexcept { return m_.group; }
 
 const Param& as_param() const noexcept { return m_.param; }
 const Group& as_group() const noexcept { return m_.group; }
 
 private:
 void destroy_content() {
 switch(type_) {
 default:
 case type::param: m_.param.~Param(); break;
 case type::group: m_.group.~Group(); break;
 }
 }
 
 union data {
 data() {}
 
 data(const Param& v) : param{v} {}
 data( Param&& v) noexcept : param{std::move(v)} {}
 
 data(const Group& g) : group{g} {}
 data( Group&& g) noexcept : group{std::move(g)} {}
 ~data() {}
 
 Param param;
 Group group;
 };
 
 data m_;
 type type_;
 };
 
 
public:
 //---------------------------------------------------------------
 using child = child_t<parameter,group>;
 using value_type = child;
 
private:
 using children_store = std::vector<child>;
 
public:
 using const_iterator = children_store::const_iterator;
 using iterator = children_store::iterator;
 using size_type = children_store::size_type;
 
 
 //---------------------------------------------------------------
 class depth_first_traverser
 {
 public:
 //-----------------------------------------------------
 struct context {
 context() = default;
 context(const group& p):
 parent{&p}, cur{p.begin()}, end{p.end()}
 {}
 const group* parent = nullptr;
 const_iterator cur;
 const_iterator end;
 };
 using context_list = std::vector<context>;
 
 //-----------------------------------------------------
 class memento {
 friend class depth_first_traverser;
 int level_;
 context context_;
 public:
 int level() const noexcept { return level_; }
 const child* param() const noexcept { return &(*context_.cur); }
 };
 
 depth_first_traverser() = default;
 
 explicit
 depth_first_traverser(const group& cur): stack_{} {
 if(!cur.empty()) stack_.emplace_back(cur);
 }
 
 explicit operator bool() const noexcept {
 return !stack_.empty();
 }
 
 int level() const noexcept {
 return int(stack_.size());
 }
 
 bool is_first_in_group() const noexcept {
 if(stack_.empty()) return false;
 return (stack_.back().cur == stack_.back().parent->begin());
 }
 
 bool is_last_in_group() const noexcept {
 if(stack_.empty()) return false;
 return (stack_.back().cur+1 == stack_.back().end);
 }
 
 bool is_last_in_path() const noexcept {
 if(stack_.empty()) return false;
 for(const auto& t : stack_) {
 if(t.cur+1 != t.end) return false;
 }
 const auto& top = stack_.back();
 //if we have to descend into group on next ++ => not last in path
 if(top.cur->is_group()) return false;
 return true;
 }
 
 bool is_alternative(int minlevel = 0) const noexcept {
 if(stack_.empty()) return false;
 if(minlevel > 0) minlevel -= 1;
 if(minlevel >= int(stack_.size())) return false;
 return std::any_of(stack_.begin() + minlevel, stack_.end(),
 [](const context& c) { return c.parent->exclusive(); });
 }
 
 bool is_repeatable(int minlevel = 0) const noexcept {
 if(stack_.empty()) return false;
 if(stack_.back().cur->repeatable()) return true;
 if(minlevel > 0) minlevel -= 1;
 if(minlevel >= int(stack_.size())) return false;
 return std::any_of(stack_.begin() + minlevel, stack_.end(),
 [](const context& c) { return c.parent->repeatable(); });
 }
 bool joinable() const noexcept {
 if(stack_.empty()) return false;
 return std::any_of(stack_.begin(), stack_.end(),
 [](const context& c) { return c.parent->joinable(); });
 }
 
 const context_list&
 stack() const {
 return stack_;
 }
 
 const group*
 repeat_group() const noexcept {
 auto i = std::find_if(stack_.rbegin(), stack_.rend(),
 [](const context& c) { return c.parent->repeatable(); });
 
 return i != stack_.rend() ? i->parent : nullptr;
 }
 
 const group*
 join_group() const noexcept {
 auto i = std::find_if(stack_.begin(), stack_.end(),
 [](const context& c) { return c.parent->joinable(); });
 return i != stack_.end() ? i->parent : nullptr;
 }
 
 const group* root() const noexcept {
 return stack_.empty() ? nullptr : stack_.front().parent;
 }
 
 arg_string common_flag_prefix() const noexcept {
 if(stack_.empty()) return "";
 auto g = join_group();
 return g ? g->common_flag_prefix() : arg_string("");
 }
 
 const child&
 operator * () const noexcept {
 return *stack_.back().cur;
 }
 
 const child*
 operator -> () const noexcept {
 return &(*stack_.back().cur);
 }
 
 const group&
 parent() const noexcept {
 return *(stack_.back().parent);
 }
 
 
 depth_first_traverser&
 operator ++ () {
 if(stack_.empty()) return *this;
 //at group -> decend into group
 if(stack_.back().cur->is_group()) {
 stack_.emplace_back(stack_.back().cur->as_group());
 }
 else {
 next_sibling();
 }
 return *this;
 }
 
 depth_first_traverser&
 next_sibling() {
 if(stack_.empty()) return *this;
 ++stack_.back().cur;
 //at the end of current group?
 while(stack_.back().cur == stack_.back().end) {
 //go to parent
 stack_.pop_back();
 if(stack_.empty()) return *this;
 //go to next sibling in parent
 ++stack_.back().cur;
 }
 return *this;
 }
 
 depth_first_traverser&
 next_after_siblings() {
 if(stack_.empty()) return *this;
 stack_.back().cur = stack_.back().end-1;
 next_sibling();
 return *this;
 }
 
 depth_first_traverser&
 next_alternative() {
 if(stack_.empty()) return *this;
 
 //find first exclusive group (from the top of the stack!)
 auto i = std::find_if(stack_.rbegin(), stack_.rend(),
 [](const context& c) { return c.parent->exclusive(); });
 if(i == stack_.rend()) return *this;
 
 stack_.erase(i.base(), stack_.end());
 next_sibling();
 return *this;
 }
 
 depth_first_traverser&
 back_to_parent() {
 if(stack_.empty()) return *this;
 stack_.pop_back();
 return *this;
 }
 
 depth_first_traverser&
 skip_siblings() {
 if(stack_.empty()) return *this;
 //future increments won't visit subsequent siblings:
 stack_.back().end = stack_.back().cur+1;
 return *this;
 }
 
 depth_first_traverser&
 skip_alternatives() {
 if(stack_.empty()) return *this;
 
 //exclude all other alternatives in surrounding groups
 //by making their current position the last one
 for(auto& c : stack_) {
 if(c.parent && c.parent->exclusive() && c.cur < c.end)
 c.end = c.cur+1;
 }
 
 return *this;
 }
 
 void invalidate() {
 stack_.clear();
 }
 
 inline friend bool operator == (const depth_first_traverser& a,
 const depth_first_traverser& b)
 {
 if(a.stack_.empty() || b.stack_.empty()) return false;
 
 //parents not the same -> different position
 if(a.stack_.back().parent != b.stack_.back().parent) return false;
 
 bool aEnd = a.stack_.back().cur == a.stack_.back().end;
 bool bEnd = b.stack_.back().cur == b.stack_.back().end;
 //either both at the end of the same parent => same position
 if(aEnd && bEnd) return true;
 //or only one at the end => not at the same position
 if(aEnd || bEnd) return false;
 return std::addressof(*a.stack_.back().cur) ==
 std::addressof(*b.stack_.back().cur);
 }
 inline friend bool operator != (const depth_first_traverser& a,
 const depth_first_traverser& b)
 {
 return !(a == b);
 }
 
 memento
 undo_point() const {
 memento m;
 m.level_ = int(stack_.size());
 if(!stack_.empty()) m.context_ = stack_.back();
 return m;
 }
 
 void undo(const memento& m) {
 if(m.level_ < 1) return;
 if(m.level_ <= int(stack_.size())) {
 stack_.erase(stack_.begin() + m.level_, stack_.end());
 stack_.back() = m.context_;
 }
 else if(stack_.empty() && m.level_ == 1) {
 stack_.push_back(m.context_);
 }
 }
 
 private:
 context_list stack_;
 };
 
 
 //---------------------------------------------------------------
 group() = default;
 
 template<class Param, class... Params>
 explicit
 group(doc_string docstr, Param param, Params... params):
 children_{}, exclusive_{false}, joinable_{false}, scoped_{true}
 {
 doc(std::move(docstr));
 push_back(std::move(param), std::move(params)...);
 }
 
 template<class... Params>
 explicit
 group(parameter param, Params... params):
 children_{}, exclusive_{false}, joinable_{false}, scoped_{true}
 {
 push_back(std::move(param), std::move(params)...);
 }
 
 template<class P2, class... Ps>
 explicit
 group(group p1, P2 p2, Ps... ps):
 children_{}, exclusive_{false}, joinable_{false}, scoped_{true}
 {
 push_back(std::move(p1), std::move(p2), std::move(ps)...);
 }
 
 
 //-----------------------------------------------------
 group(const group&) = default;
 group(group&&) = default;
 
 
 //---------------------------------------------------------------
 group& operator = (const group&) = default;
 group& operator = (group&&) = default;
 
 
 //---------------------------------------------------------------
 group& joinable(bool yes) {
 joinable_ = yes;
 return *this;
 }
 
 bool joinable() const noexcept {
 return joinable_;
 }
 
 
 //---------------------------------------------------------------
 group& scoped(bool yes) {
 scoped_ = yes;
 return *this;
 }
 
 bool scoped() const noexcept
 {
 return scoped_;
 }
 
 
 //---------------------------------------------------------------
 group& exclusive(bool yes) {
 exclusive_ = yes;
 return *this;
 }
 bool exclusive() const noexcept {
 return exclusive_;
 }
 
 
 //---------------------------------------------------------------
 bool any_required() const
 {
 return std::any_of(children_.begin(), children_.end(),
 [](const child& n){ return n.required(); });
 }
 bool all_required() const
 {
 return std::all_of(children_.begin(), children_.end(),
 [](const child& n){ return n.required(); });
 }
 
 
 //---------------------------------------------------------------
 bool any_optional() const {
 return !all_required();
 }
 bool all_optional() const {
 return !any_required();
 }
 
 
 //---------------------------------------------------------------
 bool blocking() const noexcept {
 return token<group>::blocking() || (exclusive() && all_blocking());
 }
 //-----------------------------------------------------
 group& blocking(bool yes) {
 return token<group>::blocking(yes);
 }
 
 //---------------------------------------------------------------
 bool any_blocking() const
 {
 return std::any_of(children_.begin(), children_.end(),
 [](const child& n){ return n.blocking(); });
 }
 //---------------------------------------------------------------
 bool all_blocking() const
 {
 return std::all_of(children_.begin(), children_.end(),
 [](const child& n){ return n.blocking(); });
 }
 
 
 //---------------------------------------------------------------
 bool any_flagless() const
 {
 return std::any_of(children_.begin(), children_.end(),
 [](const child& p){
 return p.is_param() && p.as_param().flags().empty();
 });
 }
 bool all_flagless() const
 {
 return std::all_of(children_.begin(), children_.end(),
 [](const child& p){
 return p.is_param() && p.as_param().flags().empty();
 });
 }
 
 
 //---------------------------------------------------------------
 group&
 push_back(const parameter& v) {
 children_.emplace_back(v);
 return *this;
 }
 //-----------------------------------------------------
 group&
 push_back(parameter&& v) {
 children_.emplace_back(std::move(v));
 return *this;
 }
 //-----------------------------------------------------
 group&
 push_back(const group& g) {
 children_.emplace_back(g);
 return *this;
 }
 //-----------------------------------------------------
 group&
 push_back(group&& g) {
 children_.emplace_back(std::move(g));
 return *this;
 }
 
 
 //-----------------------------------------------------
 template<class Param1, class Param2, class... Params>
 group&
 push_back(Param1&& param1, Param2&& param2, Params&&... params)
 {
 children_.reserve(children_.size() + 2 + sizeof...(params));
 push_back(std::forward<Param1>(param1));
 push_back(std::forward<Param2>(param2), std::forward<Params>(params)...);
 return *this;
 }
 
 
 //---------------------------------------------------------------
 group&
 push_front(const parameter& v) {
 children_.emplace(children_.begin(), v);
 return *this;
 }
 //-----------------------------------------------------
 group&
 push_front(parameter&& v) {
 children_.emplace(children_.begin(), std::move(v));
 return *this;
 }
 //-----------------------------------------------------
 group&
 push_front(const group& g) {
 children_.emplace(children_.begin(), g);
 return *this;
 }
 //-----------------------------------------------------
 group&
 push_front(group&& g) {
 children_.emplace(children_.begin(), std::move(g));
 return *this;
 }
 
 
 //---------------------------------------------------------------
 group&
 merge(group&& g)
 {
 children_.insert(children_.end(),
 std::make_move_iterator(g.begin()),
 std::make_move_iterator(g.end()));
 return *this;
 }
 //-----------------------------------------------------
 template<class... Groups>
 group&
 merge(group&& g1, group&& g2, Groups&&... gs)
 {
 merge(std::move(g1));
 merge(std::move(g2), std::forward<Groups>(gs)...);
 return *this;
 }
 
 
 //---------------------------------------------------------------
 child& operator [] (size_type index) noexcept {
 return children_[index];
 }
 const child& operator [] (size_type index) const noexcept {
 return children_[index];
 }
 
 //---------------------------------------------------------------
 child& front() noexcept { return children_.front(); }
 const child& front() const noexcept { return children_.front(); }
 //-----------------------------------------------------
 child& back() noexcept { return children_.back(); }
 const child& back() const noexcept { return children_.back(); }
 
 
 //---------------------------------------------------------------
 bool empty() const noexcept { return children_.empty(); }
 
 size_type size() const noexcept { return children_.size(); }
 
 size_type depth() const {
 size_type n = 0;
 for(const auto& c : children_) {
 auto l = 1 + c.depth();
 if(l > n) n = l;
 }
 return n;
 }
 
 
 //---------------------------------------------------------------
 iterator begin() noexcept { return children_.begin(); }
 const_iterator begin() const noexcept { return children_.begin(); }
 const_iterator cbegin() const noexcept { return children_.begin(); }
 
 iterator end() noexcept { return children_.end(); }
 const_iterator end() const noexcept { return children_.end(); }
 const_iterator cend() const noexcept { return children_.end(); }
 
 
 //---------------------------------------------------------------
 depth_first_traverser
 begin_dfs() const noexcept {
 return depth_first_traverser{*this};
 }
 
 
 //---------------------------------------------------------------
 size_type param_count() const {
 size_type c = 0;
 for(const auto& n : children_) {
 c += n.param_count();
 }
 return c;
 }
 
 
 //---------------------------------------------------------------
 arg_list all_flags() const
 {
 std::vector<arg_string> all;
 gather_flags(children_, all);
 return all;
 }
 
 bool flags_are_prefix_free() const
 {
 const auto fs = all_flags();
 
 using std::begin; using std::end;
 for(auto i = begin(fs), e = end(fs); i != e; ++i) {
 if(!i->empty()) {
 for(auto j = i+1; j != e; ++j) {
 if(!j->empty() && *i != *j) {
 if(i->find(*j) == 0) return false;
 if(j->find(*i) == 0) return false;
 }
 }
 }
 }
 
 return true;
 }
 
 
 //---------------------------------------------------------------
 arg_string common_flag_prefix() const
 {
 arg_list prefixes;
 gather_prefixes(children_, prefixes);
 return str::longest_common_prefix(prefixes);
 }
 
 
private:
 //---------------------------------------------------------------
 static void
 gather_flags(const children_store& nodes, arg_list& all)
 {
 for(const auto& p : nodes) {
 if(p.is_group()) {
 gather_flags(p.as_group().children_, all);
 }
 else {
 const auto& pf = p.as_param().flags();
 using std::begin;
 using std::end;
 if(!pf.empty()) all.insert(end(all), begin(pf), end(pf));
 }
 }
 }
 //---------------------------------------------------------------
 static void
 gather_prefixes(const children_store& nodes, arg_list& all)
 {
 for(const auto& p : nodes) {
 if(p.is_group()) {
 gather_prefixes(p.as_group().children_, all);
 }
 else if(!p.as_param().flags().empty()) {
 auto pfx = str::longest_common_prefix(p.as_param().flags());
 if(!pfx.empty()) all.push_back(std::move(pfx));
 }
 }
 }
 
 //---------------------------------------------------------------
 children_store children_;
 bool exclusive_ = false;
 bool joinable_ = false;
 bool scoped_ = false;
};
 
 
 
/*************************************************************************/
using pattern = group::child;
 
 
 
/*************************************************************************/
inline group
operator , (parameter a, parameter b)
{
 return group{std::move(a), std::move(b)}.scoped(false);
}
 
//---------------------------------------------------------
inline group
operator , (parameter a, group b)
{
 return !b.scoped() && !b.blocking() && !b.exclusive() && !b.repeatable()
 && !b.joinable() && (b.doc().empty() || b.doc() == a.doc())
 ? b.push_front(std::move(a))
 : group{std::move(a), std::move(b)}.scoped(false);
}
 
//---------------------------------------------------------
inline group
operator , (group a, parameter b)
{
 return !a.scoped() && !a.blocking() && !a.exclusive() && !a.repeatable()
 && !a.joinable() && (a.doc().empty() || a.doc() == b.doc())
 ? a.push_back(std::move(b))
 : group{std::move(a), std::move(b)}.scoped(false);
}
 
//---------------------------------------------------------
inline group
operator , (group a, group b)
{
 return !a.scoped() && !a.blocking() && !a.exclusive() && !a.repeatable()
 && !a.joinable() && (a.doc().empty() || a.doc() == b.doc())
 ? a.push_back(std::move(b))
 : group{std::move(a), std::move(b)}.scoped(false);
}
 
 
 
/*************************************************************************/
template<class Param, class... Params>
inline group
one_of(Param param, Params... params)
{
 return group{std::move(param), std::move(params)...}.exclusive(true);
}
 
 
/*************************************************************************/
inline group
operator | (parameter a, parameter b)
{
 return group{std::move(a), std::move(b)}.scoped(false).exclusive(true);
}
 
//-------------------------------------------------------------------
inline group
operator | (parameter a, group b)
{
 return !b.scoped() && !b.blocking() && b.exclusive() && !b.repeatable()
 && !b.joinable()
 && (b.doc().empty() || b.doc() == a.doc())
 ? b.push_front(std::move(a))
 : group{std::move(a), std::move(b)}.scoped(false).exclusive(true);
}
 
//-------------------------------------------------------------------
inline group
operator | (group a, parameter b)
{
 return !a.scoped() && a.exclusive() && !a.repeatable() && !a.joinable()
 && a.blocking() == b.blocking()
 && (a.doc().empty() || a.doc() == b.doc())
 ? a.push_back(std::move(b))
 : group{std::move(a), std::move(b)}.scoped(false).exclusive(true);
}
 
inline group
operator | (group a, group b)
{
 return !a.scoped() && a.exclusive() &&!a.repeatable() && !a.joinable()
 && a.blocking() == b.blocking()
 && (a.doc().empty() || a.doc() == b.doc())
 ? a.push_back(std::move(b))
 : group{std::move(a), std::move(b)}.scoped(false).exclusive(true);
}
 
 
 
namespace detail {
 
inline void set_blocking(bool) {}
 
template<class P, class... Ps>
void set_blocking(bool yes, P& p, Ps&... ps) {
 p.blocking(yes);
 set_blocking(yes, ps...);
}
 
} // namespace detail
 
 
/*************************************************************************/
template<class Param, class... Params>
inline group
in_sequence(Param param, Params... params)
{
 detail::set_blocking(true, param, params...);
 return group{std::move(param), std::move(params)...}.scoped(true);
}
 
 
/*************************************************************************/
inline group
operator & (parameter a, parameter b)
{
 a.blocking(true);
 b.blocking(true);
 return group{std::move(a), std::move(b)}.scoped(true);
}
 
//---------------------------------------------------------
inline group
operator & (parameter a, group b)
{
 a.blocking(true);
 return group{std::move(a), std::move(b)}.scoped(true);
}
 
//---------------------------------------------------------
inline group
operator & (group a, parameter b)
{
 b.blocking(true);
 if(a.all_blocking() && !a.exclusive() && !a.repeatable() && !a.joinable()
 && (a.doc().empty() || a.doc() == b.doc()))
 {
 return a.push_back(std::move(b));
 }
 else {
 if(!a.all_blocking()) a.blocking(true);
 return group{std::move(a), std::move(b)}.scoped(true);
 }
}
 
inline group
operator & (group a, group b)
{
 if(!b.all_blocking()) b.blocking(true);
 if(a.all_blocking() && !a.exclusive() && !a.repeatable()
 && !a.joinable() && (a.doc().empty() || a.doc() == b.doc()))
 {
 return a.push_back(std::move(b));
 }
 else {
 if(!a.all_blocking()) a.blocking(true);
 return group{std::move(a), std::move(b)}.scoped(true);
 }
}
 
 
 
/*************************************************************************/
inline group&
joinable(group& param) {
 return param.joinable(true);
}
 
inline group&&
joinable(group&& param) {
 return std::move(param.joinable(true));
}
 
//-------------------------------------------------------------------
template<class... Params>
inline group
joinable(parameter param, Params... params)
{
 return group{std::move(param), std::move(params)...}.joinable(true);
}
 
template<class P2, class... Ps>
inline group
joinable(group p1, P2 p2, Ps... ps)
{
 return group{std::move(p1), std::move(p2), std::move(ps)...}.joinable(true);
}
 
template<class Param, class... Params>
inline group
joinable(doc_string docstr, Param param, Params... params)
{
 return group{std::move(param), std::move(params)...}
 .joinable(true).doc(std::move(docstr));
}
 
 
 
/*************************************************************************/
inline parameter
repeatable(parameter p) {
 return p.repeatable(true);
}
 
/*************************************************************************/
inline group
repeatable(group g) {
 return g.repeatable(true);
}
 
 
 
/*************************************************************************/
template<class P2, class... Ps>
inline group
repeatable(parameter p1, P2 p2, Ps... ps)
{
 return group{std::move(p1), std::move(p2),
 std::move(ps)...}.repeatable(true);
}
 
template<class P2, class... Ps>
inline group
repeatable(group p1, P2 p2, Ps... ps)
{
 return group{std::move(p1), std::move(p2),
 std::move(ps)...}.repeatable(true);
}
 
 
 
/*************************************************************************/
inline parameter&&
with_prefix(const arg_string& prefix, parameter&& p) {
 return std::move(with_prefix(prefix, p));
}
 
 
//-------------------------------------------------------------------
inline group&
with_prefix(const arg_string& prefix, group& params)
{
 for(auto& p : params) {
 if(p.is_group()) {
 with_prefix(prefix, p.as_group());
 } else {
 with_prefix(prefix, p.as_param());
 }
 }
 return params;
}
 
 
inline group&&
with_prefix(const arg_string& prefix, group&& params)
{
 return std::move(with_prefix(prefix, params));
}
 
 
template<class Param, class... Params>
inline group
with_prefix(arg_string prefix, Param&& param, Params&&... params)
{
 return with_prefix(prefix, group{std::forward<Param>(param),
 std::forward<Params>(params)...});
}
 
 
 
/*************************************************************************/
inline parameter&&
with_prefixes_short_long(const arg_string& shortpfx, const arg_string& longpfx,
 parameter&& p)
{
 return std::move(with_prefixes_short_long(shortpfx, longpfx, p));
}
 
 
//-------------------------------------------------------------------
inline group&
with_prefixes_short_long(const arg_string& shortFlagPrefix,
 const arg_string& longFlagPrefix,
 group& params)
{
 for(auto& p : params) {
 if(p.is_group()) {
 with_prefixes_short_long(shortFlagPrefix, longFlagPrefix, p.as_group());
 } else {
 with_prefixes_short_long(shortFlagPrefix, longFlagPrefix, p.as_param());
 }
 }
 return params;
}
 
 
inline group&&
with_prefixes_short_long(const arg_string& shortFlagPrefix,
 const arg_string& longFlagPrefix,
 group&& params)
{
 return std::move(with_prefixes_short_long(shortFlagPrefix, longFlagPrefix,
 params));
}
 
 
template<class Param, class... Params>
inline group
with_prefixes_short_long(const arg_string& shortFlagPrefix,
 const arg_string& longFlagPrefix,
 Param&& param, Params&&... params)
{
 return with_prefixes_short_long(shortFlagPrefix, longFlagPrefix,
 group{std::forward<Param>(param),
 std::forward<Params>(params)...});
}
 
 
 
 
 
 
 
 
/*************************************************************************/
namespace detail {
 
 
/*************************************************************************/
class scoped_dfs_traverser
{
public:
 using dfs_traverser = group::depth_first_traverser;
 
 scoped_dfs_traverser() = default;
 
 explicit
 scoped_dfs_traverser(const group& g):
 pos_{g}, lastMatch_{}, posAfterLastMatch_{}, scopes_{},
 curMatched_{false}, ignoreBlocks_{false},
 repeatGroupStarted_{false}, repeatGroupContinues_{false}
 {}
 
 const dfs_traverser& base() const noexcept { return pos_; }
 const dfs_traverser& last_match() const noexcept { return lastMatch_; }
 
 const group& parent() const noexcept { return pos_.parent(); }
 const group* repeat_group() const noexcept { return pos_.repeat_group(); }
 const group* join_group() const noexcept { return pos_.join_group(); }
 
 const pattern* operator ->() const noexcept { return pos_.operator->(); }
 const pattern& operator *() const noexcept { return *pos_; }
 
 const pattern* ptr() const noexcept { return pos_.operator->(); }
 
 explicit operator bool() const noexcept { return bool(pos_); }
 
 bool joinable() const noexcept { return pos_.joinable(); }
 arg_string common_flag_prefix() const { return pos_.common_flag_prefix(); }
 
 void ignore_blocking(bool yes) { ignoreBlocks_ = yes; }
 
 void invalidate() { pos_.invalidate(); curMatched_ = false; }
 bool matched() const noexcept { return curMatched_; }
 
 bool start_of_repeat_group() const noexcept { return repeatGroupStarted_; }
 
 //-----------------------------------------------------
 scoped_dfs_traverser&
 next_sibling() { pos_.next_sibling(); return *this; }
 
 scoped_dfs_traverser&
 next_alternative() { pos_.next_alternative(); return *this; }
 
 scoped_dfs_traverser&
 next_after_siblings() { pos_.next_after_siblings(); return *this; }
 
 //-----------------------------------------------------
 scoped_dfs_traverser&
 operator ++ ()
 {
 if(!pos_) return *this;
 
 if(pos_.is_last_in_path()) {
 return_to_outermost_scope();
 return *this;
 }
 
 //current pattern can block if it didn't match already
 if(!ignoreBlocks_ && !matched()) {
 //current group can block if we didn't have any match in it
 if(pos_.is_last_in_group() && pos_.parent().blocking()
 && (!posAfterLastMatch_ || &(posAfterLastMatch_.parent()) != &(pos_.parent())))
 {
 //ascend to parent's level
 ++pos_;
 //skip all siblings of parent group
 pos_.next_after_siblings();
 if(!pos_) return_to_outermost_scope();
 }
 else if(pos_->blocking() && !pos_->is_group()) {
 if(pos_.parent().exclusive()) { //is_alternative(pos_.level())) {
 pos_.next_alternative();
 } else {
 //no match => skip siblings of blocking param
 pos_.next_after_siblings();
 }
 if(!pos_) return_to_outermost_scope();
 } else {
 ++pos_;
 }
 } else {
 ++pos_;
 }
 check_left_scope();
 return *this;
 }
 
 //-----------------------------------------------------
 void next_after_match(scoped_dfs_traverser match)
 {
 if(!match || ignoreBlocks_) return;
 
 check_repeat_group_start(match);
 
 lastMatch_ = match.base();
 
 if(!match->blocking() && match.base().parent().blocking()) {
 match.pos_.back_to_parent();
 }
 
 //if match is not in current position & current position is blocking
 //=> current position has to be advanced by one so that it is
 //no longer reachable within current scope
 //(can happen for repeatable, blocking parameters)
 if(match.base() != pos_ && pos_->blocking()) pos_.next_sibling();
 
 if(match->blocking()) {
 if(match.pos_.is_alternative()) {
 //discard other alternatives
 match.pos_.skip_alternatives();
 }
 
 if(is_last_in_current_scope(match.pos_)) {
 //if current param is not repeatable -> back to previous scope
 if(!match->repeatable() && !match->is_group()) {
 curMatched_ = false;
 pos_ = std::move(match.pos_);
 if(!scopes_.empty()) pos_.undo(scopes_.top());
 }
 else { //stay at match position
 curMatched_ = true;
 pos_ = std::move(match.pos_);
 }
 }
 else { //not last in current group
 //if current param is not repeatable, go directly to next
 if(!match->repeatable() && !match->is_group()) {
 curMatched_ = false;
 ++match.pos_;
 } else {
 curMatched_ = true;
 }
 
 if(match.pos_.level() > pos_.level()) {
 scopes_.push(pos_.undo_point());
 pos_ = std::move(match.pos_);
 }
 else if(match.pos_.level() < pos_.level()) {
 return_to_level(match.pos_.level());
 }
 else {
 pos_ = std::move(match.pos_);
 }
 }
 posAfterLastMatch_ = pos_;
 }
 else {
 if(match.pos_.level() < pos_.level()) {
 return_to_level(match.pos_.level());
 }
 posAfterLastMatch_ = pos_;
 }
 repeatGroupContinues_ = repeat_group_continues();
 }
 
private:
 //-----------------------------------------------------
 bool is_last_in_current_scope(const dfs_traverser& pos)
 {
 if(scopes_.empty()) return pos.is_last_in_path();
 //check if we would leave the current scope on ++
 auto p = pos;
 ++p;
 return p.level() < scopes_.top().level();
 }
 
 //-----------------------------------------------------
 void check_repeat_group_start(const scoped_dfs_traverser& newMatch)
 {
 const auto newrg = newMatch.repeat_group();
 if(!newrg) {
 repeatGroupStarted_ = false;
 }
 else if(lastMatch_.repeat_group() != newrg) {
 repeatGroupStarted_ = true;
 }
 else if(!repeatGroupContinues_ || !newMatch.repeatGroupContinues_) {
 repeatGroupStarted_ = true;
 }
 else {
 //special case: repeat group is outermost group
 //=> we can never really 'leave' and 'reenter' it
 //but if the current scope is the first element, then we are
 //conceptually at a position 'before' the group
 repeatGroupStarted_ = scopes_.empty() || (
 newrg == pos_.root() &&
 scopes_.top().param() == &(*pos_.root()->begin()) );
 }
 repeatGroupContinues_ = repeatGroupStarted_;
 }
 
 //-----------------------------------------------------
 bool repeat_group_continues()
 {
 if(!repeatGroupContinues_) return false;
 const auto curRepGroup = pos_.repeat_group();
 if(!curRepGroup) return false;
 if(curRepGroup != lastMatch_.repeat_group()) return false;
 if(!posAfterLastMatch_) return false;
 return true;
 }
 
 //-----------------------------------------------------
 void check_left_scope()
 {
 if(posAfterLastMatch_) {
 if(pos_.level() < posAfterLastMatch_.level()) {
 while(!scopes_.empty() && scopes_.top().level() >= pos_.level()) {
 pos_.undo(scopes_.top());
 scopes_.pop();
 }
 posAfterLastMatch_.invalidate();
 }
 }
 while(!scopes_.empty() && scopes_.top().level() > pos_.level()) {
 pos_.undo(scopes_.top());
 scopes_.pop();
 }
 repeatGroupContinues_ = repeat_group_continues();
 }
 
 //-----------------------------------------------------
 void return_to_outermost_scope()
 {
 posAfterLastMatch_.invalidate();
 
 if(scopes_.empty()) {
 pos_.invalidate();
 repeatGroupContinues_ = false;
 return;
 }
 
 while(!scopes_.empty() && (!pos_ || pos_.level() >= 1)) {
 pos_.undo(scopes_.top());
 scopes_.pop();
 }
 while(!scopes_.empty()) scopes_.pop();
 
 repeatGroupContinues_ = repeat_group_continues();
 }
 
 //-----------------------------------------------------
 void return_to_level(int level)
 {
 if(pos_.level() <= level) return;
 while(!scopes_.empty() && pos_.level() > level) {
 pos_.undo(scopes_.top());
 scopes_.pop();
 }
 };
 
 dfs_traverser pos_;
 dfs_traverser lastMatch_;
 dfs_traverser posAfterLastMatch_;
 std::stack<dfs_traverser::memento> scopes_;
 bool curMatched_ = false;
 bool ignoreBlocks_ = false;
 bool repeatGroupStarted_ = false;
 bool repeatGroupContinues_ = false;
};
 
 
 
 
/*****************************************************************************
 *
 * some parameter property predicates
 *
 *****************************************************************************/
struct select_all {
 bool operator () (const parameter&) const noexcept { return true; }
};
 
struct select_flags {
 bool operator () (const parameter& p) const noexcept {
 return !p.flags().empty();
 }
};
 
struct select_values {
 bool operator () (const parameter& p) const noexcept {
 return p.flags().empty();
 }
};
 
 
 
/*************************************************************************/
class match_t {
public:
 match_t() = default;
 match_t(arg_string s, scoped_dfs_traverser p):
 str_{std::move(s)}, pos_{std::move(p)}
 {}
 
 const arg_string& str() const noexcept { return str_; }
 const scoped_dfs_traverser& pos() const noexcept { return pos_; }
 
 explicit operator bool() const noexcept { return !str_.empty(); }
 
private:
 arg_string str_;
 scoped_dfs_traverser pos_;
};
 
 
 
/*************************************************************************/
template<class Predicate>
match_t
full_match(scoped_dfs_traverser pos, const arg_string& arg,
 const Predicate& select)
{
 if(arg.empty()) return match_t{};
 
 while(pos) {
 if(pos->is_param()) {
 const auto& param = pos->as_param();
 if(select(param)) {
 const auto match = param.match(arg);
 if(match && match.length() == arg.size()) {
 return match_t{arg, std::move(pos)};
 }
 }
 }
 ++pos;
 }
 return match_t{};
}
 
 
 
/*************************************************************************/
template<class Predicate>
match_t
prefix_match(scoped_dfs_traverser pos, const arg_string& arg,
 const Predicate& select)
{
 if(arg.empty()) return match_t{};
 
 while(pos) {
 if(pos->is_param()) {
 const auto& param = pos->as_param();
 if(select(param)) {
 const auto match = param.match(arg);
 if(match.prefix()) {
 if(match.length() == arg.size()) {
 return match_t{arg, std::move(pos)};
 }
 else {
 return match_t{arg.substr(match.at(), match.length()),
 std::move(pos)};
 }
 }
 }
 }
 ++pos;
 }
 return match_t{};
}
 
 
 
/*************************************************************************/
template<class Predicate>
match_t
partial_match(scoped_dfs_traverser pos, const arg_string& arg,
 const Predicate& select)
{
 if(arg.empty()) return match_t{};
 
 while(pos) {
 if(pos->is_param()) {
 const auto& param = pos->as_param();
 if(select(param)) {
 const auto match = param.match(arg);
 if(match) {
 return match_t{arg.substr(match.at(), match.length()),
 std::move(pos)};
 }
 }
 }
 ++pos;
 }
 return match_t{};
}
 
} //namespace detail
 
 
 
 
 
 
/***************************************************************/
class parser
{
public:
 using dfs_traverser = group::depth_first_traverser;
 using scoped_dfs_traverser = detail::scoped_dfs_traverser;
 
 
 /*****************************************************/
 class arg_mapping {
 public:
 friend class parser;
 
 explicit
 arg_mapping(arg_index idx, arg_string s,
 const dfs_traverser& match)
 :
 index_{idx}, arg_{std::move(s)}, match_{match},
 repeat_{0}, startsRepeatGroup_{false},
 blocked_{false}, conflict_{false}
 {}
 
 explicit
 arg_mapping(arg_index idx, arg_string s) :
 index_{idx}, arg_{std::move(s)}, match_{},
 repeat_{0}, startsRepeatGroup_{false},
 blocked_{false}, conflict_{false}
 {}
 
 arg_index index() const noexcept { return index_; }
 const arg_string& arg() const noexcept { return arg_; }
 
 const parameter* param() const noexcept {
 return match_ && match_->is_param()
 ? &(match_->as_param()) : nullptr;
 }
 
 std::size_t repeat() const noexcept { return repeat_; }
 
 bool blocked() const noexcept { return blocked_; }
 bool conflict() const noexcept { return conflict_; }
 
 bool bad_repeat() const noexcept {
 if(!param()) return false;
 return repeat_ > 0 && !param()->repeatable()
 && !match_.repeat_group();
 }
 
 bool any_error() const noexcept {
 return !match_ || blocked() || conflict() || bad_repeat();
 }
 
 private:
 arg_index index_;
 arg_string arg_;
 dfs_traverser match_;
 std::size_t repeat_;
 bool startsRepeatGroup_;
 bool blocked_;
 bool conflict_;
 };
 
 /*****************************************************/
 class missing_event {
 public:
 explicit
 missing_event(const parameter* p, arg_index after):
 param_{p}, aftIndex_{after}
 {}
 
 const parameter* param() const noexcept { return param_; }
 
 arg_index after_index() const noexcept { return aftIndex_; }
 
 private:
 const parameter* param_;
 arg_index aftIndex_;
 };
 
 //-----------------------------------------------------
 using missing_events = std::vector<missing_event>;
 using arg_mappings = std::vector<arg_mapping>;
 
 
private:
 struct miss_candidate {
 miss_candidate(dfs_traverser p, arg_index idx,
 bool firstInRepeatGroup = false):
 pos{std::move(p)}, index{idx},
 startsRepeatGroup{firstInRepeatGroup}
 {}
 
 dfs_traverser pos;
 arg_index index;
 bool startsRepeatGroup;
 };
 using miss_candidates = std::vector<miss_candidate>;
 
 
public:
 //---------------------------------------------------------------
 explicit
 parser(const group& root, arg_index offset = 0):
 root_{&root}, pos_{root},
 index_{offset-1}, eaten_{0},
 args_{}, missCand_{}, blocked_{false}
 {
 for_each_potential_miss(dfs_traverser{root},
 [this](const dfs_traverser& p){
 missCand_.emplace_back(p, index_);
 });
 }
 
 
 //---------------------------------------------------------------
 bool operator() (const arg_string& arg)
 {
 ++eaten_;
 ++index_;
 
 if(!valid() || arg.empty()) return false;
 
 if(!blocked_ && try_match(arg)) return true;
 
 if(try_match_blocked(arg)) return false;
 
 //skipping of blocking & required patterns is not allowed
 if(!blocked_ && !pos_.matched() && pos_->required() && pos_->blocking()) {
 blocked_ = true;
 return false;
 }
 
 add_nomatch(arg);
 return false;
 }
 
 
 //---------------------------------------------------------------
 const arg_mappings& args() const {
 return args_;
 }
 
 missing_events missed() const {
 missing_events misses;
 misses.reserve(missCand_.size());
 for(auto i = missCand_.begin(); i != missCand_.end(); ++i) {
 misses.emplace_back(&(i->pos->as_param()), i->index);
 }
 return misses;
 }
 
 arg_index parse_count() const noexcept { return eaten_; }
 
 bool valid() const noexcept { return bool(pos_); }
 
 explicit operator bool() const noexcept { return valid(); }
 
 
private:
 //---------------------------------------------------------------
 using match_t = detail::match_t;
 
 
 //---------------------------------------------------------------
 bool try_match_blocked(const arg_string& arg)
 {
 //try to match ahead (using temporary parser)
 if(pos_) {
 auto ahead = *this;
 if(try_match_blocked(std::move(ahead), arg)) return true;
 }
 
 //try to match from the beginning (using temporary parser)
 if(root_) {
 parser all{*root_, index_+1};
 if(try_match_blocked(std::move(all), arg)) return true;
 }
 
 return false;
 }
 
 //---------------------------------------------------------------
 bool try_match_blocked(parser&& parse, const arg_string& arg)
 {
 const auto nold = int(parse.args_.size());
 
 parse.pos_.ignore_blocking(true);
 
 if(!parse.try_match(arg)) return false;
 
 for(auto i = parse.args_.begin() + nold; i != parse.args_.end(); ++i) {
 args_.push_back(*i);
 args_.back().blocked_ = true;
 }
 return true;
 }
 
 //---------------------------------------------------------------
 bool try_match(const arg_string& arg)
 {
 //Note: flag-params will always take precedence over value-params
 if(try_match_full(arg, detail::select_flags{})) return true;
 if(try_match_joined_flags(arg)) return true;
 if(try_match_joined_sequence(arg, detail::select_flags{})) return true;
 if(try_match_full(arg, detail::select_values{})) return true;
 if(try_match_joined_sequence(arg, detail::select_all{})) return true;
 if(try_match_joined_params(arg)) return true;
 return false;
 }
 
 //---------------------------------------------------------------
 template<class Predicate>
 bool try_match_full(const arg_string& arg, const Predicate& select)
 {
 auto match = detail::full_match(pos_, arg, select);
 
 if(!match) return false;
 
 add_match(match);
 return true;
 }
 
 //---------------------------------------------------------------
 template<class Predicate>
 bool try_match_joined_sequence(arg_string arg, const Predicate& acceptFirst)
 {
 auto fstMatch = detail::prefix_match(pos_, arg, acceptFirst);
 
 if(!fstMatch) return false;
 
 if(fstMatch.str().size() == arg.size()) {
 add_match(fstMatch);
 return true;
 }
 
 if(!fstMatch.pos()->blocking()) return false;
 
 auto pos = fstMatch.pos();
 pos.ignore_blocking(true);
 const auto parent = &pos.parent();
 if(!pos->repeatable()) ++pos;
 
 arg.erase(0, fstMatch.str().size());
 std::vector<match_t> matches { std::move(fstMatch) };
 
 while(!arg.empty() && pos &&
 pos->blocking() && pos->is_param() &&
 (&pos.parent() == parent))
 {
 auto match = pos->as_param().match(arg);
 
 if(match.prefix()) {
 matches.emplace_back(arg.substr(0,match.length()), pos);
 arg.erase(0, match.length());
 if(!pos->repeatable()) ++pos;
 }
 else {
 if(!pos->repeatable()) return false;
 ++pos;
 }
 
 }
 
 if(!arg.empty() || matches.empty()) return false;
 
 for(const auto& m : matches) add_match(m);
 return true;
 }
 
 //-----------------------------------------------------
 bool try_match_joined_flags(const arg_string& arg)
 {
 return try_match_joined([&](const group& g) {
 if(try_match_joined(g, arg, detail::select_flags{},
 g.common_flag_prefix()) )
 {
 return true;
 }
 return false;
 });
 }
 
 //---------------------------------------------------------------
 bool try_match_joined_params(const arg_string& arg)
 {
 return try_match_joined([&](const group& g) {
 if(try_match_joined(g, arg, detail::select_all{}) ) {
 return true;
 }
 return false;
 });
 }
 
 //-----------------------------------------------------
 template<class Predicate>
 bool try_match_joined(const group& joinGroup, arg_string arg,
 const Predicate& pred,
 const arg_string& prefix = "")
 {
 parser parse {joinGroup};
 std::vector<match_t> matches;
 
 while(!arg.empty()) {
 auto match = detail::prefix_match(parse.pos_, arg, pred);
 
 if(!match) return false;
 
 arg.erase(0, match.str().size());
 //make sure prefix is always present after the first match
 //ensures that, e.g., flags "-a" and "-b" will be found in "-ab"
 if(!arg.empty() && !prefix.empty() && arg.find(prefix) != 0 &&
 prefix != match.str())
 {
 arg.insert(0,prefix);
 }
 
 parse.add_match(match);
 matches.push_back(std::move(match));
 }
 
 if(!arg.empty() || matches.empty()) return false;
 
 if(!parse.missCand_.empty()) return false;
 for(const auto& a : parse.args_) if(a.any_error()) return false;
 
 //replay matches onto *this
 for(const auto& m : matches) add_match(m);
 return true;
 }
 
 //-----------------------------------------------------
 template<class Predicate>
 bool try_match_joined(const Predicate& pred)
 {
 if(pos_ && pos_.parent().joinable()) {
 const auto& g = pos_.parent();
 if(pred(g)) return true;
 return false;
 }
 
 auto pos = pos_;
 while(pos) {
 if(pos->is_group() && pos->as_group().joinable()) {
 const auto& g = pos->as_group();
 if(pred(g)) return true;
 pos.next_sibling();
 }
 else {
 ++pos;
 }
 }
 return false;
 }
 
 
 //---------------------------------------------------------------
 void add_nomatch(const arg_string& arg) {
 args_.emplace_back(index_, arg);
 }
 
 
 //---------------------------------------------------------------
 void add_match(const match_t& match)
 {
 const auto& pos = match.pos();
 if(!pos || !pos->is_param() || match.str().empty()) return;
 
 pos_.next_after_match(pos);
 
 arg_mapping newArg{index_, match.str(), pos.base()};
 newArg.repeat_ = occurrences_of(&pos->as_param());
 newArg.conflict_ = check_conflicts(pos.base());
 newArg.startsRepeatGroup_ = pos_.start_of_repeat_group();
 args_.push_back(std::move(newArg));
 
 add_miss_candidates_after(pos);
 clean_miss_candidates_for(pos.base());
 discard_alternative_miss_candidates(pos.base());
 
 }
 
 //-----------------------------------------------------
 bool check_conflicts(const dfs_traverser& match)
 {
 if(pos_.start_of_repeat_group()) return false;
 bool conflict = false;
 for(const auto& m : match.stack()) {
 if(m.parent->exclusive()) {
 for(auto i = args_.rbegin(); i != args_.rend(); ++i) {
 if(!i->blocked()) {
 for(const auto& c : i->match_.stack()) {
 //sibling within same exclusive group => conflict
 if(c.parent == m.parent && c.cur != m.cur) {
 conflict = true;
 i->conflict_ = true;
 }
 }
 }
 //check for conflicts only within current repeat cycle
 if(i->startsRepeatGroup_) break;
 }
 }
 }
 return conflict;
 }
 
 //-----------------------------------------------------
 void clean_miss_candidates_for(const dfs_traverser& match)
 {
 auto i = std::find_if(missCand_.rbegin(), missCand_.rend(),
 [&](const miss_candidate& m) {
 return &(*m.pos) == &(*match);
 });
 
 if(i != missCand_.rend()) {
 missCand_.erase(prev(i.base()));
 }
 }
 
 //-----------------------------------------------------
 void discard_alternative_miss_candidates(const dfs_traverser& match)
 {
 if(missCand_.empty()) return;
 //find out, if miss candidate is sibling of one of the same
 //alternative groups that the current match is a member of
 //if so, we can discard the miss
 
 //go through all exclusive groups of matching pattern
 for(const auto& m : match.stack()) {
 if(m.parent->exclusive()) {
 for(auto i = int(missCand_.size())-1; i >= 0; --i) {
 bool removed = false;
 for(const auto& c : missCand_[i].pos.stack()) {
 //sibling within same exclusive group => discard
 if(c.parent == m.parent && c.cur != m.cur) {
 missCand_.erase(missCand_.begin() + i);
 if(missCand_.empty()) return;
 removed = true;
 break;
 }
 }
 //remove miss candidates only within current repeat cycle
 if(i > 0 && removed) {
 if(missCand_[i-1].startsRepeatGroup) break;
 } else {
 if(missCand_[i].startsRepeatGroup) break;
 }
 }
 }
 }
 }
 
 //-----------------------------------------------------
 void add_miss_candidates_after(const scoped_dfs_traverser& match)
 {
 auto npos = match.base();
 if(npos.is_alternative()) npos.skip_alternatives();
 ++npos;
 //need to add potential misses if:
 //either new repeat group was started
 const auto newRepGroup = match.repeat_group();
 if(newRepGroup) {
 if(pos_.start_of_repeat_group()) {
 for_each_potential_miss(std::move(npos),
 [&,this](const dfs_traverser& pos) {
 //only add candidates within repeat group
 if(newRepGroup == pos.repeat_group()) {
 missCand_.emplace_back(pos, index_, true);
 }
 });
 }
 }
 //... or an optional blocking param was hit
 else if(match->blocking() && !match->required() &&
 npos.level() >= match.base().level())
 {
 for_each_potential_miss(std::move(npos),
 [&,this](const dfs_traverser& pos) {
 //only add new candidates
 if(std::find_if(missCand_.begin(), missCand_.end(),
 [&](const miss_candidate& c){
 return &(*c.pos) == &(*pos);
 }) == missCand_.end())
 {
 missCand_.emplace_back(pos, index_);
 }
 });
 }
 
 }
 
 //-----------------------------------------------------
 template<class Action>
 static void
 for_each_potential_miss(dfs_traverser pos, Action&& action)
 {
 const auto level = pos.level();
 while(pos && pos.level() >= level) {
 if(pos->is_group() ) {
 const auto& g = pos->as_group();
 if(g.all_optional() || (g.exclusive() && g.any_optional())) {
 pos.next_sibling();
 } else {
 ++pos;
 }
 } else { //param
 if(pos->required()) {
 action(pos);
 ++pos;
 } else if(pos->blocking()) { //optional + blocking
 pos.next_after_siblings();
 } else {
 ++pos;
 }
 }
 }
 }
 
 
 //---------------------------------------------------------------
 std::size_t occurrences_of(const parameter* p) const
 {
 auto i = std::find_if(args_.rbegin(), args_.rend(),
 [p](const arg_mapping& a){ return a.param() == p; });
 
 if(i != args_.rend()) return i->repeat() + 1;
 return 0;
 }
 
 
 //---------------------------------------------------------------
 const group* root_;
 scoped_dfs_traverser pos_;
 arg_index index_;
 arg_index eaten_;
 arg_mappings args_;
 miss_candidates missCand_;
 bool blocked_;
};
 
 
 
 
/*************************************************************************/
class parsing_result
{
public:
 using arg_mapping = parser::arg_mapping;
 using arg_mappings = parser::arg_mappings;
 using missing_event = parser::missing_event;
 using missing_events = parser::missing_events;
 using iterator = arg_mappings::const_iterator;
 
 //-----------------------------------------------------
 parsing_result() = default;
 
 parsing_result(arg_mappings arg2param, missing_events misses):
 arg2param_{std::move(arg2param)}, missing_{std::move(misses)}
 {}
 
 //-----------------------------------------------------
 arg_mappings::size_type
 unmapped_args_count() const noexcept {
 return std::count_if(arg2param_.begin(), arg2param_.end(),
 [](const arg_mapping& a){ return !a.param(); });
 }
 
 bool any_blocked() const noexcept {
 return std::any_of(arg2param_.begin(), arg2param_.end(),
 [](const arg_mapping& a){ return a.blocked(); });
 }
 
 bool any_conflict() const noexcept {
 return std::any_of(arg2param_.begin(), arg2param_.end(),
 [](const arg_mapping& a){ return a.conflict(); });
 }
 
 bool any_bad_repeat() const noexcept {
 return std::any_of(arg2param_.begin(), arg2param_.end(),
 [](const arg_mapping& a){ return a.bad_repeat(); });
 }
 
 bool any_error() const noexcept {
 return unmapped_args_count() > 0 || !missing().empty() ||
 any_blocked() || any_conflict() || any_bad_repeat();
 }
 
 explicit operator bool() const noexcept { return !any_error(); }
 
 const missing_events& missing() const noexcept { return missing_; }
 
 iterator begin() const noexcept { return arg2param_.begin(); }
 iterator end() const noexcept { return arg2param_.end(); }
 
private:
 //-----------------------------------------------------
 arg_mappings arg2param_;
 missing_events missing_;
};
 
 
 
 
namespace detail {
namespace {
 
/*************************************************************************/
void sanitize_args(arg_list& args)
{
 //e.g. {"-o12", ".34"} -> {"-o", "12.34"}
 
 if(args.empty()) return;
 
 for(auto i = begin(args)+1; i != end(args); ++i) {
 if(i != begin(args) && i->size() > 1 &&
 i->find('.') == 0 && std::isdigit((*i)[1]) )
 {
 //find trailing digits in previous arg
 using std::prev;
 auto& prv = *prev(i);
 auto fstDigit = std::find_if_not(prv.rbegin(), prv.rend(),
 [](arg_string::value_type c){
 return std::isdigit(c);
 }).base();
 
 //handle leading sign
 if(fstDigit > prv.begin() &&
 (*prev(fstDigit) == '+' || *prev(fstDigit) == '-'))
 {
 --fstDigit;
 }
 
 //prepend digits from previous arg
 i->insert(begin(*i), fstDigit, end(prv));
 
 //erase digits in previous arg
 prv.erase(fstDigit, end(prv));
 }
 }
}
 
 
 
/*************************************************************************/
void execute_actions(const parsing_result& res)
{
 for(const auto& m : res) {
 if(m.param()) {
 const auto& param = *(m.param());
 
 if(m.repeat() > 0) param.notify_repeated(m.index());
 if(m.blocked()) param.notify_blocked(m.index());
 if(m.conflict()) param.notify_conflict(m.index());
 //main action
 if(!m.any_error()) param.execute_actions(m.arg());
 }
 }
 
 for(auto m : res.missing()) {
 if(m.param()) m.param()->notify_missing(m.after_index());
 }
}
 
 
 
/*************************************************************************/
static parsing_result
parse_args(const arg_list& args, const group& cli,
 arg_index offset = 0)
{
 //parse args and store unrecognized arg indices
 parser parse{cli, offset};
 for(const auto& arg : args) {
 parse(arg);
 if(!parse.valid()) break;
 }
 
 return parsing_result{parse.args(), parse.missed()};
}
 
/*************************************************************************/
static parsing_result
parse_and_execute(const arg_list& args, const group& cli,
 arg_index offset = 0)
{
 auto result = parse_args(args, cli, offset);
 
 execute_actions(result);
 
 return result;
}
 
} //anonymous namespace
} // namespace detail
 
 
 
 
/*************************************************************************/
inline parsing_result
parse(arg_list args, const group& cli)
{
 detail::sanitize_args(args);
 return detail::parse_and_execute(args, cli);
}
 
 
/*************************************************************************/
inline parsing_result
parse(std::initializer_list<const char*> arglist, const group& cli)
{
 arg_list args;
 args.reserve(arglist.size());
 for(auto a : arglist) {
 if(std::strlen(a) > 0) args.push_back(a);
 }
 
 return parse(std::move(args), cli);
}
 
 
/*************************************************************************/
template<class InputIterator>
inline parsing_result
parse(InputIterator first, InputIterator last, const group& cli)
{
 return parse(arg_list(first,last), cli);
}
 
 
/*************************************************************************/
inline parsing_result
parse(const int argc, char* argv[], const group& cli, arg_index offset = 1)
{
 arg_list args;
 if(offset < argc) args.assign(argv+offset, argv+argc);
 detail::sanitize_args(args);
 return detail::parse_and_execute(args, cli, offset);
}
 
 
 
 
 
 
/*************************************************************************/
class param_filter
{
public:
 param_filter& prefix(const arg_string& p) noexcept {
 prefix_ = p; return *this;
 }
 param_filter& prefix(arg_string&& p) noexcept {
 prefix_ = std::move(p); return *this;
 }
 const arg_string& prefix() const noexcept { return prefix_; }
 
 param_filter& required(tri t) noexcept { required_ = t; return *this; }
 tri required() const noexcept { return required_; }
 
 param_filter& blocking(tri t) noexcept { blocking_ = t; return *this; }
 tri blocking() const noexcept { return blocking_; }
 
 param_filter& repeatable(tri t) noexcept { repeatable_ = t; return *this; }
 tri repeatable() const noexcept { return repeatable_; }
 
 param_filter& has_doc(tri t) noexcept { hasDoc_ = t; return *this; }
 tri has_doc() const noexcept { return hasDoc_; }
 
 
 bool operator() (const parameter& p) const noexcept {
 if(!prefix_.empty()) {
 if(!std::any_of(p.flags().begin(), p.flags().end(),
 [&](const arg_string& flag){
 return str::has_prefix(flag, prefix_);
 })) return false;
 }
 if(required() != p.required()) return false;
 if(blocking() != p.blocking()) return false;
 if(repeatable() != p.repeatable()) return false;
 if(has_doc() != !p.doc().empty()) return false;
 return true;
 }
 
private:
 arg_string prefix_;
 tri required_ = tri::either;
 tri blocking_ = tri::either;
 tri repeatable_ = tri::either;
 tri exclusive_ = tri::either;
 tri hasDoc_ = tri::yes;
};
 
 
 
 
 
 
/*************************************************************************/
class doc_formatting
{
public:
 using string = doc_string;
 
 doc_formatting& start_column(int col) { startCol_ = col; return *this; }
 int start_column() const noexcept { return startCol_; }
 
 doc_formatting& doc_column(int col) { docCol_ = col; return *this; }
 int doc_column() const noexcept { return docCol_; }
 
 doc_formatting& indent_size(int indent) { indentSize_ = indent; return *this; }
 int indent_size() const noexcept { return indentSize_; }
 
 doc_formatting& empty_label(const string& label) {
 emptyLabel_ = label;
 return *this;
 }
 const string& empty_label() const noexcept { return emptyLabel_; }
 
 doc_formatting& param_separator(const string& sep) {
 paramSep_ = sep;
 return *this;
 }
 const string& param_separator() const noexcept { return paramSep_; }
 
 doc_formatting& group_separator(const string& sep) {
 groupSep_ = sep;
 return *this;
 }
 const string& group_separator() const noexcept { return groupSep_; }
 
 doc_formatting& alternative_param_separator(const string& sep) {
 altParamSep_ = sep;
 return *this;
 }
 const string& alternative_param_separator() const noexcept { return altParamSep_; }
 
 doc_formatting& alternative_group_separator(const string& sep) {
 altGroupSep_ = sep;
 return *this;
 }
 const string& alternative_group_separator() const noexcept { return altGroupSep_; }
 
 doc_formatting& flag_separator(const string& sep) {
 flagSep_ = sep;
 return *this;
 }
 const string& flag_separator() const noexcept { return flagSep_; }
 
 doc_formatting&
 surround_labels(const string& prefix, const string& postfix) {
 labelPre_ = prefix;
 labelPst_ = postfix;
 return *this;
 }
 const string& label_prefix() const noexcept { return labelPre_; }
 const string& label_postfix() const noexcept { return labelPst_; }
 
 doc_formatting&
 surround_optional(const string& prefix, const string& postfix) {
 optionPre_ = prefix;
 optionPst_ = postfix;
 return *this;
 }
 const string& optional_prefix() const noexcept { return optionPre_; }
 const string& optional_postfix() const noexcept { return optionPst_; }
 
 doc_formatting&
 surround_repeat(const string& prefix, const string& postfix) {
 repeatPre_ = prefix;
 repeatPst_ = postfix;
 return *this;
 }
 const string& repeat_prefix() const noexcept { return repeatPre_; }
 const string& repeat_postfix() const noexcept { return repeatPst_; }
 
 doc_formatting&
 surround_alternatives(const string& prefix, const string& postfix) {
 alternPre_ = prefix;
 alternPst_ = postfix;
 return *this;
 }
 const string& alternatives_prefix() const noexcept { return alternPre_; }
 const string& alternatives_postfix() const noexcept { return alternPst_; }
 
 doc_formatting&
 surround_alternative_flags(const string& prefix, const string& postfix) {
 alternFlagPre_ = prefix;
 alternFlagPst_ = postfix;
 return *this;
 }
 const string& alternative_flags_prefix() const noexcept { return alternFlagPre_; }
 const string& alternative_flags_postfix() const noexcept { return alternFlagPst_; }
 
 doc_formatting&
 surround_group(const string& prefix, const string& postfix) {
 groupPre_ = prefix;
 groupPst_ = postfix;
 return *this;
 }
 const string& group_prefix() const noexcept { return groupPre_; }
 const string& group_postfix() const noexcept { return groupPst_; }
 
 doc_formatting&
 surround_joinable(const string& prefix, const string& postfix) {
 joinablePre_ = prefix;
 joinablePst_ = postfix;
 return *this;
 }
 const string& joinable_prefix() const noexcept { return joinablePre_; }
 const string& joinable_postfix() const noexcept { return joinablePst_; }
 
 doc_formatting& max_flags_per_param_in_doc(int max) {
 maxAltInDocs_ = max > 0 ? max : 0;
 return *this;
 }
 int max_flags_per_param_in_doc() const noexcept { return maxAltInDocs_; }
 
 doc_formatting& max_flags_per_param_in_usage(int max) {
 maxAltInUsage_ = max > 0 ? max : 0;
 return *this;
 }
 int max_flags_per_param_in_usage() const noexcept { return maxAltInUsage_; }
 
 doc_formatting& line_spacing(int lines) {
 lineSpc_ = lines > 0 ? lines : 0;
 return *this;
 }
 int line_spacing() const noexcept { return lineSpc_; }
 
 doc_formatting& paragraph_spacing(int lines) {
 paragraphSpc_ = lines > 0 ? lines : 0;
 return *this;
 }
 int paragraph_spacing() const noexcept { return paragraphSpc_; }
 
 doc_formatting& merge_alternative_flags_with_common_prefix(bool yes = true) {
 mergeAltCommonPfx_ = yes;
 return *this;
 }
 bool merge_alternative_flags_with_common_prefix() const noexcept {
 return mergeAltCommonPfx_;
 }
 
 doc_formatting& merge_joinable_with_common_prefix(bool yes = true) {
 mergeJoinableCommonPfx_ = yes;
 return *this;
 }
 bool merge_joinable_with_common_prefix() const noexcept {
 return mergeJoinableCommonPfx_;
 }
 
 doc_formatting& split_alternatives(bool yes = true) {
 splitTopAlt_ = yes;
 return *this;
 }
 bool split_alternatives() const noexcept {
 return splitTopAlt_;
 }
 
 doc_formatting& alternatives_min_split_size(int size) {
 groupSplitSize_ = size > 0 ? size : 0;
 return *this;
 }
 int alternatives_min_split_size() const noexcept { return groupSplitSize_; }
 
private:
 string paramSep_ = string(" ");
 string groupSep_ = string(" ");
 string altParamSep_ = string("|");
 string altGroupSep_ = string(" | ");
 string flagSep_ = string(", ");
 string labelPre_ = string("<");
 string labelPst_ = string(">");
 string optionPre_ = string("[");
 string optionPst_ = string("]");
 string repeatPre_ = string("");
 string repeatPst_ = string("...");
 string groupPre_ = string("(");
 string groupPst_ = string(")");
 string alternPre_ = string("(");
 string alternPst_ = string(")");
 string alternFlagPre_ = string("");
 string alternFlagPst_ = string("");
 string joinablePre_ = string("(");
 string joinablePst_ = string(")");
 string emptyLabel_ = string("");
 int startCol_ = 8;
 int docCol_ = 20;
 int indentSize_ = 4;
 int maxAltInUsage_ = 1;
 int maxAltInDocs_ = 32;
 int lineSpc_ = 0;
 int paragraphSpc_ = 1;
 int groupSplitSize_ = 3;
 bool splitTopAlt_ = true;
 bool mergeAltCommonPfx_ = false;
 bool mergeJoinableCommonPfx_ = true;
};
 
 
 
 
/*************************************************************************/
class usage_lines
{
public:
 using string = doc_string;
 
 usage_lines(const group& params, string prefix = "",
 const doc_formatting& fmt = doc_formatting{})
 :
 params_(params), fmt_(fmt), prefix_(std::move(prefix))
 {
 if(!prefix_.empty()) prefix_ += ' ';
 if(fmt_.start_column() > 0) prefix_.insert(0, fmt.start_column(), ' ');
 }
 
 usage_lines(const group& params, const doc_formatting& fmt):
 usage_lines(params, "", fmt)
 {}
 
 usage_lines& ommit_outermost_group_surrounders(bool yes) {
 ommitOutermostSurrounders_ = yes;
 return *this;
 }
 bool ommit_outermost_group_surrounders() const {
 return ommitOutermostSurrounders_;
 }
 
 template<class OStream>
 inline friend OStream& operator << (OStream& os, const usage_lines& p) {
 p.print_usage(os);
 return os;
 }
 
 string str() const {
 std::ostringstream os; os << *this; return os.str();
 }
 
 
private:
 const group& params_;
 doc_formatting fmt_;
 string prefix_;
 bool ommitOutermostSurrounders_ = false;
 
 
 //-----------------------------------------------------
 struct context {
 group::depth_first_traverser pos;
 std::stack<string> separators;
 std::stack<string> postfixes;
 int level = 0;
 const group* outermost = nullptr;
 bool linestart = false;
 bool useOutermost = true;
 int line = 0;
 
 bool is_singleton() const noexcept {
 return linestart && pos.is_last_in_path();
 }
 bool is_alternative() const noexcept {
 return pos.parent().exclusive();
 }
 };
 
 
 /***************************************************************/
 template<class OStream>
 void print_usage(OStream& os) const
 {
 context cur;
 cur.pos = params_.begin_dfs();
 cur.linestart = true;
 cur.level = cur.pos.level();
 cur.outermost = &params_;
 
 print_usage(os, cur, prefix_);
 }
 
 
 /***************************************************************/
 template<class OStream>
 void print_usage(OStream& os, context cur, string prefix) const
 {
 if(!cur.pos) return;
 
 std::ostringstream buf;
 if(cur.linestart) buf << prefix;
 const auto initPos = buf.tellp();
 
 cur.level = cur.pos.level();
 
 if(cur.useOutermost) {
 //we cannot start outside of the outermost group
 //so we have to treat it separately
 start_group(buf, cur.pos.parent(), cur);
 if(!cur.pos) {
 os << buf.str();
 return;
 }
 }
 else {
 //don't visit siblings of starter node
 cur.pos.skip_siblings();
 }
 check_end_group(buf, cur);
 
 do {
 if(buf.tellp() > initPos) cur.linestart = false;
 if(!cur.linestart && !cur.pos.is_first_in_group()) {
 buf << cur.separators.top();
 }
 if(cur.pos->is_group()) {
 start_group(buf, cur.pos->as_group(), cur);
 if(!cur.pos) {
 os << buf.str();
 return;
 }
 }
 else {
 buf << param_label(cur.pos->as_param(), cur);
 ++cur.pos;
 }
 check_end_group(buf, cur);
 } while(cur.pos);
 
 os << buf.str();
 }
 
 
 /***************************************************************/
 void start_group(std::ostringstream& os,
 const group& group, context& cur) const
 {
 //does cur.pos already point to a member or to group itself?
 //needed for special treatment of outermost group
 const bool alreadyInside = &(cur.pos.parent()) == &group;
 
 auto lbl = joined_label(group, cur);
 if(!lbl.empty()) {
 os << lbl;
 cur.linestart = false;
 //skip over entire group as its label has already been created
 if(alreadyInside) {
 cur.pos.next_after_siblings();
 } else {
 cur.pos.next_sibling();
 }
 }
 else {
 const bool splitAlternatives = group.exclusive() &&
 fmt_.split_alternatives() &&
 std::any_of(group.begin(), group.end(),
 [this](const pattern& p) {
 return int(p.param_count()) >= fmt_.alternatives_min_split_size();
 });
 
 if(splitAlternatives) {
 cur.postfixes.push("");
 cur.separators.push("");
 //recursively print alternative paths in decision-DAG
 //enter group?
 if(!alreadyInside) ++cur.pos;
 cur.linestart = true;
 cur.useOutermost = false;
 auto pfx = os.str();
 os.str("");
 //print paths in DAG starting at each group member
 for(std::size_t i = 0; i < group.size(); ++i) {
 std::stringstream buf;
 cur.outermost = cur.pos->is_group() ? &(cur.pos->as_group()) : nullptr;
 print_usage(buf, cur, pfx);
 if(buf.tellp() > int(pfx.size())) {
 os << buf.str();
 if(i < group.size()-1) {
 if(cur.line > 0) {
 os << string(fmt_.line_spacing(), '\n');
 }
 ++cur.line;
 os << '\n';
 }
 }
 cur.pos.next_sibling(); //do not descend into memebers
 }
 cur.pos.invalidate(); //signal end-of-path
 return;
 }
 else {
 //pre & postfixes, separators
 auto surround = group_surrounders(group, cur);
 os << surround.first;
 cur.postfixes.push(std::move(surround.second));
 cur.separators.push(group_separator(group, fmt_));
 //descend into group?
 if(!alreadyInside) ++cur.pos;
 }
 }
 cur.level = cur.pos.level();
 }
 
 
 /***************************************************************/
 void check_end_group(std::ostringstream& os, context& cur) const
 {
 for(; cur.level > cur.pos.level(); --cur.level) {
 os << cur.postfixes.top();
 cur.postfixes.pop();
 cur.separators.pop();
 }
 cur.level = cur.pos.level();
 }
 
 
 /***************************************************************/
 string param_label(const parameter& p, const context& cur) const
 {
 const auto& parent = cur.pos.parent();
 
 const bool startsOptionalSequence =
 parent.size() > 1 && p.blocking() && cur.pos.is_first_in_group();
 
 const bool outermost =
 ommitOutermostSurrounders_ && cur.outermost == &parent;
 
 const bool showopt = !cur.is_alternative() && !p.required()
 && !startsOptionalSequence && !outermost;
 
 const bool showrep = p.repeatable() && !outermost;
 
 string lbl;
 
 if(showrep) lbl += fmt_.repeat_prefix();
 if(showopt) lbl += fmt_.optional_prefix();
 
 const auto& flags = p.flags();
 if(!flags.empty()) {
 const int n = std::min(fmt_.max_flags_per_param_in_usage(),
 int(flags.size()));
 
 const bool surrAlt = n > 1 && !showopt && !cur.is_singleton();
 
 if(surrAlt) lbl += fmt_.alternative_flags_prefix();
 bool sep = false;
 for(int i = 0; i < n; ++i) {
 if(sep) {
 if(cur.is_singleton())
 lbl += fmt_.alternative_group_separator();
 else
 lbl += fmt_.flag_separator();
 }
 lbl += flags[i];
 sep = true;
 }
 if(surrAlt) lbl += fmt_.alternative_flags_postfix();
 }
 else {
 if(!p.label().empty()) {
 lbl += fmt_.label_prefix()
 + p.label()
 + fmt_.label_postfix();
 } else if(!fmt_.empty_label().empty()) {
 lbl += fmt_.label_prefix()
 + fmt_.empty_label()
 + fmt_.label_postfix();
 } else {
 return "";
 }
 }
 
 if(showopt) lbl += fmt_.optional_postfix();
 if(showrep) lbl += fmt_.repeat_postfix();
 
 return lbl;
 }
 
 
 /***************************************************************/
 string joined_label(const group& params, const context& cur) const
 {
 if(!fmt_.merge_alternative_flags_with_common_prefix() &&
 !fmt_.merge_joinable_with_common_prefix()) return "";
 
 const bool flagsonly = std::all_of(params.begin(), params.end(),
 [](const pattern& p){
 return p.is_param() && !p.as_param().flags().empty();
 });
 
 if(!flagsonly) return "";
 
 const bool showOpt = params.all_optional() &&
 !(ommitOutermostSurrounders_ && cur.outermost == &params);
 
 auto pfx = params.common_flag_prefix();
 if(pfx.empty()) return "";
 
 const auto n = pfx.size();
 if(params.exclusive() &&
 fmt_.merge_alternative_flags_with_common_prefix())
 {
 string lbl;
 if(showOpt) lbl += fmt_.optional_prefix();
 lbl += pfx + fmt_.alternatives_prefix();
 bool first = true;
 for(const auto& p : params) {
 if(p.is_param()) {
 if(first)
 first = false;
 else
 lbl += fmt_.alternative_param_separator();
 lbl += p.as_param().flags().front().substr(n);
 }
 }
 lbl += fmt_.alternatives_postfix();
 if(showOpt) lbl += fmt_.optional_postfix();
 return lbl;
 }
 //no alternatives, but joinable flags
 else if(params.joinable() &&
 fmt_.merge_joinable_with_common_prefix())
 {
 const bool allSingleChar = std::all_of(params.begin(), params.end(),
 [&](const pattern& p){
 return p.is_param() &&
 p.as_param().flags().front().substr(n).size() == 1;
 });
 
 if(allSingleChar) {
 string lbl;
 if(showOpt) lbl += fmt_.optional_prefix();
 lbl += pfx;
 for(const auto& p : params) {
 if(p.is_param())
 lbl += p.as_param().flags().front().substr(n);
 }
 if(showOpt) lbl += fmt_.optional_postfix();
 return lbl;
 }
 }
 
 return "";
 }
 
 
 /***************************************************************/
 std::pair<string,string>
 group_surrounders(const group& group, const context& cur) const
 {
 string prefix;
 string postfix;
 
 const bool isOutermost = &group == cur.outermost;
 if(isOutermost && ommitOutermostSurrounders_)
 return {string{}, string{}};
 
 if(group.exclusive()) {
 if(group.all_optional()) {
 prefix = fmt_.optional_prefix();
 postfix = fmt_.optional_postfix();
 if(group.all_flagless()) {
 prefix += fmt_.label_prefix();
 postfix = fmt_.label_prefix() + postfix;
 }
 } else if(group.all_flagless()) {
 prefix = fmt_.label_prefix();
 postfix = fmt_.label_postfix();
 } else if(!cur.is_singleton() || !isOutermost) {
 prefix = fmt_.alternatives_prefix();
 postfix = fmt_.alternatives_postfix();
 }
 }
 else if(group.size() > 1 &&
 group.front().blocking() && !group.front().required())
 {
 prefix = fmt_.optional_prefix();
 postfix = fmt_.optional_postfix();
 }
 else if(group.size() > 1 && cur.is_alternative() &&
 &group != cur.outermost)
 {
 prefix = fmt_.group_prefix();
 postfix = fmt_.group_postfix();
 }
 else if(!group.exclusive() &&
 group.joinable() && !cur.linestart)
 {
 prefix = fmt_.joinable_prefix();
 postfix = fmt_.joinable_postfix();
 }
 
 if(group.repeatable()) {
 if(prefix.empty()) prefix = fmt_.group_prefix();
 prefix = fmt_.repeat_prefix() + prefix;
 if(postfix.empty()) postfix = fmt_.group_postfix();
 postfix += fmt_.repeat_postfix();
 }
 
 return {std::move(prefix), std::move(postfix)};
 }
 
 
 /***************************************************************/
 static string
 group_separator(const group& group, const doc_formatting& fmt)
 {
 const bool only1ParamPerMember = std::all_of(group.begin(), group.end(),
 [](const pattern& p) { return p.param_count() < 2; });
 
 if(only1ParamPerMember) {
 if(group.exclusive()) {
 return fmt.alternative_param_separator();
 } else {
 return fmt.param_separator();
 }
 }
 else { //there is at least one large group inside
 if(group.exclusive()) {
 return fmt.alternative_group_separator();
 } else {
 return fmt.group_separator();
 }
 }
 }
};
 
 
 
 
/*************************************************************************/
class documentation
{
public:
 using string = doc_string;
 
 documentation(const group& cli,
 const doc_formatting& fmt = doc_formatting{},
 const param_filter& filter = param_filter{})
 :
 cli_(cli), fmt_{fmt}, usgFmt_{fmt}, filter_{filter}
 {
 //necessary, because we re-use "usage_lines" to generate
 //labels for documented groups
 usgFmt_.max_flags_per_param_in_usage(
 usgFmt_.max_flags_per_param_in_doc());
 }
 
 documentation(const group& params,
 const param_filter& filter,
 const doc_formatting& fmt = doc_formatting{})
 :
 documentation(params, fmt, filter)
 {}
 
 template<class OStream>
 inline friend OStream& operator << (OStream& os, const documentation& p) {
 printed prn = printed::nothing;
 p.print_doc(os, p.cli_, prn);
 return os;
 }
 
 string str() const {
 std::ostringstream os; os << *this; return os.str();
 }
 
 
private:
 using dfs_traverser = group::depth_first_traverser;
 enum class printed { nothing, line, paragraph };
 
 const group& cli_;
 doc_formatting fmt_;
 doc_formatting usgFmt_;
 param_filter filter_;
 
 
 /***************************************************************/
 template<class OStream>
 void print_doc(OStream& os, const group& params,
 printed& sofar,
 int indentLvl = 0) const
 {
 if(params.empty()) return;
 
 //if group itself doesn't have docstring
 if(params.doc().empty()) {
 for(const auto& p : params) {
 print_doc(os, p, sofar, indentLvl);
 }
 }
 else { //group itself does have docstring
 bool anyDocInside = std::any_of(params.begin(), params.end(),
 [](const pattern& p){ return !p.doc().empty(); });
 
 if(anyDocInside) { //group docstring as title, then child entries
 if(sofar != printed::nothing) {
 os << string(fmt_.paragraph_spacing() + 1, '\n');
 }
 auto indent = string(fmt_.start_column(), ' ');
 if(indentLvl > 0) indent += string(fmt_.indent_size() * indentLvl, ' ');
 os << indent << params.doc() << '\n';
 sofar = printed::nothing;
 for(const auto& p : params) {
 print_doc(os, p, sofar, indentLvl + 1);
 }
 sofar = printed::paragraph;
 }
 else { //group label first then group docstring
 auto lbl = usage_lines(params, usgFmt_)
 .ommit_outermost_group_surrounders(true).str();
 
 str::trim(lbl);
 print_entry(os, lbl, params.doc(), fmt_, sofar, indentLvl);
 }
 }
 }
 
 
 /***************************************************************/
 template<class OStream>
 void print_doc(OStream& os, const pattern& ptrn,
 printed& sofar, int indentLvl) const
 {
 if(ptrn.is_group()) {
 print_doc(os, ptrn.as_group(), sofar, indentLvl);
 }
 else {
 const auto& p = ptrn.as_param();
 if(!filter_(p)) return;
 print_entry(os, param_label(p, fmt_), p.doc(), fmt_, sofar, indentLvl);
 }
 }
 
 
 /*********************************************************************/
 template<class OStream>
 static void
 print_entry(OStream& os,
 const string& label, const string& docstr,
 const doc_formatting& fmt, printed& sofar, int indentLvl)
 {
 if(label.empty()) return;
 
 auto indent = string(fmt.start_column(), ' ');
 if(indentLvl > 0) indent += string(fmt.indent_size() * indentLvl, ' ');
 
 const auto len = int(indent.size() + label.size());
 const bool oneline = len < fmt.doc_column();
 
 if(oneline) {
 if(sofar == printed::line)
 os << string(fmt.line_spacing() + 1, '\n');
 else if(sofar == printed::paragraph)
 os << string(fmt.paragraph_spacing() + 1, '\n');
 }
 else if(sofar != printed::nothing) {
 os << string(fmt.paragraph_spacing() + 1, '\n');
 }
 
 sofar = oneline ? printed::line : printed::paragraph;
 
 os << indent << label;
 
 if(!docstr.empty()) {
 if(oneline) {
 os << string(fmt.doc_column() - len, ' ');
 } else {
 os << '\n' << string(fmt.doc_column(), ' ');
 }
 os << docstr;
 }
 }
 
 
 /*********************************************************************/
 static doc_string
 param_label(const parameter& param, const doc_formatting& fmt)
 {
 doc_string lbl;
 
 if(param.repeatable()) lbl += fmt.repeat_prefix();
 
 const auto& flags = param.flags();
 if(!flags.empty()) {
 lbl += flags[0];
 const int n = std::min(fmt.max_flags_per_param_in_doc(),
 int(flags.size()));
 for(int i = 1; i < n; ++i) {
 lbl += fmt.flag_separator() + flags[i];
 }
 }
 else if(!param.label().empty() || !fmt.empty_label().empty()) {
 lbl += fmt.label_prefix();
 if(!param.label().empty()) {
 lbl += param.label();
 } else {
 lbl += fmt.empty_label();
 }
 lbl += fmt.label_postfix();
 }
 
 if(param.repeatable()) lbl += fmt.repeat_postfix();
 
 return lbl;
 }
 
};
 
 
 
 
/*************************************************************************/
class man_page
{
public:
 //---------------------------------------------------------------
 using string = doc_string;
 
 //---------------------------------------------------------------
 class section {
 public:
 using string = doc_string;
 
 section(string stitle, string scontent):
 title_{std::move(stitle)}, content_{std::move(scontent)}
 {}
 
 const string& title() const noexcept { return title_; }
 const string& content() const noexcept { return content_; }
 
 private:
 string title_;
 string content_;
 };
 
private:
 using section_store = std::vector<section>;
 
public:
 //---------------------------------------------------------------
 using value_type = section;
 using const_iterator = section_store::const_iterator;
 using size_type = section_store::size_type;
 
 
 //---------------------------------------------------------------
 man_page&
 append_section(string title, string content)
 {
 sections_.emplace_back(std::move(title), std::move(content));
 return *this;
 }
 //-----------------------------------------------------
 man_page&
 prepend_section(string title, string content)
 {
 sections_.emplace(sections_.begin(),
 std::move(title), std::move(content));
 return *this;
 }
 
 
 //---------------------------------------------------------------
 const section& operator [] (size_type index) const noexcept {
 return sections_[index];
 }
 
 //---------------------------------------------------------------
 size_type size() const noexcept { return sections_.size(); }
 
 bool empty() const noexcept { return sections_.empty(); }
 
 
 //---------------------------------------------------------------
 const_iterator begin() const noexcept { return sections_.begin(); }
 const_iterator end() const noexcept { return sections_.end(); }
 
 
 //---------------------------------------------------------------
 man_page& program_name(const string& n) {
 progName_ = n;
 return *this;
 }
 man_page& program_name(string&& n) {
 progName_ = std::move(n);
 return *this;
 }
 const string& program_name() const noexcept {
 return progName_;
 }
 
 
 //---------------------------------------------------------------
 man_page& section_row_spacing(int rows) {
 sectionSpc_ = rows > 0 ? rows : 0;
 return *this;
 }
 int section_row_spacing() const noexcept { return sectionSpc_; }
 
 
private:
 int sectionSpc_ = 1;
 section_store sections_;
 string progName_;
};
 
 
 
/*************************************************************************/
inline man_page
make_man_page(const group& params,
 doc_string progname = "",
 const doc_formatting& fmt = doc_formatting{})
{
 man_page man;
 man.append_section("SYNOPSIS", usage_lines(params,progname,fmt).str());
 man.append_section("OPTIONS", documentation(params,fmt).str());
 return man;
}
 
 
 
/*************************************************************************/
template<class OStream>
OStream&
operator << (OStream& os, const man_page& man)
{
 bool first = true;
 const auto secSpc = doc_string(man.section_row_spacing() + 1, '\n');
 for(const auto& section : man) {
 if(!section.content().empty()) {
 if(first) first = false; else os << secSpc;
 if(!section.title().empty()) os << section.title() << '\n';
 os << section.content();
 }
 }
 os << '\n';
 return os;
}
 
 
 
 
 
/*************************************************************************/
namespace debug {
 
 
/*************************************************************************/
inline doc_string doc_label(const parameter& p)
{
 if(!p.flags().empty()) return p.flags().front();
 if(!p.label().empty()) return p.label();
 return doc_string{"<?>"};
}
 
inline doc_string doc_label(const group&)
{
 return "<group>";
}
 
inline doc_string doc_label(const pattern& p)
{
 return p.is_group() ? doc_label(p.as_group()) : doc_label(p.as_param());
}
 
 
/*************************************************************************/
template<class OStream>
void print(OStream& os, const parsing_result& result)
{
 for(const auto& m : result) {
 os << "#" << m.index() << " " << m.arg() << " -> ";
 auto p = m.param();
 if(p) {
 os << doc_label(*p) << " \t";
 if(m.repeat() > 0) {
 os << (m.bad_repeat() ? "[bad repeat " : "[repeat ")
 << m.repeat() << "]";
 }
 if(m.blocked()) os << " [blocked]";
 if(m.conflict()) os << " [conflict]";
 os << '\n';
 }
 else {
 os << " [unmapped]\n";
 }
 }
 
 for(const auto& m : result.missing()) {
 auto p = m.param();
 if(p) {
 os << doc_label(*p) << " \t";
 os << " [missing after " << m.after_index() << "]\n";
 }
 }
}
 
 
/*************************************************************************/
template<class OStream>
void print(OStream& os, const parameter& p)
{
 if(p.blocking()) os << '!';
 if(!p.required()) os << '[';
 os << doc_label(p);
 if(p.repeatable()) os << "...";
 if(!p.required()) os << "]";
}
 
 
//-------------------------------------------------------------------
template<class OStream>
void print(OStream& os, const group& g, int level = 0);
 
 
/*************************************************************************/
template<class OStream>
void print(OStream& os, const pattern& param, int level = 0)
{
 if(param.is_group()) {
 print(os, param.as_group(), level);
 }
 else {
 os << doc_string(4*level, ' ');
 print(os, param.as_param());
 }
}
 
 
/*************************************************************************/
template<class OStream>
void print(OStream& os, const group& g, int level)
{
 auto indent = doc_string(4*level, ' ');
 os << indent;
 if(g.blocking()) os << '!';
 if(g.joinable()) os << 'J';
 os << (g.exclusive() ? "(|\n" : "(\n");
 for(const auto& p : g) {
 print(os, p, level+1);
 }
 os << '\n' << indent << (g.exclusive() ? "|)" : ")");
 if(g.repeatable()) os << "...";
 os << '\n';
}
 
 
} // namespace debug
} //namespace clipp
 
#endif