[Monotone-devel] Re: [RFC] New options handling

[Timothy Brownawell]

On Sun, 2006-10-22 at 18:28 -0500, Timothy Brownawell wrote:
> Thoughts, comments? Does this sound like a good way to handle things?

Nobody's said anything, so I guess there isn't anything horribly wrong
with it. So, it's on mainline now.

> New option handling
> ===================
> 
> net.venge.monotone.experiment.options is a rewrite of our options
> handling. It gets rid of boost::program_options, and moves option
> variables out of app_state and into an 'options' class.
> 
> It does not yet have any new unit tests for option handling.
> 
> option.cc has tokenize_for_command_line() and wordwrap() functions
> that could possibly be moved to simplestring_xform.{cc,hh} .
> 
> Class overview
> --------------
> 
> concrete_option
>       This is a single option; you probably won't use it directly.
>       it has a long name, a short name, a description, and
>       'setter' and 'resetter' functors.
> 
> concrete_option_set
>       A collection of options. It has a 'reset' function that
>       calls each option's resetter functor, and a from_command_line
>       function that will call the 'setter' functor that belongs to
>       each given option.
> 
> option<T>
>       Like concrete_option, except that instead of functors it has
>       member-function-of-T pointers. It also has an 'instantiate'
>       function that takes a T* and converts it to a concrete_option.
> 
> option_set<T>
>       A set of option<T>, with an 'instantiate' function that
>       will instantiate each option<T> in it and return them as a
>       concrete_option_set.
> 
> options.{cc,hh} and options_list.hh
>       These define an "options" class, and several option_set<options>
>       static objects that represent individual options and sets of
>       options (all global options belong to the same set, and there is
>       a set for diff-related options).
> 
> 
> Usage
> -----
> 
> concrete_option_set and option_set<T> each have an operator| that
> returns the union of two sets, or the addition of an option to a set.
> They also each have an operator() that takes the same arguments as the
> appropriate concrete_option or option<T> constructor, and appends a new
> option to the set.
> 
> concrete_option_set has a get_usage_str() function that returns a usage
> string, word-wrapped to the terminal width, for all options it contains.
> It also has a reset() function that will reset all the options it
> contains. It has a pair of from_command_line() functions that will parse
> a command line and store the results into the options in the set.
> 
> Special option names:
>       --xargs/-@ takes one argument which is the name of a file to
>       parse and insert into the list of tokens.
> 
>       -- is the name of the positional option. If positional options
>       are to be accepted, the option set must include an option with
>       this name. If a '--' is seen in the input all further items are
>       treated as positional options, even if the start with - or -- .
> 
>       An option with empty names is never set. These can still be
>       useful if there is a group of options that all operate on the
>       same variable; put them in a option_set along with a nameless
>       option that has its reset function set up to reset that
>       variable. This is used by the options* files.
> 
> Exceptions:
>       from_command_line() will generate these, which are all derived
>       from option::option_error :
> 
>       option::unknown_option
>               from_command_line() encountered a given option that
>               doesn't match the name of any options it knows about.
>       option::missing_arg
>               An option that takes an argument was given without one.
>       option::extra_arg
>               An option that doesn't take an argument was given one.
> 
>       option::bad_arg
>               The setter function failed (see below).
> 
>       from_command_line() will catch these if a setter function
>       throws them:
> 
>       option::bad_arg_internal
>               The given argument is invalid. When throwing this, give
>               it a reason that the argument is invalid.
>       boost::bad_lexical_cast
> 
> 
> 
> options_list.hh
> ---------------
> 
> This uses several macros to define options.
> 
> OPTSET(name)
>       Defines a named group of options.
> 
> OPTVAR(optset, type, name, default)
>       Defines a variable that belongs to a given set of options.
>       When that group is reset, the variable will be reset.
> 
> OPTION(optset, name, has_arg, option, description)
>       Defines an option. The name is in the same namespace as the
>       optset names; these names are what is given to the CMD macro.
>       'option' is a string like "long,s", which will match when
>       --long or -s is given on the command line. 'has_arg' is a
>       boolean that says whether this option expects an argument.
> 
> OPT(...), GOPT(...)
>       Convenience macros defined at the top of options_list.hh, for
>       either command-specific or global options that want a variable
>       of the same name as the option.
> 
> 
> Currently, the setter function for each option is also in this file.
> These really should be split into a separate file so that changing one
> doesn't mean recompiling the world.

-- 
Timothy

Free (experimental) public monotone hosting: http://mtn-host.prjek.net