commit 196f6c0b5bcd9599150fa58a04a17eccea5d4a3a Author: Vladimir Prus Date: Fri May 14 13:40:31 2004 +0000 Import revision 295 of the program_options library. [SVN r22823] diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..3e84d7c --- /dev/null +++ b/.gitattributes @@ -0,0 +1,96 @@ +* text=auto !eol svneol=native#text/plain +*.gitattributes text svneol=native#text/plain + +# Scriptish formats +*.bat text svneol=native#text/plain +*.bsh text svneol=native#text/x-beanshell +*.cgi text svneol=native#text/plain +*.cmd text svneol=native#text/plain +*.js text svneol=native#text/javascript +*.php text svneol=native#text/x-php +*.pl text svneol=native#text/x-perl +*.pm text svneol=native#text/x-perl +*.py text svneol=native#text/x-python +*.sh eol=lf svneol=LF#text/x-sh +configure eol=lf svneol=LF#text/x-sh + +# Image formats +*.bmp binary svneol=unset#image/bmp +*.gif binary svneol=unset#image/gif +*.ico binary svneol=unset#image/ico +*.jpeg binary svneol=unset#image/jpeg +*.jpg binary svneol=unset#image/jpeg +*.png binary svneol=unset#image/png +*.tif binary svneol=unset#image/tiff +*.tiff binary svneol=unset#image/tiff +*.svg text svneol=native#image/svg%2Bxml + +# Data formats +*.pdf binary svneol=unset#application/pdf +*.avi binary svneol=unset#video/avi +*.doc binary svneol=unset#application/msword +*.dsp text svneol=crlf#text/plain +*.dsw text svneol=crlf#text/plain +*.eps binary svneol=unset#application/postscript +*.gz binary svneol=unset#application/gzip +*.mov binary svneol=unset#video/quicktime +*.mp3 binary svneol=unset#audio/mpeg +*.ppt binary svneol=unset#application/vnd.ms-powerpoint +*.ps binary svneol=unset#application/postscript +*.psd binary svneol=unset#application/photoshop +*.rdf binary svneol=unset#text/rdf +*.rss text svneol=unset#text/xml +*.rtf binary svneol=unset#text/rtf +*.sln text svneol=native#text/plain +*.swf binary svneol=unset#application/x-shockwave-flash +*.tgz binary svneol=unset#application/gzip +*.vcproj text svneol=native#text/xml +*.vcxproj text svneol=native#text/xml +*.vsprops text svneol=native#text/xml +*.wav binary svneol=unset#audio/wav +*.xls binary svneol=unset#application/vnd.ms-excel +*.zip binary svneol=unset#application/zip + +# Text formats +.htaccess text svneol=native#text/plain +*.bbk text svneol=native#text/xml +*.cmake text svneol=native#text/plain +*.css text svneol=native#text/css +*.dtd text svneol=native#text/xml +*.htm text svneol=native#text/html +*.html text svneol=native#text/html +*.ini text svneol=native#text/plain +*.log text svneol=native#text/plain +*.mak text svneol=native#text/plain +*.qbk text svneol=native#text/plain +*.rst text svneol=native#text/plain +*.sql text svneol=native#text/x-sql +*.txt text svneol=native#text/plain +*.xhtml text svneol=native#text/xhtml%2Bxml +*.xml text svneol=native#text/xml +*.xsd text svneol=native#text/xml +*.xsl text svneol=native#text/xml +*.xslt text svneol=native#text/xml +*.xul text svneol=native#text/xul +*.yml text svneol=native#text/plain +boost-no-inspect text svneol=native#text/plain +CHANGES text svneol=native#text/plain +COPYING text svneol=native#text/plain +INSTALL text svneol=native#text/plain +Jamfile text svneol=native#text/plain +Jamroot text svneol=native#text/plain +Jamfile.v2 text svneol=native#text/plain +Jamrules text svneol=native#text/plain +Makefile* text svneol=native#text/plain +README text svneol=native#text/plain +TODO text svneol=native#text/plain + +# Code formats +*.c text svneol=native#text/plain +*.cpp text svneol=native#text/plain +*.h text svneol=native#text/plain +*.hpp text svneol=native#text/plain +*.ipp text svneol=native#text/plain +*.tpp text svneol=native#text/plain +*.jam text svneol=native#text/plain +*.java text svneol=native#text/plain diff --git a/build/Jamfile b/build/Jamfile new file mode 100644 index 0000000..d91981a --- /dev/null +++ b/build/Jamfile @@ -0,0 +1,43 @@ + +subproject libs/program_options/build ; + +SOURCES = cmdline config_file options_description parsers variables_map + value_semantic positional_options utf8_codecvt_facet convert +; + +lib boost_program_options + : ../src/$(SOURCES).cpp + : # build requirements + [ common-names ] # magic for install and auto-link features + $(BOOST_ROOT) $(BOOST_ROOT) + : debug release # build variants + ; + +dll boost_program_options + : ../src/$(SOURCES).cpp + : # build requirements + [ common-names ] # magic for install and auto-link features + BOOST_ALL_DYN_LINK=1 # tell source we're building dll's + dynamic # build only for dynamic runtimes + $(BOOST_ROOT) $(BOOST_ROOT) + : debug release # build variants + ; + +install program_options lib + : boost_program_options boost_program_options + ; + +stage stage/lib : boost_program_options boost_program_options + : + # copy to a path rooted at BOOST_ROOT: + $(BOOST_ROOT) + # make sure the names of the libraries are correctly named: + [ common-names ] + # add this target to the "stage" and "all" psuedo-targets: + stage + all + : + debug release + ; + +# end diff --git a/build/Jamfile.v2 b/build/Jamfile.v2 new file mode 100644 index 0000000..3bf3280 --- /dev/null +++ b/build/Jamfile.v2 @@ -0,0 +1,20 @@ + +project boost/program_options + : source-location ../src + ; + +SOURCES = cmdline config_file options_description parsers variables_map + value_semantic positional_options utf8_codecvt_facet + convert + ; + +import os ; +if [ os.name ] = NT +{ + linkage = static ; +} + +lib program_options + : $(SOURCES).cpp + : $(linkage) + ; diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 0000000..4b41dc9 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,8 @@ + +import toolset ; +toolset.using doxygen ; + +boostbook program_option : program_options.xml ; + +doxygen autodoc + : [ GLOB ../../../boost/program_options : *.hpp ] ; \ No newline at end of file diff --git a/doc/acknowledgements.xml b/doc/acknowledgements.xml new file mode 100644 index 0000000..f6cfabd --- /dev/null +++ b/doc/acknowledgements.xml @@ -0,0 +1,81 @@ + + + %entities; +]> +
+ Acknowledgements + + I'm very gratefull to all the people who helped with the development, + by discussion, fixes, and as users. It was pleasant + to see all that involvement, which made the library much better than it + would be otherwise. + + + In the early stages, the library was affected by discussions with + Gennadiy Rozental, William Kempf and Alexander Okhotin. + + + Hartmut Kaiser was the first person to try the library on his project + and send a number of suggestions and fixes. + + + The formal review lead to numerous comments and enhancements. Pavol + Droba helped with the option description semantic. Gennadiy Rozental has + critisized many aspects of the library which caused various simplifications. + Pavel Vozenilek did carefull review of the implementation. A number of + comments were made by: + + David Abrahams + Neal D. Becker + Misha Bergal + James Curran + Carl Daniel + Beman Dawes + Tanton Gibbs + Holger Grund + Hartmut Kaiser + Petr Kocmid + Baptiste Lepilleur + Marcelo E. Magallon + Chuck Messenger + John Torjo + Matthias Troyer + + + + Doug Gregor and Reece Dunn helped to resolve the issues with Boostbook + version of the documentation. + + + Even after review, a number of people have helped with further development: + + Rob Lievaart + Thorsten Ottosen + Joseph Wu + Ferdinand Prantl + Miro Jurisic + + + + + + + + + + + + +
+ + diff --git a/doc/alternatives b/doc/alternatives new file mode 100644 index 0000000..9782e05 --- /dev/null +++ b/doc/alternatives @@ -0,0 +1,43 @@ + +CLI (part of the Jarakta project) +http://jakarta.apache.org/commons/cli/index.html + +This is Java library. +The interface seems to be similiar, except for data storage. +1. Instead of variables_map, the library can store the data +as Java system properties. +2. The class Option, which uses to describe the data, is also + used to keep the value. In contract, I keep them in separate + place. This facilitate using the same options description + for different data sources. + +TODO: Need to check that Option.setType method does. + +Werken.opt +http://sourceforge.net/projects/werken-opt/ + +This is a much simpler library then CLI, which +somewhat less features. + +JArgs +http://jargs.sourceforge.net/ + +Another Java library. Has a fixed set of value types it can +handle. + +Options (by Brad Appleton) +http://www.enteract.com/~bradapp/ftp/src/libs/C++/Options.html + +This is very lean library. It does not provide argument validation, +and the only iterface is iteration over arguments. An interesting +iterface decision is using chars to identify presense of option's parameters. +This may be moved to my library (|, :, ?, *, +) + +Cmdline (by Brad Appleton) +http://www.enteract.com/~bradapp/ftp/src/libs/C++/CmdLine.html + +This library provides options validation and storage. Unfortunately +1. Only a fixed set of data types is supported. +2. It's intrusive -- one has to declare variable of "class ArgChar" or +something, and then extract data from there. + diff --git a/doc/changes.xml b/doc/changes.xml new file mode 100644 index 0000000..cf5cfff --- /dev/null +++ b/doc/changes.xml @@ -0,0 +1,150 @@ + + + %entities; +]> +
+ Changes since formal review + + During formal review, a large number of changes was suggested. To make + using the new version easier, the implemented changes are described + below. + + Let's start with an example. The following is a typical code for the + reviewed version: + options_description desc; + desc.add_options() + ("magic", parameter<int>("value"), "magic value for the program") + .default_value("43") + + variables_map vm; + options_and_arguments oa1 = parse_command_line(ac, av, desc); + store(oa1, vm, desc) + + variables_map vm2; + ifstream ifs("main.cfg"); + options_and_arguments oa2 = parse_config_file(ifs, desc); + store(oa1, vm2, desc); + + vm.next(&vm2); + The code for the current version would look like: + + options_description desc; + desc.add_options() + ("magic", value<int>()->default_value(43), + "magic value for the program") + + variables_map vm; + + store(parse_command_line(ac, av, desc), vm); + + ifstream ifs("main.cfg"); + store(parse_command_line(ifs, desc), vm); + + notify(vm); + + + + Let's examine all the changes in detail + +
+ Option description + + + + The parameter function was renamed to + value. Rationale: "paramater" is yet another term with no + clear definition, while "value" is already used everywhere in + docs. + + + The default value is specified in different place, and should + use the value of desired type, not string. Previous code was: + + ("magic", parameter<int>("value")).default_value("43") + + and the new code is + + ("magic", parameter<int>("value")->default_value(43)); + + Rationale: the new way is less restrictive. At the same time, the + new design allows to implement other behaviour, like validation of + the value, which require knowledge of the value type. + + + + + The number of token value can take on command line, which was + specified using character suffix appended to value name, is now + specified using more explicit member calls. Moreover, it's not longer + possible to specify the "value name". + For example: +("numbers", parameter<int>("n+")) + has became +("numbers", value<int>()->multitoken()) + Rationale: such modifiers tend to make command line usage less + clear. There's no need to make evil things too easy to do. + The "value name" had only two roles: specifying modifiers, and + telling what to output in automated help. The first role has became + obsolete, and the second was questionable too. It was very unclear how + to decide on the best "value name", and eventually the selection was randon. + + + + +
+ +
+ Parsers + + + + + The options_and_argument class was removed. + + + The cmdline and config_file classes + were removed from the public interface. Various command line styles + are now declared in the command_line_style subnamespace. + + + + + New function parse_environment was added. + + + + Support for positional options was added + + + +
+ + +
+ Storage + + + + The notify function should be called after all + sources are stored in a variales_map instance. This is + done to property support priority of configuration sources. + + + +
+ + + +
+ + \ No newline at end of file diff --git a/doc/design.xml b/doc/design.xml new file mode 100644 index 0000000..3b17ab0 --- /dev/null +++ b/doc/design.xml @@ -0,0 +1,211 @@ + + + %entities; +]> +
+ Design discussion + + This section focuses on some of the design questions. + + +
+ + Unicode support + + Unicode support was one of the features specifically requested + during the formal review. For the remainder of this document we'll use + "Unicode support" as synonim for "wchar_t" support, that is assuming + that "wchar_t" always use Unicode encoding. Also, when talking about + "ascii" we'll not mean strict 7-bit ASCII encoding, but rather "char" + strings in local 8-bit encoding. + + + + Generally, "Unicode support" can mean + many things, but for the program_options library it means that: + + + + Each parser should be able to accept either char* + or wchar_t*, correctly split the input into option + names and option values and return the data. + + + + For each option, it should be possible to specify if + convertion from string to value should use ascii or unicode. + + + + The library guarantees that: + + + ascii input is passed to an ascii value without change + + + + unicode input is passed to an unicode value without change + + + ascii input passed to an unicode value, and + unicode input passed to an ascii value will be converted + using codecvt + facet (which can be specified by the user) + + + + + + + + + The important point is that it's possible to have some "ascii + options" together with "unicode options". There are two reasons for + this. First, for a given type you might not have a code to extract the + value from unicode string and it's not good to require to write such code. + Second, imagine a reusable library which has some options and exposes + options description in its interface. If all + options are either ascii or unicode, and the library does not use any + unicode strings, then the author will likely to use ascii options, which + would make the library unusable inside unicode + applications. Essentially, it would be necessary to provide two version + of the library -- ascii and unicode. + + + Another important point is that ascii strings are passed though + without modification. In other words, it's not possible to just convert + ascii to unicode and process the unicode further. The problem is that the + default conversion mechanism -- the codecvt facet -- might + not work with 8-bit input without additional setup. + + + The unicode support outlined above is not complete. For example, + it's not planned to allow unicode in option names. The reason is that + Unicode support beyond the basic one is hard and requires a Boost-wide + solution. For example, even comparing two arbitrary Unicode strings is + non-trivial. Finally, using Unicode in option names is related to + internationalization, which has it's own complexities. E.g. if option + names depend on current locale, then all program parts and other parts + which use the name must be internationaled too. + + + The primary question in implementing the Unicode support is whether + to use templates and std::basic_string or to use some + internal encoding and convert between internal and external encodings on + the interface boundaries. + + + The choice, mostly, is between code size and execution + speed. Templated solution would either link library code into every + application that uses the library (thereby making shared library + impossible), or provide explicit instantiations in the shared library + (increasing its size). The solution based on internal encoding would + necessary make conversions in a number of places and will be somewhat slower. + Since speed is generally not an issue for this library, the second + solution looks more attractive, but we'll take a closer look at + individual components. + + + For the parsers component, we have three choices: + + + Use fully templated implementation: given a string of certain + type, a parser will return &parsed_options; instance with strings of the + same type (i.e. the &parsed_options; class will be templated). + + + Use internal encoding: same as above, but strings will be + converted to/from internal encoding. + + + Use and partly expose the internal encoding: same as above, + but the strings in the &parsed_options; instance will be in the + internal encoding. This might avoid a conversion if + &parsed_options; instance is passed directly to other component, + but can be also dangerous/confusing for a user. + + + + + + The second solution appears to be the best -- it does not increase + the code size much and is cleaner than the third. To avoid extra + conversions, the unicode version of &parsed_options; can also store + strings in internal encoding. + + + For the options descriptions component, we don't have much + choice. Since it's not desirable to have either all options use ascii or all + of them use unicode, but rather have some ascii and some unicode options, the + interface of the &value_semantic; should works with both. The only way is + to pass additional flag telling if strings use ascii or internal encoding. + The instance of &value_semantic; can then convert into some + other encoding if needed. + + + For the storage component, the only affected function is &store;. + For unicode input, it should convert it to the internal encoding. It + should also inform the &value_semantic; class about the used encoding. + + + The final decision is what internal encoding to use. The + alternatives are: + std::wstring (using UCS-4 encoding) and + std::string (using UTF-8 encoding). The difference between + alternatives is: + + + Speed: UTF-8 is a bit slower + + + Space: UTF-8 takes less space when input is ascii + + + Code size: UTF-8 requires additional conversion code. However, + it allows to use existing parsers without converting them to + std::wstring and such conversion is likely to create a + number of new instantinations. + + + + + There's no clear leader, but the last point seems important, so UTF-8 + will be used. + + + The reason why UTF-8 allows to use existing parsers is that + searching for 7-bit ascii characters is really simple. However, there are + two subtle issues: + + + We need to assume the character literals use ascii encoding + and that input use Unicode encoding. + + + Unicode character (say '=') can be followed by 'composing + character' and the combination is not the same as just '=', so + simple search for '=' might find the wrong character. + + + + Neither of issues appear to be critical in practice, since ascii is + almost universal encoding and since composing characters on '=' (and + other characters with special meaning to the library) are not likely. + + +
+ + +
+ + \ No newline at end of file diff --git a/doc/footer.html b/doc/footer.html new file mode 100644 index 0000000..5dc75a1 --- /dev/null +++ b/doc/footer.html @@ -0,0 +1,10 @@ + +
+
+
+Generated on $date with
+ +doxygen +
+ + diff --git a/doc/glossary.dox b/doc/glossary.dox new file mode 100644 index 0000000..8a410ef --- /dev/null +++ b/doc/glossary.dox @@ -0,0 +1,19 @@ +/** @page glossary Glosary + +
+
Token
A single whitespace-separated part of + command line. In other words, an element of argv array.
+ +
Option
No definition yet. Options typically correspond to + (name, value) pair. Then can spawn several tokens.
+ +
Argument
No definition yet.
+ +
Command line element
A complete part of command line. May + be either option or argument.
+ +
Parameter
The syntantic element which specify value of the + option
+ +
+*/ \ No newline at end of file diff --git a/doc/glossary.xml b/doc/glossary.xml new file mode 100644 index 0000000..bb8a472 --- /dev/null +++ b/doc/glossary.xml @@ -0,0 +1,48 @@ + + + Glossary + + + Token + + A single whitespace-separated part of + command line. In other words, an element of argv array. + + + + + + Option + + No definition yet. Options typically correspond to + (name, value) pair. Then can spawn several tokens. + + + + + + Argument + + No definition yet. + + + + + + Command line element + + A complete part of command line. May + be either option or argument. + + + + + + Parameter + + The syntantic element which specify value of an + option. + + + + \ No newline at end of file diff --git a/doc/header.html b/doc/header.html new file mode 100644 index 0000000..9e2257a --- /dev/null +++ b/doc/header.html @@ -0,0 +1,16 @@ + + +$title + + +
+ Main   + Classes   + Namespace members   + Examples   + Recipes   + Rationale   + Related pages +
+ +
diff --git a/doc/howto.xml b/doc/howto.xml new file mode 100644 index 0000000..4950ac0 --- /dev/null +++ b/doc/howto.xml @@ -0,0 +1,100 @@ + + + %entities; +]> +
+ + Howto + + This section describes how the library can be used in specific situations. + +
+ Unicode support + + To use the library with Unicode, you'd need to: + + + Use Unicode-aware parsers for unicode input + + + Require unicode support for options which need it + + + + + Most of the parsers have unicode versions. For example, the + &parse_command_line; function has an overload which takes + wchar_t strings, instead of ordinary char. + + + Even if some of the parsers are Unicode-aware, it does not mean you + need to change definition of all the options. In fact, for many options, + like integer ones, it makes no sense. But to makes use of Unicode, you'd + need some Unicode-aware options. They are different + from ordinary option is + that they accept wstring input, and process it using wide + character streams. Creating an Unicode-aware option is easy, just use the + the wvalue function instead of the regular value. + + + When ascii parser passes data to ascii option, or unicode parser + passes data to unicode option, the data is not changed at all. So, ascii + option will see string in local 8 bit encoding, and unicode option will + see whatever string was passes as unicode input. + + + The interesting question is what happens when unicode data is passed + to ascii option, and vice versa. The library perform automatic + conversion from Unicode to local 8 bit encoding. For example, if command + line is always ascii, but you use wstring options, then the + ascii input will be converted into unicode. + + + To perform the conversion, library uses thecodecvt<wchar_t, + char> locale facet from the global locale. This means that if + you want to work with string which use local 8 bit encoding (as opposed to + 7 bit ascii subset), your application should start with: + +locale::global(locale("")); + + which would set up the conversion facet according to user's selected + locale. + + + It's wise to check the status of C++ locale support on your + implementation, though. The quick test involves three steps: + + + Go the the "test" directory and built the "test_convert" binary. + + + Set some non-ascii locale in the environemt. On Linux, one can + run, for example: +$ export LC_CTYPE=ru_RU.KOI8-R + + + + + Run the "test_convert" binary passing it as parameter + arbitrary non-ascii string in selected encoding. If you see a list + of Unicode codepoints, everything's OK. Otherwise, locale support on + your system might be broken. + + + + +
+ +
+ + diff --git a/doc/options_description.xml b/doc/options_description.xml new file mode 100644 index 0000000..321d12d --- /dev/null +++ b/doc/options_description.xml @@ -0,0 +1,193 @@ + + + %entities; +]> + +
+ Options description + + The options description layer allows to specify what options are + allowed -- and how they are should be processed. There are two + sublayers: syntactic and semantic. The syntactic layer allows the parsers + to group tokens into (name, value) pairs, where value is just vector of + string. The semantic layer is responsible for converting value of option + into more usable C++ types. + + + This separation is an important part of library design. The parsers + use only syntactic layer, which takes away some of the freddom -- actually, + freedom to use overly complex structures. For example, it's not easily + possible to parse syntax like: calc --expression=1 + 2/3 + because it's not possible to parse "1 + 2/3" without known that it's C + expression. With a little help from user the task becomes trivial, and the + syntax becomes much clear: calc --expression="1 + 2/3" + + +
Syntactic layer + + + The syntactic layer is represented by + boost::program_options::options_description. The + simplest usage is illustrated below: + + options_description desc; + desc.add_options() + ("help", "produce help message") + ; + + This declares one option named "help" and associates a description with + it. No much, but it's just a start. + + + To make an option accept a parameter, you need to pass a third + parameter to the call, the name of the value: + + options_description desc; + desc.add_options() + ("help", "produce help message") + ("verbose", "change verbosity level", "number") + ; + + Since we're talking about syntactic layer, we can't expect any + interesting logic yet. In fact, the passed value name is only used for + help message, and the value itself will represented as vector of string, + leaving all interpretation to the user. + + + The only other thing that's possible to specify is number of tokens in + the value. Consider the following example: + + ("verbose", "change verbosity level", "number?") + ("users", "list of users", "email+") + ("log", "where to send log", "logger*") + + For the first option, it's possible to specify no value at all -- it's + optional. For the second option, the option name can be followed by + several tokens, for example: + + --users jim john + + Lastly, the third option can accept value with no tokens (i.e. no value), + and value with several tokens. + + + Wondering why characters are using to specify properties? Find out + here. + +
+ +
+ Semantic layer + + The sematic layer is more interesting. As said before, it converts + values, represented as vector of strings, into C++ type that the programmer + desires. In order to do so, it's necessary to pass something smarter + than a value name. That "smarter" thing is a pointer to the + boost::program_options::value_semantic abstract + class. Most of the time, you'd be using the + boost::program_options::typed_value, created via + call to boost::program_options::value + function. + For example: + + options_description desc; + desc.add_options() + ("verbose", "change verbosity level", value<int>("number")) + ; + + Specifies that the value of the "verbose" option is of type + int. + + + The + pointer returned by the value function can be used to + specify additional information about the value, for example: + + options_description desc; + desc.add_options() + ("verbose", "change verbosity level", value<int>("number")->default_value(0)) + ; + + would cause the "verbose" option to have value of 0 when nothing else if + specified. For the complete list of methods which can be be called on the + pointer, refer to class + boost::program_options::typed_value documentation. + + +
+ +
+ Positional options + + Our definition of option as (name, value) pairs is simple and + usefull, but in one special case of command line, there's a + problem. Command line can include positional option, + which does not specify any name at all, for example: + + archiver --compression=9 /etc/passwd + + Here, there's no option name to assign to "/etc/passwd" element. + + + One solution is to ask the user to extract positional options + himself and process as he likes. However, there's a nicer approach -- + provide a method to guess names for positional options, so that the + above command line can be interpreted the same way as: + + archiver --compression=9 --input-file=/etc/passwd + + + + The &positional_options_desc; class is what allows command line + parser to guess the names. The class specifies how many positional options + are allowed, and for each allowed option, specifies the name. For example: + + positional_options_description pd; + pd.add("input-file", 1, 1); + specifies that for exactly one, first, positinal option the guessed + name will be "input-file". + + + It's possible to specify that a number of positional options will be + given the same name, or even all positional options. + + positional_options_description pd; + pd.add("output-file", 2, 2).add_optional("input-file", 0, -1); + + In the above examples, first two positional options will be associated + with name "output-file", and all others (which can be omitted), with the + name "input-file". + + +
+ +
+ Classes list + The following classes belong to this component + Classes list + + + + + Name + Description + + + + + + options_description + + Description of a number of options + + + +
+ +
+ +
\ No newline at end of file diff --git a/doc/overview.xml b/doc/overview.xml new file mode 100644 index 0000000..6c9445e --- /dev/null +++ b/doc/overview.xml @@ -0,0 +1,306 @@ + + + %entities; +]> +
+ Library overview + + In the previous section, we've seen several examples of library usage. + This section will describe overall library design: what are the primary + components and what do they do. + + + The library has thee main components: + + + The options description component, which is used to describe which options + are allowed and what to do with the values of the options. + + + + The parsers component, which uses this information to find option names + and values in input source and return them. + + + + The storage component, which provides the + interface to access the value of an option. It also converts string + representation of value that parsers return into desired C++ types. + + + + + + To be a little more concrete, the options_description + class is from options description component, the + parse_command_line function is from parsers component, and the + variables_map class is from storage component. + + We've learned how those components can be used by the + main function to parse command line and config file. Before + going into details of each component, few notes about world outside of + main + + + + For that outside world, the storage component is the most important. It + provides a class which stores all option values and that class can be + freely passed around your program to modules which need access to the + options. All the other components can be used in the place where actual + parsing is done. However, it might also make sense to make individual program + modules to describe their options and pass them to main module, which will + merge all options together. Of course, this is only important when the + number of options is large and declaring them in one place becomes + troublesome. + + + + +
+ Options description component + + The options description component has three main classes: + &option_description;, &value_semantic; and &options_description;. The + first two together describe a single option. The &option_description; + class contains the option's name, description and a pointer to &value_semantic;, + which, in turn, knows the type of option's value and can parse the value, + apply default value, and so on. The &options_description; class is a + container for instances of &option_description;. + + + For almost every library, those classes could be created in a + conventional way: e.g. you'd create new options using constructors and + then call insert method of &options_description;. However, + that's overly verbose for declaring 20 or 30 options. This concern lead + to creation of the syntax that you've already seen: + +options_description desc; +desc.add_options() + ("help", "produce help") + ("optimization", value<int>()->default_value(10), "optimization level") + ; + + + + The call to the value function creates instance of + suitable class, derived from options_semantic. Calling member + functions of that instance allows to specify additional information (this + essentially emulates named parameters for constructor). Calls to + operator() on the object returned by add_options + forward arguments to constructor of the option_description + class and add the new instance. + + + +
+ +
+ Parsers component + + The parsers component splits input sources into (name, value) pairs. + Each parser looks for possible options and consult the options + description component to find if the option is know and how the value + can be specified. In the simplest case, name is explicitly specified, + which allows to decide if such option is known. If it is known, the + &value_semantic; instance tells how the value can be specified. Common + cases are when the value is explicitly specified by the user, and when + the value cannot be specified by the user, but the presense of the + option implies some value (for example, true). So, the + parser checks that the value is specified when needed and not specified + when not needed, and returns new (name, value) pair. + + + + To invoke a parser you typically call a function, passing options + desription and command line or config_file or something else. + The results of parsing are returned as instance of the &parsed_options; + class. Typically, it's passed directly to the storage + component. However, it also can be used to add some special processing, + for example if order in which options are specified is important. + + + + There are three exceptions to the above model -- all related to tradional + usage of command line. While they require some support from the options + description component, the additional complexity is tolerable. + + + The name specified on command line can be + different from the option name -- it's common to provide "short option + name" alias to a longer name. It's also common to allow abbreviated name + to be specified on command line. + + + + Sometimes it's desirable to specify value as several + tokens. For example, an option "--email-recipient" can be followed + by several emails, each as a separate command line token. This + behaviour is supported, though it can lead to parsing ambiguities + and is not enabled by default. + + + + Command line can contain positional options -- i.e. elements + which don't have any name. The command line parser provides a + mechanism to guess names for such options, as we've seen in the + tutorial. + + + + + +
+ + +
+ Storage component + + The storage component is responsible for: + + + Storing the final values of option into speciall class and in + regular variables + + + Handling priorities between different sources. + + + + Calling user-specified 'notify' functions with the final + values of options. + + + + + Let's consider an example: + + variables_map vm; + store(parse_command_line(argc, argv, desc), vm); + store(parse_config_file("example.cfg", desc), vm); + finish(vm); + + The variables_map class is used to store the option + values. The two calls to the store function add values + found on command line and in config file. Finally the call to + notify function runs user-specified notify functions and + stores values into regular variables, if needed. + + + The priority is handled + in a simple way: the store function will not change value + of an option if it's already assigned. In this case, if command line + specifies a value for an option, that value will be preferred to the + value specified in confict file. + + + + Don't forget to call the notify function when you've + stored all parsed values. + + +
+ +
+ Annotated list of symbols + + The following table describes all the important symbols in the + library, for quick access. + + + + + + + + + + Symbol + Description + + + + + + + Options description component + + + + &options_description; + describes a number of options + + + &value; + defines the option's value + + + + Parsers component + + + + &parse_command_line; + parses command line + + + &parse_config_file; + parses config file + + + + &parse_environment; + parses environment + + + + Storage component + + + + &variables_map; + storage for option values + + + + + + + +
+ +
+ + \ No newline at end of file diff --git a/doc/post_review_plan.txt b/doc/post_review_plan.txt new file mode 100644 index 0000000..9055cff --- /dev/null +++ b/doc/post_review_plan.txt @@ -0,0 +1,182 @@ + + Program options post-review development plan. + +0. Convert all documentation to BoostBook format + +1. (done) + Simplify and clarify interface. + + It turns out that most users are interested in 'variables_map' class, so + it must be possible to use it directly, without even knowing about + 'options_and_arguments'. The proposed interface is: + + options_description desc; + .... + variables_map vm; + load_from_command_line(vm, desc, argc, argv); + +2. (done) + Better separation of syntaxic and semantic processing, as suggested by + Pavol Droba. + + The problem with current 'option_description' interface is that the + 'validator' and 'notifier' callbacks are not really usable by ordinary + users --- it's extender's interface. The current 'parameter' function uses + those callback to provide user-friendly semantic interface, but it's not + documented nor completely worked out. + + In the new interface, the second parameter of 'option_description' ctor + will have two possibilities: just a string and a pointer to a new class + 'value_descriptor'. When passed the latter, it will invoke the instance on + itself, and then delete the object. A function 'value' will be provided, + that will create value specific for a type. + + Example + ("magic", value("n", &n)->default_value(10), "magic value"). + + The 'value' function will create instances of 'typed_value_descriptor' + type, with the following methods: + - default_value + - interpreter + - validator + - notifier + + The 'option_description' class we'll have two attributes to support + semantic operation: 'generator', which will handle conversion from string + into value (including application of default value), and 'notifier'. Similiar + to the the current design, those attributes will be set by + 'value_descriptor' instances. + + Another function, "bool_switch" will create value descriptor for type bool, + with default value of false. The function is needed to avoid special-casing + 'value' function on bool type, which was considered confusing (Neal D. Becker). + +3. (done) Support for positional options. + + Positional options will be treated uniformly with ordinary ones. User will + be able to specify that, for example, third positional option is to be + interpreted as option "output-file" with the same value. + + The user interface will be simple: user will provide two instanes of + 'options_description' to functions which parse command line. For example. + + options_description desc; + desc.add_options() + ("magic", "n", "magic value") + ; + + options_description pdesc; + pdesc.add_options() + ("output-file", "n", "output file") + ("input-files*", value< vector >("n"), "files") + ; + + variables_map vm; + load_from_command_line(vm, desc, pdesc, argc, argv); + +4. (done, except for registry) + Multiple sources improvement. + + Need to implement support for registry/environment. + Also, must devise a way to handle different naming of option in + sources. Lastly, the storing of values into program variables should + become part of 'variables_map' interface. + +5. Improve documentation. + + Chuck Messenger: + "When code is given for an example program, after the code, give examples of + using the program, along with the expected output." + + Pavol Droba: + "I would prefer a few chapters explaining various components of the + library, each followed by a reference." + + Pavel Vozenilek: + > Documentation should contain list of compilers the library works on and + > also info whether MSVC 6 port is feasible or not. + > + > The non-Doxygen part of documentation can be also a bit expanded: e.g. I + > would welcome some high level overview of the algorithms and structures and + > info about expected CPU/memory consumption. + > + > Also info whether there are any internal limits (like option length) . + > + > Some examples may be bit more annotated, also contain what is expected + > output. + + Syntax highligting. + + Document "*" in option names + Automated tests for examples? + (new) Comments inside code snippets? + (new) Table of all symbols + + +6. (deferred) + Unicode support + + - unicode in argv/argc + - Unicode in config files not supported + ( + The difference between ASCII and unicode files is: + - big endian UTF16 starts with 2 bytes FE FF 9mandatory by Unicode + standard) - little endian UTF16 starts with FF FE + - UTF8 text starts with EF BB BF + + Pavel Vozenilek + ) + +7. Config file improvements + + - should have "allow_unregistered" for config_file. + - (done) bool options in config file do not work. + - "#" inside strings, in config files (Pavel Vozenilek) + +8. + Cmdline improvements + + - must be able to parse WinMain string + - support for response files + +9. Other changes. + + - (outdated) get_value -> value (Beman) + - (done) is "argv" const in std, or not? Adjust docs if not. + - variables_map::count_if, find_if (Tanton Gibbs) + - Works with exceptions disabled. + - (outdated) disallow empty name for the 'parameter' function + - check for prefixes if 'allow_guessing' is on + - check for duplicate declaration of options. + - test additional parser + - Show default values in help output + - Adaptive field width + - Mandatory options + - (new) return vector from parsers by auto_ptr, not by value? + - (new) rename value_semantic into value_description + - (new) output for positional_options_description + - (new) variables_map should throw when value not found + - (important) decide where we check that the number of passed option + tokens is less than the allowed number. In parser or later? + - (important) what if the same option has different definitions? + - (new) We lost the ability to specify options_description instance + in call to 'store'. So now we can't store just subset of options. + Is it a problem? + - (new) Improve formatting of 'arg'. + - (new) revive real and regexp examples. + - (new) even more simpler syntax for assignent to var? + + +10. Uncertain + - Function to get program name + - Order of 'description' and 'value'. + + +11. (new) Look at all "TODO" comments. + (new) Check that all methods are documented. + + +12. Deferred + + - storing value to boost::optional + - setting a flag when option is found diff --git a/doc/program_options.dox b/doc/program_options.dox new file mode 100644 index 0000000..1e1e423 --- /dev/null +++ b/doc/program_options.dox @@ -0,0 +1,162 @@ +/** @mainpage Program options documentation + + @section scope Scope + + Briefly, the library should allow program developers to obtain + program options, i.e. (name,value) pairs from the user, + via conventional methods such as command line and config file. + + Necessary facilities include: + - parse command line + - parse config files + - perform semantic validation on input, such as checking for correct + type of parameters, and storing values. + - combine all inputs together, so that all program options can + be obtained in one place. + + @section goals Goals + The fundamental goals for this library were: + - it should be more convenient to use it than parse command line by hand, + even when the number of possible options is 2, + - all popular command line styles should be supported, + - "you pay for what you use" principle is important: simple utilities + need not be forced to depend on excessive amount of code. + - it must be possible to validate option values, convert them to required + types, and store either in program variables, or in data structures + maintained by the library. + - data from command line and config file should be usable together, and + alternative program option sources (such as registry) should be + possible. + + @section design_overview Design overview + + To meet the stated goals, the library uses a layered architecture. + -# At the bottom, there are two parser classes, + boost::program_options::cmdline and + boost::program_options::config_file. + They are responsible for syntax matters only and provide simple + iterator-like interface. + -# The boost::program_options::options_and_arguments holds the result of parsing command line or + config file. It is still concerned with syntax only and holds precisely + what is found on command line. There's a couple of associated parse + functions ( + @ref parse_cmdline_func "1", + @ref parse_config_file_func "2"), + which relieve the user from the need to iterate over options + and arguments manually. + -# The class boost::program_options::options_description is a high-level + description of allowed + program options, which does not depend on concrete parser class. In + addition, it can be used to provide help message. There are parse + functions which return options_and_arguments given options_description. + -# The options_description class also has semantic responsibilities. It's + possible to specify validators for option, their default values, and the + like. There's a function boost::program_options::perform_semantic_actions, + which handles this information and returns a map of option values. + -# Finally, at the top, there boost::program_options::variables_map class. + It's possible to + store options in it, and obtain them later. Another feature is that + different variable_map instances can be linked together, so that both + command line and config file data is used. Additional option sources can + be added at this level. + + @section futher_reading Futher reading + + To get further information about the library, you might want to read + the documentation for the classes referenced above. Another possibility + is to look through the examples: + + - @ref options_description "simple usage" + - @ref variables_map "parsing with validation and assignment to program variables" + - @ref multiple_sources "using command line and config file together" + - @ref custom_syntax "customized options syntax" + - @ref real_example "real example" + - @ref custom_validator "custom validator" + - @ref multiple_modules "possible approach for multi-module programs" + - @ref cmdline "low level cmdline parsing" + + Finally, you might want the check out the @ref recipes "recipes" page. +*/ + +/** @page examples Examples + + - @ref options_description "simple usage" + - @ref variables_map "parsing with validation and assignment to program variables" + - @ref multiple_sources "using command line and config file together" + - @ref custom_syntax "customized options syntax" + - @ref real_example "real example" + - @ref custom_validator "custom validator" + - @ref multiple_modules "possible approach for multi-module programs" + - @ref cmdline "low level cmdline parsing" +*/ + +/** @page options_description Options description + + Example of quite a simple usage. Options are registered and the + command line is parsed. The user is responsible to interpreting the + option values. This also how automatic help message. + + @include options_description.cpp +*/ + +/** @page variables_map Variables map + + In this example, the parameter function is used to enable + validation of options (i.e. checking that they are of correct type). + The option values are also stored in program variables. + + @include variables_map.cpp +*/ + +/** @page multiple_sources Multiple sources + + It is possible for program options to come from different sources. + Here, the command line and a config file are used, and the values + specified in both are combined, with preferrence given to the + command line. + + @include multiple_sources.cpp +*/ + +/** @page custom_syntax Custom syntax + + Some applications use a custom syntax for the command line. In this + example, the gcc style of "-fbar"/"-f" is handled. + + @include custom_syntax.cpp +*/ + +/** @page real_example A real example + + Shows how to use custom option description class and custom formatter. + Also validates some option relationship. + + @include real.cpp +*/ + +/** @page multiple_modules Multiple modules + + Large programs are likely to have several modules which want to use + some options. One possible approach is show here. + @sa @ref recipe_multiple_modules + + @include multiple_modules.cpp +*/ + +/** @page custom_validator Custom validator + + It's possible to plug in arbitrary function for converting the string + value from the command line to the value used in your program. The + example below illustrates this. + + @include regex.cpp +*/ + +/** @page cmdline The cmdline class + + When validation or automatic help message are not needed, it's possible + to use low-level boost::program_options::cmdline class, like shown + in this example. + + @include cmdline.cpp +*/ \ No newline at end of file diff --git a/doc/program_options.ent b/doc/program_options.ent new file mode 100644 index 0000000..4d53cd8 --- /dev/null +++ b/doc/program_options.ent @@ -0,0 +1,39 @@ + +positional_options_description"> + +options_description"> + +option_description"> + +value_semantic"> + +parsed_options"> + +variables_map"> + + +value"> + +parse_command_line"> + +parse_config_file"> + +parse_environment"> + +store"> + +command_line_parser"> + diff --git a/doc/program_options.xml b/doc/program_options.xml new file mode 100644 index 0000000..9b58c5b --- /dev/null +++ b/doc/program_options.xml @@ -0,0 +1,102 @@ + + + + + + Vladimir + Prus + + + + Facilities to obtain configuration data from command line, config files + and other sources. + + + + + Boost.program_options library + +
+ Introduction + + The program_options library allows program developers to obtain + program options, i.e. (name,value) pairs from the user, + via conventional methods such as command line and config file. + + Why would you use such a library, and why it's better than parsing + your command line by trivial hand-written code? Some of the reasons are: + + + It's easier. The syntax for declaring options is simple, and + the library itself is small. Things like conversion of option values to + desired type and storing into program variables are handled + automatically. + + + + Error reporting is better. All problems with command line are + reported, while hand-written code can just misparse the input. In + addition, the usage message can be automatically generated, to + avoid falling out of sync with the real list of options. + + + Options can be read from anywhere. Sooner or later command + line will be not enough for your users, and you'd want config files + or maybe even environment variables. This can be added without no + effort on your part. + + + + + + + Now let's see some examples of the library usage in the . + + + + +
+ + + + + + + + + + + + diff --git a/doc/questions b/doc/questions new file mode 100644 index 0000000..f0f055f --- /dev/null +++ b/doc/questions @@ -0,0 +1,16 @@ + +Rename 'parameter' in option_description with something +better, e.g. 'value_specification'? + +Approximate matching for variable_map access? + +Should be able to stack validators? + +Case with variables like this + 'foo' = 10 + 'foo.bar' = 12 + should become an error + + + + diff --git a/doc/questions.dox b/doc/questions.dox new file mode 100644 index 0000000..2cd8194 --- /dev/null +++ b/doc/questions.dox @@ -0,0 +1,12 @@ +/** @page open_questions Open questions. + +
    +
  1. Shouldn't validators always use "C" locale? + +
  2. Shouldn't validator for intr check for different bases? + +
  3. Does anyone need "getop_option_description"?. + +
+ +*/ \ No newline at end of file diff --git a/doc/rationale b/doc/rationale new file mode 100644 index 0000000..b597b78 --- /dev/null +++ b/doc/rationale @@ -0,0 +1,15 @@ + +We could either implement simple chaining for variable maps, or +implement generic composition classes. The former was choosen, +mostly because of simplicity. + +There were two implementation approaches for multiple option +occurences in options_and_arguments. First is store them +separately. The advantage is that it's easy to obtain all +occurences before certain position on command line. The +disadvantage is that we cannot return a reference to +vector > in get_all_values. It was considered +that if support for position-dependent options is to be +added, then we're be mostly interested in occurences of +a single option that were before some point. That's possible +with vector > storage. \ No newline at end of file diff --git a/doc/rationale.dox b/doc/rationale.dox new file mode 100644 index 0000000..7e3582e --- /dev/null +++ b/doc/rationale.dox @@ -0,0 +1,95 @@ +/** @page rationale Rationale + + @section code_size Focus on code size + + The program options library has two important properties: + - runtime performance is not important. After all, command line processing + is done only once, and the amount of data is small. + - code size matters. Since parsing command line is utility task, users + won't be glad to have lots of code linked to every binary which has + options. + + For the above reasons, the the library is designed so that it can be easily + used as shared library, with minimum code on the side of main application. + In particular, templates are used only where necessary, for example for + validation of user-defined types. In other places, boost::function is + used to allow customization, but keep templates out of the public + interface. + + @section string_vs_enums Strings vs. enums + + In some places, the library uses strings to convey information that + could be represented by enumerations or values. For example, + the program_options::option_description class allows to add "?" to the + parameter name to specify that the parameter is optional. For another + example, while program_options::cmdline class allows to obtain the + index of option, it does not require to specify an index for each option, + and it's possible to tell options by their names. + + Such interface appears to be much more usable. If we were using + enumeration for different properties of parameter, there would be + another argument to many functions, the need to type long, possible + qualified names, and little advantage. + + That little advantage is that if you type a wrong enumeration name, + you'd get a compile error. If you type '!' instead of '?' after parameter + name, you'd get incorrect behaviour. However, such errors are deemed + rare. + + @section char_vs_string const char* vs. std::string + + Most of the interface uses const char* where std::string seems a natural + choice. The reason is that those functions are called many times: for + example to declare all options. They are typically called with string + literals, and implicit conversion to string appears to take a lot of + code space. Providing both std::string and const char* version would + considerably bloat the interface. Since passing std::string is considered + rare, only const char* versions are provided. + + @section init_syntax Initialization syntax + + The syntax used for creating options_description instance was designed to + be as easy as possible in the most common case. Consider: + @code + desc.add_options() + ("verbose", "", "verbosity level") + ("magic", "int", "magic value").notify(some_func) + ; + @endcode + Here, most common properties of options: name, presense of parameter and + description, are specified very concisely, and additional properties can + be given quite naturally, too. + + Another possibility would be: + @code + option_description d1(...), d2(...); + desc.add(d1 & d2); + @endcode + or + @code + option_description d1(...), d2(...); + desc = d1, d2; + @endcode + + The drawback is the need to explicitly create new objects and give names + to them. The latter problem can be helped if objects are created inside + expressions: + @code + desc = option_description(...), option_description(...) + @endcode + but there's still extra typing. + + @section help_handling Handling of --help + + It was suggested by Gennadiy Rozental that occurence of --help + on command line results in throwing an exception. Actually, the + "special" option must have been configurable. This was not + implemeneted, because applications might reasonable want to process + the rest of command line even of --help was seen. For example, + --verbose option can control how much help should be output, + or there may be several subcommand with different help screens. + + + + +*/ \ No newline at end of file diff --git a/doc/recipes.dox b/doc/recipes.dox new file mode 100644 index 0000000..a3cd623 --- /dev/null +++ b/doc/recipes.dox @@ -0,0 +1,91 @@ +/** @page recipes Recipes + + Here, we'll give solution for some desires which seem common. + + @section recipe_parameter_validation How to check for correct option value types and assign them? + + There's the boost::program_options::parameter function. It + returns a object, which, if passed as the second parameter + to boost::program_options::option_description constructor, + establishes correct validation routine. A simple example + is + @code + options_description desc; + desc.add_options() + ("foo", parameter("arg"), "obscure option") + ; + @endcode + + If you pass an address of int variable as the second + parameter of the parameter function, that variable will + be assigned the options's value. + + @sa @ref variables_map + + @section recipe_lazy What if I don't want to declare any options? + + I'm not sure this is good idea. In particular, mistyped options + will be silently ignored, leading to possible user surprises. + Futher, the boost::program_options::cmdline class was specially + designed to be very lightweight. + + Anyway, there's a version of the parse_command_line function + which does not take an options_description instance. Also, the + cmdline class ctor accepts an 'allow_unregistered' parameter. + In both cases, all options will be allowed, and treated as if + they have optional parameter. + + Note that with the default style, + @verbatim + --foo bar + @endverbatim + will be taken as option "foo" with value "bar", which is + probably not correct. You should disable option parameter in + the next token to avoid problems. + + @sa boost::program_options::cmdline + + @section recipe_multiple_modules I have several separate modules which must controlled by options. What am I to do? + + There are several solutions. + + @subsection sb1 Everything's global + + You can create a single instance of the options_description class + somewhere near main. All the modules will export their own + options using other options_description instances which can + be added to the main one. After that, you'd parse command line and + config files. The parsing results will be stored in one variables_map, + which will be passed to all modules, which can work with their own + options. + + @subsection sb2 Private option data + + Assume one of the modules does not like to see irrelevant options. + For example, it outputs a configuration file for other program, and + irrelevant options will confuse that program. + + It's possible to give the module only the options that it has + registered. First, the module provides an options_description instance + which is added to the global one. Second the command line is parsed + to produce an options_and_arguments instance. Lastly, the store + function is called. If passed the options_description instance previously + returned by the module, it will store only options specified in that + instance. + @sa @ref multiple_modules + + + @subsection sb3 Unique option names + + The most general solution would be to give unique names to options + for different modules. One module will declare option "module1.server", + and another would declare "module2.internal_checks". Of course, there + can be global options like "verbosity", declared by main and + used by all modules. + + This solution avoids all possible name clashes between modules. On + the other hand, longer option names can be less user-friendly. This + problem can be alleviated if module prefix is used only for less + common option, needed for fine-tuning. + +*/ \ No newline at end of file diff --git a/doc/requirements-Rozental b/doc/requirements-Rozental new file mode 100644 index 0000000..580fb9c --- /dev/null +++ b/doc/requirements-Rozental @@ -0,0 +1,209 @@ +From rogeeff@mail.com Fri Nov 16 19:57:49 2001 +Received: from imap.cs.msu.su (imap.cs.msu.su [158.250.10.15]) + by redsun.cs.msu.su (8.9.3/8.9.3) with ESMTP id TAA06515 + for ; Fri, 16 Nov 2001 19:59:43 +0300 (MSK) +Received: from n15.groups.yahoo.com (n15.groups.yahoo.com [216.115.96.65]) + by imap.cs.msu.su (8.11.6/8.11.6) with SMTP id fAGGtrd57869 + for ; Fri, 16 Nov 2001 19:55:54 +0300 (MSK) + (envelope-from sentto-1234907-17382-1005929874-ghost=cs.msu.su@returns.groups.yahoo.com) +X-eGroups-Return: sentto-1234907-17382-1005929874-ghost=cs.msu.su@returns.groups.yahoo.com +Received: from [10.1.1.222] by n15.groups.yahoo.com with NNFMP; 16 Nov 2001 16:57:42 -0000 +X-Sender: rogeeff@mail.com +X-Apparently-To: boost@yahoogroups.com +Received: (EGP: mail-8_0_0_1); 16 Nov 2001 16:57:53 -0000 +Received: (qmail 2553 invoked from network); 16 Nov 2001 16:57:53 -0000 +Received: from unknown (216.115.97.172) + by m4.grp.snv.yahoo.com with QMQP; 16 Nov 2001 16:57:53 -0000 +Received: from unknown (HELO n6.groups.yahoo.com) (216.115.96.56) + by mta2.grp.snv.yahoo.com with SMTP; 16 Nov 2001 16:57:53 -0000 +X-eGroups-Return: rogeeff@mail.com +Received: from [10.1.10.109] by n6.groups.yahoo.com with NNFMP; 16 Nov 2001 16:57:52 -0000 +To: boost@yahoogroups.com +Message-ID: <9t3gid+hdf3@eGroups.com> +In-Reply-To: +User-Agent: eGroups-EW/0.82 +X-Mailer: eGroups Message Poster +X-Originating-IP: 199.119.33.162 +From: "Gennadiy E. Rozental" +X-Yahoo-Profile: rogeeff +MIME-Version: 1.0 +Mailing-List: list boost@yahoogroups.com; contact boost-owner@yahoogroups.com +Delivered-To: mailing list boost@yahoogroups.com +Precedence: bulk +List-Unsubscribe: +Date: Fri, 16 Nov 2001 16:57:49 -0000 +Reply-To: boost@yahoogroups.com +Subject: [boost] Re: arguments parsing, wildcard matcher +Content-Transfer-Encoding: 7bit +Content-Type: text/plain; + charset=US-ASCII +Content-Length: 5662 +Status: R +X-Status: N + +--- In boost@y..., Vladimir Prus wrote: +> +> > Just a couple of classes I wrote that I wondered if anyone thought +> > any place in boost: +> > +> > arguments : simple command-line arguments and options parser: +> > +> > class arguments +> > { +> > public: +> > arguments(int argc, char* argv[]); +> > +> > bool has_option(const char* name) const; +> > bool get_option(const char* name, bool& value) const; +> +> > Any interest? Already proposed? Wasting my time? +> +> Actually, I'm already working on library with the same goals but +more +> elaborated. Moreover, it's almost finished. I planned to announce +it later, +> but have to do it now. My design goals were: +> - It should be resonable to use the library to parse as little as +2 command +> line options. +> - It must be extandable to privide any resonable handling +> - since command line is just a way to affect the program behaviour, +other +> ways to accomplish that must be provided, most notable is +configuration file +> - library should provide a way to store information from command +line and +> config file in a way allowing easy retrieval and using to change +configurable +> parameters of the program. +> +> The docs are available at: +> http://chronos.cs.msu.su/~ghost/projects/config_db/doc/index.html +> +> Let me know what you think. + +Privet, Volodya. + +Here what I am looking for to be supported by Command Line Argument +Framework directly or by means of easy extension: + +1. command line argument formats + a. - + b. - + c. - + d. -