util/Sawyer/CommandLine.h

// WARNING: Changes to this file must be contributed back to Sawyer or else they will
//          be clobbered by the next update from Sawyer.  The Sawyer repository is at
//          https://github.com/matzke1/sawyer.
 
 
 
 
/* Command-line switch parsing. */
#ifndef Sawyer_CommandLine_H
#define Sawyer_CommandLine_H
 
#include <Sawyer/Assert.h>
#include <Sawyer/BitFlags.h>
#include <Sawyer/DocumentMarkup.h>
#include <Sawyer/IntervalSet.h>
#include <Sawyer/Map.h>
#include <Sawyer/Message.h>
#include <Sawyer/Optional.h>
#include <Sawyer/Sawyer.h>
#include <Sawyer/Set.h>
#include <Sawyer/SharedPointer.h>
 
#include <boost/algorithm/string/case_conv.hpp>
#include <boost/any.hpp>
#include <boost/cstdint.hpp>
#include <boost/foreach.hpp>
#include <boost/lexical_cast.hpp>
#include <boost/numeric/conversion/cast.hpp>
#include <cerrno>
#include <ctype.h>
#include <list>
#include <regex>
#include <set>
#include <stdexcept>
#include <string>
#include <vector>
 
namespace Sawyer { // documented in Sawyer.h
 
namespace CommandLine {
 
SAWYER_EXPORT extern const std::string STR_NONE;
class Switch;
class SwitchGroup;
class Parser;
class ParserResult;
 
enum SortOrder {
    INSERTION_ORDER,                                    
    DOCKEY_ORDER                                        
};
 
enum Canonical {
    CANONICAL,                                          
    NONCANONICAL,                                       
    ALL_STRINGS                                         
};
 
enum ShowGroupName {
    SHOW_GROUP_OPTIONAL,                                
    SHOW_GROUP_REQUIRED,                                
    SHOW_GROUP_NONE,                                    
    SHOW_GROUP_INHERIT                                  
};
 
enum SwitchSkipping {
    SKIP_NEVER,                                         
    SKIP_WEAK,                                          
    SKIP_STRONG                                         
};
 
//                                      Program argument cursor
 
struct SAWYER_EXPORT Location {
    size_t idx;                                                 
    size_t offset;                                              
    Location(): idx(0), offset(0) {}
 
    Location(size_t idx, size_t offset): idx(idx), offset(offset) {}
 
    bool operator==(const Location &other) const { return idx==other.idx && offset==other.offset; }
 
    bool operator!=(const Location &other) const { return !(*this==other); }
 
    bool operator<(const Location &other) const { return idx<other.idx || (idx==other.idx && offset<other.offset); }
 
    bool operator<=(const Location &other) const { return *this<other || *this==other; }
};
 
SAWYER_EXPORT std::ostream& operator<<(std::ostream&, const Location&);
 
SAWYER_EXPORT extern const Location NOWHERE;
 
class SAWYER_EXPORT Cursor {
#include <Sawyer/WarningsOff.h>
    std::vector<std::string> strings_;
    Location loc_;
#include <Sawyer/WarningsRestore.h>
public:
    Cursor(const std::vector<std::string> &strings): strings_(strings) { location(Location()); }
 
    Cursor(const std::string &string): strings_(1, string) { location(Location()); }
 
    Cursor() {}
 
    const std::vector<std::string>& strings() const { return strings_; }
 
    const Location& location() const { return loc_; }
    Cursor& location(const Location &loc);
    bool atArgBegin() const { return loc_.idx<strings_.size() && 0==loc_.offset; }
 
    bool atArgEnd() const { return loc_.idx<strings_.size() && loc_.offset>=strings_[loc_.idx].size(); }
 
    bool atEnd() const { return atEnd(loc_); }
    bool atEnd(const Location &location) const { return location.idx >= strings_.size(); }
    const std::string& arg() const { return arg(loc_); }
    const std::string& arg(const Location &location) const;
    std::string rest() const { return rest(loc_); }
    std::string rest(const Location &location) const;
    std::string substr(const Location &limit, const std::string &separator=" ") const { return substr(loc_, limit, separator); }
    std::string substr(const Location &limit1, const Location &limit2, const std::string &separator=" ") const;
    void replace(const std::vector<std::string>&);
 
    void consumeChars(size_t nchars);
 
    void consumeArgs(size_t nargs) {
        loc_.idx = std::min(strings_.size(), loc_.idx+nargs);
        loc_.offset = 0;
    }
    void consumeArg() { consumeArgs(1); }
    size_t linearDistance() const;
};
 
class ExcursionGuard {
    Cursor &cursor_;
    Location loc_;
    bool canceled_;
public:
    ExcursionGuard(Cursor &cursor): cursor_(cursor), loc_(cursor.location()), canceled_(false) {} // implicit
    ~ExcursionGuard() { if (!canceled_) cursor_.location(loc_); }
 
    void cancel() { canceled_ = true; }
 
    const Location &startingLocation() const { return loc_; }
};
 
 
//                                      Switch value savers
 
// used internally
class SAWYER_EXPORT ValueSaver: public SharedObject {
protected:
    ValueSaver() {}
public:
    typedef SharedPointer<ValueSaver> Ptr;
    virtual ~ValueSaver() {}
    virtual void save(const boost::any&, const std::string &switchKey) = 0;
};
 
// used internally
template<typename T>
class TypedSaver: public ValueSaver {
    T &storage_;
protected:
    TypedSaver(T &storage): storage_(storage) {}
public:
    typedef SharedPointer<TypedSaver> Ptr;
    static Ptr instance(T &storage) { return Ptr(new TypedSaver(storage)); }
    virtual void save(const boost::any &value, const std::string &/*switchKey*/) /*override*/ {
        storage_ = boost::any_cast<T>(value);
    }
};
 
// Partial specialization of TypedSaver, saving a value of any type T into a container of type CONTAINER_TEMPLATE calling the
// containers INSERT_METHOD with one argument: the value.  The CONTAINER_TEMPLATE is the name of a class template that
// takes one argument: type type of value stored by the container.
#define SAWYER_COMMANDLINE_SEQUENCE_SAVER(CONTAINER_TEMPLATE, INSERT_METHOD)                                                   \
    template<typename T>                                                                                                       \
    class TypedSaver<CONTAINER_TEMPLATE<T> >: public ValueSaver {                                                              \
        CONTAINER_TEMPLATE<T> &storage_;                                                                                       \
    protected:                                                                                                                 \
        TypedSaver(CONTAINER_TEMPLATE<T> &storage): storage_(storage) {}                                                       \
    public:                                                                                                                    \
        static Ptr instance(CONTAINER_TEMPLATE<T> &storage) { return Ptr(new TypedSaver(storage)); }                           \
        virtual void save(const boost::any &value, const std::string &/*switchKey*/) /*override*/ {                            \
            T typed = boost::any_cast<T>(value);                                                                               \
            storage_.INSERT_METHOD(typed);                                                                                     \
        }                                                                                                                      \
    }
 
// Partial specialization of TypedSaver for saving values into map-like containers. The CONTAINER_TEMPLATE should take two
// parameters: the key type (always std::string) and the value type (not part of this specialization). The value is stored by
// invoking the INSERT_METHOD with two arguments: the key string for the switch whose value is being saved, and the value to
// save.
#define SAWYER_COMMANDLINE_MAP_SAVER(CONTAINER_TEMPLATE, INSERT_METHOD)                                                        \
    template<typename T>                                                                                                       \
    class TypedSaver<CONTAINER_TEMPLATE<std::string, T> >: public ValueSaver {                                                 \
        CONTAINER_TEMPLATE<std::string, T> &storage_;                                                                          \
    protected:                                                                                                                 \
        TypedSaver(CONTAINER_TEMPLATE<std::string, T> &storage): storage_(storage) {}                                          \
    public:                                                                                                                    \
        static Ptr instance(CONTAINER_TEMPLATE<std::string, T> &storage) { return Ptr(new TypedSaver(storage)); }              \
        virtual void save(const boost::any &value, const std::string &switchKey) /*override*/ {                                \
            T typed = boost::any_cast<T>(value);                                                                               \
            storage_.INSERT_METHOD(switchKey, typed);                                                                          \
        }                                                                                                                      \
    }
 
// Partial specialization of TypedSaver for saving values into set-like containers. The CONTAINER_TEMPLATE should take one
// parameter: the value type (not part of this specialization). The value is stored by invoking the INSERT_METHOD with one
// argument: the value to save. The value is always an interval.
#define SAWYER_COMMANDLINE_INTERVALSET_SAVER(CONTAINER_TEMPLATE, INSERT_METHOD)                                                \
    template<typename Interval>                                                                                                \
    class TypedSaver<CONTAINER_TEMPLATE<Interval> >: public ValueSaver {                                                         \
        CONTAINER_TEMPLATE<Interval> &storage_;                                                                                \
    protected:                                                                                                                 \
        TypedSaver(CONTAINER_TEMPLATE<Interval> &storage): storage_(storage) {}                                                \
    public:                                                                                                                    \
        static Ptr instance(CONTAINER_TEMPLATE<Interval> &storage) { return Ptr(new TypedSaver(storage)); }                    \
        virtual void save(const boost::any &value, const std::string &switchKey) /*override*/ {                                \
            Interval typed = boost::any_cast<Interval>(value);                                                                        \
            storage_.INSERT_METHOD(typed);                                                                                     \
        }                                                                                                                      \
    }
 
// Partial specialization of TypedSaver for saving values into map-like containers using the STL approach where the insert
// operator takes an std::pair(key,value) rather than two arguments. The CONTAINER_TEMPLATE should take two parameters: the key
// type (always std::string) and the value type (not part of this specialization). The value is stored by invoking the
// INSERT_METHOD with two arguments: the key string for the switch whose value is being saved, and the value to save.
#define SAWYER_COMMANDLINE_MAP_PAIR_SAVER(CONTAINER_TEMPLATE, INSERT_METHOD)                                                   \
    template<typename T>                                                                                                       \
    class TypedSaver<CONTAINER_TEMPLATE<std::string, T> >: public ValueSaver {                                                 \
        CONTAINER_TEMPLATE<std::string, T> &storage_;                                                                          \
    protected:                                                                                                                 \
        TypedSaver(CONTAINER_TEMPLATE<std::string, T> &storage): storage_(storage) {}                                          \
    public:                                                                                                                    \
        static Ptr instance(CONTAINER_TEMPLATE<std::string, T> &storage) { return Ptr(new TypedSaver(storage)); }              \
        virtual void save(const boost::any &value, const std::string &switchKey) /*override*/ {                                \
            T typed = boost::any_cast<T>(value);                                                                               \
            storage_.INSERT_METHOD(std::make_pair(switchKey, typed));                                                          \
        }                                                                                                                      \
    }
 
SAWYER_COMMANDLINE_SEQUENCE_SAVER(std::vector, push_back);
SAWYER_COMMANDLINE_SEQUENCE_SAVER(std::list, push_back);
SAWYER_COMMANDLINE_SEQUENCE_SAVER(std::set, insert);
SAWYER_COMMANDLINE_SEQUENCE_SAVER(Sawyer::Container::Set, insert);
SAWYER_COMMANDLINE_SEQUENCE_SAVER(Optional, operator=);
SAWYER_COMMANDLINE_SEQUENCE_SAVER(BitFlags, set);
SAWYER_COMMANDLINE_MAP_PAIR_SAVER(std::map, insert);
SAWYER_COMMANDLINE_MAP_SAVER(Sawyer::Container::Map, insert);
SAWYER_COMMANDLINE_INTERVALSET_SAVER(Sawyer::Container::IntervalSet, insert);
 
//                                      Parsed value
 
class SAWYER_EXPORT ParsedValue {
#include <Sawyer/WarningsOff.h>
    boost::any value_;
    Location valueLocation_;                            
    std::string valueString_;                           
    std::string switchKey_;                             
    Location switchLocation_;                           
    std::string switchString_;                          
    size_t keySequence_;                                
    size_t switchSequence_;                             
    ValueSaver::Ptr valueSaver_;                        
#include <Sawyer/WarningsRestore.h>
 
public:
    ParsedValue(): keySequence_(0), switchSequence_(0) {}
 
    ParsedValue(const boost::any value, const Location &loc, const std::string &str, const ValueSaver::Ptr &saver)
        : value_(value), valueLocation_(loc), valueString_(str), keySequence_(0), switchSequence_(0), valueSaver_(saver) {}
 
    ParsedValue& switchInfo(const std::string &key, const Location &loc, const std::string &str) {
        switchKey_ = key;
        switchLocation_ = loc;
        switchString_ = str;
        return *this;
    }
 
private:
    friend class ParserResult;
    void sequenceInfo(size_t keySequence, size_t switchSequence) {
        keySequence_ = keySequence;
        switchSequence_ = switchSequence;
    }
 
public:
    const boost::any& value() const { return value_; }
    void value(const boost::any &v) { value_ = v; }
    Location valueLocation() const { return valueLocation_; }
    ParsedValue& valueLocation(const Location &loc) { valueLocation_ = loc; return *this; }
    const std::string &string() const { return valueString_; }
 
    int asInt() const;
    unsigned asUnsigned() const;
    long asLong() const;
    unsigned long asUnsignedLong() const;
    boost::int64_t asInt64() const;
    boost::uint64_t asUnsigned64() const;
    double asDouble() const;
    float asFloat() const;
    bool asBool() const;
    std::string asString() const;
    template<typename T> T as() const { return boost::any_cast<T>(value_); }
 
    ParsedValue& switchKey(const std::string &s) { switchKey_ = s; return *this; }
    const std::string& switchKey() const { return switchKey_; }
    const std::string& switchString() const { return switchString_; }
 
    Location switchLocation() const { return switchLocation_; }
 
    size_t keySequence() const { return keySequence_; }
 
    size_t switchSequence() const { return switchSequence_; }
 
    const ValueSaver::Ptr valueSaver() const { return valueSaver_; }
 
    void save() const;
 
    bool isEmpty() const { return value_.empty(); }
 
    void print(std::ostream&) const;
};
 
SAWYER_EXPORT std::ostream& operator<<(std::ostream&, const ParsedValue&);
 
typedef std::vector<ParsedValue> ParsedValues;
 
 
 
 
//                                      Switch argument parsers
 
class SAWYER_EXPORT ValueParser: public SharedObject, public SharedFromThis<ValueParser> {
#include <Sawyer/WarningsOff.h>
    ValueSaver::Ptr valueSaver_;
#include <Sawyer/WarningsRestore.h>
protected:
    ValueParser() {}
 
    explicit ValueParser(const ValueSaver::Ptr &valueSaver): valueSaver_(valueSaver) {}
public:
    typedef SharedPointer<ValueParser> Ptr;
 
    virtual ~ValueParser() {}
 
    ParsedValue matchString(const std::string&) /*final*/;
 
    ParsedValue match(Cursor&) /*final*/;
 
    Ptr valueSaver(const ValueSaver::Ptr &f) { valueSaver_ = f; return sharedFromThis(); }
    const ValueSaver::Ptr valueSaver() const { return valueSaver_; }
private:
    virtual ParsedValue operator()(Cursor&);
    virtual ParsedValue operator()(const char *input, const char **endptr, const Location&);
};
 
// used internally to convert from one type to another via boost::lexical_cast or throw a runtime_error with a decent message.
template<typename T>
struct LexicalCast {
    static T convert(const std::string &src) {
        try {
            return boost::lexical_cast<T>(src);
        } catch (const boost::bad_lexical_cast &e) {
            throw std::runtime_error(e.what());
        }
    }
};
 
template<>
struct LexicalCast<boost::regex> {
    static boost::regex convert(const std::string &src) {
        return boost::regex(src);
    }
};
 
template<>
struct LexicalCast<std::regex> {
    static std::regex convert(const std::string &src) {
        return std::regex(src);
    }
};
 
template<>
struct LexicalCast<boost::filesystem::path> {
    static boost::filesystem::path convert(const std::string &src) {
        return boost::filesystem::path(src);
    }
};
 
template<>
struct LexicalCast<boost::any> {
    static boost::any convert(const std::string &src) {
        return src;
    }
};
 
template<typename T>
struct LexicalCast<Optional<T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
struct LexicalCast<Sawyer::Container::Set<T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
struct LexicalCast<Sawyer::Container::Map<std::string, T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
struct LexicalCast<std::vector<T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
struct LexicalCast<std::set<T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
struct LexicalCast<std::list<T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
struct LexicalCast<std::map<std::string, T> > {
    static T convert(const std::string &src) {
        return LexicalCast<T>::convert(src);
    }
};
 
template<typename T>
class AnyParser: public ValueParser {
protected:
    AnyParser() {}
 
    AnyParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<AnyParser> Ptr;
 
    static Ptr instance() { return Ptr(new AnyParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new AnyParser(valueSaver)); }
private:
    virtual ParsedValue operator()(Cursor &cursor) /*override*/ {
        if (cursor.atEnd())
            throw std::runtime_error("string expected");
        Location startLoc = cursor.location();
        std::string s = cursor.rest();
        cursor.consumeChars(s.size());
        return ParsedValue(LexicalCast<T>::convert(s), startLoc, s, valueSaver());
    }
};
 
// used internally to cast one numeric type to another and throw a range_error with a decent message.
template<typename Target, typename Source>
struct NumericCast {
    static Target convert(Source from, const std::string &parsed) {
        try {
            return boost::numeric_cast<Target>(from);
        } catch (const boost::numeric::positive_overflow&) {
            std::string bound = boost::lexical_cast<std::string>(boost::numeric::bounds<Target>::highest());
            throw std::range_error("parsed string \""+parsed+"\" is greater than "+bound);
        } catch (const boost::numeric::negative_overflow&) {
            std::string bound = boost::lexical_cast<std::string>(boost::numeric::bounds<Target>::lowest());
            throw std::range_error("parsed string \""+parsed+"\" is less than "+bound);
        } catch (const boost::numeric::bad_numeric_cast&) {
            throw std::range_error("cannot cast \""+parsed+"\" to destination type");
        }
    }
};
 
// partial specialization for Sawyer::Optional<Target>
template<typename Target, typename Source>
struct NumericCast<Optional<Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
// partial specialization for std::vector<Target>
template<typename Target, typename Source>
struct NumericCast<std::vector<Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
// partial specialization for std::list<Target>
template<typename Target, typename Source>
struct NumericCast<std::list<Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
// partial specialization for std::set<Target>
template<typename Target, typename Source>
struct NumericCast<std::set<Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
// partial specialization for Sawyer::Container::Set<Target>
template<typename Target, typename Source>
struct NumericCast<Sawyer::Container::Set<Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
// partial specialization for std::map<std::string, Target>
template<typename Target, typename Source>
struct NumericCast<std::map<std::string, Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
// partial specialization for Sawyer::Container::Map<std::string, Target>
template<typename Target, typename Source>
struct NumericCast<Sawyer::Container::Map<std::string, Target>, Source> {
    static Target convert(Source from, const std::string &parsed) {
        return NumericCast<Target, Source>::convert(from, parsed);
    }
};
 
template<typename T>
class IntegerParser: public ValueParser {
protected:
    IntegerParser() {}
 
    explicit IntegerParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<IntegerParser> Ptr;
 
    static Ptr instance() { return Ptr(new IntegerParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new IntegerParser(valueSaver)); }
private:
    virtual ParsedValue operator()(const char *input, const char **rest, const Location &loc) /*override*/ {
        errno = 0;
        boost::int64_t big = strtoll(input, (char**)rest, 0);
        if (*rest==input)
            throw std::runtime_error("integer expected");
        while (isspace(**rest)) ++*rest;
        std::string parsed(input, *rest-input);
        if (ERANGE==errno)
            throw std::range_error("integer overflow when parsing \""+parsed+"\"");
        return ParsedValue(NumericCast<T, boost::int64_t>::convert(big, parsed), loc, parsed, valueSaver());
    }
};
 
template<typename T>
class NonNegativeIntegerParser: public ValueParser {
protected:
    NonNegativeIntegerParser() {}
 
    NonNegativeIntegerParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<NonNegativeIntegerParser> Ptr;
 
    static Ptr instance() { return Ptr(new NonNegativeIntegerParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new NonNegativeIntegerParser(valueSaver)); }
private:
    virtual ParsedValue operator()(const char *input, const char **rest, const Location &loc) /*override*/ {
        errno = 0;
        while (isspace(*input)) ++input;
        if ('+'!=*input && !isdigit(*input))
            throw std::runtime_error("unsigned integer expected");
        boost::uint64_t big = strtoull(input, (char**)rest, 0);
        if (*rest==input)
            throw std::runtime_error("unsigned integer expected");
        while (isspace(**rest)) ++*rest;
        std::string parsed(input, *rest-input);
        if (ERANGE==errno)
            throw std::range_error("integer overflow when parsing \""+parsed+"\"");
        return ParsedValue(NumericCast<T, boost::uint64_t>::convert(big, parsed), loc, parsed, valueSaver());
    }
};
 
template<typename T>
class PositiveIntegerParser: public ValueParser {
protected:
    PositiveIntegerParser() {}
 
    PositiveIntegerParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<PositiveIntegerParser> Ptr;
 
    static Ptr instance() { return Ptr(new PositiveIntegerParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new PositiveIntegerParser(valueSaver)); }
private:
    virtual ParsedValue operator()(const char *input, const char **rest, const Location &loc) /*override*/ {
        errno = 0;
        while (isspace(*input)) ++input;
        if ('+'!=*input && !isdigit(*input))
            throw std::runtime_error("positive integer expected");
        boost::uint64_t big = strtoull(input, (char**)rest, 0);
        if (*rest==input || big==0)
            throw std::runtime_error("positive integer expected");
        while (isspace(**rest)) ++*rest;
        std::string parsed(input, *rest-input);
        if (ERANGE==errno)
            throw std::range_error("integer overflow when parsing \""+parsed+"\"");
        return ParsedValue(NumericCast<T, boost::uint64_t>::convert(big, parsed), loc, parsed, valueSaver());
    }
};
 
template<typename T>
class RealNumberParser: public ValueParser {
protected:
    RealNumberParser() {}
 
    RealNumberParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<RealNumberParser> Ptr;
 
    static Ptr instance() { return Ptr(new RealNumberParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new RealNumberParser(valueSaver)); }
private:
    virtual ParsedValue operator()(const char *input, const char **rest, const Location &loc) /*override*/ {
        double big = strtod(input, (char**)rest);
        if (*rest==input)
            throw std::runtime_error("real number expected");
        while (isspace(**rest)) ++*rest;
        std::string parsed(input, *rest-input);
        return ParsedValue(NumericCast<T, double>::convert(big, parsed), loc, parsed, valueSaver());
    }
};
 
template<typename T>
class BooleanParser: public ValueParser {
protected:
    BooleanParser() {}
 
    BooleanParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<BooleanParser> Ptr;
 
    static Ptr instance() { return Ptr(new BooleanParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new BooleanParser(valueSaver)); }
private:
    virtual ParsedValue operator()(const char *input, const char **rest, const Location &loc) /*override*/ {
        static const char *neg[] = {"false", "off", "no", "0", "f", "n"}; // longest to shortest
        static const char *pos[] = {"true",  "yes", "on", "1", "t", "y"};
        const char *start = input;
        while (isspace(*input)) ++input;
        for (int negpos=0; negpos<2; ++negpos) {
            const char **list = 0==negpos ? neg : pos;
            size_t listsz = 0==negpos ? sizeof(neg)/sizeof(*neg) : sizeof(pos)/sizeof(*pos);
            for (size_t i=0; i<listsz; ++i) {
                if (0==my_strncasecmp(list[i], input, strlen(list[i]))) {
                    *rest = input + strlen(list[i]);
                    while (isspace(**rest)) ++*rest;
                    std::string parsed(start, *rest-start);
                    return ParsedValue(NumericCast<T, bool>::convert(0!=negpos, parsed), loc, parsed, valueSaver());
                }
            }
        }
        throw std::runtime_error("Boolean expected");
    }
 
    // Microsoft doesn't have the POSIX.1-2001 strncasecmp function
    int my_strncasecmp(const char *a, const char *b, size_t nchars) {
        ASSERT_not_null(a);
        ASSERT_not_null(b);
        for (size_t i=0; i<nchars; ++i) {
            if (!a[i] || !b[i])
                return a[i] ? 1 : (b[i] ? -1 : 0);
            char achar = (char)tolower(a[i]);
            char bchar = (char)tolower(b[i]);
            if (achar != bchar)
                return achar < bchar ? -1 : 1;
        }
        return 0;
    }
};
 
class SAWYER_EXPORT StringSetParser: public ValueParser {
#include <Sawyer/WarningsOff.h>
    std::vector<std::string> strings_;
#include <Sawyer/WarningsRestore.h>
protected:
    StringSetParser() {}
 
    StringSetParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver) {}
public:
    typedef SharedPointer<StringSetParser> Ptr;
 
    static Ptr instance() { return Ptr(new StringSetParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new StringSetParser(valueSaver)); }
 
    Ptr with(const std::string &s) { return with(&s, &s+1); }
    Ptr with(const std::vector<std::string> sv) { return with(sv.begin(), sv.end()); }
    template<class InputIterator>
    Ptr with(InputIterator begin, InputIterator end) {
        strings_.insert(strings_.end(), begin, end);
        return sharedFromThis().dynamicCast<StringSetParser>();
    }
private:
    virtual ParsedValue operator()(Cursor&) /*override*/;
};
 
template<typename T>
class EnumParser: public ValueParser {
    StringSetParser::Ptr strParser_;
    Container::Map<std::string, T> members_;
protected:
    EnumParser(): strParser_(StringSetParser::instance()) {}
 
    EnumParser(const ValueSaver::Ptr &valueSaver): ValueParser(valueSaver), strParser_(StringSetParser::instance()) {}
public:
    typedef SharedPointer<EnumParser> Ptr;
 
    static Ptr instance() { return Ptr(new EnumParser); }
 
    static Ptr instance(const ValueSaver::Ptr &valueSaver) { return Ptr(new EnumParser(valueSaver)); }
 
    Ptr with(const std::string &name, T value) {
        strParser_->with(name);
        members_.insert(name, value);
        return sharedFromThis().template dynamicCast<EnumParser>();
    }
private:
    virtual ParsedValue operator()(Cursor &cursor) /*override*/ {
        ParsedValue strVal = strParser_->match(cursor);
        return ParsedValue(members_[strVal.string()], strVal.valueLocation(), strVal.string(), valueSaver());
    }
};
 
class SAWYER_EXPORT ListParser: public ValueParser {
    typedef std::pair<ValueParser::Ptr, std::string> ParserSep;
#include <Sawyer/WarningsOff.h>
    std::vector<ParserSep> elements_;
    size_t minLength_, maxLength_;                      // limits on the number of values permitted
#include <Sawyer/WarningsRestore.h>
protected:
    ListParser(const ValueParser::Ptr &firstElmtType, const std::string &separatorRe)
        : minLength_(1), maxLength_((size_t)-1) {
        elements_.push_back(ParserSep(firstElmtType, separatorRe));
    }
public:
    typedef SharedPointer<ListParser> Ptr;
 
    typedef std::list<ParsedValue> ValueList;
 
    static Ptr instance(const ValueParser::Ptr &firstElmtType, const std::string &separatorRe="[,;:]\\s*") {
        return Ptr(new ListParser(firstElmtType, separatorRe));
    }
 
    Ptr nextMember(const ValueParser::Ptr &elmtType, const std::string &separatorRe="[,;:]\\s*") {
        elements_.push_back(ParserSep(elmtType, separatorRe));
        return sharedFromThis().dynamicCast<ListParser>();
    }
 
    Ptr limit(size_t minLength, size_t maxLength);
    Ptr limit(size_t maxLength) { return limit(std::min(minLength_, maxLength), maxLength); }
    Ptr exactly(size_t length) { return limit(length, length); }
private:
    virtual ParsedValue operator()(Cursor&) /*override*/;
};
 
template<typename T>
typename AnyParser<T>::Ptr anyParser(T &storage) {
    return AnyParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename AnyParser<T>::Ptr anyParser() {
    return AnyParser<T>::instance();
}
SAWYER_EXPORT AnyParser<std::string>::Ptr anyParser();
 
template<typename T>
typename IntegerParser<T>::Ptr integerParser(T &storage) {
    return IntegerParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename IntegerParser<T>::Ptr integerParser() {
    return IntegerParser<T>::instance();
}
SAWYER_EXPORT IntegerParser<int>::Ptr integerParser();
 
template<typename T>
typename NonNegativeIntegerParser<T>::Ptr nonNegativeIntegerParser(T &storage) {
    return NonNegativeIntegerParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename NonNegativeIntegerParser<T>::Ptr nonNegativeIntegerParser() {
    return NonNegativeIntegerParser<T>::instance();
}
SAWYER_EXPORT NonNegativeIntegerParser<unsigned>::Ptr nonNegativeIntegerParser();
 
template<typename T>
typename PositiveIntegerParser<T>::Ptr positiveIntegerParser(T &storage) {
    return PositiveIntegerParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename PositiveIntegerParser<T>::Ptr positiveIntegerParser() {
    return PositiveIntegerParser<T>::instance();
}
SAWYER_EXPORT PositiveIntegerParser<unsigned>::Ptr positiveIntegerParser();
 
template<typename T>
typename RealNumberParser<T>::Ptr realNumberParser(T &storage) {
    return RealNumberParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename RealNumberParser<T>::Ptr realNumberParser() {
    return RealNumberParser<T>::instance();
}
SAWYER_EXPORT RealNumberParser<double>::Ptr realNumberParser();
 
template<typename T>
typename BooleanParser<T>::Ptr booleanParser(T &storage) {
    return BooleanParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename BooleanParser<T>::Ptr booleanParser() {
    return BooleanParser<T>::instance();
}
SAWYER_EXPORT BooleanParser<bool>::Ptr booleanParser();
 
template<typename T>
typename EnumParser<T>::Ptr enumParser(T &storage) {
    return EnumParser<T>::instance(TypedSaver<T>::instance(storage));
}
template<typename T>
typename EnumParser<T>::Ptr enumParser(std::vector<T> &storage) {
    return EnumParser<T>::instance(TypedSaver<std::vector<T> >::instance(storage));
}
template<typename T>
typename EnumParser<T>::Ptr enumParser(Optional<T> &storage) {
    return EnumParser<T>::instance(TypedSaver<Optional<T> >::instance(storage));
}
template<typename T>
typename EnumParser<T>::Ptr enumParser(BitFlags<T> &storage) {
    return EnumParser<T>::instance(TypedSaver<BitFlags<T> >::instance(storage));
}
template<typename T>
typename EnumParser<T>::Ptr enumParser() {
    return EnumParser<T>::instance();
}
 
SAWYER_EXPORT StringSetParser::Ptr stringSetParser(std::string &storage);
SAWYER_EXPORT StringSetParser::Ptr stringSetParser();
 
SAWYER_EXPORT ListParser::Ptr listParser(const ValueParser::Ptr&, const std::string &sepRe="[,;:]\\s*");
//                                      Switch argument descriptors
 
class SAWYER_EXPORT SwitchArgument {
#include <Sawyer/WarningsOff.h>
    std::string name_;                                  // argument name for synopsis
    ValueParser::Ptr parser_;                           // how to match and parse this argument
    ParsedValue defaultValue_;                          // default value if the argument is optional
#include <Sawyer/WarningsRestore.h>
public:
    explicit SwitchArgument(const std::string &name, const ValueParser::Ptr &parser = anyParser())
        : name_(name), parser_(parser) {}
 
    SwitchArgument(const std::string &name, const ValueParser::Ptr &parser, const std::string &defaultValueString)
        : name_(name), parser_(parser), defaultValue_(parser->matchString(defaultValueString)) {
        defaultValue_.valueLocation(NOWHERE);
    }
 
    bool isRequired() const {
        return defaultValue_.isEmpty();
    }
 
    bool isOptional() const {
        return !isRequired();
    }
 
    const std::string &name() const { return name_; }
 
    std::string nameAsText() const;
 
    const ParsedValue& defaultValue() const {
        return defaultValue_;
    }
 
    const std::string& defaultValueString() const {
        return defaultValue_.string();
    }
 
    const ValueParser::Ptr& parser() const { return parser_; }
};
 
 
//                                      Switch actions
 
class SAWYER_EXPORT SwitchAction: public SharedObject {
public:
    typedef SharedPointer<SwitchAction> Ptr;
    virtual ~SwitchAction() {}
 
    void run(const ParserResult &parserResult) /*final*/ { (*this)(parserResult); }
protected:
    virtual void operator()(const ParserResult&) = 0;
};
 
class SAWYER_EXPORT ShowVersion: public SwitchAction {
#include <Sawyer/WarningsOff.h>
    std::string versionString_;
#include <Sawyer/WarningsRestore.h>
protected:
    explicit ShowVersion(const std::string &versionString): versionString_(versionString) {}
public:
    typedef SharedPointer<ShowVersion> Ptr;
 
    static Ptr instance(const std::string &versionString) { return Ptr(new ShowVersion(versionString)); }
protected:
    virtual void operator()(const ParserResult&) /*overload*/;
};
 
class SAWYER_EXPORT ShowVersionAndExit: public ShowVersion {
    int exitStatus_;
protected:
    explicit ShowVersionAndExit(const std::string &versionString, int exitStatus)
        : ShowVersion(versionString), exitStatus_(exitStatus) {}
public:
    typedef SharedPointer<ShowVersionAndExit> Ptr;
 
    static Ptr instance(const std::string &versionString, int exitStatus) {
        return Ptr(new ShowVersionAndExit(versionString, exitStatus));
    }
protected:
    virtual void operator()(const ParserResult&) /*overload*/;
};
 
class SAWYER_EXPORT ShowHelp: public SwitchAction {
protected:
    ShowHelp() {}
public:
    typedef SharedPointer<ShowHelp> Ptr;
 
    static Ptr instance() { return Ptr(new ShowHelp); }
protected:
    virtual void operator()(const ParserResult&) /*override*/;
};
 
class SAWYER_EXPORT ShowHelpAndExit: public ShowHelp {
    int exitStatus_;
protected:
    ShowHelpAndExit(int exitStatus): exitStatus_(exitStatus) {}
public:
    typedef SharedPointer<ShowHelpAndExit> Ptr;
 
    static Ptr instance(int exitStatus) { return Ptr(new ShowHelpAndExit(exitStatus)); }
protected:
    virtual void operator()(const ParserResult&) /*override*/;
};
 
class SAWYER_EXPORT ConfigureDiagnostics: public SwitchAction {
#include <Sawyer/WarningsOff.h>
    std::string switchKey_;
    Message::Facilities &facilities_;
    bool exitOnHelp_;
#include <Sawyer/WarningsRestore.h>
protected:
    ConfigureDiagnostics(const std::string &switchKey, Message::Facilities &facilities, bool exitOnHelp)
        : switchKey_(switchKey), facilities_(facilities), exitOnHelp_(exitOnHelp) {}
public:
    typedef SharedPointer<ConfigureDiagnostics> Ptr;
 
    static Ptr instance(const std::string &switchKey, Message::Facilities &facilities, bool exitOnHelp=true) {
        return Ptr(new ConfigureDiagnostics(switchKey, facilities, exitOnHelp));
    }
 
    bool exitOnHelp() const { return exitOnHelp_; }
    void exitOnHelp(bool b) { exitOnHelp_=b; }
protected:
    virtual void operator()(const ParserResult&) /*override*/;
};
 
class SAWYER_EXPORT ConfigureDiagnosticsQuiet: public SwitchAction {
#include <Sawyer/WarningsOff.h>
    Message::Facilities &facilities_;
#include <Sawyer/WarningsRestore.h>
protected:
    ConfigureDiagnosticsQuiet(Message::Facilities &facilities)
        : facilities_(facilities) {
    }
 
public:
    typedef SharedPointer<ConfigureDiagnosticsQuiet> Ptr;
 
    static Ptr instance(Message::Facilities &facilities) {
        return Ptr(new ConfigureDiagnosticsQuiet(facilities));
    }
 
protected:
    virtual void operator()(const ParserResult&) /*override*/;
};
 
template<class Functor>
class UserAction: public SwitchAction {
    Functor &functor_;
protected:
    UserAction(Functor &f): functor_(f) {}
public:
    typedef SharedPointer<class UserAction> Ptr;
 
    static Ptr instance(Functor &f) { return Ptr(new UserAction(f)); }
protected:
    virtual void operator()(const ParserResult &parserResult) /*override*/ { (functor_)(parserResult); }
};
 
SAWYER_EXPORT ShowVersion::Ptr showVersion(const std::string &versionString);
SAWYER_EXPORT ShowVersionAndExit::Ptr showVersionAndExit(const std::string &versionString, int exitStatus);
 
SAWYER_EXPORT ShowHelp::Ptr showHelp();
 
SAWYER_EXPORT ShowHelpAndExit::Ptr showHelpAndExit(int exitStatus);
 
SAWYER_EXPORT ConfigureDiagnostics::Ptr configureDiagnostics(const std::string&, Message::Facilities&, bool exitOnHelp=true);
 
SAWYER_EXPORT ConfigureDiagnosticsQuiet::Ptr configureDiagnosticsQuiet(Message::Facilities&);
 
template<class Functor>
typename UserAction<Functor>::Ptr userAction(const Functor &functor) {
    return UserAction<Functor>::instance(functor);
}
//                                      Switch value agumenters
 
class SAWYER_EXPORT ValueAugmenter: public SharedObject {
public:
    typedef SharedPointer<ValueAugmenter> Ptr;
    virtual ~ValueAugmenter() {}
 
    virtual ParsedValues operator()(const ParsedValues &savedValues, const ParsedValues &newValues) = 0;
};
 
template<typename T>
class Sum: public ValueAugmenter {
protected:
    Sum() {}
public:
    typedef SharedPointer<Sum> Ptr;
 
    static Ptr instance() { return Ptr(new Sum<T>); }
 
    virtual ParsedValues operator()(const ParsedValues &savedValues, const ParsedValues &newValues) /*override*/ {
        ASSERT_forbid(newValues.empty());
        T sum = 0;
        BOOST_FOREACH (const ParsedValue &pv, savedValues)
            sum = sum + boost::any_cast<T>(pv.value());
        BOOST_FOREACH (const ParsedValue &pv, newValues)
            sum = sum + boost::any_cast<T>(pv.value());
        ParsedValue pval = newValues.front();           // so we keep the same location information
        pval.value(sum);
        ParsedValues pvals;
        pvals.push_back(pval);
        return pvals;
    }
};
 
template<typename T>
typename Sum<T>::Ptr sum() {
    return Sum<T>::instance();
}
//                                      Switch descriptors
 
// Used internally to pass around switch properties that are common among parsers, switch groups, and switches.
struct SAWYER_EXPORT ParsingProperties {
#include <Sawyer/WarningsOff.h>
    std::vector<std::string> longPrefixes;              // Prefixes for long command-line switches
    bool inheritLongPrefixes;                           // True if this also inherits longPrefixes from a higher layer
    std::vector<std::string> shortPrefixes;
    bool inheritShortPrefixes;
    std::vector<std::string> valueSeparators;           // What separates a long switch from its value.
    bool inheritValueSeparators;
    ShowGroupName showGroupName;                        // How to show group name in switch synopsis
#include <Sawyer/WarningsRestore.h>
    ParsingProperties()
        : inheritLongPrefixes(true), inheritShortPrefixes(true), inheritValueSeparators(true),
          showGroupName(SHOW_GROUP_INHERIT) {}
    ParsingProperties inherit(const ParsingProperties &base) const;
};
 
enum WhichValue {
    SAVE_NONE,                                          
    SAVE_ONE,                                           
    SAVE_LAST,                                          
    SAVE_FIRST,                                         
    SAVE_ALL,                                           
    SAVE_AUGMENTED                                      
};
 
class SAWYER_EXPORT Switch {
private:
#include <Sawyer/WarningsOff.h>
    std::vector<std::string> longNames_;                // Long name of switch, or empty string.
    std::string shortNames_;                            // Optional short names for this switch.
    std::string key_;                                   // Unique key, usually the long name or the first short name.
    ParsingProperties properties_;                      // Properties valid at multiple levels of the hierarchy.
    std::string synopsis_;                              // User-defined synopsis or empty string.
    std::string documentation_;                         // Main documentation for the switch.
    std::string documentationKey_;                      // For sorting documentation.
    bool hidden_;                                       // Whether to hide documentation.
    std::vector<SwitchArgument> arguments_;             // Arguments with optional default values.
    SwitchAction::Ptr action_;                          // Optional action to perform during ParserResult::apply.
    WhichValue whichValue_;                             // Which switch values should be saved.
    ValueAugmenter::Ptr valueAugmenter_;                // Used if <code>whichValue_==SAVE_AUGMENTED</code>.
    ParsedValue intrinsicValue_;                        // Value for switches that have no declared arguments.
    bool explosiveLists_;                               // Whether to expand ListParser::ValueList into separate values.
    SwitchSkipping skipping_;                           // Whether to skip over this switch without saving or acting.
#include <Sawyer/WarningsRestore.h>
 
public:
    explicit Switch(const std::string &longName, char shortName='\0')
        : hidden_(false), whichValue_(SAVE_LAST), intrinsicValue_(ParsedValue(true, NOWHERE, "true", ValueSaver::Ptr())),
          explosiveLists_(false), skipping_(SKIP_NEVER) {
        init(longName, shortName);
    }
 
    // FIXME[Robb Matzke 2014-03-03]: test that "--prefix=5" works when names are "pre" and "prefix" in that order
    Switch& longName(const std::string &name);
    const std::string& longName() const { return longNames_.front(); }
    const std::vector<std::string>& longNames() const { return longNames_; }
    Switch& shortName(char c) { if (c) shortNames_ += std::string(1, c); return *this; }
    const std::string& shortNames() const { return shortNames_; }
    std::string preferredName() const { return longNames_.empty() ? std::string(1, shortNames_[0]) : longNames_[0]; }
 
    Switch& key(const std::string &s) { key_ = s; return *this; }
    const std::string &key() const { return key_; }
    Switch& synopsis(const std::string &s) { synopsis_ = s; return *this; }
    std::string synopsis() const;
    Switch& doc(const std::string &s) { documentation_ = s; return *this; }
    const std::string& doc() const { return documentation_; }
    Switch& docKey(const std::string &s) { documentationKey_ = s; return *this; }
    const std::string &docKey() const { return documentationKey_; }
    Switch& hidden(bool b) { hidden_ = b; return *this; }
    bool hidden() const { return hidden_; }
    Switch& skipping(SwitchSkipping how) { skipping_ = how; return *this; }
    SwitchSkipping skipping() const { return skipping_; }
    Switch& resetLongPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                              const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Switch& longPrefix(const std::string &s1) { properties_.longPrefixes.push_back(s1); return *this; }
    const std::vector<std::string>& longPrefixes() const { return properties_.longPrefixes; }
    Switch& resetShortPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                               const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Switch& shortPrefix(const std::string &s1) { properties_.shortPrefixes.push_back(s1); return *this; }
    const std::vector<std::string>& shortPrefixes() const { return properties_.shortPrefixes; }
    Switch& resetValueSeparators(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                 const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Switch& valueSeparator(const std::string &s1) { properties_.valueSeparators.push_back(s1); return *this; }
    const std::vector<std::string>& valueSeparators() const { return properties_.valueSeparators; }
    Switch& argument(const std::string &name, const ValueParser::Ptr &parser = anyParser());
    Switch& argument(const std::string &name, const ValueParser::Ptr &parser, const std::string &defaultValue);
    Switch& argument(const SwitchArgument &arg) { arguments_.push_back(arg); return *this; }
    const SwitchArgument& argument(size_t idx) const { return arguments_[idx]; }
    const std::vector<SwitchArgument>& arguments() const { return arguments_; }
    size_t nArguments() const { return arguments_.size(); }
 
    size_t nRequiredArguments() const;
 
    template<typename T>
    Switch& intrinsicValue(const T &value, T &storage) {
        intrinsicValue_ = ParsedValue(value, NOWHERE, boost::lexical_cast<std::string>(value), TypedSaver<T>::instance(storage));
        return *this;
    }
    Switch& intrinsicValue(const char *value, std::string &storage) {
        intrinsicValue_ = ParsedValue(std::string(value), NOWHERE, value, TypedSaver<std::string>::instance(storage));
        return *this;
    }
    Switch& intrinsicValue(const std::string &text, const ValueParser::Ptr &p) {
        intrinsicValue_ = p->matchString(text);
        intrinsicValue_.valueLocation(NOWHERE);
        return *this;
    }
    Switch& intrinsicValue(const std::string &text) {
        intrinsicValue_ = anyParser()->matchString(text);
        intrinsicValue_.valueLocation(NOWHERE);
        return *this;
    }
    Switch& intrinsicValue(const ParsedValue &value) { intrinsicValue_ = value; return *this; }
    ParsedValue intrinsicValue() const { return intrinsicValue_; }
    Switch& explosiveLists(bool b) { explosiveLists_ = b; return *this; }
    bool explosiveLists() const { return explosiveLists_; }
    Switch& action(const SwitchAction::Ptr &f) { action_ = f; return *this; }
    const SwitchAction::Ptr& action() const { return action_; }
    Switch& whichValue(WhichValue s) { whichValue_ = s; return *this; }
    WhichValue whichValue() const { return whichValue_; }
    Switch& valueAugmenter(const ValueAugmenter::Ptr &f) { valueAugmenter_ = f; return *this; }
    ValueAugmenter::Ptr valueAugmenter() const { return valueAugmenter_; }
public:
    // Used internally
    const ParsingProperties& properties() const { return properties_; }
 
private:
    friend class Parser;
    friend class ParserResult;
 
    void init(const std::string &longName, char shortName);
 
    std::runtime_error noSeparator(const std::string &switchString, const Cursor&, const ParsingProperties&) const;
 
    std::runtime_error extraTextAfterSwitch(const std::string &switchString, const Location &endOfSwitch, const Cursor&,
                                            const ParsingProperties&, const ParsedValues&) const;
 
    std::runtime_error extraTextAfterArgument(const Cursor&, const ParsedValue &va) const;
 
    std::runtime_error notEnoughArguments(const std::string &switchString, const Cursor&, size_t nargs) const;
 
    std::runtime_error missingArgument(const std::string &switchString, const Cursor &cursor,
                                       const SwitchArgument &sa, const std::string &reason) const;
 
    std::runtime_error malformedArgument(const std::string &switchString, const Cursor &cursor,
                                         const SwitchArgument &sa, const std::string &reason) const;
 
    size_t matchLongName(Cursor&/*in,out*/, const ParsingProperties &props,
                         const std::string &optionalPart, const std::string &requiredPart) const;
 
    size_t matchShortName(Cursor&/*in,out*/, const ParsingProperties &props, std::string &name) const;
 
    bool explode(ParsedValues &pvals /*in,out*/) const;
 
    void matchLongArguments(const std::string &switchString, Cursor &cursor /*in,out*/, const ParsingProperties &props,
                            ParsedValues &result /*out*/) const;
 
    void matchShortArguments(const std::string &switchString, Cursor &cursor /*in,out*/, const ParsingProperties &props,
                             ParsedValues &result /*out*/, bool mayNestle) const;
 
    size_t matchArguments(const std::string &switchString, const Location &endOfSwitch, Cursor &cursor /*in,out*/,
                          const ParsingProperties &props, ParsedValues &result /*out*/, bool isLongSwitch) const;
 
    std::string synopsisForArgument(const SwitchArgument&) const;
 
    // If the synopsis is empty, create one from an optional switch group and name space separator
    std::string synopsis(const ParsingProperties &swProps, const SwitchGroup *sg, const std::string &nameSpaceSeparator) const;
};
 
//                                      Switch groups
 
 
class SAWYER_EXPORT SwitchGroup {
#include <Sawyer/WarningsOff.h>
    std::vector<Switch> switches_;
    ParsingProperties properties_;
    std::string name_;                                  // name optionally prepended to all switches
    std::string title_;                                 // title showing in documentation
    std::string docKey_;                                // for sorting
    std::string documentation_;
    SortOrder switchOrder_;
#include <Sawyer/WarningsRestore.h>
public:
    SwitchGroup(): switchOrder_(DOCKEY_ORDER) { initializeLibrary(); }
 
    explicit SwitchGroup(const std::string &title, const std::string &docKey="")
        : title_(title), docKey_(docKey), switchOrder_(DOCKEY_ORDER) {}
 
    const std::string& title() const { return title_; }
    SwitchGroup& title(const std::string &title) { title_ = title; return *this; }
    const std::string& name() const { return name_; }
    SwitchGroup& name(const std::string &name) { name_ = name; return *this; }
    const std::string& docKey() const { return docKey_; }
    SwitchGroup& docKey(const std::string &key) { docKey_ = key; return *this; }
    SwitchGroup& doc(const std::string &s) { documentation_ = s; return *this; }
    const std::string& doc() const { return documentation_; }
    ShowGroupName showingGroupNames() const { return properties_.showGroupName; }
    void showingGroupNames(ShowGroupName x) { properties_.showGroupName = x; }
    SwitchGroup& resetLongPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                   const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    SwitchGroup& longPrefix(const std::string &s1) { properties_.longPrefixes.push_back(s1); return *this; }
    const std::vector<std::string>& longPrefixes() const { return properties_.longPrefixes; }
    SwitchGroup& resetShortPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                    const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    SwitchGroup& shortPrefix(const std::string &s1) { properties_.shortPrefixes.push_back(s1); return *this; }
    const std::vector<std::string>& shortPrefixes() const { return properties_.shortPrefixes; }
    SwitchGroup& resetValueSeparators(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                      const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    SwitchGroup& valueSeparator(const std::string &s1) { properties_.valueSeparators.push_back(s1); return *this; }
    const std::vector<std::string>& valueSeparators() const { return properties_.valueSeparators; }
    size_t nSwitches() const { return switches_.size(); }
 
    const std::vector<Switch>& switches() const { return switches_; }
 
    bool nameExists(const std::string &switchName);
 
    const Switch& getByName(const std::string &switchName);
 
    bool keyExists(const std::string &switchKey);
 
    const Switch& getByKey(const std::string &switchKey);
 
    SwitchGroup& insert(const Switch&);
 
    SwitchGroup& insert(const SwitchGroup&);
 
    SwitchGroup& removeByIndex(size_t n);
 
    SwitchGroup& removeByName(const std::string &switchName);
 
    SwitchGroup& removeByKey(const std::string &switchKey);
 
    const SortOrder& switchOrder() const { return switchOrder_; }
    SwitchGroup& switchOrder(SortOrder order) { switchOrder_ = order; return *this; }
public:
    // Used internally
    const ParsingProperties& properties() const { return properties_; }
 
private:
    friend class Parser;
    bool removeByPointer(const void*);
};
 
typedef Container::Map<const SwitchGroup*, std::set<const Switch*> > GroupedSwitches;
 
typedef Container::Map<std::string, GroupedSwitches> NamedSwitches;
 
//                                      Parser
 
class SAWYER_EXPORT Parser {
#include <Sawyer/WarningsOff.h>
    std::vector<SwitchGroup> switchGroups_;             
    ParsingProperties properties_;                      
    std::string groupNameSeparator_;                    
    std::vector<std::string> terminationSwitches_;      
    bool shortMayNestle_;                               
    std::vector<std::string> inclusionPrefixes_;        
    bool skipNonSwitches_;                              
    bool skipUnknownSwitches_;                          
    mutable std::string programName_;                   
    std::string purpose_;                               
    std::string versionString_;                         
    mutable std::string dateString_;                    
    int chapterNumber_;                                 
    std::string chapterName_;                           
    typedef Container::Map<std::string, std::string> StringStringMap;
    StringStringMap sectionDoc_;                        
    StringStringMap sectionOrder_;                      
    Message::SProxy errorStream_;                       
    Optional<std::string> exitMessage_;                 
    SortOrder switchGroupOrder_;                        
    bool reportingAmbiguities_;                         
    std::string environmentVariable_;                   
#include <Sawyer/WarningsRestore.h>
 
public:
    Parser()
        : groupNameSeparator_("-"), shortMayNestle_(true), skipNonSwitches_(false), skipUnknownSwitches_(false),
          versionString_("alpha"), chapterNumber_(1), chapterName_("User Commands"), switchGroupOrder_(INSERTION_ORDER),
          reportingAmbiguities_(true) {
        init();
    }
 
    Parser& with(const SwitchGroup &sg) {
        switchGroups_.push_back(sg);
        return *this;
    }
    Parser& with(const SwitchGroup &sg, const std::string &docKey) {
        switchGroups_.push_back(sg);
        switchGroups_.back().docKey(docKey);
        return *this;
    }
    Parser& with(const std::vector<SwitchGroup> &sgs) {
        switchGroups_.insert(switchGroups_.end(), sgs.begin(), sgs.end());
        return *this;
    }
    Parser& with(const Switch &sw) {
        switchGroups_.push_back(SwitchGroup().insert(sw));
        return *this;
    }
    Parser& with(Switch sw, const std::string &docKey) {
        sw.docKey(docKey);
        switchGroups_.push_back(SwitchGroup().insert(sw));
        return *this;
    }
    const std::vector<SwitchGroup>& switchGroups() const {
        return switchGroups_;
    }
    std::vector<SwitchGroup>& switchGroups() {
        return switchGroups_;
    }
    bool switchGroupExists(const std::string &name) const;
 
    const SwitchGroup& switchGroup(const std::string &name) const;
    SwitchGroup& switchGroup(const std::string &name);
    bool eraseSwitchGroup(const std::string &name);
 
    bool reportingAmbiguities() const { return reportingAmbiguities_; }
    Parser& reportingAmbiguities(bool b) { reportingAmbiguities_ = b; return *this; }
    const std::string& groupNameSeparator() const { return groupNameSeparator_; }
    Parser& groupNameSeparator(const std::string &s) { groupNameSeparator_ = s; return *this; }
    ShowGroupName showingGroupNames() const { return properties_.showGroupName; }
    Parser& showingGroupNames(ShowGroupName x) { properties_.showGroupName = x; return *this; }
    Parser& resetLongPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                              const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Parser& longPrefix(const std::string &s1) { properties_.longPrefixes.push_back(s1); return *this; }
    const std::vector<std::string>& longPrefixes() const { return properties_.longPrefixes; }
    Parser& resetShortPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                               const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Parser& shortPrefix(const std::string &s1) { properties_.shortPrefixes.push_back(s1); return *this; }
    const std::vector<std::string>& shortPrefixes() const { return properties_.shortPrefixes; }
    Parser& resetValueSeparators(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Parser& valueSeparator(const std::string &s1) { properties_.valueSeparators.push_back(s1); return *this; }
    const std::vector<std::string>& valueSeparators() const { return properties_.valueSeparators; }
    Parser& resetTerminationSwitches(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                   const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Parser& terminationSwitch(const std::string &s1) { terminationSwitches_.push_back(s1); return *this; }
    const std::vector<std::string>& terminationSwitches() const { return terminationSwitches_; }
    Parser& shortMayNestle(bool b) { shortMayNestle_ = b; return *this; }
    bool shortMayNestle() const { return shortMayNestle_; }
    Parser& resetInclusionPrefixes(const std::string &s1=STR_NONE, const std::string &s2=STR_NONE,
                                   const std::string &s3=STR_NONE, const std::string &s4=STR_NONE);
    Parser& inclusionPrefix(const std::string &s1) { inclusionPrefixes_.push_back(s1); return *this; }
    const std::vector<std::string>& inclusionPrefixes() const { return inclusionPrefixes_; }
    Parser& skippingNonSwitches(bool b) { skipNonSwitches_ = b; return *this; }
    bool skippingNonSwitches() const { return skipNonSwitches_; }
    Parser& skippingUnknownSwitches(bool b) { skipUnknownSwitches_ = b; return *this; }
    bool skippingUnknownSwitches() const { return skipUnknownSwitches_; }
    Parser& errorStream(const Message::SProxy &stream) { errorStream_ = stream; return *this; }
    const Message::SProxy& errorStream() const { return errorStream_; }
    Parser& exitMessage(const std::string &s) { exitMessage_ = s; return *this; }
    std::string exitMessage() const { return exitMessage_ ? *exitMessage_ : std::string(); }
    Parser& environmentVariable(const std::string &s) { environmentVariable_ = s; return *this; }
    const std::string& environmentVariable() const { return environmentVariable_; }
    ParserResult parse(int argc, char *argv[]);
 
    ParserResult parse(const std::vector<std::string>&);
 
#if 0 /* [Robb Matzke 2014-03-04] */
 
    template<typename Iterator>
    ParserResult parse(Iterator begin, Iterator end) {
        std::vector<std::string> args(begin, end);
        return parse(args);
    }
#endif
 
    static std::vector<std::string> splitLineIntoWords(std::string);
 
    static std::vector<std::string> readArgsFromFile(const std::string &filename);
 
    static std::vector<std::string> readArgsFromEnvVar(const std::string &varName);
 
    std::vector<std::string> expandIncludedFiles(const std::vector<std::string> &args);
 
    enum GroupingFlags {
        DEFAULT_GROUPING        = 0,                    
        PROHIBIT_EMPTY_GROUPS   = 0x0001,               
        SPLIT_SINGLE_GROUP      = 0x0002                
    };
 
    std::vector<std::vector<std::string> >
    regroupArgs(const std::vector<std::string> &args,
                const Container::Interval<size_t> &limits = Container::Interval<size_t>::whole(),
                unsigned flags = 0 /*GroupingFlags*/);
 
    Parser& programName(const std::string& programName) { programName_ = programName; return *this; }
    const std::string& programName() const;
    Parser& purpose(const std::string &purpose) { purpose_ = purpose; return *this; }
    const std::string& purpose() const { return purpose_; }
    Parser& version(const std::string &versionString, const std::string &dateString="");
    Parser& version(const std::pair<std::string, std::string> &p) { return version(p.first, p.second); }
    std::pair<std::string, std::string> version() const;
    Parser& chapter(int chapterNumber, const std::string &chapterName="");
    Parser& chapter(const std::pair<int, std::string> &p) { return chapter(p.first, p.second); }
    std::pair<int, std::string> chapter() const;
    Parser& doc(const std::string &sectionName, const std::string &docKey, const std::string &text);
    Parser& doc(const std::string &sectionName, const std::string &text) { return doc(sectionName, sectionName, text); }
    std::vector<std::string> docSections() const;
    std::string docForSwitches() const;
    std::string docForSection(const std::string &sectionName) const;
    std::string documentationMarkup() const;
 
    std::string podDocumentation() const;
 
    std::string textDocumentation() const;
 
    void emitDocumentationToPager() const;
 
    template<class Grammar>
    void emitDocumentationToPager() const {
        Grammar grammar;
        initDocGrammar(grammar);
        grammar.title(programName(), boost::lexical_cast<std::string>(chapter().first), chapter().second);
        grammar.version(version().first, version().second);
        grammar.emit(documentationMarkup());
    }
 
    SortOrder switchGroupOrder() const { return switchGroupOrder_; }
    Parser& switchGroupOrder(SortOrder order) { switchGroupOrder_ = order; return *this; }
    void insertLongSwitchStrings(Canonical, NamedSwitches &index /*in,out*/) const;
 
    void insertShortSwitchStrings(NamedSwitches &index /*in,out*/) const;
 
    void insertSwitchStrings(Canonical, NamedSwitches &index /*in,out*/) const;
 
    static void printIndex(std::ostream&, const NamedSwitches&, const std::string &linePrefix = "");
 
    NamedSwitches findAmbiguities() const;
 
    NamedSwitches findUnresolvableAmbiguities() const;
 
    Sawyer::Optional<Switch> removeMatchingSwitch(const std::string &arg);
    Sawyer::Optional<Switch> removeMatchingSwitch(const std::vector<std::string> &args);
public:
    // Used internally
    const ParsingProperties& properties() const { return properties_; }
 
private:
    void init();
 
    // Implementation for the public parse methods.
    ParserResult parseInternal(std::vector<std::string> programArguments);
 
    // Parse one switch from the current position in the command line and return the switch descriptor.  If the cursor is at
    // the end of the command line then return false without updating the cursor or parsed values.  If the cursor is at a
    // termination switch (e.g., "--") then consume the terminator and return false.  If the switch name is valid but the
    // arguments cannot be parsed, then throw an error.  If the cursor is at what appears to be a switch but no matching switch
    // declaration can be found, then throw an error.  The cursor will not be modified when an error is thrown.
    bool parseOneSwitch(Cursor&, const NamedSwitches &ambiguities, ParserResult&/*out*/);
 
    const Switch* parseLongSwitch(Cursor&, ParsedValues&, const NamedSwitches &ambiguities, Optional<std::runtime_error>&);
 
    const Switch* parseShortSwitch(Cursor&, ParsedValues&, const NamedSwitches &ambiguities,
                                   Optional<std::runtime_error>&, bool mayNestle);
 
    // Returns true if the program argument at the cursor looks like it might be a switch.  Apparent switches are any program
    // argument that starts with a long or short prefix.
    bool apparentSwitch(const Cursor&) const;
 
    // Returns the best prefix for each switch--the one used for documentation
    void preferredSwitchPrefixes(Container::Map<std::string, std::string> &prefixMap /*out*/) const;
 
    // Construct an error message for an ambiguous switch, switchString, having an optional group name part (including the
    // separator), and the required switch name.  The switchString must be present in the ambiguities table.
    std::string ambiguityErrorMesg(const std::string &longSwitchString, const std::string &optionalPart,
                                   const std::string &longSwitchName, const NamedSwitches &ambiguities);
    std::string ambiguityErrorMesg(const std::string &shortSwitchString, const NamedSwitches &ambiguities);
 
    // Initialize a documentation parser by registering things like @s, @man, etc.  The argument is a subclass such as
    // Document::PodMarkup.
    void initDocGrammar(Document::Markup::Grammar& /*in,out*/) const;
 
    // FIXME[Robb Matzke 2014-02-21]: Some way to parse command-lines from a config file, or to merge parsed command-lines with
    // a yaml config file, etc.
};
 
class SAWYER_EXPORT ParserResult {
#include <Sawyer/WarningsOff.h>
    Parser parser_;
    Cursor cursor_;
    ParsedValues values_;
 
    // Maps a name to indexes into the values_ vector.
    typedef Container::Map<std::string, std::vector<size_t> > NameIndex;
    NameIndex keyIndex_;                                // Values per switch key
    NameIndex switchIndex_;                             // Values per switch preferred name
 
    // List of parsed values organized by their location on the command line.  The location is for the switch itself even if
    // the values are spread out across subsequent argv members. We do it this way because many of the values are defaults that
    // don't actually have an argv location.  The integers are indexes into the values_ vector. In other words, this is a
    // mapping from switch location to values_ elements for the switch's values.
    typedef Container::Map<Location, std::vector<size_t> > ArgvIndex;
    ArgvIndex argvIndex_;
 
    // Information about program arguments that the parser skipped over. Indexes into argv_.
    typedef std::vector<size_t> SkippedIndex;
    SkippedIndex skippedIndex_;
 
    // Information about terminator switches like "--". Indexes into argv_.
    SkippedIndex terminators_;
 
    Container::Map<std::string, SwitchAction::Ptr> actions_;
#include <Sawyer/WarningsRestore.h>
 
private:
    friend class Parser;
    ParserResult(const Parser &parser, const std::vector<std::string> &argv): parser_(parser), cursor_(argv) {}
 
public:
    ParserResult() {}
 
    const ParserResult& apply() const;
 
    size_t have(const std::string &switchKey) const {
        return keyIndex_.getOrDefault(switchKey).size();
    }
 
    const ParsedValue& parsed(const std::string &switchKey, size_t idx) const;
    ParsedValues parsed(const std::string &switchKey) const;
    std::vector<std::string> skippedArgs() const;
 
    std::vector<std::string> unreachedArgs() const;
 
    std::vector<std::string> unparsedArgs(bool includeTerminators=false) const;
 
    std::vector<std::string> parsedArgs() const;
 
    const std::vector<std::string>& allArgs() const { return cursor_.strings(); }
 
    const Parser& parser() const { return parser_; }
 
private:
    // Insert more parsed values.  Values should be inserted one switch's worth at a time (or fewer)
    void insertValuesForSwitch(const ParsedValues&, const Parser*, const Switch*);
    void insertOneValue(const ParsedValue&, const Switch*, bool save=true);
 
    // Indicate that we're skipping over a program argument
    void skip(const Location&);
 
    // Add a terminator
    void terminator(const Location&);
 
    Cursor& cursor() { return cursor_; }
};
 
} // namespace
} // namespace
 
#endif