program_options.h

Go to the documentation of this file.

//
//  Copyright (c) Benjamin Kaufmann 2004
//
//  This is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version. 
// 
//  This file is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this file; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//
//
// NOTE: ProgramOptions is inspired by Boost.Program_options
//       see: www.boost.org/libs/program_options
//
#ifndef PROGRAM_OPTIONS_PROGRAM_OPTIONS_H_INCLUDED
#define PROGRAM_OPTIONS_PROGRAM_OPTIONS_H_INCLUDED
#include "value.h"
#include "detail/refcountable.h"
#include <iosfwd>
#include <set>
#include <map>
#include <vector>
#include <stdexcept>
#include <memory>
#include <cstdio>
namespace ProgramOptions {


class Option : public detail::RefCountable {
public:
    Option( const std::string& longName, char shortName,
        const char* description, Value* value);

    ~Option();

    const std::string& name()           const  { return name_; }
    char               alias()          const  { return value_->alias(); }
    Value*             value()          const  { return value_; }
    const char*        description()    const  { return description_; }
    const char*        argName()        const  { return value_->arg(); }
    bool               assignDefault()  const;
    std::size_t        maxColumn()      const;
    DescriptionLevel   descLevel()      const  { return value_->level(); }
private:
    std::string name_;        // name (and unique key) of option
    const char* description_; // description of the option (used for --help)
    Value*      value_;       // the option's value manager
};

typedef detail::IntrusiveSharedPtr<Option> SharedOptPtr;

class OptionInitHelper;
class OptionContext;
class OptionParser;
class ParsedValues;
class ParsedOptions;
class OptionOutput;


class OptionGroup {
public:
    typedef std::vector<SharedOptPtr>  OptionList;
    typedef OptionList::const_iterator option_iterator;

    OptionGroup(const std::string& caption = "", DescriptionLevel descLevel = desc_level_default);
    ~OptionGroup();

    const std::string& caption() const { return caption_; }

    std::size_t      size()     const { return options_.size();  }
    bool             empty()    const { return options_.empty(); }
    option_iterator  begin()    const { return options_.begin(); }
    option_iterator  end()      const { return options_.end();   }
    DescriptionLevel descLevel()const { return level_; }
    

    OptionInitHelper addOptions();

    void addOption(std::auto_ptr<Option> option);

    void setDescriptionLevel(DescriptionLevel level) { level_ = level; }

    void format(OptionOutput& out, size_t maxW, DescriptionLevel level = desc_level_default) const;

    std::size_t maxColumn(DescriptionLevel level) const;
private:
    friend class OptionContext;
    std::string      caption_;
    OptionList       options_;
    DescriptionLevel level_;
};

class OptionInitHelper {
public:
    explicit OptionInitHelper(OptionGroup& owner);
    

    OptionInitHelper& operator()(const char* key,
        Value* val, const char* desc);
private:
    OptionGroup* owner_;
};


class OptionContext {
private:
    typedef std::size_t                               key_type;
    typedef std::map<std::string, key_type>           Name2Key;
    typedef std::vector<OptionGroup>                  GroupList;
    typedef Name2Key::const_iterator                  index_iterator;
    typedef std::pair<index_iterator, index_iterator> PrefixRange;
    typedef OptionGroup::OptionList                   OptionList;
public:
    typedef OptionList::const_iterator option_iterator;
    typedef PrefixRange                OptionRange;  
    
    OptionContext(const std::string& caption = "", DescriptionLevel desc_default = desc_level_default);
    ~OptionContext();

    const std::string& caption() const;
    

    OptionContext& add(const OptionGroup& group);


    OptionContext& addAlias(const std::string& aliasName, option_iterator option);


    OptionContext& add(const OptionContext& other);
    
    option_iterator begin() const { return options_.begin(); }
    option_iterator end()   const { return options_.end();   }
    
    std::size_t    size()   const { return options_.size(); }
    std::size_t    groups() const { return groups_.size(); }

    enum FindType { find_name = 1, find_prefix = 2, find_name_or_prefix = find_name|find_prefix, find_alias = 4 };
    

    option_iterator find(const char* key, FindType t = find_name) const;
    option_iterator tryFind(const char* key, FindType t = find_name) const;

    OptionRange findImpl(const char* key, FindType t, unsigned eMask = unsigned(-1)) const { return findImpl(key, t, eMask, caption()); }
    OptionRange findImpl(const char* key, FindType t, unsigned eMask, const std::string& eCtx) const;

    const OptionGroup& findGroup(const std::string& caption) const;
    const OptionGroup* tryFindGroup(const std::string& caption) const;
    

    void             setActiveDescLevel(DescriptionLevel level);
    DescriptionLevel getActiveDescLevel() const { return descLevel_; }
    
    OptionOutput& description(OptionOutput& out) const;
    
    std::string defaults(std::size_t prefixSize = 0) const;
    
    friend std::ostream& operator<<(std::ostream& os,  const OptionContext& ctx);


    bool assignDefaults(const ParsedOptions& exclude) const;
private:
    void        insertOption(size_t groupId, const SharedOptPtr& o);
    size_t      findGroupKey(const std::string& name) const;
    
    Name2Key         index_;
    OptionList       options_;
    GroupList        groups_;
    std::string      caption_;
    DescriptionLevel descLevel_;
};

class OptionParser;
class ParsedValues;

class ParsedOptions {
public:
    ParsedOptions();
    ~ParsedOptions();
    bool        empty()                        const  { return parsed_.empty(); }
    std::size_t size()                         const  { return parsed_.size(); }
    std::size_t count(const std::string& name) const  { return parsed_.count(name); }
    void        add(const std::string& name)          { parsed_.insert(name); }
    

    bool        assign(const ParsedValues& p, const ParsedOptions* exclude = 0);
private:
    std::set<std::string> parsed_;
    int assign(const Option& o, const std::string& value);
};

class ParsedValues {
public:
    typedef std::pair<SharedOptPtr, std::string> OptionAndValue;
    typedef std::vector<OptionAndValue> Values;
    typedef Values::const_iterator iterator;

    explicit ParsedValues(const OptionContext& a_ctx)
        : ctx(&a_ctx)
    {}
    const OptionContext* ctx;
    
    void add(const std::string& opt, const std::string& value);
    void add(const SharedOptPtr& opt, const std::string& value) {
        parsed_.push_back(OptionAndValue(opt, value));
    }

    iterator begin() const { return parsed_.begin(); }
    iterator end()   const { return parsed_.end(); }

    void clear() { parsed_.clear(); }
private:
    Values parsed_;
};

class ParseContext {
public:
    typedef OptionContext::FindType FindType;
    virtual ~ParseContext();
    virtual SharedOptPtr getOption(const char* name, FindType ft)                    = 0;
    virtual SharedOptPtr getOption(int posKey, const char* tok)                      = 0;
    virtual void         addValue(const SharedOptPtr& key, const std::string& value) = 0;
};

class OptionParser {
public:
    typedef OptionContext::FindType FindType;
    explicit OptionParser(ParseContext& ctx);
    virtual ~OptionParser();
    ParseContext& parse();
protected:
    ParseContext& ctx() const { return *ctx_; }
    SharedOptPtr  getOption(const char* name, FindType ft) const { return ctx_->getOption(name, ft); }
    SharedOptPtr  getOption(int posKey, const char* tok)   const { return ctx_->getOption(posKey, tok); }
    void          addOptionValue(const SharedOptPtr& key, const std::string& value) { ctx_->addValue(key, value); } 
private:
    virtual void doParse() = 0;
    ParseContext* ctx_;
};

struct DefaultFormat {
    std::size_t format(std::vector<char>&, const OptionContext&) { return 0; }
    std::size_t format(std::vector<char>& buffer, const OptionGroup& g);
    std::size_t format(std::vector<char>& buffer, const Option& o, std::size_t maxW);

    std::size_t format(std::vector<char>& buffer, const char* desc, const Value&, std::size_t maxW);
};

class OptionOutput {
public:
    OptionOutput() {}
    virtual ~OptionOutput() {}
    virtual bool printContext(const OptionContext& ctx)           = 0;
    virtual bool printGroup(const OptionGroup& group)             = 0;
    virtual bool printOption(const Option& opt, std::size_t maxW) = 0;
};

template <class Writer, class Formatter = DefaultFormat>
class OptionOutputImpl : public OptionOutput {
public:
    OptionOutputImpl(const Writer& w = Writer(), const Formatter& form = Formatter()) 
        : writer_(w)
        , formatter_(form) { }
    bool printContext(const OptionContext& ctx) {
        writer_.write(buffer_, formatter_.format(buffer_, ctx));
        return true;
    }
    bool printGroup(const OptionGroup& group) {
        writer_.write(buffer_, formatter_.format(buffer_, group));
        return true;
    }
    bool printOption(const Option& opt, std::size_t maxW) {
        writer_.write(buffer_, formatter_.format(buffer_, opt, maxW));
        writer_.write(buffer_, formatter_.format(buffer_, opt.description(), *opt.value(), maxW));
        return true;
    }
private:
    std::vector<char> buffer_;
    Writer            writer_;
    Formatter         formatter_;
};
struct OstreamWriter {
    OstreamWriter(std::ostream& os) : out(os) {}
    void write(const std::vector<char>& buf, std::size_t num);
    std::ostream& out;
private: void operator=(const OstreamWriter&);
};
struct StringWriter {
    StringWriter(std::string& str) : out(str) {}
    void write(const std::vector<char>& buf, std::size_t num);
    std::string& out;
private: void operator=(const StringWriter&);
};
struct FileWriter {
    FileWriter(FILE* f) : out(f) {}
    void write(const std::vector<char>& buf, std::size_t num);
    FILE* out;
};
typedef OptionOutputImpl<OstreamWriter> StreamOut;
typedef OptionOutputImpl<StringWriter>  StringOut;
typedef OptionOutputImpl<FileWriter>    FileOut;
// parse functions

typedef bool (*PosOption)(const std::string&, std::string&);

enum CommandLineFlags {
    command_line_allow_flag_value = 1u,
};

ParsedValues parseCommandLine(int& argc, char** argv, const OptionContext& ctx,
    bool allowUnregistered = true,
    PosOption posParser = 0, unsigned flags = 0);

ParseContext& parseCommandLine(int& argc, char** argv, ParseContext& ctx, unsigned flags = 0); 

ParsedValues parseCommandString(const std::string& cmd, const OptionContext& ctx, bool allowUnreg = false, PosOption posParser = 0, unsigned flags = command_line_allow_flag_value);
ParseContext& parseCommandString(const char* cmd, ParseContext& ctx, unsigned flags = command_line_allow_flag_value); 

ParsedValues parseCfgFile(std::istream& is, const OptionContext& o, bool allowUnregistered);

}

#endif