Created a branch from trunk

[SVN r38959]

build/Jamfile

@@ -1,49 +0,0 @@
-
-subproject libs/program_options/build ;
-
-SOURCES = cmdline config_file options_description parsers variables_map 
-          value_semantic positional_options utf8_codecvt_facet convert
-          winmain
-;
-
-lib boost_program_options
-     : ../src/$(SOURCES).cpp
-     : # build requirements
-       [ common-names ] # magic for install and auto-link features
-       <include>$(BOOST_ROOT) <sysinclude>$(BOOST_ROOT)
-       std::facet-support std::locale-support
-     : debug release  # build variants
-     ;
-
-dll boost_program_options
-     : ../src/$(SOURCES).cpp
-     : # build requirements
-       [ common-names ]  # magic for install and auto-link features
-       <define>BOOST_ALL_DYN_LINK=1  # tell source we're building dll's
-       <runtime-link>dynamic  # build only for dynamic runtimes
-       <include>$(BOOST_ROOT) <sysinclude>$(BOOST_ROOT)
-       # The following really turns on static runtime linking
-       # which leads to runtime crashes when using DLL, so
-       # seem DLL is not usable on Metrowerks 8
-       # std::facet-support std::locale-support
-     : debug release  # build variants
-     ;
-
-install program_options lib
-     : <lib>boost_program_options <dll>boost_program_options
-     ;
-
-stage stage/lib : <lib>boost_program_options <dll>boost_program_options
-    :
-        # copy to a path rooted at BOOST_ROOT:
-        <locate>$(BOOST_ROOT)
-        # make sure the names of the libraries are correctly named:
-        [ common-names ]
-        # add this target to the "stage" and "all" psuedo-targets:
-        <target>stage
-        <target>all
-    :
-        debug release
-    ;
-
-# end

build/Jamfile.v2

@@ -1,20 +1,28 @@
 
 project boost/program_options 
-    : source-location ../src 
+    :
+    source-location ../src 
     ;
 
-SOURCES = cmdline config_file options_description parsers variables_map 
-          value_semantic positional_options utf8_codecvt_facet
-          convert winmain
-      ;
-
-import os ;
-if [ os.name ] = NT
-{
-    linkage = <link>static ;
-}
-
-lib program_options
-  : $(SOURCES).cpp
-  : $(linkage)
+SOURCES =
+    cmdline config_file options_description parsers variables_map 
+    value_semantic positional_options utf8_codecvt_facet
+    convert winmain
     ;
+
+lib boost_program_options
+    :
+    $(SOURCES).cpp
+    :
+    <link>shared:<define>BOOST_PROGRAM_OPTIONS_DYN_LINK=1 # tell source we're building dll's
+    ;
+
+install dist-lib
+    :
+    boost_program_options
+    :
+    <install-type>LIB
+    <location>../../../dist/lib
+    ;
+
+explicit dist-lib ;

doc/Jamfile.v2

@@ -2,7 +2,10 @@
 import toolset ;
 toolset.using doxygen ;
 
-boostbook program_option : program_options.xml ;
+boostbook program_option 
+    : program_options.xml 
+    : <implicit-dependency>autodoc 
+    ;
 
 doxygen autodoc 
     : [ glob ../../../boost/program_options/*.hpp ] ;

doc/acknowledgements.xml

@@ -57,6 +57,10 @@
       <listitem><para>Joseph Wu</para></listitem>
       <listitem><para>Ferdinand Prantl</para></listitem>
       <listitem><para>Miro Jurisic</para></listitem>
+      <listitem><para>John Maddock</para></listitem>
+      <listitem><para>Janusz Piwowarski</para></listitem>
+      <listitem><para>Charles Brockman</para></listitem>
+      <listitem><para>Jonathan Wakely</para></listitem>
 
 
     </itemizedlist>

doc/design.xml

@@ -6,21 +6,21 @@
     %entities;
 ]>
 <section id="program_options.design">
-  <title>Design discussion</title>
+  <title>Design Discussion</title>
 
   <para>This section focuses on some of the design questions.
   </para>
 
   <section id="program_options.design.unicode">
 
-    <title>Unicode support</title>
+    <title>Unicode Support</title>
 
     <para>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 a 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.
+      during the formal review. Throughout this document "Unicode support" is
+      a synonym for "wchar_t" support, assuming that "wchar_t" always uses
+      Unicode encoding.  Also, when talking about "ascii" (in lowercase) we'll
+      not mean strict 7-bit ASCII encoding, but rather "char" strings in local
+      8-bit encoding.
     </para>
           
     <para>
@@ -29,14 +29,14 @@
 
       <itemizedlist>
         <listitem>
-          <para>Each parser should be able to accept either <code>char*</code>
+          <para>Each parser should accept either <code>char*</code>
           or <code>wchar_t*</code>, correctly split the input into option
           names and option values and return the data.
           </para>
         </listitem>
         <listitem>
-          <para>For each option, it should be possible to specify if
-          conversion from string to value should use ascii or unicode.
+          <para>For each option, it should be possible to specify whether the conversion
+            from string to value uses ascii or Unicode.
           </para>
         </listitem>
         <listitem>
@@ -47,13 +47,12 @@
                 </para>
               </listitem>
               <listitem>
-                <para>unicode input is passed to an unicode value without change</para>
+                <para>Unicode input is passed to a Unicode value without change</para>
               </listitem>
               <listitem>
-                <para>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)
+                <para>ascii input passed to a Unicode value, and Unicode input
+                  passed to an ascii value will be converted using a codecvt
+                  facet (which may be specified by the user).
                 </para>
               </listitem>                 
             </itemizedlist>
@@ -63,33 +62,33 @@
     </para>
 
     <para>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 that such code be written.
+      options" together with "Unicode options". There are two reasons for
+      this. First, for a given type you might not have the code to extract the
+      value from Unicode string and it's not good to require that such code be written.
       Second, imagine a reusable library which has some options and exposes
       options description in its interface. If <emphasis>all</emphasis>
-      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
+      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 versions
-      of the library -- ascii and unicode.
+      of the library -- ascii and Unicode.
     </para>
 
     <para>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
+      ascii to Unicode and process the Unicode further. The problem is that the
       default conversion mechanism -- the <code>codecvt</code> facet -- might
       not work with 8-bit input without additional setup.
     </para>
 
-    <para>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.
+    <para>The Unicode support outlined above is not complete. For example, we
+      don't support Unicode option names. Unicode support is hard and
+      requires a Boost-wide solution. 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
+      internationalized too.
     </para>
 
     <para>The primary question in implementing the Unicode support is whether
@@ -112,20 +111,21 @@
     <para>For the parsers component, we have three choices:
       <itemizedlist>
         <listitem>
-          <para>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).</para>            
+          <para>Use a fully templated implementation: given a string of a
+            certain type, a parser will return a &parsed_options; instance
+            with strings of the same type (i.e. the &parsed_options; class
+            will be templated).</para>
         </listitem>
         <listitem>
-          <para>Use internal encoding: same as above, but strings will be
-          converted to/from internal encoding.</para>
+          <para>Use internal encoding: same as above, but strings will be converted to and
+            from the internal encoding.</para>
         </listitem>
         <listitem>
           <para>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 components,
-            but can be also dangerous/confusing for a user.
+            but can be also dangerous or confusing for a user.
           </para>
         </listitem>
       </itemizedlist>
@@ -133,25 +133,26 @@
 
     <para>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
+    conversions, the Unicode version of &parsed_options; can also store
     strings in internal encoding.
     </para>
 
     <para>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 work with both. The only way is
+      of them use Unicode, but rather have some ascii and some Unicode options, the
+      interface of the &value_semantic; must work with both. The only way is
       to pass an additional flag telling if strings use ascii or internal encoding.
       The instance of &value_semantic; can then convert into some
       other encoding if needed.
     </para>
 
     <para>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.
+      For Unicode input, the &store; function should convert the value to the
+      internal encoding.  It should also inform the &value_semantic; class
+      about the used encoding.
     </para>
 
-    <para>The final decision is what internal encoding to use. The
+    <para>Finally, what internal encoding should we use? The
     alternatives are:
     <code>std::wstring</code> (using UCS-4 encoding) and
     <code>std::string</code> (using UTF-8 encoding). The difference between
@@ -176,8 +177,9 @@
       will be used.      
     </para>
 
-    <para>The reason why UTF-8 allows the use existing parsers is that
-      searching for 7-bit ascii characters is really simple. However, there are
+    <para>Choosing the UTF-8 encoding allows the use of existing parsers, 
+      because 7-bit ascii characters retain their values in UTF-8, 
+      so searching for 7-bit strings is simple. However, there are
       two subtle issues:
       <itemizedlist>
         <listitem>
@@ -185,15 +187,15 @@
           and that inputs use Unicode encoding.</para>
         </listitem>
         <listitem>
-          <para>Unicode character (say '=') can be followed by 'composing
+          <para>A Unicode character (say '=') can be followed by 'composing
           character' and the combination is not the same as just '=', so a
           simple search for '=' might find the wrong character.
           </para>
         </listitem>
       </itemizedlist>
       Neither of these 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.
+      almost universal encoding and since composing characters following '=' (and
+      other characters with special meaning to the library) are not likely to appear.
     </para>
                    
   </section>

doc/glossary.xml

@@ -40,7 +40,7 @@
     <glossentry>
         <glossterm>Parameter</glossterm>
         <glossdef>
-            <para>The syntantic element which specify value of an
+            <para>The syntactic element which specify value of an
                 option.
             </para>
         </glossdef>

doc/howto.xml

@@ -7,94 +7,440 @@
 ]>
 <section id="program_options.howto">
 
-  <title>Howto</title>
+  <title>How To</title>
 
-  <para>This section describes how the library can be used in specific situations.</para>
+  <para>This section describes how the library can be used in specific
+  situations.</para>
+
+<!--
+
+validators
+positional options
+options groups/hidden options
+
+-->
+  <section>
+    <title>Non-conventional Syntax</title>
+    
+    <para>Sometimes, standard command line syntaxes are not enough. For
+    example, the gcc compiler has "-frtti" and -fno-rtti" options, and this
+    syntax is not directly supported.
+    </para>
+
+    <indexterm><primary>additional parser</primary></indexterm>
+    <para>For such cases, the library allows the user to provide an
+    <firstterm>additional parser</firstterm> -- a function which will be called on each
+    command line element, before any processing by the library. If the
+    additional parser recognises the syntax, it returns the option name and
+    value, which are used directly. The above example can be handled by the
+    following code:
+    </para>
+
+    <para>
+      <programlisting>
+pair&lt;string, string&gt; reg_foo(const string&amp; s)
+{
+    if (s.find("-f") == 0) {
+        if (s.substr(2, 3) == "no-")
+            return make_pair(s.substr(5), string("false"));
+        else
+            return make_pair(s.substr(2), string("true"));
+    } else {
+        return make_pair(string(), string());
+    }
+}
+</programlisting>
+      Here's the definition of the additional parser. When parsing the command
+      line, we pass the additional parser:
+<programlisting>
+store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo)
+        .run(), vm);
+</programlisting>
+      The complete example can be found in the "example/custom_syntax.cpp"
+      file.                
+    </para>
+  </section>
 
   <section>
-    <title>Unicode support</title>
+    <title>Response Files</title>
 
-    <para>To use the library with Unicode, you'd need to:
+    <indexterm><primary>response files</primary></indexterm> 
+
+    <para>Some operating system have very low limits of the command line
+      length. The common way to work around those limitations is using
+      <firstterm>response files</firstterm>.  A response file is just a
+      configuration file which uses the same syntax as the command line. If
+      the command line specifies a name of response file to use, it's loaded
+      and parsed in addition to the command line.  The library does not
+      provide direct support for response files, so you'll need to write some
+      extra code.
+    </para>
+
+    <para>
+      First, you need to define an option for the response file:
+<programlisting>
+("response-file", value&lt;string&gt;(), 
+     "can be specified with '@name', too")
+</programlisting>
+    </para>
+
+    <para>Second, you'll need an additional parser to support the standard syntax
+    for specifying response files: "@file":
+<programlisting><![CDATA[
+pair<string, string> at_option_parser(string const&s)
+{
+    if ('@' == s[0])
+        return std::make_pair(string("response-file"), s.substr(1));
+    else
+        return pair<string, string>();
+}
+]]>
+</programlisting>
+    </para>
+
+    <para>Finally, when the "response-file" option is found, you'll have to
+    load that file and pass it to the command line parser. This part is the
+    hardest. We'll use the Boost.Tokenizer library, which works but has some
+    limitations. You might also consider Boost.StringAlgo. The code is:
+<programlisting><![CDATA[
+if (vm.count("response-file")) {
+     // Load the file and tokenize it
+     ifstream ifs(vm["response-file"].as<string>().c_str());
+     if (!ifs) {
+         cout << "Could no open the response file\n";
+         return 1;
+     }
+     // Read the whole file into a string
+     stringstream ss;
+     ss << ifs.rdbuf();
+     // Split the file content
+     char_separator<char> sep(" \n\r");
+     tokenizer<char_separator<char> > tok(ss.str(), sep);
+     vector<string> args;
+     copy(tok.begin(), tok.end(), back_inserter(args));
+     // Parse the file and store the options
+     store(command_line_parser(args).options(desc).run(), vm);     
+}
+]]>
+</programlisting>
+      The complete example can be found in the "example/response_file.cpp"
+      file.                
+    </para>
+ 
+  </section>
+
+  <section>
+    <title>Winmain Command Line</title>
+
+    <para>On the Windows operating system, GUI applications receive the
+    command line as a single string, not split into elements. For that reason,
+    the command line parser cannot be used directly. At least on some
+    compilers, it is possible to obtain
+    the split command line, but it's not clear if all compilers support the
+    same mechanism on all versions of the operating system. The
+    <code>split_winmain</code> function is a portable mechanism provided
+    by the library.</para>
+
+    <para>Here's an example of use:
+<programlisting>
+vector&lt;string&gt; args = split_winmain(lpCmdLine);
+store(command_line_parser(args).options(desc).run(), vm);
+</programlisting>      
+      The function is an overload for <code>wchar_t</code> strings, so can
+      also be used in Unicode applications.
+    </para>
+
+  </section>
+
+  <section>
+    <title>Option Groups and Hidden Options</title>
+
+    <para>Having a single instance of the &options_description; class with all
+    the program's options can be problematic:
       <itemizedlist>
         <listitem>
-          <para>Use Unicode-aware parsers for unicode input</para>
+          <para>Some options make sense only for specific source, for example,
+          configuration files.</para>
         </listitem>
         <listitem>
-          <para>Require unicode support for options which need it</para>
+          <para>The user would prefer some structure in the generated help message.</para>
+        </listitem>
+        <listitem>
+          <para>Some options shouldn't appear in the generated help message at all.</para>
         </listitem>
       </itemizedlist>
     </para>
 
-    <para>Most of the parsers have unicode versions. For example, the
+    <para>To solve the above issues, the library allows a programmer to create several
+      instances of the &options_description; class, which can be merged in
+      different combinations. The following example will define three groups of
+      options: command line specific, and two options group for specific program
+      modules, only one of which is shown in the generated help message.
+    </para>
+
+    <para>Each group is defined using standard syntax. However, you should
+      use reasonable names for each &options_description; instance:
+<programlisting><![CDATA[
+options_description general("General options");
+general.add_options()
+    ("help", "produce a help message")
+    ("help-module", value<string>(),
+        "produce a help for a given module")
+    ("version", "output the version number")
+    ;
+
+options_description gui("GUI options");
+gui.add_options()
+    ("display", value<string>(), "display to use")
+    ;
+
+options_description backend("Backend options");
+backend.add_options()
+    ("num-threads", value<int>(), "the initial number of threads")
+    ;
+]]></programlisting>
+    </para>
+
+    <para>After declaring options groups, we merge them in two
+      combinations. The first will include all options and be used for parsing. The
+      second will be used for the "--help" option.
+<programlisting>
+// Declare an options description instance which will include
+// all the options
+options_description all("Allowed options");
+all.add(general).add(gui).add(backend);
+
+// Declare an options description instance which will be shown
+// to the user
+options_description visible("Allowed options");
+visible.add(general).add(gui);
+</programlisting>
+    </para>
+
+    <para>What is left is to parse and handle the options:
+<programlisting><![CDATA[
+variables_map vm;
+store(parse_command_line(ac, av, all), vm);
+
+if (vm.count("help")) 
+{
+    cout << visible;
+    return 0;
+}
+if (vm.count("help-module")) {
+    const string& s = vm["help-module"].as<string>();
+    if (s == "gui") {
+        cout << gui;
+    } else if (s == "backend") {
+        cout << backend;
+    } else {
+        cout << "Unknown module '" 
+             << s << "' in the --help-module option\n";
+        return 1;
+    }
+    return 0;
+}
+if (vm.count("num-threads")) {
+    cout << "The 'num-threads' options was set to "
+         << vm["num-threads"].as<int>() << "\n";            
+}                           
+]]></programlisting>
+      When parsing the command line, all options are allowed. The "--help"
+      message, however, does not include the "Backend options" group -- the
+      options in that group are hidden. The user can explicitly force the
+      display of that options group by passing "--help-module backend"
+      option. The complete example can be found in the
+      "example/option_groups.cpp" file.
+    </para>
+  
+  </section>
+
+  <section>
+    <title>Custom Validators</title>
+
+    <para>By default, the conversion of option's value from string into C++
+      type is done using iostreams, which sometimes is not convenient. The
+      library allows the user to customize the conversion for specific
+      classes. In order to do so, the user should provide suitable overload of
+      the <code>validate</code> function.
+    </para>
+
+    <para>
+      Let's first define a simple class:
+<programlisting><![CDATA[
+struct magic_number {
+public:
+    magic_number(int n) : n(n) {}
+    int n;
+};
+]]></programlisting> and then overload the <code>validate</code> function:
+<programlisting><![CDATA[
+void validate(boost::any& v, 
+              const std::vector<std::string>& values,
+              magic_number* target_type, int)
+{
+    static regex r("\\d\\d\\d-(\\d\\d\\d)");
+
+    using namespace boost::program_options;
+
+    // Make sure no previous assignment to 'a' was made.
+    validators::check_first_occurrence(v);
+    // Extract the first string from 'values'. If there is more than
+    // one string, it's an error, and exception will be thrown.
+    const string& s = validators::get_single_string(values);
+
+    // Do regex match and convert the interesting part to 
+    // int.
+    smatch match;
+    if (regex_match(s, match, r)) {
+        v = any(magic_number(lexical_cast<int>(match[1])));
+    } else {
+        throw validation_error("invalid value");
+    }        
+}
+]]>        
+</programlisting>The function takes four parameters. The first is the storage
+      for the value, and in this case is either empty or contains an instance of
+      the <code>magic_number</code> class. The second is the list of strings
+      found in the next occurrence of the option. The remaining two parameters
+      are needed to workaround the lack of partial template specialization and
+      partial function template ordering on some compilers.
+    </para>
+
+    <para>The function first checks that we don't try to assign to the same
+      option twice. Then it checks that only a single string was passed
+      in. Next the string is verified with the help of the Boost.Regex
+      library. If that test is passed, the parsed value is stored into the
+      <code>v</code> variable.
+    </para>
+
+    <para>The complete example can be found in the "example/regex.cpp" file.
+    </para>
+
+
+  </section>
+
+  <section>
+    <title>Unicode Support</title>
+
+    <para>To use the library with Unicode, you'd need to:
+      <itemizedlist>
+        <listitem>
+          <para>Use Unicode-aware parsers for Unicode input</para>
+        </listitem>
+        <listitem>
+          <para>Require Unicode support for options which need it</para>
+        </listitem>
+      </itemizedlist>
+    </para>
+
+    <para>Most of the parsers have Unicode versions. For example, the
       &parse_command_line; function has an overload which takes
       <code>wchar_t</code> strings, instead of ordinary <code>char</code>.
     </para>
 
     <para>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 <emphasis>some</emphasis> Unicode-aware options. They are different
-    from ordinary option is
-    that they accept <code>wstring</code> input, and process it using wide
-    character streams. Creating an Unicode-aware option is easy, just use the
-    the <code>wvalue</code> function instead of the regular <code>value</code>.
+    like integer ones, it makes no sense. To make use of Unicode you'll need
+    <emphasis>some</emphasis> Unicode-aware options. They are different from
+    ordinary options in that they accept <code>wstring</code> input, and
+    process it using wide character streams. Creating an Unicode-aware option
+    is easy: just use the the <code>wvalue</code> function instead of the
+    regular <code>value</code>.
     </para>
 
-    <para>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.
+    <para>When an ascii parser passes data to an ascii option, or a Unicode
+      parser passes data to a Unicode option, the data are not changed at
+      all. So, the ascii option will see a string in local 8-bit encoding, and
+      the Unicode option will see whatever string was passed as the Unicode
+      input.
     </para>
 
-    <para>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 <code>wstring</code> options, then the
-      ascii input will be converted into unicode.     
+    <para>What happens when Unicode data is passed to an ascii option, and
+      vice versa? The library automatically performs the conversion from
+      Unicode to local 8-bit encoding. For example, if command line is in
+      ascii, but you use <code>wstring</code> options, then the ascii input
+      will be converted into Unicode.
     </para>
 
-    <para>To perform the conversion, library uses the<code>codecvt&lt;wchar_t,
-    char&gt;</code> 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:
+    <para>To perform the conversion, the library uses the <code>codecvt&lt;wchar_t,
+    char&gt;</code> locale facet from the global locale. If
+    you want to work with strings that use local 8-bit encoding (as opposed to
+    7-bit ascii subset), your application should start with:
       <programlisting>
 locale::global(locale(""));
       </programlisting>
-      which would set up the conversion facet according to user's selected
+      which would set up the conversion facet according to the user's selected
       locale. 
     </para>
 
-    <para>It's wise to check the status of C++ locale support on your
+    <para>It's wise to check the status of the C++ locale support on your
       implementation, though. The quick test involves three steps:
       <orderedlist>
         <listitem>
-          <para>Go the the "test" directory and built the "test_convert" binary.</para>
+          <para>Go the the "test" directory and build the "test_convert" binary.</para>
         </listitem>
         <listitem>
-          <para>Set some non-ascii locale in the environemt. On Linux, one can
+          <para>Set some non-ascii locale in the environmemt. On Linux, one can
           run, for example: <screen>
 $ export LC_CTYPE=ru_RU.KOI8-R
 </screen>
           </para>
         </listitem>
         <listitem>
-          <para>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.</para>
+          <para>Run the "test_convert" binary with any non-ascii string in the
+            selected encoding as its parameter. If you see a list of Unicode codepoints,
+            everything's OK. Otherwise, locale support on your system might be
+            broken.</para>
         </listitem>
       </orderedlist>
     </para>
 
     </section>
 
+    <section>
+      <title>Allowing Unknown Options</title>
+
+      <para>Usually, the library throws an exception on unknown option names. This 
+      behaviour can be changed. For example, only some part of your application uses 
+      <libraryname>Program_options</libraryname>, and you wish to pass unrecognized options to another part of
+      the program, or even to another application.</para>
+
+      <para>To allow unregistered options on the command line, you need to use 
+      the &basic_command_line_parser; class for parsing (not &parse_command_line;)
+      and call the <methodname alt="boost::program_options::basic_command_line_parser::allow_unregistered">allow_unregistered</methodname> 
+      method of that class:
+      <programlisting>
+parsed_options parsed = 
+    command_line_parser(argc, argv).options(desc).allow_unregistered().run();      
+      </programlisting>
+      
+      For each token that looks like an option, but does not have a known name, 
+      an instance of &basic_option; will be added to the result. 
+      The <code>string_key</code> and <code>value</code> fields of the instance will contain results 
+      of syntactic parsing of the token, the <code>unregistered</code> field will be set to <code>true</code>,
+      and the <code>original_tokens</code> field will contain the token as it appeared on the command line.
+      </para>
+
+      <para>If you want to pass the unrecognized options further, the 
+      <functionname alt="boost::program_options::collect_unrecognized">collect_unrecognized</functionname> function can be used.
+      The function will collect original tokens for all unrecognized values, and optionally, all found positional options.
+      Say, if your code handles a few options, but does not handles positional options at all, you can use the function like this:
+      <programlisting>
+vector&lt;string&gt; to_pass_further = collect_unrecognized(parsed.options, include_positional);
+      </programlisting>
+      
+      </para>     
+            
+    </section>
+
 </section>
 
 <!--
      Local Variables:
-     mode: xml
-     sgml-indent-data: t     
-     sgml-parent-document: ("program_options.xml" "section")
+     mode: nxml
+     sgml-indent-data: t
+     sgml-parent-document: ("userman.xml" "chapter")
      sgml-set-face: t
      End:
 -->

doc/index.html

@@ -1,9 +1,14 @@
 <html>
 <head>
-<meta http-equiv="refresh" content="0; URL=../../../doc/html/progmra_option.html">
+<meta http-equiv="refresh" content="0; URL=../../../doc/html/program_options.html">
 </head>
 <body>
 Automatic redirection failed, please go to
-<a href="../../../doc/html/signals.html">../../../doc/html/program_options.html</a>
+<a href="../../../doc/html/program_options.html">../../../doc/html/program_options.html</a> 
+&nbsp;<hr>
+<p>© Copyright Beman Dawes, 2001</p>
+<p>Distributed under the Boost Software License, Version 1.0. (See accompanying 
+file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy 
+at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
 </body>
 </html>

doc/options_description.xml

@@ -1,193 +0,0 @@
-<?xml version="1.0" standalone="yes"?>
-<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
-     "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"
-[
-    <!ENTITY % entities SYSTEM "program_options.ent" >
-    %entities;
-]>
-
-<section>
-  <title>Options description</title>
-
-  <para>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. 
-  </para>
-
-  <para>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: <screen>calc --expression=1 + 2/3</screen>
-    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: <screen>calc --expression="1 + 2/3"</screen>
-  </para>
-
-  <section><title>Syntactic layer</title>
-
-    <para>
-      The syntactic layer is represented by 
-      <classname>boost::program_options::options_description</classname>. The
-      simplest usage is illustrated below:
-      <programlisting>
-        options_description desc;
-        desc.add_options()
-        ("help", "produce help message")
-        ;
-      </programlisting>
-      This declares one option named "help" and associates a description with
-      it. No much, but it's just a start.
-    </para>
-    
-    <para>To make an option accept a parameter, you need to pass a third
-      parameter to the call, the name of the value:
-      <programlisting>
-        options_description desc;
-        desc.add_options()
-        ("help", "produce help message")
-        ("verbose", "change verbosity level", "number")
-        ;
-      </programlisting>
-      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.       
-    </para>
-    
-    <para>The only other thing that's possible to specify is number of tokens in
-      the value. Consider the following example:
-      <programlisting>
-        ("verbose", "change verbosity level", "number?")
-        ("users", "list of users", "email+")
-        ("log", "where to send log", "logger*")
-      </programlisting>
-      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:
-      <screen>
-        --users jim john
-      </screen>
-      Lastly, the third option can accept value with no tokens (i.e. no value),
-      and value with several tokens.    
-    </para>
-    
-    <para>Wondering why characters are using to specify properties? Find out
-    here.</para>
-
-  </section>
-
-  <section>
-    <title>Semantic layer</title>
-
-    <para>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 
-      <classname>boost::program_options::value_semantic</classname> abstract
-      class. Most of the time, you'd be using the 
-      <classname>boost::program_options::typed_value</classname>, created via
-      call to <functionname>boost::program_options::value</functionname>
-      function.
-      For example:
-      <programlisting>
-        options_description desc;
-        desc.add_options()
-        ("verbose", "change verbosity level", value&lt;int&gt;("number"))
-        ;        
-      </programlisting>
-      Specifies that the value of the "verbose" option is of type
-      <code>int</code>. 
-    </para>
-
-    <para>The
-      pointer returned by the <code>value</code> function can be used to
-      specify additional information about the value, for example:
-      <programlisting>
-        options_description desc;
-        desc.add_options()
-        ("verbose", "change verbosity level", value&lt;int&gt;("number")->default_value(0))
-        ;        
-      </programlisting>
-      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
-      <classname>boost::program_options::typed_value</classname> documentation.                  
-    </para>
-    
-  </section>
-
-  <section>
-    <title>Positional options</title>
-
-    <para>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 <firstterm>positional option</firstterm>,
-    which does not specify any name at all, for example:
-      <screen>
-        archiver --compression=9 /etc/passwd
-      </screen>
-      Here, there's no option name to assign to "/etc/passwd" element. 
-    </para>
-
-    <para>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:
-      <screen>
-        archiver --compression=9 --input-file=/etc/passwd
-      </screen>
-    </para>
-
-    <para>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:
-      <programlisting>
-        positional_options_description pd;
-        pd.add("input-file", 1, 1);</programlisting>
-      specifies that for exactly one, first, positinal option the guessed
-      name will be "input-file".
-    </para>
-
-    <para>It's possible to specify that a number of positional options will be
-    given the same name, or even all positional options. 
-      <programlisting>
-        positional_options_description pd;
-        pd.add("output-file", 2, 2).add_optional("input-file", 0, -1);
-      </programlisting>
-      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".
-    </para>
-    
-  </section>
-
-  <section>
-    <title>Classes list</title>
-    <para>The following classes belong to this component<table>
-        <title>Classes list</title>
-        <tgroup cols="2">
-
-          <thead>
-            <row>
-              <entry><para>Name</para></entry>
-              <entry><para>Description</para></entry>
-            </row>
-          </thead>
-          
-          <tbody>
-            <row>
-              <entry><para><classname
-                    alt="boost::program_options::options_description">options_description
-                  </classname></para></entry>
-              <entry><para>Description of a number of options</para></entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-    </para>
-  </section>
-
-</section>

doc/overview.xml

@@ -6,55 +6,55 @@
     %entities;
 ]>
 <section id="program_options.overview">
-  <title>Library overview</title>
+  <title>Library Overview</title>
 
-  <para>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.
+  <para>In the tutorial section, we saw several examples of library usage.
+    Here we will describe the overall library design including the primary
+    components and their function.
   </para>
 
-  <para>The library has thee main components:
+  <para>The library has three main components:
     <itemizedlist>
       <listitem>
-        <para>The options description component, which is used to describe which options
-          are allowed and what to do with the values of the options.
+        <para>The options description component, which describes the allowed options
+          and what to do with the values of the options.
         </para>
       </listitem>
       <listitem>
         <para>The parsers component, which uses this information to find option names
-          and values in input source and return them. 
+          and values in the input sources and return them. 
         </para>
       </listitem>
       <listitem>
         <para>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.
+          interface to access the value of an option. It also converts the string
+          representation of values that parsers return into desired C++ types.
         </para>
       </listitem>
     </itemizedlist>
   </para>
 
   <para>To be a little more concrete, the <code>options_description</code>
-  class is from options description component, the
-  <code>parse_command_line</code> function is from parsers component, and the
-  <code>variables_map</code> class is from storage component. </para>
+  class is from the options description component, the
+  <code>parse_command_line</code> function is from the parsers component, and the
+  <code>variables_map</code> class is from the storage component. </para>
 
-  <para>We've learned how those components can be used by the
-  <code>main</code> function to parse command line and config file. Before
-  going into details of each component, few notes about world outside of
-  <code>main</code>
+  <para>In the tutorial we've learned how those components can be used by the
+    <code>main</code> function to parse the command line and config
+    file. Before going into the details of each component, a few notes about
+    the world outside of <code>main</code>.
   </para>
 
   <para>
     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. All the other components can be used only in the place where
+    the actual parsing is the done.  However, it might also make sense for the
+    individual program modules to describe their options and pass them to the
+    main module, which will merge all options. Of course, this is only
+    important when the number of options is large and declaring them in one
+    place becomes troublesome.
   </para>
 
 <!--
@@ -66,9 +66,9 @@
         options are described, all parsers can use that description.</para>
       </listitem>
       <listitem>
-        <para>The parsers are intended to be fairly dump. They just
+        <para>The parsers are intended to be fairly dumb. They just
           split the input into (name, value) pairs, using strings to represent
-          names and values. No meaningfull processing of values is done.
+          names and values. No meaningful processing of values is done.
         </para>
       </listitem>
       <listitem>
@@ -83,21 +83,21 @@
 -->
 
   <section>
-    <title>Options description component</title>
+    <title>Options Description Component</title>
 
     <para>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
+      which, in turn, knows the type of the option's value and can parse the value,
+      apply the default value, and so on. The &options_description; class is a
       container for instances of &option_description;.
     </para>
 
     <para>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 <code>insert</code> method of &options_description;. However,
-      that's overly verbose for declaring 20 or 30 options. This concern lead
+      conventional way: that is, you'd create new options using constructors and
+      then call the <code>add</code> method of &options_description;. However,
+      that's overly verbose for declaring 20 or 30 options. This concern led
       to creation of the syntax that you've already seen:
 <programlisting>
 options_description desc;
@@ -108,65 +108,314 @@ desc.add_options()
 </programlisting>      
     </para>
 
-    <para>The call to the <code>value</code> function creates instance of
-    suitable class, derived from <code>options_semantic</code>. Calling member
-    functions of that instance allows to specify additional information (this
-    essentially emulates named parameters for constructor). Calls to
-    <code>operator()</code> on the object returned by <code>add_options</code>
-    forward arguments to constructor of the <code>option_description</code>
-    class and add the new instance.</para>
+    <para>The call to the <code>value</code> function creates an instance of
+      a class derived from the <code>value_semantic</code> class: <code>typed_value</code>.
+      That class contains the code to parse
+      values of a specific type, and contains a number of methods which can be
+      called by the user to specify additional information. (This
+      essentially emulates named parameters of the constructor.) Calls to
+      <code>operator()</code> on the object returned by <code>add_options</code>
+      forward arguments to the constructor of the <code>option_description</code>
+      class and add the new instance. 
+    </para>
 
+    <para>
+      Note that in addition to the
+      <code>value</code>, library provides the <code>bool_switch</code>
+      function, and user can write his own function which will return
+      other subclasses of <code>value_semantic</code> with 
+      different behaviour. For the remainder of this section, we'll talk only
+      about the <code>value</code> function.
+    </para>
+
+    <para>The information about an option is divided into syntactic and
+      semantic. Syntactic information includes the name of the option and the
+      number of tokens which can be used to specify the value. This
+      information is used by parsers to group tokens into (name, value) pairs,
+      where value is just a vector of strings
+      (<code>std::vector&lt;std::string&gt;</code>). The semantic layer
+      is responsible for converting the value of the option into more usable C++
+      types. 
+    </para>
+
+    <para>This separation is an important part of library design. The parsers
+      use only the syntactic layer, which takes away some of the freedom to
+      use overly complex structures. For example, it's not easy to parse
+      syntax like: <screen>calc --expression=1 + 2/3</screen> because it's not
+      possible to parse <screen>1 + 2/3</screen> without knowing that it's a C
+      expression. With a little help from the user the task becomes trivial,
+      and the syntax clear: <screen>calc --expression="1 + 2/3"</screen>
+    </para>
+
+    <section>
+      <title>Syntactic Information</title>
+      <para>The syntactic information is provided by the
+        <classname>boost::program_options::options_description</classname> class
+        and some methods of the
+        <classname>boost::program_options::value_semantic</classname> class
+        and includes:        
+        <itemizedlist>
+          <listitem>
+            <para>
+              name of the option, used to identify the option inside the
+              program,
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              description of the option, which can be presented to the user,
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              the allowed number of source tokens that comprise options's
+              value, which is used during parsing.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+
+      <para>Consider the following example:
+      <programlisting>
+options_description desc;
+desc.add_options()
+    ("help", "produce help message")
+    ("compression", value&lt;string&gt;(), "compression level")
+    ("verbose", value&lt;string&gt;()->zero_tokens(), "verbosity level")
+    ("email", value&lt;string&gt;()->multitoken(), "email to send to")
+    ;
+      </programlisting>
+      For the first parameter, we specify only the name and the
+      description. No value can be specified in the parsed source.
+      For the first option, the user must specify a value, using a single
+      token. For the third option, the user may either provide a single token
+      for the value, or no token at all. For the last option, the value can
+      span several tokens. For example, the following command line is OK:
+      <screen>
+          test --help --compression 10 --verbose --email beadle@mars beadle2@mars
+      </screen>      
+      </para>
+
+      <section>
+        <title>Description formatting</title>
+
+        <para>
+          Sometimes the description can get rather long, for example, when
+          several option's values need separate documentation. Below we
+          describe some simple formatting mechanisms you can use.
+        </para>
+
+        <para>The description string has one or more paragraphs, separated by
+        the newline character ('\n'). When an option is output, the library
+        will compute the indentation for options's description. Each of the
+        paragraph is output as a separate line with that intentation. If 
+        a paragraph does not fit on one line it is spanned over multiple
+        lines (which will have the same indentation).
+        </para>
+
+        <para>You may specify additional indent for the first specified by
+        inserting spaces at the beginning of a paragraph. For example: 
+        <programlisting>
+options.add_options()
+    ("help", "   A long help msg a long help msg a long help msg a long help
+msg a long help msg a long help msg a long help msg a long help msg ")
+    ;  
+        </programlisting>
+        will specify a four-space indent for the first line. The output will
+        look like:
+        <screen>
+  --help                    A long help msg a long
+                        help msg a long help msg
+                        a long help msg a long
+                        help msg a long help msg
+                        a long help msg a long
+                        help msg
+          
+        </screen>
+        </para>
+
+        <para>For the case where line is wrapped, you can want an additional
+        indent for wrapped text. This can be done by
+        inserting a tabulator character ('\t') at the desired position. For
+        example: 
+        <programlisting>
+options.add_options()
+      ("well_formated", "As you can see this is a very well formatted
+option description.\n"
+                        "You can do this for example:\n\n"
+                        "Values:\n"
+                        "  Value1: \tdoes this and that, bla bla bla bla
+bla bla bla bla bla bla bla bla bla bla bla\n"
+                        "  Value2: \tdoes something else, bla bla bla bla
+bla bla bla bla bla bla bla bla bla bla bla\n\n"
+                        "    This paragraph has a first line indent only,
+bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");          
+        </programlisting>
+        will produce:
+        <screen>
+  --well_formated       As you can see this is a
+                        very well formatted
+                        option description.
+                        You can do this for
+                        example:
+
+                        Values:
+                          Value1: does this and
+                                  that, bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla
+                          Value2: does something
+                                  else, bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla
+
+                            This paragraph has a
+                        first line indent only,
+                        bla bla bla bla bla bla
+                        bla bla bla bla bla bla
+                        bla bla bla
+        </screen>
+        The tab character is removed before output. Only one tabulator per
+        paragraph is allowed, otherwisee an exception of type
+        program_options::error is thrown. Finally, the tabulator is ignored if
+        it's is not on the first line of the paragraph or is on the last
+        possible position of the first line.
+        </para>
+
+      </section>
+
+    </section>
+      
+    <section>
+      <title>Semantic Information</title>
+      
+      <para>The semantic information is completely provided by the 
+        <classname>boost::program_options::value_semantic</classname> class. For
+        example:
+<programlisting>
+options_description desc;
+desc.add_options()
+    ("compression", value&lt;int&gt;()->default_value(10), "compression level")
+    ("email", value&lt; vector&lt;string&gt; &gt;()
+        ->composing()->notifier(&amp;your_function), "email")
+    ;
+</programlisting>      
+        These declarations specify that default value of the first option is 10,
+        that the second option can appear several times and all instances should
+        be merged, and that after parsing is done, the library will  call
+        function <code>&amp;your_function</code>, passing the value of the
+        "email" option as argument.      
+      </para>
+    </section>
+    
+    <section>
+      <title>Positional Options</title>
+      
+      <para>Our definition of option as (name, value) pairs is simple and
+        useful, but in one special case of the command line, there's a
+        problem. A command line can include a <firstterm>positional option</firstterm>,
+        which does not specify any name at all, for example:
+        <screen>
+          archiver --compression=9 /etc/passwd
+        </screen>
+        Here, the "/etc/passwd" element does not have any option name.
+      </para>
+      
+      <para>One solution is to ask the user to extract positional options
+        himself and process them as he likes. However, there's a nicer approach
+        -- provide a method to automatically assign the names for positional
+        options, so that the above command line can be interpreted the same way
+        as:
+        <screen>
+          archiver --compression=9 --input-file=/etc/passwd
+        </screen>
+      </para>
+      
+      <para>The &positional_options_desc; class allows the command line
+        parser to assign the names. The class specifies how many positional options
+        are allowed, and for each allowed option, specifies the name. For example:
+<programlisting>
+positional_options_description pd; pd.add("input-file", 1);
+</programlisting> specifies that for exactly one, first, positional
+        option the name will be "input-file".
+      </para>
+      
+      <para>It's possible to specify that a number, or even all positional options, be
+        given the same name.
+<programlisting>
+positional_options_description pd;
+pd.add("output-file", 2).add("input-file", -1);
+</programlisting>
+        In the above example, the first two positional options will be associated
+        with name "output-file", and any others with the name "input-file".
+      </para>
+
+    <warning>
+      <para>The &positional_options_desc; class only specifies translation from
+      position to name, and the option name should still be registered with
+      an instance of the &options_description; class.</para>
+    </warning>
+
+      
+    </section>
+              
     <!-- Note that the classes are not modified during parsing -->
           
   </section>
 
   <section>
-    <title>Parsers component</title>
+    <title>Parsers Component</title>
 
     <para>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
+      Each parser looks for possible options and consults the options
+      description component to determine if the option is known and how its value
+      is specified. In the simplest case, the name is explicitly specified,
+      which allows the library to decide if such option is known. If it is known, the
+      &value_semantic; instance determines how the value is specified. (If
+      it is not known, an exception is thrown.) 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
+      the value cannot be specified by the user, but the presence of the
       option implies some value (for example, <code>true</code>). So, the
       parser checks that the value is specified when needed and not specified
       when not needed, and returns new (name, value) pair.
     </para>
 
     <para>
-      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.                  
+      To invoke a parser you typically call a function, passing the options
+      description and command line or config file or something else.
+      The results of parsing are returned as an instance of the &parsed_options;
+      class. Typically, that object is passed directly to the storage
+      component. However, it also can be used directly, or undergo some additional
+      processing. 
     </para>
 
     <para>
-      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.
+      There are three exceptions to the above model -- all related to
+      traditional usage of the command line. While they require some support
+      from the options description component, the additional complexity is
+      tolerable.
       <itemizedlist>
         <listitem>
-          <para>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.
+          <para>The name specified on the command line may be
+            different from the option name -- it's common to provide a "short option
+            name" alias to a longer name. It's also common to allow an abbreviated name
+            to be specified on the command line.
           </para>
         </listitem>
         <listitem>
           <para>Sometimes it's desirable to specify value as several
-          tokens. For example, an option "--email-recipient" can be followed
+          tokens. For example, an option "--email-recipient" may 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.
           </para>
         </listitem>
         <listitem>
-          <para>Command line can contain positional options -- i.e. elements
+          <para>The command line may contain positional options -- 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.
@@ -179,55 +428,145 @@ desc.add_options()
 
 
   <section>
-    <title>Storage component</title>
+    <title>Storage Component</title>
 
     <para>The storage component is responsible for:
       <itemizedlist>
         <listitem>
-          <para>Storing the final values of option into speciall class and in
+          <para>Storing the final values of an option into a special class and in
             regular variables</para>
         </listitem>
         <listitem>
-          <para>Handling priorities between different sources.</para>
+          <para>Handling priorities among different sources.</para>
         </listitem>
 
         <listitem>
-          <para>Calling user-specified 'notify' functions with the final
+          <para>Calling user-specified <code>notify</code> functions with the final
          values of options.</para>
         </listitem>
       </itemizedlist>
     </para>
 
     <para>Let's consider an example:
-      <programlisting>
-        variables_map vm;
-        store(parse_command_line(argc, argv, desc), vm);
-        store(parse_config_file("example.cfg", desc), vm);
-        finish(vm);
-      </programlisting>
+<programlisting>
+variables_map vm;
+store(parse_command_line(argc, argv, desc), vm);
+store(parse_config_file("example.cfg", desc), vm);
+notify(vm);
+</programlisting>
       The <code>variables_map</code> class is used to store the option
       values. The two calls to the <code>store</code> function add values
-      found on command line and in config file. Finally the call to 
-      <code>notify</code> function runs user-specified notify functions and
-      stores values into regular variables, if needed. 
+      found on the command line and in the config file. Finally the call to
+      the <code>notify</code> function runs the user-specified notify
+      functions and stores the values into regular variables, if needed.
     </para>
 
-    <para>The priority is handled
-      in a simple way: the <code>store</code> 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.
+    <para>The priority is handled in a simple way: the <code>store</code>
+      function will not change the value of an option if it's already
+      assigned. In this case, if the command line specifies the value for an
+      option, any value in the config file is ignored.
     </para>
 
     <warning>
-      <para>Don't forget to call the <code>notify</code> function when you've
+      <para>Don't forget to call the <code>notify</code> function after you've
       stored all parsed values.</para>
     </warning>
 
   </section>
 
   <section>
-    <title>Annotated list of symbols</title>
+    <title>Specific parsers</title>
+
+    <section>
+      <title>Configuration file parser</title>
+
+      <para>The &parse_config_file; function implements parsing
+      of simple INI-like configuration files. Configuration file
+      syntax is line based:
+      </para>
+      <itemizedlist>
+        <listitem><para>A line in the form:</para>
+        <screen>
+<replaceable>name</replaceable>=<replaceable>value</replaceable>
+        </screen>
+        <para>gives a value to an option.</para>
+        </listitem>
+        <listitem><para>A line in the form:</para>
+        <screen>
+[<replaceable>section name</replaceable>]
+        </screen>
+        <para>introduces a new section in the configuration file.</para>
+        </listitem>
+        <listitem><para>The <literal>#</literal> character introduces a
+        comment that spans until the end of the line.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>The option names are relative to the section names, so
+      the following configuration file part:</para>
+      <screen>
+[gui.accessibility]
+visual_bell=yes
+      </screen>
+      <para>is equivalent to</para>
+      <screen>
+gui.accessibility.visual_bell=yes
+      </screen>
+                  
+    </section>
+
+    <section>
+      <title>Environment variables parser</title>
+
+      <para><firstterm>Environment variables</firstterm> are string variables
+      which are available to all programs via the <code>getenv</code> function
+      of C runtime library. The operating system allows to set initial values
+      for a given user, and the values can be further changed on the command
+      line.  For example, on Windows one can use the
+      <filename>autoexec.bat</filename> file or (on recent versions) the
+      <filename>Control Panel/System/Advanced/Environment Variables</filename>
+      dialog, and on Unix &#x2014;, the <filename>/etc/profile</filename>,
+      <filename>~/.profile</filename> and <filename>~/.bash_profile</filename>
+      files. Because environment variables can be set for the entire system,
+      they are particularly suitable for options which apply to all programs.
+      </para>
+
+      <para>The environment variables can be parsed with the
+      &parse_environment; function. The function have several overloaded
+      versions. The first parameter is always an &options_description;
+      instance, and the second specifies what variables must be processed, and
+      what option names must correspond to it. To describe the second
+      parameter we need to consider naming conventions for environment
+      variables.</para>
+      
+      <para>If you have an option that should be specified via environment
+      variable, you need make up the variable's name. To avoid name clashes,
+      we suggest that you use a sufficiently unique prefix for environment
+      variables. Also, while option names are most likely in lower case,
+      environment variables conventionally use upper case. So, for an option
+      name <literal>proxy</literal> the environment variable might be called
+      <envar>BOOST_PROXY</envar>. During parsing, we need to perform reverse
+      conversion of the names. This is accomplished by passing the choosen
+      prefix as the second parameter of the &parse_environment; function.
+      Say, if you pass <literal>BOOST_</literal> as the prefix, and there are
+      two variables, <envar>CVSROOT</envar> and <envar>BOOST_PROXY</envar>, the
+      first variable will be ignored, and the second one will be converted to
+      option <literal>proxy</literal>. 
+      </para>
+      
+      <para>The above logic is sufficient in many cases, but it is also
+      possible to pass, as the second parameter of the &parse_environment;
+      function, any function taking a <code>std::string</code> and returning
+      <code>std::string</code>. That function will be called for each
+      environment variable and should return either the name of the option, or
+      empty string if the variable should be ignored.
+      </para>
+            
+    </section>
+  </section>
+
+  <section>
+    <title>Annotated List of Symbols</title>
     
     <para>The following table describes all the important symbols in the
       library, for quick access.</para>
@@ -266,8 +605,15 @@ desc.add_options()
           
           <row>
             <entry>&parse_command_line;</entry>
-            <entry>parses command line</entry>
+            <entry>parses command line (simpified interface)</entry>
           </row>
+
+          <row>
+            <entry>&basic_command_line_parser;</entry>
+            <entry>parses command line (extended interface)</entry>
+          </row>
+
+
           <row>
             <entry>&parse_config_file;</entry>
             <entry>parses config file</entry>
@@ -298,7 +644,7 @@ desc.add_options()
 
 <!--
      Local Variables:
-     mode: xml
+     mode: nxml
      sgml-indent-data: t     
      sgml-parent-document: ("program_options.xml" "section")
      sgml-set-face: t

doc/post_review_plan.txt

@@ -151,7 +151,7 @@
    - test additional parser
    - Show default values in help output
    - Adaptive field width
-   - Mandatory options
+   - Mandatory options (2 votes (second Jonathan Graehl))
    - (new) return vector from parsers by auto_ptr, not by value?
    - (new) rename value_semantic into value_description
    - (new) output for positional_options_description

doc/program_options.ent

@@ -37,3 +37,10 @@
 <!ENTITY command_line_parser
      "<classname alt='boost::program_options::command_line_parser'>command_line_parser</classname>">
 
+<!ENTITY basic_command_line_parser
+     "<classname alt='boost::program_options::basic_command_line_parser'>basic_command_line_parser</classname>">
+
+
+<!ENTITY basic_option
+     "<classname alt='boost::program_options::basic_option'>basic_option</classname>">
+

doc/program_options.xml

@@ -40,11 +40,11 @@
     <title>Introduction</title>
 
     <para>The program_options library allows program developers to obtain
-    <emphasis>program options</emphasis>, i.e. (name,value) pairs from the user,
+    <emphasis>program options</emphasis>, that is (name, value) pairs from the user,
     via conventional methods such as command line and config file.</para>
 
-    <para>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:
+    <para>Why would you use such a library, and why is it better than parsing
+    your command line by straightforward hand-written code?
       <itemizedlist>
         <listitem>
           <para>It's easier. The syntax for declaring options is simple, and
@@ -54,15 +54,15 @@
           </para>
         </listitem>
         <listitem>
-          <para>Error reporting is better. All problems with the command line are
+          <para>Error reporting is better. All the problems with the 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.</para>
         </listitem>
         <listitem>
           <para>Options can be read from anywhere. Sooner or later the command
-          line will be not enough for your users, and you'd want config files
-          or maybe even environment variables. These can be added without significanto 
+          line will be not enough for your users, and you'll want config files
+          or maybe even environment variables. These can be added without significant 
           effort on your part.
           </para>
         </listitem>        
@@ -81,9 +81,7 @@
   
   <xi:include href="howto.xml"/>
   <xi:include href="design.xml"/>
-  <xi:include href="acknowledgements.xml"/>
-  <xi:include href="changes.xml"/>
-    
-  
-  <xi:include href="autodoc.boostbook"/> 
+  <xi:include href="acknowledgements.xml"/>    
+   
+  <xi:include href="autodoc.xml"/> 
 </library>

doc/todo.txt

@@ -1,4 +1,67 @@
 
+Say that variables_map is actually derived from std::map.
+
+Make parse_config_file("foo.cfg", desc) work.
+
+Document handling of positional options which depends on precedding options. 
+I.e scanning the parsed options and creating new variables_map when we see
+a positional option. (Email from Tony).
+
+> My instinctive reaction is to provide both via an options argument to
+> split_command_line (a name that would now be more appropriate). But I
+> haven't devoted much time to thinking this through, so I may be wrong. :-)
+> 
+> In any event, the tokenization isn't much fun. I'd expect the library to
+> provide a convenient mechanism for parsing a response file.
+
+
+> Similarly, is there some easy to use hook for customizing the "arg" to
+> indicate the type of the data (similar to how the textual representation
+> of the default argument can be changed, e.g.
+> value<Infile>(&forests_file)->default_value(default_in,"STDIN"), so that
+> I could get something like: "-f filename (=STDIN)   :" instead of "-f
+> arg (=STDIN)  :"?
+
+> A minor nit pick, with option groups (chained options_description), the
+> colons for the same group align but not across groups.
+
+
+There's another possibility:
+
+   value<type>(&variable, "filename")->......
+
+something like that was in the pre-review version, with the difference that the value name was also used to specify flags, e.g "filename?" would mean the value is optional.
+
+
+Should we also store the name specified on the command line in basic_option,
+so that validation_error can mention the *specified* option name?
+
+
+The config file is a bit different from command line. E.g. 'bool_switch' can't
+be specified in the config file. Further, it's not possible to specify a list
+of values in config file. For example, you can't write
+
+   include=a,b,c,d
+
+(or some other separator). You need:
+
+   include=a
+   ...
+   include=d
+
+
+ 
+> I often find it beneficial to start a log file, by tracing all options
+> in effect. Thus, it would be nice if one could iterate over all values
+> in a variable_map and get a string representation of all values. Perhaps
+> as an iterator range to the original string that was parsed into the
+> value in the first place. Using as<string> delegates to boost::any and
+> only succeeds if the value is indeed a string (a design decision I can
+> only applaud, btw), so I'm out of luck there.
+
+
+
+
 UML diagram?
 
 src/cmdline.cpp: function strncmp_nocase():
@@ -25,3 +88,151 @@ The program_options.reference.html may contain one-liner
 > One tiny example concentrating on one feature as short/long options,
 > multiple sources, hidden options, positional options, INI handling etc.
 > Something what user can skim over and cut/paste into app.
+
+
+> I would prefer that all occurrences of ASCII be capitalized.  It is the
+> abbreviation of the name of the Standard.  You may show it in lower case,
+> though, to distinguish "char strings in local 8-bit encoding" from the
+> Standard but it may confuse some readers.  I can't think of a good
+> alternative right now.
+
+> [By the way, "positional options" _desperately_ needs an entry in the
+> glossary. It's the most mystifying term in the library.]
+
+> If not already stated, you should note that all options must appear in the
+> options description layer (or class or object).  No options may make their
+> first appearance in the runtime configuration file, for instance.  The
+> library doesn't like surprises.  (I bring this up because other
+> initialization libraries allow an option to be declared in the
+> configuration file alone.  The file reader stores the option and parses it
+> to determine its type, for example, Boolean, double, integer or string.)
+
+-----------
+> "In the simplest case, the name is explicitly specified, which allows the
+> program to decide if such an option is known."
+>
+> or
+>
+> "In the simplest case, the name is explicitly specified and the program
+> decides that the option is known."
+> (This paragraph is a bit hard to read.  Maybe when I understand the library
+> better I can suggest some wording which flows more smoothly.)
+
+Maybe some explanation can help. Most of the time, input source contains both 
+the name of option and the value, for example, --foo=10. In this case, we 
+just lookup the option name, decide we know this option, and process it.
+
+In one specific case -- positional command line options, we don't have 
+explicit name. For example:
+
+   my_prog 1 2 3
+
+so more complex logic is necessary.
+
+
+> Rather than clutter up this list it might be better for the word "sources"
+> to be a link to another part of the document which lists the sources and
+> the order of precedence.
+
+Style of 'screen' in docs.
+
+> Perhaps you should include some sample output to show correct and incorrect
+> locale support or include a link to somewhere else in Boost where the
+> reader can find more information.  I wouldn't know a Unicode if it came up
+> and bit me on the ankle.
+
+
+> "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, <code>true</code>). So, the parser
+> checks that the value is specified when needed and not specified when not
+> needed, and returns new (name, value) pair."
+>
+> This wording is quite stiff and I can't decipher it, especially the "not
+> specified when not needed" phrase.  Can you rewrite this?
+
+> While I'm thinking about it, can you add the "Last revised..." line at the
+> bottom of each HTML page as it is on program_options.html or it that
+> governed by an xsl file?
+
+> If it doesn't already exist, there should be something in the tutorial to
+> explicitly define the steps required prior to the use of a configuration
+> variable as:
+> 1. declaration
+> 2. addition or composition
+> 3. storage or insertion
+> 4. notification.
+
+
+> I think a few lines should be added to aid the library user with the test
+> programs.  You could place them here in howto.xml or elsewhere or in a new
+> section entirely.  Users will want to know if their compiler is known to
+> work with the library and should be directed to the Boost Compiler Status
+> Tables page (\status\compiler_status.html or similar) or directly to the
+> Compiler Status Summary (http://boost.sourceforge.net/regression-logs/).
+
+> Many users will want to run the test programs on their own computer.  Your
+> documentation should answer these questions:
+> Which libraries must be linked to build the programs? (Dynamic? Static?)
+> Are there any other special considerations or any compiler switches to be
+> set? For those without a full Boost package, which other Boost libraries
+> are "included" by the test programs and, therefore, must be available?
+
+Basically, it's assumed that test programs with be run with Boost.Build. 
+Maybe it's worth noting that if a user wants to compiler them himself, 
+he should link the program_options library.
+
+> If you decide to make a separate section to describe the implementation of
+> the test programs, you might move the "test_convert" paragraphs starting at
+> line 379 of howto.xml there and put a referring link in its place.
+
+> I thought there was a bit of correspondence on one of the Boost mailing
+> lists concerning the inability of program_options to show the stored
+> variables 'en masse' but I can't find it now.  You should include that in
+> the documentation. Most users will be searching for a method to verify that
+> command line and configuration file values were actually stored in place of
+> the default values, for instance.  You could put in a line or two stating
+> that there is no one function which will send the entire database to a file
+> for later review.  (I think it had something to do with the fact that
+> program_options doesn't "know" the type of each option.)  I think it will
+> acquire the status of a Frequently-Asked Question.)
+
+
+> > Agreed. Though it's no FAQ section yet.... maybe, I can add this to howto
+>
+> section, though a question without full solution is not good.
+>
+> For the time being, those who want to know if such a display function
+> exists will have their question answered and the reason for it.  I suppose
+> that the library user could insert a series of statements in his program
+> immediately after the "notify" function which would write each known option
+> to a file for later examination.  Some people may use a number of "assert"
+> statements instead. They would only come into play in the debug mode.
+
+More visibility for bool_switch.
+
+
+> BTW: I thought of one other comment. One of the things I missed a little
+> in the documentation is a description of the config file format, as well
+> as what can be achieved with the po::command_line_style::style_t enum. I
+> think most users will need this information sooner or later. A few
+> examples would be fine... But then again time is such a precious thing
+
+> Does the library supports sections in config files
+
+> What about the combination of (if some user-settable switch is thrown,
+> but not by default):
+> 
+> * allowing unknown options -- these are considered positional parameters
+> * rearranging the argument list such that all positional parameters
+> are moved to the end
+> 
+> This way:
+> 
+> program --unknown 42 --known-flag --known-arg value
+> 
+> is handled as if it were (in standard UNIX command-line-ese):
+> 
+> program --known-flag --known-arg value -- --unknown 42
+
+

doc/tutorial.xml

@@ -12,13 +12,13 @@
   <para>In this section, we'll take a look at the most common usage scenarios
   of the program_options library, starting with the simplest one. The examples
   show only the interesting code parts, but the complete programs can be found
-  in the "example" directory. Through all the examples, we'll assume that the
-  following namespace alias is in effect:
-    <programlisting>namespace po = boost::program_options;</programlisting>    
+  in the "BOOST_ROOT/libs/program_options/example" directory. Through all the
+  examples, we'll assume that the following namespace alias is in effect:
+<programlisting>namespace po = boost::program_options;</programlisting>
   </para>
 
   <section>
-    <title>Getting started</title>
+    <title>Getting Started</title>
 
   <para>The first example is the simplest possible: it only handles two
     options. Here's the source code (the full program is in
@@ -60,29 +60,30 @@ if (vm.count(&quot;compression&quot;)) {
   </para>
   
   <para>After that, an object of class <code>variables_map</code> is
-    declared. That class is indented to store values of options, and can store
-    values of arbitrary types. The following calls to
-    <code>parse_command_line</code>, <code>store</code> and <code>notify</code>
-    functions cause <code>vm</code> to contain all option found on the command
+    declared. That class is intended to store values of options, and can store
+    values of arbitrary types. Next, the calls to <code>store</code>,
+    <code>parse_command_line</code> and <code>notify</code> functions cause
+    <code>vm</code> to contain all the options found on the command
     line.</para>
 
   <para>And now, finally, we can use the options as we like. The
     <code>variables_map</code> class can be used just like
-    <code>std::map</code>, except that values stored there must be converted to
-    the desired type with the <code>as</code> method, as shown above.
+    <code>std::map</code>, except that values stored there must be retrieved
+    with the <code>as</code> method shown above. (If the type specified in the
+    call to the <code>as</code> method is different from the actually stored
+    type, an exception is thrown.)
   </para>
 
   <para>It's now a good time to try compiling the code yourself, but if
     you're not yet ready, here's an example session:
 <screen>
-$bin/gcc/debug/first
+$<userinput>bin/gcc/debug/first</userinput>
 Compression level was not set.
-$bin/gcc/debug/first --help
+$<userinput>bin/gcc/debug/first --help</userinput>
 Allowed options:
   --help                 : produce help message
   --compression arg      : set compression level
-
-$bin/gcc/debug/first --compression 10
+$<userinput>bin/gcc/debug/first --compression 10</userinput>
 Compression level was set to 10.
     </screen>
   </para>
@@ -90,14 +91,14 @@ Compression level was set to 10.
   </section>
 
   <section>
-    <title>Option details</title>
+    <title>Option Details</title>
     
-  <para>Option value, surely, can have other types than <code>int</code>, and
+  <para>An option value, surely, can have other types than <code>int</code>, and
   can have other interesting properties, which we'll discuss right now. The
-  complete version of code snipped below can be found in
-  "example/options_description.cpp".</para>
+  complete version of the code snipped below can be found in
+  <filename>example/options_description.cpp</filename>.</para>
 
-  <para>Imagine we're writing a compiler. It should take the optimizaiton
+  <para>Imagine we're writing a compiler. It should take the optimization
     level, a number of include paths, and a number of input files, and perform some
     interesting work. Let's describe the options:
     <programlisting>
@@ -114,38 +115,45 @@ desc.add_options()
 </programlisting>
   </para>
 
-  <para>The "--help" option should be familiar from the previous example. 
-    It's a good idea to have this option in all cases.</para>
-
-  <para>The "optimization" option shows
-    two new features. First, we specify the address of variable. After 
-    storing values, that variable will have the value of the option. Second,
-    we specify a default value of 10, which will be used if no value is
-    specified by the user. 
+  <para>The <literal>"help"</literal> option should be familiar from 
+  the previous example. It's a good idea to have this option in all cases.
   </para>
 
-  <para>The "include-path" option is an example of the only case, where
-    interface of the <code>options_description</code> class serves specific
+  <para>The <literal>"optimization"</literal> option shows two new features. First, we specify
+    the address of the variable(<code>&amp;opt</code>). After storing values, that
+    variable will have the value of the option. Second, we specify a default
+    value of 10, which will be used if no value is specified by the user.
+  </para>
+
+  <para>The <literal>"include-path"</literal> option is an example of the 
+  only case where the interface of the <code>options_description</code> 
+  class serves only one
     source -- the command line. Users typically like to use short option names
     for common options, and the "include-path,I" name specifies that short
     option name is "I". So, both "--include-path" and "-I" can be used.
   </para>
+
+  <para>Note also that the type of the <literal>"include-path"</literal>
+  option is <type>std::vector</type>. The library provides special 
+  support for vectors -- it will be possible to specify the option several 
+  times, and all specified values will be collected in one vector.  
+  </para>
     
-  <para>The "input-file" option is used to specify the list of files to
+  <para>The "input-file" option specifies the list of files to
     process. That's okay for a start, but, of course, writing something like:
     <screen>
-compiler --input-file=a.cpp
+<userinput>compiler --input-file=a.cpp</userinput>
     </screen>
     is a little non-standard, compared with
     <screen>
-compiler a.cpp
+<userinput>compiler a.cpp</userinput>
     </screen>
     We'll address this in a moment.
   </para>
 
   <para>
-    The command line tokens which don't have any option name, like above, are
-    called "positional options" by this library. They can be handled,
+    The command line tokens which have no option name, as above, are
+    called "positional options" by this library. They can be handled
     too. With a little help from the user, the library can decide that "a.cpp"
     really means the same as "--input-file=a.cpp". Here's the additional code
     we need:
@@ -162,16 +170,16 @@ po::notify(vm);
 
   <para>
     The first two lines say that all positional options should be translated
-    into "input-file" option. Also note that we use the
+    into "input-file" options. Also note that we use the
     &command_line_parser; class to parse the command
     line, not the &parse_command_line;
     function. The latter is a convenient wrapper for simple cases, but now we
     need to pass additional information.
   </para>
 
-  <para>By now, all options are described and parsed. We'll save ourself the
-  trouble of implementing the rest of compiler logic, and only print the
-  options:
+  <para>By now, all options are described and parsed. We'll save ourselves the
+      trouble of implementing the rest of the compiler logic and only print the
+      options:
     <programlisting>
 if (vm.count(&quot;include-path&quot;))
 {
@@ -191,7 +199,7 @@ cout &lt;&lt; &quot;Optimization level is &quot; &lt;&lt; opt &lt;&lt; &quot;\n&
 
   <para>Here's an example session:
     <screen>
-$bin/gcc/debug/options_description --help
+$<userinput>bin/gcc/debug/options_description --help</userinput>
 Usage: options_description [options]
 Allowed options:
   --help                 : produce help message
@@ -200,7 +208,7 @@ Allowed options:
   --input-file arg       : input file
 $bin/gcc/debug/options_description
 Optimization level is 10
-$bin/gcc/debug/options_description --optimization 4 -I foo a.cpp
+$<userinput>bin/gcc/debug/options_description --optimization 4 -I foo a.cpp</userinput>
 Include paths are: foo
 Input files are: a.cpp
 Optimization level is 4
@@ -217,20 +225,20 @@ Optimization level is 4
   </section>
 
   <section>
-    <title>Multiple sources</title>
+    <title>Multiple Sources</title>
 
     <para>It's quite likely that specifying all options to our compiler on the
-    command line will annoy users. What if user installs a new library and
+    command line will annoy users. What if a user installs a new library and
     wants to always pass an additional command line element? What if he has
     made some choices which should be applied on every run? It's desirable to
-    create a config file with common setting, which will used together with
-    command line.
+    create a config file with common settings which will be used together with
+    the command line.
     </para>
 
-    <para>Of course, there should be a need to combine the values from command
-    line and config file. For example, optimization level specified on command
-    line should override value from config file. On the other hand, include
-    paths are better merged together.
+    <para>Of course, there will be a need to combine the values from command
+    line and config file. For example, the optimization level specified on the
+    command line should override the value from the config file. On the other
+    hand, include paths should be combined.
     </para>
 
     <para>Let's see the code now. The complete program is in
@@ -240,7 +248,7 @@ Optimization level is 4
       not all options are alike. Some options, like "input-file" above, should
       not be presented in an automatic help message. Some options make sense only
       in the config file. Finally, it's nice to have some structure in the help message,
-      not jump a long list of options. Let's declare several option groups:
+      not just a long list of options. Let's declare several option groups:
       <programlisting>
 // Declare a group of options that will be 
 // allowed only on command line
@@ -262,15 +270,15 @@ config.add_options()
          &quot;include path&quot;)
     ;
 
-// Hidden options will be allowed both on the command line and
-// in the config file, but will not be show to the user.
+// Hidden options, will be allowed both on command line and
+// in config file, but will not be shown to the user.
 po::options_description hidden(&quot;Hidden options&quot;);
 hidden.add_options()
     (&quot;input-file&quot;, po::value&lt; vector&lt;string&gt; &gt;(), &quot;input file&quot;)
     ;        
 </programlisting>
-      Note the call to the <code>composing</code> method in declaration of the
-      "include-path" option. It tells that values from different sources
+      Note the call to the <code>composing</code> method in the declaration of the
+      "include-path" option. It tells the library that values from different sources
       should be composed together, as we'll see shortly.
     </para>
 
@@ -289,21 +297,21 @@ visible.add(generic).add(config);
       </programlisting>
     </para>
 
-    <para>Parsing and storing of values follows the usual pattern, except that
+    <para>The parsing and storing of values follows the usual pattern, except that
       we additionally call <functionname>parse_config_file</functionname>, and
       call the &store; function twice. But what
       happens if the same value is specified both on the command line and in
-      config file. Usually, the value stored first is preferred. This is what
+      config file? Usually, the value stored first is preferred. This is what
       happens for the "--optimization" option. For "composing" options, like
-      "include-file", the values are merged together.
+      "include-file", the values are merged.
     </para>
 
     <para>Here's an example session:
 <screen>
-$bin/gcc/debug/multiple_sources
+$<userinput>bin/gcc/debug/multiple_sources</userinput>
 Include paths are: /opt
 Optimization level is 1
-$bin/gcc/debug/multiple_sources --help
+$<userinput>bin/gcc/debug/multiple_sources --help</userinput>
 Allows options:
 
 Generic options:
@@ -314,15 +322,15 @@ Configuration:
   --optimization n       : optimization level
   -I [ --include-path ] path : include path
 
-$bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp
+$<userinput>bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp</userinput>
 Include paths are: foo /opt
 Input files are: a.cpp b.cpp
 Optimization level is 4
 </screen>
-      The first invocation uses values from configuration file. The last
+      The first invocation uses values from the configuration file. The second
       invocation also uses values from command line. As we see, the include
-      paths on command line and config file are merged, while optimization is
-      taked from command line.
+      paths on the command line and in the configuration file are merged,
+      while optimization is taken from the command line.
     </para>
       
   </section>
@@ -337,7 +345,7 @@ Optimization level is 4
 
 <!--
      Local Variables:
-     mode: xml
+     mode: nxml
      sgml-indent-data: t     
      sgml-parent-document: ("program_options.xml" "section")
      sgml-set-face: t

example/Jamfile

@@ -1,16 +0,0 @@
-
-subproject libs/program_options/example ;
-
-rule program-options-example ( name extra-sources * )
-{
-    exe $(name) : $(name).cpp <lib>../build/boost_program_options $(extra-sources)
-    : <include>$(BOOST_ROOT) ;
-}
-
-program-options-example first ;
-program-options-example options_description ;
-program-options-example multiple_sources ;
-program-options-example custom_syntax ;
-
-#program-options-example real ;
-#program-options-example regex <lib>../../regex/build/boost_regex ;

example/Jamfile.v2

@@ -1,6 +1,6 @@
 
 project 
-    : requirements <library>../build//program_options
+    : requirements <library>../build//boost_program_options
       <hardcode-dll-paths>true
     ;
 
@@ -9,7 +9,5 @@ exe options_description : options_description.cpp ;
 exe multiple_sources : multiple_sources.cpp ;
 exe custom_syntax : custom_syntax.cpp ;
 
-exe a : a.cpp ;
-
-#exe real : real.cpp ;
-#exe regex : regex.cpp /boost/regex//boost_regex ;
+exe real : real.cpp ;
+exe regex : regex.cpp /boost/regex//boost_regex ;

example/multiple_sources.cpp

@@ -48,8 +48,8 @@ int main(int ac, char* av[])
                  "include path")
             ;
 
-        // Hidden options, will be alled both on command line and
-        // in config file, but will not be show to the user.
+        // Hidden options, will be allowed both on command line and
+        // in config file, but will not be shown to the user.
         po::options_description hidden("Hidden options");
         hidden.add_options()
             ("input-file", po::value< vector<string> >(), "input file")

example/option_groups.cpp

@@ -0,0 +1,97 @@
+// Copyright Vladimir Prus 2002-2004.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+/** This example shows how to handle options groups.
+
+    For a test, run:
+
+    option_groups --help
+    option_groups --num-threads 10
+    option_groups --help-module backend
+
+    The first invocation would show to option groups, and will not show the
+    '--num-threads' options. The second invocation will still get the value of
+    the hidden '--num-threads' option. Finally, the third invocation will show
+    the options for the 'backend' module, including the '--num-threads' option.
+
+*/
+
+
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/parsers.hpp>
+#include <boost/program_options/variables_map.hpp>
+#include <boost/tokenizer.hpp>
+#include <boost/token_functions.hpp>
+using namespace boost;
+using namespace boost::program_options;
+
+#include <iostream>
+#include <fstream>
+using namespace std;
+
+
+int main(int ac, char* av[])
+{
+    try {
+        // Declare three groups of options.
+        options_description general("General options");
+        general.add_options()
+            ("help", "produce a help message")
+            ("help-module", value<string>()->implicit(),
+                "produce a help for a given module")
+            ("version", "output the version number")
+            ;
+
+        options_description gui("GUI options");
+        gui.add_options()
+            ("display", value<string>(), "display to use")
+            ;
+
+        options_description backend("Backend options");
+        backend.add_options()
+            ("num-threads", value<int>(), "the initial number of threads")
+            ;
+            
+        // Declare an options description instance which will include
+        // all the options
+        options_description all("Allowed options");
+        all.add(general).add(gui).add(backend);
+
+        // Declare an options description instance which will be shown
+        // to the user
+        options_description visible("Allowed options");
+        visible.add(general).add(gui);
+           
+
+        variables_map vm;
+        store(parse_command_line(ac, av, all), vm);
+
+        if (vm.count("help")) 
+        {
+            cout << visible;
+            return 0;
+        }
+        if (vm.count("help-module")) {
+            const string& s = vm["help-module"].as<string>();
+            if (s == "gui") {
+                cout << gui;
+            } else if (s == "backend") {
+                cout << backend;
+            } else {
+                cout << "Unknown module '" 
+                     << s << "' in the --help-module option\n";
+                return 1;
+            }
+            return 0;
+        }
+        if (vm.count("num-threads")) {
+            cout << "The 'num-threads' options was set to "
+                 << vm["num-threads"].as<int>() << "\n";            
+        }                           
+    }
+    catch(exception& e) {
+        cout << e.what() << "\n";
+    }
+}

example/options_description.cpp

@@ -26,11 +26,17 @@ int main(int ac, char* av[])
 {
     try {
         int opt;
+        int portnum;
         po::options_description desc("Allowed options");
         desc.add_options()
             ("help", "produce help message")
             ("optimization", po::value<int>(&opt)->default_value(10), 
                   "optimization level")
+            ("verbose,v", po::value<int>()->implicit_value(1),
+                  "enable verbosity (optionally specify level)")
+            ("listen,l", po::value<int>(&portnum)->implicit_value(1001)
+                  ->default_value(0,"no"),
+                  "listen on a port.")
             ("include-path,I", po::value< vector<string> >(), 
                   "include path")
             ("input-file", po::value< vector<string> >(), "input file")
@@ -62,7 +68,14 @@ int main(int ac, char* av[])
                  << vm["input-file"].as< vector<string> >() << "\n";
         }
 
+        if (vm.count("verbose")) {
+            cout << "Verbosity enabled.  Level is " << vm["verbose"].as<int>()
+                 << "\n";
+        }
+
         cout << "Optimization level is " << opt << "\n";                
+
+        cout << "Listen port is " << portnum << "\n";                
     }
     catch(exception& e)
     {

example/real.cpp

@@ -10,7 +10,7 @@ using namespace boost::program_options;
 #include <iostream>
 using namespace std;
 
-/* Auxilliary functions for checking input for validity. */
+/* Auxiliary functions for checking input for validity. */
 
 /* Function used to check that 'opt1' and 'opt2' are not specified
    at the same time. */
@@ -20,7 +20,7 @@ void conflicting_options(const variables_map& vm,
     if (vm.count(opt1) && !vm[opt1].defaulted() 
         && vm.count(opt2) && !vm[opt2].defaulted())
         throw logic_error(string("Conflicting options '") 
-                          + opt1 + "' and '" + opt2 + "'");
+                          + opt1 + "' and '" + opt2 + "'.");
 }
 
 /* Function used to check that of 'for_what' is specified, then
@@ -31,33 +31,7 @@ void option_dependency(const variables_map& vm,
     if (vm.count(for_what) && !vm[for_what].defaulted())
         if (vm.count(required_option) == 0 || vm[required_option].defaulted())
             throw logic_error(string("Option '") + for_what 
-                              + "' requires option '" + required_option + "'");
-}
-
-/* Custom class for describing option. Allows to specify that the option is
-  'internal'.
-*/
-class custom_description : public option_description_easy_init<custom_description> {
-public:
-    custom_description() : m_internal(false) {}
-    void internal() { m_internal = true ; }
-    bool is_internal() const { return m_internal; }
-    
-private:
-    bool m_internal;            
-};
-
-
-/* Custom function for formatting one option. Does not print description for
-   internal options, and prints description on a separate line for all others. */
-void format_option(ostream& os, const option_description& desc)
-{
-    os << "  " << desc.format_name() << " " << desc.format_parameter();
-    const custom_description* d;
-    if ((d = dynamic_cast<const custom_description*>(&desc)) && d->is_internal()) 
-        os <<  "  (internal)\n";
-    else    
-        os << "\n      " << desc.description() << "\n";
+                              + "' requires option '" + required_option + "'.");
 }
 
 int main(int argc, char* argv[])
@@ -73,30 +47,30 @@ int main(int argc, char* argv[])
         string root = ".";
 
         options_description desc("Allowed options");
-        desc.add_options<custom_description>()
+        desc.add_options()
         // First parameter describes option name/short name
         // The second is parameter to option
         // The third is description
-        ("help,h", "", "print usage message")
-        ("output,o", value("<pathname>", &ofile), "pathname for output")
-        ("macrofile,m", value("<macrofile>", &macrofile), "full pathname of macro.h")
-        ("two,t", value("", &t_given), "preprocess both header and body")
-        ("body,b", value("", &b_given), "preprocess body in the header context")
-        ("libmakfile,l", value("<pathname>", &libmakfile), "write include makefile for library")
-        ("mainpackage,p", value("<name>", &mainpackage), "output dependency information")
-        ("depends,d", value("<pathname>", &depends), "write dependendies to <pathname>")
-        ("sources,s", value("<pathname>", &sources), "write source package list to <pathname>")
-        ("root,r", value("<pathname>", &root), "treat <dirname> as project root directory")
-        ("foo", "", "").default_value("10").internal()
+        ("help,h", "print usage message")
+        ("output,o", value(&ofile), "pathname for output")
+        ("macrofile,m", value(&macrofile), "full pathname of macro.h")
+        ("two,t", bool_switch(&t_given), "preprocess both header and body")
+        ("body,b", bool_switch(&b_given), "preprocess body in the header context")
+        ("libmakfile,l", value(&libmakfile), 
+             "write include makefile for library")
+        ("mainpackage,p", value(&mainpackage), 
+             "output dependency information")
+        ("depends,d", value(&depends), 
+         "write dependencies to <pathname>")
+        ("sources,s", value(&sources), "write source package list to <pathname>")
+        ("root,r", value(&root), "treat <dirname> as project root directory")
         ;
     
-        options_and_arguments oa = parse_command_line(argc, argv, desc);
         variables_map vm;
-        store(oa, vm, desc);
+        store(parse_command_line(argc, argv, desc), vm);
 
-        if (vm.count("help")) {
-            desc.output(cout, format_option);
-            cout << "\n";
+        if (vm.count("help")) {  
+            cout << desc << "\n";
             return 0;
         }
 

example/regex.cpp

@@ -3,6 +3,22 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+// This example shows how a user-defined class can be parsed using
+// specific mechanism -- not the iostream operations used by default.
+//
+// A new class 'magic_number' is defined and the 'validate' method is overloaded
+// to validate the values of that class using Boost.Regex.
+// To test, run
+//   
+//    regex -m 123-456
+//    regex -m 123-4567
+// 
+// The first invocation should output:
+//
+//   The magic is "456"
+//
+// and the second invocation should issue an error message.
+
 #include <boost/program_options.hpp>
 #include <boost/regex.hpp>
 
@@ -12,19 +28,29 @@ using namespace boost::program_options;
 #include <iostream>
 using namespace std;
 
-/* This validator makes sure that value is of form
-   XXX-XXX 
-   where X are digits. It then converts the second group to a integer
-   value. This has no practical meaning, meant only to show how
+/* Define a completely non-sensical class. */
+struct magic_number {
+public:
+    magic_number(int n) : n(n) {}
+    int n;
+};
+
+/* Overload the 'validate' function for the user-defined class.
+   It makes sure that value is of form XXX-XXX 
+   where X are digits and converts the second group to an integer.
+   This has no practical meaning, meant only to show how
    regex can be used to validate values.
 */
-void fancy_parameter_validator(boost::any& a, 
-                               const std::vector<std::string>& values)
+void validate(boost::any& v, 
+              const std::vector<std::string>& values,
+              magic_number* target_type, int)
 {
     static regex r("\\d\\d\\d-(\\d\\d\\d)");
 
+    using namespace boost::program_options;
+
     // Make sure no previous assignment to 'a' was made.
-    validators::check_first_occurence(a);
+    validators::check_first_occurrence(v);
     // Extract the first string from 'values'. If there is more than
     // one string, it's an error, and exception will be thrown.
     const string& s = validators::get_single_string(values);
@@ -33,39 +59,39 @@ void fancy_parameter_validator(boost::any& a,
     // int.
     smatch match;
     if (regex_match(s, match, r)) {
-        a = any(lexical_cast<int>(match[1]));
+        v = any(magic_number(lexical_cast<int>(match[1])));
     } else {
         throw validation_error("invalid value");
     }        
 }
 
 
-int main(int ac, const char **av)
+int main(int ac, char* av[])
 {
     try {
         options_description desc("Allowed options");
         desc.add_options()
-        ("help", "", "produce a help screen")
-        ("version,v", "", "print the version number")
-        ("magic,m", "arg", "magic value (in NNN-NNN format)").
-             validator(fancy_parameter_validator)
-        ;
+            ("help", "produce a help screen")
+            ("version,v", "print the version number")
+            ("magic,m", value<magic_number>(), 
+                 "magic value (in NNN-NNN format)")
+            ;
         
-        options_and_arguments oa = parse_command_line(ac, av, desc);
         variables_map vm;
-        store(oa, vm, desc);
+        store(parse_command_line(ac, av, desc), vm);
    
-        if (oa.count("help")) {
+        if (vm.count("help")) {
             cout << "Usage: regex [options]\n";
             cout << desc;
             return 0;
         }
-        if (oa.count("version")) {
+        if (vm.count("version")) {
             cout << "Version 1.\n";
             return 0;
         }
-        if (oa.count("magic")) {
-            cout << "The magic is \"" << vm["magic"].as<int>() << "\"\n";
+        if (vm.count("magic")) {
+            cout << "The magic is \"" 
+                 << vm["magic"].as<magic_number>().n << "\"\n";
         }
     }
     catch(exception& e)

example/response_file.cpp

@@ -0,0 +1,93 @@
+// Copyright Vladimir Prus 2002-2004.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+/** This example shows how to handle response file.
+
+    For a test, build and run:
+       response_file -I foo @response_file.rsp
+
+    The expected output is:
+      Include paths: foo bar biz
+
+    Thanks to Hartmut Kaiser who raised the issue of response files
+    and discussed the possible approach.
+*/
+
+
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/parsers.hpp>
+#include <boost/program_options/variables_map.hpp>
+#include <boost/tokenizer.hpp>
+#include <boost/token_functions.hpp>
+using namespace boost;
+using namespace boost::program_options;
+
+#include <iostream>
+#include <fstream>
+using namespace std;
+
+// Additional command line parser which interprets '@something' as a
+// option "config-file" with the value "something"
+pair<string, string> at_option_parser(string const&s)
+{
+    if ('@' == s[0])
+        return std::make_pair(string("response-file"), s.substr(1));
+    else
+        return pair<string, string>();
+}
+
+int main(int ac, char* av[])
+{
+    try {
+        options_description desc("Allowed options");
+        desc.add_options()
+            ("help", "produce a help message")
+            ("include-path,I", value< vector<string> >()->composing(), 
+                 "include path")
+            ("magic", value<int>(), "magic value")
+            ("response-file", value<string>(), 
+                 "can be specified with '@name', too")
+        ;
+
+        variables_map vm;
+        store(command_line_parser(ac, av).options(desc)
+              .extra_parser(at_option_parser).run(), vm);
+
+        if (vm.count("help")) {
+            cout << desc;            
+        }
+        if (vm.count("response-file")) {
+            // Load the file and tokenize it
+            ifstream ifs(vm["response-file"].as<string>().c_str());
+            if (!ifs) {
+                cout << "Could not open the response file\n";
+                return 1;
+            }
+            // Read the whole file into a string
+            stringstream ss;
+            ss << ifs.rdbuf();
+            // Split the file content
+            char_separator<char> sep(" \n\r");
+            tokenizer<char_separator<char> > tok(ss.str(), sep);
+            vector<string> args;
+            copy(tok.begin(), tok.end(), back_inserter(args));
+            // Parse the file and store the options
+            store(command_line_parser(args).options(desc).run(), vm);            
+        }
+
+        if (vm.count("include-path")) {
+            const vector<string>& s = vm["include-path"].as<vector< string> >();
+            cout << "Include paths: ";
+            copy(s.begin(), s.end(), ostream_iterator<string>(cout, " "));
+            cout << "\n";
+        }        
+        if (vm.count("magic")) {
+            cout << "Magic value: " << vm["magic"].as<int>() << "\n";
+        }
+    }
+    catch(exception& e) {
+        cout << e.what() << "\n";
+    }
+}

example/response_file.rsp

@@ -0,0 +1,3 @@
+-I bar
+-I biz
+--magic 10

include/boost/program_options.hpp

@@ -1,8 +1,7 @@
-// Copyright Vladimir Prus 2002. Permission to copy, use,
-// modify, sell and distribute this software is granted provided this
-// copyright notice appears in all copies. This software is provided
-// "as is" without express or implied warranty, and with no claim as
-// to its suitability for any purpose.
+// Copyright Vladimir Prus 2002.
+// Distributed under the Boost Software License, Version 1.0. (See
+// accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
 
 #ifndef PROGRAM_OPTIONS_VP_2003_05_19
 #define PROGRAM_OPTIONS_VP_2003_05_19

include/boost/program_options/cmdline.hpp

@@ -12,13 +12,13 @@ namespace boost { namespace program_options { namespace command_line_style {
     There are "long" options, which start with "--" and "short",
     which start with either "-" or "/". Both kinds can be allowed or
     disallowed, see allow_long and allow_short. The allowed character
-    for short option is also configurable.
+    for short options is also configurable.
 
-    Option's value can be specified in the same token as value
+    Option's value can be specified in the same token as name
     ("--foo=bar"), or in the next token.
 
-    It's possible to introduce long option by the same character as
-    long option, see allow_long_disguise.
+    It's possible to introduce long options by the same character as
+    short options, see allow_long_disguise.
 
     Finally, guessing (specifying only prefix of option) and case
     insensitive processing are supported.
@@ -39,7 +39,7 @@ namespace boost { namespace program_options { namespace command_line_style {
             @endverbatim
         */
         long_allow_adjacent = allow_slash_for_short << 1,
-        /** Allow option parameter in the same token for
+        /** Allow option parameter in the next token for
             long options. */
         long_allow_next = long_allow_adjacent << 1,
         /** Allow option parameter in the same token for
@@ -59,17 +59,17 @@ namespace boost { namespace program_options { namespace command_line_style {
         /** Allow abbreviated spellings for long options,
             if they unambiguously identify long option. 
             No long option name should be prefix of other 
-            long option name is guessing is in effect.
+            long option name if guessing is in effect.
         */
         allow_guessing = allow_sticky << 1,
         /** Ignore the difference in case for options. 
             @todo Should this apply to long options only?
         */            
-        case_insentitive = allow_guessing << 1,
+        case_insensitive = allow_guessing << 1,
         /** Allow long options with single option starting character,
             e.g <tt>-foo=10</tt>
         */
-        allow_long_disguise = case_insentitive << 1,
+        allow_long_disguise = case_insensitive << 1,
         /** The more-or-less traditional unix style. */
         unix_style = (allow_short | short_allow_adjacent | short_allow_next
                       | allow_long | long_allow_adjacent | long_allow_next

include/boost/program_options/config.hpp

@@ -8,6 +8,7 @@
 #define BOOST_PROGRAM_OPTIONS_CONFIG_HK_2004_01_11
 
 #include <boost/config.hpp>
+#include <boost/version.hpp>
 
 // Support for autolinking.
 #if BOOST_VERSION >= 103100   // works beginning from Boost V1.31.0
@@ -20,6 +21,10 @@
 // Set the name of our library, this will get undef'ed by auto_link.hpp
 // once it's done with it:
 #define BOOST_LIB_NAME boost_program_options
+// tell the auto-link code to select a dll when required:
+#if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_PROGRAM_OPTIONS_DYN_LINK)
+#  define BOOST_DYN_LINK
+#endif
 
 // And include the header that does the work:
 #include <boost/config/auto_link.hpp>

include/boost/program_options/detail/cmdline.hpp

@@ -10,6 +10,10 @@
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/errors.hpp>
 #include <boost/program_options/cmdline.hpp>
+#include <boost/program_options/option.hpp>
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/positional_options.hpp>
+
 
 #include <boost/detail/workaround.hpp>
 
@@ -21,9 +25,9 @@
 namespace boost { namespace program_options { namespace detail {
 
     /** Command line parser class. Main requirements were:
-        - Powerfull enough to support all common uses.
+        - Powerful enough to support all common uses.
         - Simple and easy to learn/use.
-        - Minimal code size and extrernal dependencies.
+        - Minimal code size and external dependencies.
         - Extensible for custom syntaxes.
 
         First all options are registered. After that, elements of command line
@@ -55,6 +59,9 @@ namespace boost { namespace program_options { namespace detail {
         typedef function1<std::pair<std::string, std::string>, 
                           const std::string&> 
             additional_parser;
+
+        typedef function1<std::vector<option>, std::vector<std::string>&>
+            style_parser;
         
         /** Constructs a command line parser for (argc, argv) pair. Uses
             style options passed in 'style', which should be binary or'ed values
@@ -63,12 +70,30 @@ namespace boost { namespace program_options { namespace detail {
             unregistered options. They will be assigned index 1 and are
             assumed to have optional parameter.
         */
-        cmdline(const std::vector<std::string>& args, int style,
-                bool allow_unregistered = false);
+        cmdline(const std::vector<std::string>& args);
 
         /** @overload */
-        cmdline(int argc, const char*const * argv, int style, 
-                bool allow_unregistered = false);
+        cmdline(int argc, const char*const * argv);
+
+        void style(int style);
+        void allow_unregistered();
+
+        void set_options_description(const options_description& desc);
+        void set_positional_options(
+            const positional_options_description& m_positional);
+
+        std::vector<option> run();
+
+        std::vector<option> parse_long_option(std::vector<std::string>& args);
+        std::vector<option> parse_short_option(std::vector<std::string>& args);
+        std::vector<option> parse_dos_option(std::vector<std::string>& args);
+        std::vector<option> parse_disguised_long_option(
+            std::vector<std::string>& args);
+        std::vector<option> parse_terminator(
+            std::vector<std::string>& args);
+        std::vector<option> handle_additional_parser(
+            std::vector<std::string>& args);
+
 
         /** Set additional parser. This will be called for each token
             of command line. If first string in pair is not empty,
@@ -80,202 +105,27 @@ namespace boost { namespace program_options { namespace detail {
         */
         void set_additional_parser(additional_parser p);
 
-        /** Registers a new option.
-            @param long_name Long name to use. When ending '*', symbols up to
-            it give an allowed prefix -- all options starting with it will be
-            allowed. The first character may not be '-'. Empty string means no
-            long name.
-            @param short_name Short name to use. Value of '\0' means no short
-            name.
-            @param properties Tell about possible parameters
-               '|' -- no parameter
-               '?' -- optional parameter
-               ':' -- required parameter
-               '*' -- 0 or more parameters
-               '+' -- 1 or more parameters
-            @param index A distinguishing value for the option.
-            The index will be returned by 'option_index' member function. Indices
-            need not be unqiue -- e.g. client can set all indices to 0, and
-            use string value to recognize options.
-        */
-        void add_option(const std::string& long_name, char short_name,
-                        char properties = '|', int index = 0);
+        void extra_style_parser(style_parser s);
 
-        /** @overload */
-        void add_option(const char* long_name, char short_name,
-                        char properties = '|', int index = 0);
-
-
-        /** Returns false when nothing more can be extracted */
-        operator bool() const;
-
-        /** Advances to the next element on command line. 
-            When called for the first time, positions on the first element. */
-        cmdline& operator++();
-
-        /// Tells if the current element is option.
-        bool at_option() const;
-
-        /// Tells if the current element is argument.
-        bool at_argument() const;
-
-        /** Returns the option name. If there's long option name associated with
-            this option, it is returned, even if short name was used in command line.
-            Otherwise, the short name given to 'add_option' is returned with '-' prepended. 
-            For purposes of simplicity, '-' is used even when dos-style short option 
-            was found.
-        */
-        const std::string& option_name() const;
-        /** Returns the index for the current option. */
-        int option_index() const;
-        /** Returns the option name as found on the command line. Any symbols
-            that introduce the option, or delimit its parameter will be
-            stripped. This function allows to work with allowed prefixes, in
-            which case 'option_name' will return the prefix specification, and
-            full option name should be queried explicitly.
-            */
-        const std::string& raw_option_name() const;
-        /** Returns the first of option values. If there's more than one option
-            throws multiple_values. If there are no options, returns empty 
-            string. */
-        const std::string& option_value() const;
-        /** Returns all option values. */
-        const std::vector<std::string>& option_values() const;
-        /** Returns the argument. */
-        const std::string& argument() const;
-
-        /** Returns all arguments read by this command line parser. */
-        const std::vector<std::string>& arguments() const;
-
-        /** Returns the token that was current by the time 'operator++' was
-            invoked the last time. */
-        const std::string& last() const;
-
-    private:
-
-        // Properties of an option.
-        enum properties_t {
-            no_parameter = 1,
-            /// 0 or 1 parameter
-            allow_parameter,
-            /// exactly 1 parameter
-            require_parameter,
-            /// 0 or more parameters
-            allow_parameters,
-            /// 1 or more parameters 
-            require_parameters
-        };
-
-        enum element_kind_t {
-            ek_option = 0,
-            ek_argument
-        };
-
-        // General error status.
-        enum error_type_t {
-            no_error = 0,
-            unknown_option,
-            ambiguous_option,
-            invalid_syntax
-        };
-
-        // Detailed error status.
-        enum error_description_t {
-            ed_success = 0,
-            ed_long_not_allowed,
-            ed_long_adjacent_not_allowed,
-            ed_short_adjacent_not_allowed,
-            ed_empty_adjacent_parameter,
-            ed_missing_parameter,
-            ed_extra_parameter,
-            ed_unknown_option,
-            ed_ambiguous_option
-        };
-
-        // The standard say that nested classes has no access to
-        // private member of enclosing class. However, most compilers
-        // allow that and it's likely be to allowed in future:
-        // http://std.dkuug.dk/jtc1/sc22/wg21/docs/cwg_defects.html#45  
-        // For Sun compiler, try using friend declaration.
-#if BOOST_WORKAROUND(__SUNPRO_CC, BOOST_TESTED_AT(0x560))
-        struct option;
-        friend struct option;
-#endif
-
-        struct option {
-            option(const std::string& long_name, char short_name,
-                   properties_t properties, int index)
-            : long_name(long_name), short_name(short_name), index(index),
-            properties(properties)
-            {}
-
-            std::string long_name;
-            char short_name;
-            int index;
-            properties_t properties;
-        };
-
-
-        std::vector<option> options;
-
-        void init(const std::vector<std::string>& args, int style,
-                  bool allow_unregistered);
         void check_style(int style) const;
-       
-        void next();
 
-        const option* find_long_option(const char* name);
-        const option* find_short_option(char name);
 
-        enum option_kind { error_option, no_option, long_option, short_option,
-                           dos_option };
-        option_kind is_option(const char* s);
-        // All handle_* member functions take string without any "--" or "-" or "/"
-        // They return true and success and set m_num_tokens to the number of
-        // tokens that were consumed.
-        bool handle_long_option(const char* s);
-        bool handle_short_option(const char* s, bool ignore_sticky = false);
-        bool handle_dos_option(const char* s);
-        // Attempts to apply additional parser to 's'.
-        bool handle_additional_parser(const std::pair<std::string, std::string>& p);
+        void init(const std::vector<std::string>& args);
 
-        bool process_parameter(const option* opt, bool adjacent_parameter,
-                              bool next_parameter);
-        void advance(int count);
-
-        /// Converts parameter property character into enum value.
-        properties_t translate_property(char p);
-
-        /** Clears all error state. If there were an error, throws appripriate
-            exception. */
-        void clear_error();
+        void
+        finish_option(option& opt,
+                      std::vector<std::string>& other_tokens);
 
         // Copies of input.
         std::vector<std::string> args;
-        style_t style;
-        bool allow_unregistered;
+        style_t m_style;
+        bool m_allow_unregistered;
 
-        // Current state of parsing.
-        unsigned index;
-        const char* m_current;
-        const char* m_next;
-        const char* pending_short_option;
-        bool m_no_more_options;
-        error_description_t m_error_description;
-        element_kind_t m_element_kind;
-        int m_option_index;
-
-        // Results of parsing the last option
-        std::string m_last;
-        const option* m_opt;
-        std::string  m_option_name, m_raw_option_name, m_argument;
-        std::vector<std::string> m_option_values; 
-        int m_num_tokens;
-        bool m_disguised_long;
-
-        std::vector<std::string> m_arguments;
+        const options_description* m_desc;
+        const positional_options_description* m_positional;
 
         additional_parser m_additional_parser;
+        style_parser m_style_parser;
     };
     
     void test_cmdline_detail();

include/boost/program_options/detail/config_file.hpp

@@ -16,15 +16,20 @@
 #include <boost/program_options/option.hpp>
 #include <boost/program_options/eof_iterator.hpp>
 
+#include <boost/detail/workaround.hpp>
 #if BOOST_WORKAROUND(__MWERKS__, BOOST_TESTED_AT(0x3202))
 #include <boost/program_options/detail/convert.hpp>
 #endif
 
+#if BOOST_WORKAROUND(__DECCXX_VER, BOOST_TESTED_AT(60590042))
+#include <istream> // std::getline
+#endif
+
 #include <boost/static_assert.hpp>
 #include <boost/type_traits/is_same.hpp>
 #include <boost/shared_ptr.hpp>
 
-#include <boost/detail/workaround.hpp>
+
 
 namespace boost { namespace program_options { namespace detail {
 
@@ -46,7 +51,7 @@ namespace boost { namespace program_options { namespace detail {
           spaces around '=' are trimmed.
         - Section names are given in brackets. 
 
-         The actuall option name is constructed by combining current section
+         The actual option name is constructed by combining current section
          name and specified option name, with dot between. If section_name 
          already contains dot at the end, new dot is not inserted. For example:
          @verbatim
@@ -65,7 +70,8 @@ namespace boost { namespace program_options { namespace detail {
     public:
         common_config_file_iterator() { found_eof(); }
         common_config_file_iterator(
-            const std::set<std::string>& allowed_options);
+            const std::set<std::string>& allowed_options,
+            bool allow_unregistered = false);
 
         virtual ~common_config_file_iterator() {}
 
@@ -98,6 +104,7 @@ namespace boost { namespace program_options { namespace detail {
         // Invariant: no element is prefix of other element.
         std::set<std::string> allowed_prefixes;
         std::string m_prefix;
+        bool m_allow_unregistered;
     };
 
     template<class charT>
@@ -111,7 +118,8 @@ namespace boost { namespace program_options { namespace detail {
         /** Creates a config file parser for the specified stream.            
         */
         basic_config_file_iterator(std::basic_istream<charT>& is, 
-                                   const std::set<std::string>& allowed_options); 
+                                   const std::set<std::string>& allowed_options,
+                                   bool allow_unregistered = false); 
 
     private: // base overrides
 
@@ -134,8 +142,9 @@ namespace boost { namespace program_options { namespace detail {
     template<class charT>
     basic_config_file_iterator<charT>::
     basic_config_file_iterator(std::basic_istream<charT>& is, 
-                               const std::set<std::string>& allowed_options)
-    : common_config_file_iterator(allowed_options)
+                               const std::set<std::string>& allowed_options,
+                               bool allow_unregistered)
+    : common_config_file_iterator(allowed_options, allow_unregistered)
     {
         this->is.reset(&is, null_deleter());                 
         get();
@@ -159,7 +168,8 @@ namespace boost { namespace program_options { namespace detail {
     }
 
     // Specialization is needed to workaround getline bug on Comeau.
-#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303))
+#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303)) || \
+        (defined(__sgi) && BOOST_WORKAROUND(_COMPILER_VERSION, BOOST_TESTED_AT(741)))
     template<>
     bool
     basic_config_file_iterator<wchar_t>::getline(std::string& s);

include/boost/program_options/detail/convert.hpp

@@ -19,7 +19,7 @@
 #include <cwchar>
 #include <stdexcept>
 
-#if BOOST_WORKAROUND(__ICL, <= 700) || BOOST_WORKAROUND(_MSC_VER, <= 1200)
+#if defined(BOOST_NO_STDC_NAMESPACE)
 #include <wchar.h>
 namespace std
 {
@@ -64,7 +64,7 @@ namespace boost {
     namespace program_options
     {
         /** Convert the input string into internal encoding used by
-            program_options. Presense of this function allows to avoid
+            program_options. Presence of this function allows to avoid
             specializing all methods which access input on wchar_t.
         */
         BOOST_PROGRAM_OPTIONS_DECL std::string to_internal(const std::string&);

include/boost/program_options/detail/parsers.hpp

@@ -28,14 +28,14 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>::
     basic_command_line_parser(const std::vector<
                               std::basic_string<charT> >& args)
-    : common_command_line_parser(to_internal(args))
+       : detail::cmdline(to_internal(args))
     {}
 
 
     template<class charT>
     basic_command_line_parser<charT>::
     basic_command_line_parser(int argc, charT* argv[])
-    : common_command_line_parser(
+    : detail::cmdline(
         // Explicit template arguments are required by gcc 3.3.1 
         // (at least mingw version), and do no harm on other compilers.
         to_internal(detail::make_vector<charT, charT**>(argv+1, argv+argc)))
@@ -46,6 +46,7 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>& 
     basic_command_line_parser<charT>::options(const options_description& desc)
     {
+       detail::cmdline::set_options_description(desc);
         m_desc = &desc;
         return *this;
     }
@@ -55,7 +56,7 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>::positional(
         const positional_options_description& desc)
     {
-        m_positional = &desc;
+        detail::cmdline::set_positional_options(desc);
         return *this;
     }
 
@@ -63,7 +64,7 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>& 
     basic_command_line_parser<charT>::style(int style)
     {
-        m_style = style;
+        detail::cmdline::style(style);
         return *this;
     }
 
@@ -71,18 +72,38 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>& 
     basic_command_line_parser<charT>::extra_parser(ext_parser ext)
     {
-        m_ext = ext;
+        detail::cmdline::set_additional_parser(ext);
         return *this;
     }
 
+    template<class charT>
+    basic_command_line_parser<charT>& 
+    basic_command_line_parser<charT>::allow_unregistered()
+    {
+        detail::cmdline::allow_unregistered();
+        return *this;
+    }
+
+    template<class charT>
+    basic_command_line_parser<charT>& 
+    basic_command_line_parser<charT>::extra_style_parser(style_parser s)
+    {
+        detail::cmdline::extra_style_parser(s);
+        return *this;
+    }
+
+
+
     template<class charT>    
     basic_parsed_options<charT>
-    basic_command_line_parser<charT>::run() const
+    basic_command_line_parser<charT>::run()
     {
-        // Presents of parsed_options -> wparsed_options convertion
+        parsed_options result(m_desc);
+        result.options = detail::cmdline::run();
+
+        // Presense of parsed_options -> wparsed_options conversion
         // does the trick.
-        return basic_parsed_options<charT>(
-            common_command_line_parser::run());
+        return basic_parsed_options<charT>(result);
     }
 
 
@@ -98,6 +119,26 @@ namespace boost { namespace program_options {
             style(style).extra_parser(ext).run();
     }
 
+    template<class charT>
+    std::vector< std::basic_string<charT> > 
+    collect_unrecognized(const std::vector< basic_option<charT> >& options,
+                         enum collect_unrecognized_mode mode)
+    {
+        std::vector< std::basic_string<charT> >  result;
+        for(unsigned i = 0; i < options.size(); ++i)
+        {
+            if (options[i].unregistered ||
+                (mode == include_positional && options[i].position_key != -1))
+            {
+                copy(options[i].original_tokens.begin(),
+                     options[i].original_tokens.end(),
+                     back_inserter(result));
+            }
+        }
+        return result;
+    }
+
+
 }}
 
 #endif

include/boost/program_options/detail/utf8_codecvt_facet.hpp

@@ -1,14 +1,3 @@
-#ifndef BOOST_UTF8_CODECVT_FACET_HPP
-#define BOOST_UTF8_CODECVT_FACET_HPP
-
-// MS compatible compilers support #pragma once
-#if defined(_MSC_VER) && (_MSC_VER >= 1020)
-# pragma once
-#endif
-
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// utf8_codecvt_facet.hpp
-
 // Copyright © 2001 Ronald Garcia, Indiana University (garcia@osl.iu.edu)
 // Andrew Lumsdaine, Indiana University (lums@osl.iu.edu). Permission to copy, 
 // use, modify, sell and distribute this software is granted provided this
@@ -16,202 +5,21 @@
 // without express or implied warranty, and with no claim as to its suitability
 // for any purpose.
 
-// Note:(Robert Ramey).  I have made the following alterations in the original
-// code.
-// a) Rendered utf8_codecvt<wchar_t, char>  with using templates
-// b) Move longer functions outside class definition to prevent inlining
-// and make code smaller
-// c) added on a derived class to permit translation to/from current
-// locale to utf8
-
-//  See http://www.boost.org for updates, documentation, and revision history.
-
-// archives stored as text - note these ar templated on the basic
-// stream templates to accommodate wide (and other?) kind of characters
-//
-// note the fact that on libraries without wide characters, ostream is
-// is not a specialization of basic_ostream which in fact is not defined
-// in such cases.   So we can't use basic_ostream<OStream::char_type> but rather
-// use two template parameters
-//
-// utf8_codecvt_facet
-//   This is an implementation of a std::codecvt facet for translating 
-//   from UTF-8 externally to UCS-4.  Note that this is not tied to
-//   any specific types in order to allow customization on platforms
-//   where wchar_t is not big enough.
-//
-// NOTES:  The current implementation jumps through some unpleasant hoops in
-// order to deal with signed character types.  As a std::codecvt_base::result,
-// it is necessary  for the ExternType to be convertible to unsigned  char.
-// I chose not to tie the extern_type explicitly to char. But if any combination
-// of types other than <wchar_t,char_t> is used, then std::codecvt must be
-// specialized on those types for this to work.
-
-#include <locale>
-// for mbstate_t
-#include <wchar.h>
+#ifndef BOOST_PROGRAM_OPTIONS_UTF8_CODECVT_FACET_HPP
+#define BOOST_PROGRAM_OPTIONS_UTF8_CODECVT_FACET_HPP
 
 #include <boost/program_options/config.hpp>
 
-#include <boost/detail/workaround.hpp>
-#if BOOST_WORKAROUND(__BORLANDC__,BOOST_TESTED_AT(0x551))
-    #ifndef _RWSTD_NO_NAMESPACE
-    using std::codecvt;
-    using std::min;
-    #ifdef _RWSTD_NO_MBSTATE_T
-    using std::mbstate_t;
-    #endif
-    #endif
-#elif defined(__COMO__) || defined(_MSC_VER) && _MSC_VER <= 1300 
-    typedef ::mbstate_t mbstate_t;
-#elif defined(BOOST_NO_STDC_NAMESPACE)
-    typedef std::mbstate_t mbstate_t;
-    namespace std{ 
-        using ::codecvt; 
-    } // namespace std
+#define BOOST_UTF8_BEGIN_NAMESPACE \
+     namespace boost { namespace program_options { namespace detail {
+
+#define BOOST_UTF8_END_NAMESPACE }}}
+#define BOOST_UTF8_DECL BOOST_PROGRAM_OPTIONS_DECL
+
+#include <boost/detail/utf8_codecvt_facet.hpp>
+
+#undef BOOST_UTF8_BEGIN_NAMESPACE
+#undef BOOST_UTF8_END_NAMESPACE
+#undef BOOST_UTF8_DECL
+
 #endif
-
-// maximum lenght of a multibyte string
-#define MB_LENGTH_MAX 8
-
-namespace boost { namespace program_options { namespace detail {
-
-struct BOOST_PROGRAM_OPTIONS_DECL utf8_codecvt_facet_wchar_t :
-    public std::codecvt<wchar_t, char, mbstate_t>  
-{
-public:
-    explicit utf8_codecvt_facet_wchar_t(std::size_t no_locale_manage=0)
-        : std::codecvt<wchar_t, char, mbstate_t>(no_locale_manage) 
-    {}
-protected:
-    virtual std::codecvt_base::result do_in(
-        mbstate_t& state, 
-        const char * from,
-        const char * from_end, 
-        const char * & from_next,
-        wchar_t * to, 
-        wchar_t * to_end, 
-        wchar_t*& to_next
-    ) const;
-
-    virtual std::codecvt_base::result do_out(
-        mbstate_t & state, const wchar_t * from,
-        const wchar_t * from_end, const wchar_t*  & from_next,
-        char * to, char * to_end, char * & to_next
-    ) const;
-
-    bool invalid_continuing_octet(unsigned char octet_1) const {
-        return (octet_1 < 0x80|| 0xbf< octet_1);
-    }
-
-    bool invalid_leading_octet(unsigned char octet_1)   const {
-        return (0x7f < octet_1 && octet_1 < 0xc0) ||
-            (octet_1 > 0xfd);
-    }
-
-    // continuing octets = octets except for the leading octet
-    static unsigned int get_cont_octet_count(unsigned   char lead_octet) {
-        return get_octet_count(lead_octet) - 1;
-    }
-
-    static unsigned int get_octet_count(unsigned char   lead_octet);
-
-    // How many "continuing octets" will be needed for this word
-    // ==   total octets - 1.
-    int get_cont_octet_out_count(wchar_t word) const ;
-
-    virtual bool do_always_noconv() const throw() { return false; }
-
-    // UTF-8 isn't really stateful since we rewind on partial conversions
-    virtual std::codecvt_base::result do_unshift(
-        mbstate_t&,
-        char * from,
-        char * to,
-        char * & next
-    ) const 
-    {
-        next = from;
-        return ok;
-    }
-
-    virtual int do_encoding() const throw() {
-        const int variable_byte_external_encoding=0;
-        return variable_byte_external_encoding;
-    }
-
-    // How many char objects can I process to get <= max_limit
-    // wchar_t objects?
-    virtual int do_length(
-        mbstate_t &,
-        const char * from,
-        const char * from_end, 
-        std::size_t max_limit
-    ) const;
-
-    // Largest possible value do_length(state,from,from_end,1) could return.
-    virtual int do_max_length() const throw () {
-        return 6; // largest UTF-8 encoding of a UCS-4 character
-    }
-};
-
-#if 0 // not used - incorrect in any case
-// Robert Ramey - use the above to make a code converter from multi-byte
-// char strings to utf8 encoding
-struct utf8_codecvt_facet_char : public utf8_codecvt_facet_wchar_t
-{
-    typedef utf8_codecvt_facet_wchar_t base_class;
-public:
-    explicit utf8_codecvt_facet_char(size_t no_locale_manage=0)
-        : base_class(no_locale_manage)
-    {}
-protected:
-    virtual std::codecvt_base::result do_in(
-        mbstate_t & state, 
-        const char * from, 
-        const char * from_end, 
-        const char * & from_next,
-        char * to, 
-        char * to_end, 
-        char * & to_next
-    ) const;
-
-    virtual std::codecvt_base::result do_out(
-        mbstate_t & state, 
-        const char * from,
-        const char * from_end, 
-        const char*  & from_next,
-        char * to, 
-        char * to_end, 
-        char * & to_next
-    ) const;
-
-    // How many char objects can I process to get <= max_limit
-    // char objects?
-    virtual int do_length(
-        const mbstate_t&, 
-        const char * from,
-        const char * from_end, 
-        size_t max_limit
-    ) const;
-};
-#endif
-
-template<class Internal, class External>
-struct utf8_codecvt_facet
-{};
-
-template<>
-struct BOOST_PROGRAM_OPTIONS_DECL utf8_codecvt_facet<wchar_t, char>
-    : public utf8_codecvt_facet_wchar_t
-{};
-
-#if 0
-template<>
-struct utf8_codecvt_facet<char, char>
-    : public utf8_codecvt_facet_char
-{};
-#endif
-
-}}}
-
-#endif // BOOST_UTF8_CODECVT_FACET_HPP

include/boost/program_options/detail/value_semantic.hpp

@@ -6,6 +6,8 @@
 // This file defines template functions that are declared in
 // ../value_semantic.hpp.
 
+#include <boost/throw_exception.hpp>
+
 namespace boost { namespace program_options { 
 
     extern BOOST_PROGRAM_OPTIONS_DECL std::string arg;
@@ -14,7 +16,13 @@ namespace boost { namespace program_options {
     std::string
     typed_value<T, charT>::name() const
     {
-        if (!m_default_value.empty() && !m_default_value_as_text.empty()) {
+        if (!m_implicit_value.empty() && !m_implicit_value_as_text.empty()) {
+            std::string msg = "[=arg(=" + m_implicit_value_as_text + ")]";
+            if (!m_default_value.empty() && !m_default_value_as_text.empty())
+                msg += " (=" + m_default_value_as_text + ")";
+            return msg;
+        }
+        else if (!m_default_value.empty() && !m_default_value_as_text.empty()) {
             return arg + " (=" + m_default_value_as_text + ")";
         } else {
             return arg;
@@ -56,8 +64,9 @@ namespace boost { namespace program_options {
                 throw validation_error("at least one value required");
         }
 
-        /* Throws multiple_occurences if 'value' is not empty. */
-        BOOST_PROGRAM_OPTIONS_DECL void check_first_occurence(const boost::any& value);
+        /* Throws multiple_occurrences if 'value' is not empty. */
+        BOOST_PROGRAM_OPTIONS_DECL void 
+        check_first_occurrence(const boost::any& value);
     }
 
     using namespace validators;
@@ -65,23 +74,22 @@ namespace boost { namespace program_options {
     /** Validates 's' and updates 'v'.
         @pre 'v' is either empty or in the state assigned by the previous
         invocation of 'validate'.
-        Specializations are provided for bool, float, int, and string.
-        The target type is specified via a parameter of which has type of 
+        The target type is specified via a parameter which has the type of 
         pointer to the desired type. This is workaround for compilers without
         partial template ordering, just like the last 'long/int' parameter.
     */
     template<class T, class charT>
     void validate(boost::any& v, 
                   const std::vector< std::basic_string<charT> >& xs, 
-                  T* target_type, long)
+                  T*, long)
     {
-        validators::check_first_occurence(v);
+        validators::check_first_occurrence(v);
         std::basic_string<charT> s(validators::get_single_string(xs));
         try {
             v = any(lexical_cast<T>(s));
         }
         catch(const bad_lexical_cast&) {
-            throw validation_error("invalid option value");
+            boost::throw_exception(invalid_option_value(s));
         }
     }
 
@@ -116,8 +124,8 @@ namespace boost { namespace program_options {
 #endif
 #endif
 
-    /** Validates sequences. Allows multiple values per option occurence
-       and multiple occurences. */
+    /** Validates sequences. Allows multiple values per option occurrence
+       and multiple occurrences. */
     template<class T, class charT>
     void validate(boost::any& v, 
                   const std::vector<std::basic_string<charT> >& s, 
@@ -128,15 +136,21 @@ namespace boost { namespace program_options {
             v = boost::any(std::vector<T>());
         }
         std::vector<T>* tv = boost::any_cast< std::vector<T> >(&v);
-        assert(tv);
+        assert(NULL != tv);
         for (unsigned i = 0; i < s.size(); ++i)
         {
             try {
-                tv->push_back(boost::lexical_cast<T>(s[i]));
+                /* We call validate so that if user provided
+                   a validator for class T, we use it even
+                   when parsing vector<T>.  */
+                boost::any a;
+                std::vector<std::basic_string<charT> > v;
+                v.push_back(s[i]);
+                validate(a, v, (T*)0, 0);                
+                tv->push_back(boost::any_cast<T>(a));
             }
             catch(const bad_lexical_cast& /*e*/) {
-                throw validation_error(std::string("value ").append(s[i]).
-                                       append(" is invalid"));
+                boost::throw_exception(invalid_option_value(s[i]));
             }
         }
     }
@@ -147,7 +161,13 @@ namespace boost { namespace program_options {
     xparse(boost::any& value_store, 
            const std::vector<std::basic_string<charT> >& new_tokens) const
     {
-        validate(value_store, new_tokens, (T*)0, 0);
+        // If no tokens were given, and the option accepts an implicit
+        // value, then assign the implicit value as the stored value;
+        // otherwise, validate the user-provided token(s).
+        if (new_tokens.empty() && !m_implicit_value.empty())
+            value_store = m_implicit_value;
+        else
+            validate(value_store, new_tokens, (T*)0, 0);
     }
 
     template<class T>

include/boost/program_options/eof_iterator.hpp

@@ -10,7 +10,7 @@
 
 namespace boost {
 
-    /** The 'eof_iterator' class is usefull for constructing forward iterators 
+    /** The 'eof_iterator' class is useful for constructing forward iterators 
         in cases where iterator extract data from some source and it's easy 
         to detect 'eof' -- i.e. the situation where there's no data. One 
         apparent example is reading lines from a file.
@@ -37,7 +37,7 @@ namespace boost {
                method.
             - advance the data pointer.
 
-        Essentially, the 'get' method has partly functionality of 'increment' 
+        Essentially, the 'get' method has the functionality of both 'increment' 
         and 'dereference'. It's very good for the cases where data extraction 
         implicitly moves data pointer, like for stream operation.         
     */
@@ -50,7 +50,7 @@ namespace boost {
         : m_at_eof(false)
         {}
 
-    protected: // iterface for derived
+    protected: // interface for derived
 
         /** Returns the reference which should be used by derived
             class to store the next value. */

include/boost/program_options/errors.hpp

@@ -46,7 +46,7 @@ namespace boost { namespace program_options {
         {}
     };
 
-    /** Class thrown when there's ambiguity between several possible options. */
+    /** Class thrown when there's ambiguity amoung several possible options. */
     class BOOST_PROGRAM_OPTIONS_DECL ambiguous_option : public error {
     public:
         ambiguous_option(const std::string& name, 
@@ -68,28 +68,46 @@ namespace boost { namespace program_options {
         multiple_values(const std::string& what) : error(what) {}
     };
 
-    /** Class thrown when there are several occurences of an
+    /** Class thrown when there are several occurrences of an
         option, but user called a method which cannot return 
         them all. */
-    class BOOST_PROGRAM_OPTIONS_DECL multiple_occurences : public error {
+    class BOOST_PROGRAM_OPTIONS_DECL multiple_occurrences : public error {
     public:
-        multiple_occurences(const std::string& what) : error(what) {}
+        multiple_occurrences(const std::string& what) : error(what) {}
     };
 
     /** Class thrown when value of option is incorrect. */
     class BOOST_PROGRAM_OPTIONS_DECL validation_error : public error {
     public:
         validation_error(const std::string& what) : error(what) {}
+        ~validation_error() throw() {}
+        void set_option_name(const std::string& option);
+
+        const char* what() const throw();
+    private:
+        mutable std::string m_message; // For on-demand formatting in 'what'
+        std::string m_option_name; // The name of the option which
+                                   // caused the exception.
     };
 
-    /** Class thrown then there are too many positional options. */
+    class BOOST_PROGRAM_OPTIONS_DECL invalid_option_value 
+        : public validation_error
+    {
+    public:
+        invalid_option_value(const std::string& value);
+#ifndef BOOST_NO_STD_WSTRING
+        invalid_option_value(const std::wstring& value);
+#endif
+    };
+
+    /** Class thrown when there are too many positional options. */
     class BOOST_PROGRAM_OPTIONS_DECL too_many_positional_options_error : public error {
     public:
         too_many_positional_options_error(const std::string& what) 
         : error(what) {}
     };
 
-    /** Class thrown then there are too few positional options. */
+    /** Class thrown when there are too few positional options. */
     class BOOST_PROGRAM_OPTIONS_DECL too_few_positional_options_error : public error {
     public:
         too_few_positional_options_error(const std::string& what) 

include/boost/program_options/option.hpp

@@ -14,8 +14,8 @@
 namespace boost { namespace program_options {
 
     /** Option found in input source.
-        Contains a key and a value. The key, in turn, can be string (name of
-        an option), or a integer (position in input source) -- in case no name
+        Contains a key and a value. The key, in turn, can be a string (name of
+        an option), or an integer (position in input source) -- in case no name
         is specified. The latter is only possible for command line.
         The template parameter specifies the type of char used for storing the
         option's value.
@@ -23,17 +23,17 @@ namespace boost { namespace program_options {
     template<class charT>
     class basic_option {
     public:
-        basic_option() : position_key(-1) {}
+        basic_option() : position_key(-1), unregistered(false) {}
         basic_option(const std::string& string_key, 
                const std::vector< std::string> &value) 
-        : string_key(string_key), value(value)
+        : string_key(string_key), value(value), unregistered(false)
         {}
 
         /** String key of this option. Intentionally independent of the template
             parameter. */
         std::string string_key;
-        /** Position key of this option. All options without explicit name are
-            sequentally numbered starting from 0. If an option has explicit name,
+        /** Position key of this option. All options without an explicit name are
+            sequentially numbered starting from 0. If an option has explicit name,
             'position_key' is equal to -1. It is possible that both
             position_key and string_key is specified, in case name is implicitly
             added.
@@ -41,6 +41,16 @@ namespace boost { namespace program_options {
         int position_key;
         /** Option's value */
         std::vector< std::basic_string<charT> > value;
+        /** The original unchanged tokens this option was
+            created from. */
+        std::vector< std::basic_string<charT> > original_tokens;
+        /** True if option was not recognized. In that case,
+            'string_key' and 'value' are results of purely
+            syntactic parsing of source. The original tokens can be
+            recovered from the "original_tokens" member.
+        */
+        bool unregistered;
+
     };
     typedef basic_option<char> option;
     typedef basic_option<wchar_t> woption;

include/boost/program_options/options_description.hpp

@@ -1,4 +1,5 @@
 // Copyright Vladimir Prus 2002-2004.
+// Copyright Bertolt Mildner 2004.
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -33,7 +34,7 @@ namespace program_options {
         kinds of properties of an option. First describe it syntactically and
         are used only to validate input. Second affect interpretation of the
         option, for example default value for it or function that should be
-        called  when the value is finally know. Routines which perform parsing
+        called  when the value is finally known. Routines which perform parsing
         never use second kind of properties -- they are side effect free.
         @sa options_description
     */
@@ -77,11 +78,25 @@ namespace program_options {
 
         virtual ~option_description();
 
-        /// Name to be used with short-style option ("-w").
-        const std::string& short_name() const;
+        enum match_result { no_match, full_match, approximate_match };
+
+        /** Given 'option', specified in the input source,
+            return 'true' is 'option' specifies *this.
+        */
+        match_result match(const std::string& option, bool approx) const;
+
+        /** Return the key that should identify the option, in
+            particular in the variables_map class.
+            The 'option' parameter is the option spelling from the
+            input source.
+            If option name contains '*', returns 'option'.
+            If long name was specified, it's the long name, otherwise
+            it's a short name with prepended '-'.
+        */
+        const std::string& key(const std::string& option) const;
 
-        /// Name to be used with long-style option ("--whatever").
         const std::string& long_name() const;
+
         /// Explanation of this option
         const std::string& description() const;
 
@@ -96,11 +111,10 @@ namespace program_options {
         std::string format_parameter() const;
 
     private:
-
-        option_description& name(const char* name);
+    
+        option_description& set_name(const char* name);
 
         std::string m_short_name, m_long_name, m_description;
-        std::string m_default_value, m_default_parameter;
         // shared_ptr is needed to simplify memory management in
         // copy ctor and destructor.
         shared_ptr<const value_semantic> m_value_semantic;
@@ -141,18 +155,20 @@ namespace program_options {
     */
     class BOOST_PROGRAM_OPTIONS_DECL options_description {
     public:
-
+        static const unsigned m_default_line_length;
+        
         /** Creates the instance. */
-        options_description();
+        options_description(unsigned line_length = m_default_line_length);
         /** Creates the instance. The 'caption' parameter gives the name of
-            this 'options_description' instance. Primarily usefull for output.
+            this 'options_description' instance. Primarily useful for output.
         */
-        options_description(const std::string& caption);
+        options_description(const std::string& caption,
+                            unsigned line_length = m_default_line_length);
         /** Adds new variable description. Throws duplicate_variable_error if
             either short or long name matches that of already present one. 
         */
         void add(shared_ptr<option_description> desc);
-        /** Adds a group of option description. This have the same
+        /** Adds a group of option description. This has the same
             effect as adding all option_descriptions in 'desc' 
             individually, except that output operator will show
             a separate group.
@@ -169,32 +185,14 @@ namespace program_options {
         */
         options_description_easy_init add_options();
 
-        /** Count the number of option descriptions with given name. 
-            Returns 0 or 1.
-            The 'name' parameter can be either name of long option, and short
-            option prepended by '-'.
-        */
-        unsigned count(const std::string& name) const;
-        /** Count the number of descriptions having the given string as
-            prefix. This makes sense only for long options.
-        */
-        unsigned count_approx(const std::string& prefix) const;
-        /** Returns description given a name. 
-            @pre count(name) == 1
-        */
-        const option_description& find(const std::string& name) const;
-        /** Returns description given a prefix. Throws
-            @pre count_approx(name) == 1 
-        */
-        const option_description& find_approx(const std::string& prefix) const;
-        /// Returns all such strings x for which count(x) == 1
-        std::set<std::string> keys() const;
-        /** For each option description stored, contains long name if not empty,
-            if it is empty, short name is returned.
-        */
-        std::set<std::string> primary_keys() const;
-        /// Returns all such long options for which 'prefix' is prefix
-        std::set<std::string> approximations(const std::string& prefix) const;
+        const option_description& find(const std::string& name, bool approx) 
+            const;
+
+        const option_description* find_nothrow(const std::string& name, 
+                                               bool approx) const;
+
+
+        const std::vector< shared_ptr<option_description> >& options() const;
 
         /** Produces a human readable output of 'desc', listing options,
             their descriptions and allowed parameters. Other options_description
@@ -202,7 +200,7 @@ namespace program_options {
         friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os, 
                                              const options_description& desc);
 
-        /** Output 'desc' to the specified streeam, calling 'f' to output each
+        /** Output 'desc' to the specified stream, calling 'f' to output each
             option_description element. */
         void print(std::ostream& os) const;
 
@@ -211,15 +209,15 @@ namespace program_options {
         typedef std::pair<name2index_iterator, name2index_iterator> 
             approximation_range;
 
-
-        approximation_range find_approximation(const std::string& prefix) const;
+        //approximation_range find_approximation(const std::string& prefix) const;
 
         std::string m_caption;
-        // Data organization is chosen since:
+        const unsigned m_line_length;
+        // Data organization is chosen because:
         // - there could be two names for one option
         // - option_add_proxy needs to know the last added option
-        std::vector< shared_ptr<option_description> > options;
-        std::map<std::string, int> name2index;
+        std::vector< shared_ptr<option_description> > m_options;
+
         // Whether the option comes from one of declared groups.
 #if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313))
         // vector<bool> is buggy there, see
@@ -229,7 +227,7 @@ namespace program_options {
         std::vector<bool> belong_to_group;
 #endif
 
-        std::vector<options_description> groups;
+        std::vector< shared_ptr<options_description> > groups;
 
     };
 

include/boost/program_options/parsers.hpp

@@ -9,6 +9,7 @@
 
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/option.hpp>
+#include <boost/program_options/detail/cmdline.hpp>
 
 #include <boost/function/function1.hpp>
 
@@ -49,7 +50,7 @@ namespace boost { namespace program_options {
     template<>
     class BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t> {
     public:
-        /** Constructs wraped_options from options in UTF8 encoding. */
+        /** Constructs wrapped options from options in UTF8 encoding. */
         explicit basic_parsed_options(const basic_parsed_options<char>& po);
 
         std::vector< basic_option<wchar_t> > options;
@@ -69,37 +70,22 @@ namespace boost { namespace program_options {
 
     typedef function1<std::pair<std::string, std::string>, const std::string&> ext_parser;
 
-    /** Character-type independent command line parser. */
-    class BOOST_PROGRAM_OPTIONS_DECL common_command_line_parser {
-    public:
-        /// Creates the parsers. The arguments must be in internal encoding.
-        common_command_line_parser(const std::vector<std::string>& args);
-        /// Parses the command line and returns parsed options in internal
-        /// encoding.
-        parsed_options run() const;
-    protected:
-        int m_style;
-        const options_description* m_desc;
-        const positional_options_description* m_positional;
-        function1<std::pair<std::string, std::string>, const std::string&> m_ext;
+    /** Command line parser.
 
-        // Intentionally independent from charT
-        std::vector<std::string> m_args;
-    };
-
-    /** Comamnd line parser.
-
-        The class allows to specify all the information needed for parsing and
-        the parse the command line. It is primarily needed to emulate named 
-        function parameters -- a regular function with 5 parameters will be hard
-        to use and creating overloads with smaller nuber of parameters will be 
-        confusing.
+        The class allows one to specify all the information needed for parsing
+        and to parse the command line. It is primarily needed to
+        emulate named function parameters -- a regular function with 5
+        parameters will be hard to use and creating overloads with a smaller
+        nuber of parameters will be confusing.
 
         For the most common case, the function parse_command_line is a better 
         alternative.        
+
+        There are two typedefs -- command_line_parser and wcommand_line_parser,
+        for charT == char and charT == wchar_t cases.
     */
     template<class charT>
-    class basic_command_line_parser : private common_command_line_parser {
+    class basic_command_line_parser : private detail::cmdline {
     public:
         /** Creates a command line parser for the specified arguments
             list. The 'args' parameter should not include program name.
@@ -107,19 +93,42 @@ namespace boost { namespace program_options {
         basic_command_line_parser(const std::vector<
                                   std::basic_string<charT> >& args);
         /** Creates a command line parser for the specified arguments
-            list. The parameter should be the same as passes to 'main'.
+            list. The parameters should be the same as passed to 'main'.
         */
         basic_command_line_parser(int argc, charT* argv[]);
 
+        /** Sets options descriptions to use. */
         basic_command_line_parser& options(const options_description& desc);
+        /** Sets positional options description to use. */
         basic_command_line_parser& positional(
             const positional_options_description& desc);
 
+        /** Sets the command line style. */
         basic_command_line_parser& style(int);
+        /** Sets the extra parsers. */
         basic_command_line_parser& extra_parser(ext_parser);
+
+        /** Parses the options and returns the result of parsing.
+            Throws on error.
+        */
+        basic_parsed_options<charT> run();
+
+        /** Specifies that unregistered options are allowed and should
+            be passed though. For each command like token that looks
+            like an option but does not contain a recognized name, an
+            instance of basic_option<charT> will be added to result,
+            with 'unrecognized' field set to 'true'. It's possible to
+            collect all unrecognized options with the 'collect_unrecognized'
+            funciton. 
+        */
+        basic_command_line_parser& allow_unregistered();
         
-        basic_parsed_options<charT> run() const;
+        using detail::cmdline::style_parser;
+
+        basic_command_line_parser& extra_style_parser(style_parser s);
+
     private:
+        const options_description* m_desc;
     };
 
     typedef basic_command_line_parser<char> command_line_parser;
@@ -140,8 +149,28 @@ namespace boost { namespace program_options {
     /** Parse a config file. 
     */
     template<class charT>
+#if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
+    BOOST_PROGRAM_OPTIONS_DECL
+#endif
     basic_parsed_options<charT>
-    parse_config_file(std::basic_istream<charT>&, const options_description&);
+    parse_config_file(std::basic_istream<charT>&, const options_description&,
+                      bool allow_unregistered = false);
+
+    /** Controls if the 'collect_unregistered' function should
+        include positional options, or not. */
+    enum collect_unrecognized_mode 
+    { include_positional, exclude_positional };
+
+    /** Collects the original tokens for all named options with
+        'unregistered' flag set. If 'mode' is 'include_positional'
+        also collects all positional options.
+        Returns the vector of origianl tokens for all collected
+        options.
+    */
+    template<class charT>
+    std::vector< std::basic_string<charT> > 
+    collect_unrecognized(const std::vector< basic_option<charT> >& options,
+                         enum collect_unrecognized_mode mode);
 
     /** Parse environment. 
 
@@ -166,9 +195,9 @@ namespace boost { namespace program_options {
     parse_environment(const options_description&, const std::string& prefix);
 
     /** @overload
-        This function exists for resolve ambiguity between the two above 
+        This function exists to resolve ambiguity between the two above 
         functions when second argument is of 'char*' type. There's implicit
-        convension to both function1 and string.
+        conversion to both function1 and string.
     */
     BOOST_PROGRAM_OPTIONS_DECL parsed_options
     parse_environment(const options_description&, const char* prefix);
@@ -189,11 +218,12 @@ namespace boost { namespace program_options {
     split_winmain(const std::wstring& cmdline);
     #endif
 #endif
+    
 
 }}
 
 #undef DECL
 
-#include "detail/parsers.hpp"
+#include "boost/program_options/detail/parsers.hpp"
 
 #endif

include/boost/program_options/positional_options.hpp

@@ -20,9 +20,9 @@ namespace boost { namespace program_options {
         The class uses the information provided by the user to associate a name
         with every positional option, or tell that no name is known. 
 
-        The primary assumption is that only relative order of positional options
-        themself matters, and that any interleaving ordinary options don't 
-        affect interpretation of positional options.
+        The primary assumption is that only the relative order of the
+        positional options themselves matters, and that any interleaving
+        ordinary options don't affect interpretation of positional options.
         
         The user initializes the class by specifying that first N positional 
         options should be given the name X1, following M options should be given 
@@ -37,7 +37,8 @@ namespace boost { namespace program_options {
             No calls to 'add' can be made after call with 'max_value' equal to 
             '-1'.            
         */
-        void add(const char* name, int max_count);
+        positional_options_description&
+        add(const char* name, int max_count);
 
         /** Returns the maximum number of positional options that can
             be present. Can return numeric_limits<unsigned>::max() to
@@ -46,7 +47,7 @@ namespace boost { namespace program_options {
 
         /** Returns the name that should be associated with positional
             options at 'position'. 
-            Precodting: position < max_total_count()
+            Precondition: position < max_total_count()
         */
         const std::string& name_for_position(unsigned position) const;
 

include/boost/program_options/value_semantic.hpp

@@ -14,9 +14,9 @@
 #include <boost/lexical_cast.hpp>
 
 
-
 #include <string>
 #include <vector>
+#include <typeinfo>
 
 namespace boost { namespace program_options {
 
@@ -25,33 +25,28 @@ namespace boost { namespace program_options {
     */
     class BOOST_PROGRAM_OPTIONS_DECL value_semantic {
     public:
-        /** Returns the name of the option. The name is only meaningfull
+        /** Returns the name of the option. The name is only meaningful
             for automatic help message.
          */
         virtual std::string name() const = 0;
 
-        /** Returns true if value cannot be specified in source at all.
-            Other methods can still set the value somehow, but
-            user can't affect it.
-        */
-        virtual bool zero_tokens() const = 0;
+        /** The minimum number of tokens for this option that
+            should be present on the command line. */
+        virtual unsigned min_tokens() const = 0;
+
+        /** The maximum number of tokens for this option that
+            should be present on the command line. */
+        virtual unsigned max_tokens() const = 0;
 
         /** Returns true if values from different sources should be composed.
             Otherwise, value from the first source is used and values from
             other sources are discarded.
         */
         virtual bool is_composing() const = 0;
-
-        /** Returns true if explicit value of an option can be omitted. 
-        */
-        virtual bool is_implicit() const = 0;
-
-        /** Returns true if value can span several token in input source. */
-        virtual bool is_multitoken() const = 0;
         
         /** Parses a group of tokens that specify a value of option.
             Stores the result in 'value_store', using whatever representation
-            is desired. Maybe be called several times if value of the same
+            is desired. May be be called several times if value of the same
             option is specified more than once.
         */
         virtual void parse(boost::any& value_store, 
@@ -60,7 +55,7 @@ namespace boost { namespace program_options {
             = 0;
 
         /** Called to assign default value to 'value_store'. Returns
-            true if default value is assigned, and false if not default
+            true if default value is assigned, and false if no default
             value exists. */
         virtual bool apply_default(boost::any& value_store) const = 0;
                                    
@@ -79,6 +74,13 @@ namespace boost { namespace program_options {
         // Nothing here. Specializations to follow.
     };
 
+    /** Helper conversion class for values that accept ascii
+        strings as input.
+        Overrides the 'parse' method and defines new 'xparse'
+        method taking std::string. Depending on whether input
+        to parse is ascii or UTF8, will pass it to xparse unmodified,
+        or with UTF8->ascii conversion.
+    */
     template<>
     class BOOST_PROGRAM_OPTIONS_DECL 
     value_semantic_codecvt_helper<char> : public value_semantic {
@@ -92,6 +94,13 @@ namespace boost { namespace program_options {
             const = 0;
     };
 
+    /** Helper conversion class for values that accept ascii
+        strings as input.
+        Overrides the 'parse' method and defines new 'xparse'
+        method taking std::wstring. Depending on whether input
+        to parse is ascii or UTF8, will recode input to Unicode, or
+        pass it unmodified.
+    */
     template<>
     class BOOST_PROGRAM_OPTIONS_DECL
     value_semantic_codecvt_helper<wchar_t> : public value_semantic {
@@ -106,8 +115,9 @@ namespace boost { namespace program_options {
             const = 0;
 #endif
     };
-    /** Class which specify handling of value for which user did not specified
-        anything. */    
+
+    /** Class which specifies a simple handling of a value: the value will
+        have string type and only one token is allowed. */    
     class BOOST_PROGRAM_OPTIONS_DECL 
     untyped_value : public value_semantic_codecvt_helper<char>  {
     public:
@@ -117,10 +127,10 @@ namespace boost { namespace program_options {
 
         std::string name() const;
 
-        bool zero_tokens() const { return m_zero_tokens; }
+        unsigned min_tokens() const;
+        unsigned max_tokens() const;
+
         bool is_composing() const { return false; }
-        bool is_implicit() const { return false; }
-        bool is_multitoken() const { return false; }
         
         /** If 'value_store' is already initialized, or new_tokens
             has more than one elements, throws. Otherwise, assigns
@@ -134,20 +144,40 @@ namespace boost { namespace program_options {
         bool apply_default(boost::any&) const { return false; }
 
         /** Does nothing. */
-        void notify(const boost::any& value_store) const {}        
+        void notify(const boost::any&) const {}        
     private:
         bool m_zero_tokens;
     };
 
+    /** Base class for all option that have a fixed type, and are
+        willing to announce this type to the outside world.
+        Any 'value_semantics' for which you want to find out the
+        type can be dynamic_cast-ed to typed_value_base. If conversion
+        succeeds, the 'type' method can be called.
+    */
+    class typed_value_base 
+    {
+    public:
+        // Returns the type of the value described by this
+        // object.
+        virtual const std::type_info& value_type() const = 0;
+        // Not really needed, since deletion from this
+        // class is silly, but just in case.
+        virtual ~typed_value_base() {}
+    };
+
+
     /** Class which handles value of a specific type. */
     template<class T, class charT = char>
-    class typed_value : public value_semantic_codecvt_helper<charT>  {
+    class typed_value : public value_semantic_codecvt_helper<charT>,
+                        public typed_value_base
+    {
     public:
         /** Ctor. The 'store_to' parameter tells where to store
             the value when it's known. The parameter can be NULL. */
         typed_value(T* store_to) 
         : m_store_to(store_to), m_composing(false),
-        m_implicit(false), m_multitoken(false)
+          m_multitoken(false), m_zero_tokens(false)
         {} 
 
         /** Specifies default value, which will be used
@@ -174,6 +204,38 @@ namespace boost { namespace program_options {
             return this;
         }
 
+        /** Specifies an implicit value, which will be used
+            if the option is given, but without an adjacent value.
+            Using this implies that an explicit value is optional, but if
+            given, must be strictly adjacent to the option, i.e.: '-ovalue'
+            or '--option=value'.  Giving '-o' or '--option' will cause the
+            implicit value to be applied.
+        */
+        typed_value* implicit_value(const T &v)
+        {
+            m_implicit_value = boost::any(v);
+            m_implicit_value_as_text =
+                boost::lexical_cast<std::string>(v);
+            return this;
+        }
+
+        /** Specifies an implicit value, which will be used
+            if the option is given, but without an adjacent value.
+            Using this implies that an explicit value is optional, but if
+            given, must be strictly adjacent to the option, i.e.: '-ovalue'
+            or '--option=value'.  Giving '-o' or '--option' will cause the
+            implicit value to be applied.
+            Unlike the above overload, the type 'T' need not provide
+            operator<< for ostream, but textual representation of default
+            value must be provided by the user.
+        */
+        typed_value* implicit_value(const T &v, const std::string& textual)
+        {
+            m_implicit_value = boost::any(v);
+            m_implicit_value_as_text = textual;
+            return this;
+        }
+
         /** Specifies a function to be called when the final value
             is determined. */
         typed_value* notifier(function1<void, const T&> f)
@@ -191,13 +253,6 @@ namespace boost { namespace program_options {
             return this;
         }
 
-        /** Specifies that the value is implicit. */
-        typed_value* implicit()
-        {
-            m_implicit =  true;
-            return this;
-        }
-
         /** Specifies that the value can span multiple tokens. */
         typed_value* multitoken()
         {
@@ -205,18 +260,41 @@ namespace boost { namespace program_options {
             return this;
         }
 
+        typed_value* zero_tokens() 
+        {
+            m_zero_tokens = true;
+            return this;
+        }
+            
+
     public: // value semantic overrides
 
         std::string name() const;
 
-        bool zero_tokens() const { return false; }
         bool is_composing() const { return m_composing; }
-        bool is_implicit() const { return m_implicit; }        
-        bool is_multitoken() const { return m_multitoken; }
+
+        unsigned min_tokens() const
+        {
+            if (m_zero_tokens || !m_implicit_value.empty()) {
+                return 0;
+            } else {
+                return 1;
+            }
+        }
+
+        unsigned max_tokens() const {
+            if (m_multitoken) {
+                return 32000;
+            } else if (m_zero_tokens) {
+                return 0;
+            } else {
+                return 1;
+            }
+        }
 
 
         /** Creates an instance of the 'validator' class and calls
-            it's operator() to perform actual convertion. */
+            its operator() to perform the actual conversion. */
         void xparse(boost::any& value_store, 
                     const std::vector< std::basic_string<charT> >& new_tokens) 
             const;
@@ -239,16 +317,25 @@ namespace boost { namespace program_options {
             when creating *this, stores the value there. Otherwise,
             does nothing. */
         void notify(const boost::any& value_store) const;
+
+    public: // typed_value_base overrides
+        
+        const std::type_info& value_type() const
+        {
+            return typeid(T);
+        }
         
 
     private:
         T* m_store_to;
         
         // Default value is stored as boost::any and not
-        // as boost::optional to avoid unnecessary instantinations.
+        // as boost::optional to avoid unnecessary instantiations.
         boost::any m_default_value;
         std::string m_default_value_as_text;
-        bool m_composing, m_implicit, m_multitoken;
+        boost::any m_implicit_value;
+        std::string m_implicit_value_as_text;
+        bool m_composing, m_implicit, m_multitoken, m_zero_tokens;
         boost::function1<void, const T&> m_notifier;
     };
 
@@ -283,9 +370,9 @@ namespace boost { namespace program_options {
     typed_value<T, wchar_t>*
     wvalue(T* v);
 
-    /** Works the same way as the 'value' function, but also makes the created
-        value_semantic implicit, i.e. the value can be omitted. The omitted
-        value is considered to be 'true'.
+    /** Works the same way as the 'value<bool>' function, but the created
+        value_semantic won't accept any explicit value. So, if the option 
+        is present on the command line, the value will be 'true'.
     */
     BOOST_PROGRAM_OPTIONS_DECL typed_value<bool>*
     bool_switch();
@@ -297,7 +384,7 @@ namespace boost { namespace program_options {
 
 }}
 
-#include "detail/value_semantic.hpp"
+#include "boost/program_options/detail/value_semantic.hpp"
 
 #endif
 

include/boost/program_options/variables_map.hpp

@@ -14,6 +14,7 @@
 
 #include <string>
 #include <map>
+#include <set>
 
 namespace boost { namespace program_options {
 
@@ -23,6 +24,29 @@ namespace boost { namespace program_options {
     class value_semantic;
     class variables_map;
 
+    // forward declaration
+
+    /** Stores in 'm' all options that are defined in 'options'. 
+        If 'm' already has a non-defaulted value of an option, that value
+        is not changed, even if 'options' specify some value.        
+    */
+    BOOST_PROGRAM_OPTIONS_DECL 
+    void store(const basic_parsed_options<char>& options, variables_map& m,
+                    bool utf8 = false);
+
+    /** Stores in 'm' all options that are defined in 'options'. 
+        If 'm' already has a non-defaulted value of an option, that value
+        is not changed, even if 'options' specify some value.        
+        This is wide character variant.
+    */
+    BOOST_PROGRAM_OPTIONS_DECL 
+    void store(const basic_parsed_options<wchar_t>& options, 
+                    variables_map& m);
+
+
+    /** Runs all 'notify' function for options in 'm'. */
+    BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
+
     /** Class holding value of option. Contains details about how the 
         value is set and allows to conveniently obtain the value.
     */
@@ -35,14 +59,19 @@ namespace boost { namespace program_options {
 
         /** If stored value if of type T, returns that value. Otherwise,
             throws boost::bad_any_cast exception. */
-        template<class T> const T& as() const;
-
-        /** @overload */
-        template<class T> T& as();
+       template<class T>
+       const T& as() const {
+           return boost::any_cast<const T&>(v);
+       }
+       /** @overload */
+       template<class T>
+       T& as() {
+           return boost::any_cast<T&>(v);
+       }
 
         /// Returns true if no value is stored.
         bool empty() const;
-        /** Returns true if the value was not explcitly
+        /** Returns true if the value was not explicitly
             given, but has default value. */
         bool defaulted() const;
         /** Returns the contained value. */
@@ -60,10 +89,10 @@ namespace boost { namespace program_options {
         // be easily accessible, so we need to store semantic here.
         shared_ptr<const value_semantic> m_value_semantic;
 
-        friend void BOOST_PROGRAM_OPTIONS_DECL 
-        store(const basic_parsed_options<char>& options, 
+        friend BOOST_PROGRAM_OPTIONS_DECL
+        void store(const basic_parsed_options<char>& options, 
               variables_map& m, bool);
-        friend void BOOST_PROGRAM_OPTIONS_DECL notify(variables_map& m);
+        friend BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
     };
 
     /** Implements string->string mapping with convenient value casting
@@ -83,11 +112,11 @@ namespace boost { namespace program_options {
                 - otherwise, returns empty value
 
             - if there's defaulted value
-                - if there's next varaible map, which has non-defauled
+                - if there's next varaible map, which has a non-defauled
                   value, return that
                 - otherwise, return value from *this
 
-            - if there's non-defauled value, returns it.
+            - if there's a non-defauled value, returns it.
         */
         const variable_value& operator[](const std::string& name) const;
 
@@ -103,7 +132,11 @@ namespace boost { namespace program_options {
         const abstract_variables_map* m_next;
     };
 
-    /** Concrete variables map which store variables in real map. */
+    /** Concrete variables map which store variables in real map. 
+        
+        This class is derived from std::map<std::string, variable_value>,
+        so you can use all map operators to examine its content.
+    */
     class BOOST_PROGRAM_OPTIONS_DECL variables_map : public abstract_variables_map,
                                public std::map<std::string, variable_value>
     {
@@ -119,27 +152,17 @@ namespace boost { namespace program_options {
         /** Implementation of abstract_variables_map::get
             which does 'find' in *this. */
         const variable_value& get(const std::string& name) const;
+
+        /** Names of option with 'final' values -- which should not
+            be changed by subsequence assignments. */
+        std::set<std::string> m_final;
+
+        friend BOOST_PROGRAM_OPTIONS_DECL
+        void store(const basic_parsed_options<char>& options, 
+                          variables_map& xm,
+                          bool utf8);
     };
 
-    /** Stores in 'm' all options that are defined in 'options'. 
-        If 'm' already has a non-defaulted value of an option, that value
-        is not changed, even of 'options' specify some value.        
-    */
-    BOOST_PROGRAM_OPTIONS_DECL void store(const basic_parsed_options<char>& options, variables_map& m,
-                    bool utf8 = false);
-
-    /** Stores in 'm' all options that are defined in 'options'. 
-        If 'm' already has a non-defaulted value of an option, that value
-        is not changed, even of 'options' specify some value.        
-        This is wide character variant.
-    */
-    BOOST_PROGRAM_OPTIONS_DECL void store(const basic_parsed_options<wchar_t>& options, 
-                    variables_map& m);
-
-
-    /** Runs all 'notify' function for options in 'm'. */
-    BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
-
 
     /*
      * Templates/inlines
@@ -171,24 +194,6 @@ namespace boost { namespace program_options {
         return v;
     }
 
-
-    template<class T>
-    const T&
-    variable_value::as() const {
-        const T* r = boost::any_cast<T>(&v);
-        if (!r)
-            throw boost::bad_any_cast();
-        return *r;
-    }
-
-    template<class T>
-    T&
-    variable_value::as() {
-        T* r = boost::any_cast<T>(&v);
-        if (!r)
-            throw boost::bad_any_cast();
-        return *r;
-    }
 }}
 
 #endif

index.html

@@ -0,0 +1,14 @@
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=../../doc/html/program_options.html">
+</head>
+<body>
+Automatic redirection failed, please go to
+<a href="../../doc/html/program_options.html">../../doc/html/program_options.html</a> 
+&nbsp;<hr>
+<p>© Copyright Beman Dawes, 2001</p>
+<p>Distributed under the Boost Software License, Version 1.0. (See accompanying 
+file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy 
+at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
+</body>
+</html>

src/config_file.cpp

@@ -10,6 +10,7 @@
 #include <boost/program_options/detail/config_file.hpp>
 #include <boost/program_options/errors.hpp>
 #include <boost/program_options/detail/convert.hpp>
+#include <boost/throw_exception.hpp>
 
 #include <iostream>
 #include <fstream>
@@ -20,8 +21,10 @@ namespace boost { namespace program_options { namespace detail {
     using namespace std;
 
     common_config_file_iterator::common_config_file_iterator(
-        const std::set<std::string>& allowed_options)
-    : allowed_options(allowed_options)
+        const std::set<std::string>& allowed_options,
+        bool allow_unregistered)
+    : allowed_options(allowed_options),
+      m_allow_unregistered(allow_unregistered)
     {
         for(std::set<std::string>::const_iterator i = allowed_options.begin();
             i != allowed_options.end(); 
@@ -54,7 +57,7 @@ namespace boost { namespace program_options { namespace detail {
                     bad_prefixes = true;
             }
             if (bad_prefixes)
-                throw error("bad prefixes");
+                boost::throw_exception(error("bad prefixes"));
             allowed_prefixes.insert(s);
         }
     }
@@ -99,20 +102,22 @@ namespace boost { namespace program_options { namespace detail {
                     string name = m_prefix + trim_ws(s.substr(0, n));
                     string value = trim_ws(s.substr(n+1));
 
-                    if (!allowed_option(name))
-                        throw unknown_option(name);
+                    bool registered = allowed_option(name);
+                    if (!registered && !m_allow_unregistered)
+                        boost::throw_exception(unknown_option(name));
                                         
                     if (value.empty())
-                        throw invalid_syntax(s, "no value given");
+                        boost::throw_exception(invalid_syntax(s, "no value given"));
                     
                     found = true;
                     this->value().string_key = name;
                     this->value().value.clear();
                     this->value().value.push_back(value);
+                    this->value().unregistered = !registered;
                     break;
 
                 } else {
-                    throw invalid_syntax(s, "unrecognized line");
+                    boost::throw_exception(invalid_syntax(s, "unrecognized line"));
                 }
             }
         }
@@ -136,9 +141,8 @@ namespace boost { namespace program_options { namespace detail {
         return false;
     }
 
-// On Metrowerks, the function is defined inline.
-
-#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303))
+#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303)) || \
+        (defined(__sgi) && BOOST_WORKAROUND(_COMPILER_VERSION, BOOST_TESTED_AT(741)))
     template<>
     bool
     basic_config_file_iterator<wchar_t>::getline(std::string& s)

src/convert.cpp

@@ -17,6 +17,7 @@
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/detail/convert.hpp>
 #include <boost/program_options/detail/utf8_codecvt_facet.hpp>
+#include <boost/throw_exception.hpp>
 
 #include <boost/bind.hpp>
 
@@ -24,16 +25,16 @@ using namespace std;
 
 namespace boost { namespace detail {
 
-    /* Internal function to acutally pefrom convertion.
+    /* Internal function to actually perform conversion.
        The logic in from_8_bit and to_8_bit function is exactly
        the same, except that one calls 'in' method of codecvt and another
-       calls the 'out' method, and that syntax different makes straightforward
+       calls the 'out' method, and that syntax difference makes straightforward
        template implementation impossible.
 
        This functions takes a 'fun' argument, which should have the same 
        parameters and return type and the in/out methods. The actual converting
        function will pass functional objects created with boost::bind.
-       Experiments show that the performance loss is withing 10%.
+       Experiments show that the performance loss is less than 10%.
     */
     template<class ToChar, class FromChar, class Fun>
     std::basic_string<ToChar>
@@ -46,7 +47,7 @@ namespace boost { namespace detail {
 
         const FromChar* from = s.data();
         const FromChar* from_end = s.data() + s.size();
-        // The interace of cvt is not really iterator-like, and it's
+        // The interface of cvt is not really iterator-like, and it's
         // not possible the tell the required output size without the conversion.
         // All we can is convert data by pieces.
         while(from != from_end) {
@@ -56,20 +57,22 @@ namespace boost { namespace detail {
             ToChar buffer[32];
             
             ToChar* to_next = buffer;
-            // Need variable bacause boost::bind doesn't work with rvalues.
+            // Need variable because boost::bind doesn't work with rvalues.
             ToChar* to_end = buffer + 32;
             std::codecvt_base::result r = 
                 fun(state, from, from_end, from, buffer, to_end, to_next);
             
             if (r == std::codecvt_base::error)
-                throw std::logic_error("character conversion failed");
-            // 'partial' is not an error, it just means not all source characters
-            // we converted. However, we need to check that at least one new target
-            // character was produced. If not, it means the source data is 
-            // incomplete, and since we don't have extra data to add to source, it's
-            // error.
+                boost::throw_exception(
+                    std::logic_error("character conversion failed"));
+            // 'partial' is not an error, it just means not all source
+            // characters were converted. However, we need to check that at
+            // least one new target character was produced. If not, it means
+            // the source data is incomplete, and since we don't have extra
+            // data to add to source, it's error.
             if (to_next == buffer)
-                throw std::logic_error("character conversion failed");
+                boost::throw_exception(
+                    std::logic_error("character conversion failed"));
             
             // Add converted characters
             result.append(buffer, to_next);
@@ -106,7 +109,7 @@ namespace boost {
 
 
     namespace {
-        boost::program_options::detail::utf8_codecvt_facet<wchar_t, char> 
+        boost::program_options::detail::utf8_codecvt_facet
             utf8_facet;
     }
     

src/options_description.cpp

@@ -1,4 +1,5 @@
 // Copyright Vladimir Prus 2002-2004.
+// Copyright Bertolt Mildner 2004.
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -11,15 +12,18 @@
 // should move that to a separate headers.
 #include <boost/program_options/parsers.hpp>
 
-#include <boost/lexical_cast.hpp>
 
+#include <boost/lexical_cast.hpp>
+#include <boost/tokenizer.hpp>
 #include <boost/detail/workaround.hpp>
+#include <boost/throw_exception.hpp>
 
 #include <cassert>
 #include <climits>
 #include <cstring>
 #include <cstdarg>
 #include <sstream>
+#include <iterator>
 using namespace std;
 
 namespace boost { namespace program_options {
@@ -33,7 +37,7 @@ namespace boost { namespace program_options {
                        const value_semantic* s)
     : m_value_semantic(s)
     {
-        this->name(name);
+        this->set_name(name);
     }
                                            
 
@@ -43,32 +47,64 @@ namespace boost { namespace program_options {
                        const char* description)
     : m_description(description), m_value_semantic(s)
     {
-        this->name(name);
+        this->set_name(name);
     }
 
     option_description::~option_description()
     {
     }
 
-    option_description&
-    option_description::name(const char* _name)
+    option_description::match_result
+    option_description::match(const std::string& option, bool approx) const
     {
-        std::string name(_name);
-        string::size_type n = name.find(',');
-        if (n != string::npos) {
-            assert(n == name.size()-2);
-            m_long_name = name.substr(0, n);
-            m_short_name = name.substr(n+1,1);
-        } else {
-            m_long_name = name;
+        match_result result = no_match;
+        if (!m_long_name.empty()) {
+
+            if (*m_long_name.rbegin() == '*')
+            {
+                // The name ends with '*'. Any specified name with the given
+                // prefix is OK.
+                if (option.find(m_long_name.substr(0, m_long_name.length()-1))
+                    == 0)
+                    result = approximate_match;
+            }
+
+            if (approx)
+            {
+                if (m_long_name.find(option) == 0)
+                    if (m_long_name == option)
+                        result = full_match;
+                    else
+                        result = approximate_match;
+            }
+            else
+            {
+                if (m_long_name == option)
+                    result = full_match;
+            }
         }
-        return *this;
+         
+        if (m_short_name == option)
+            result = full_match;
+
+        return result;        
     }
 
-    const std::string&
-    option_description::short_name() const
-    {
-        return m_short_name;
+    const std::string& 
+    option_description::key(const std::string& option) const
+    {        
+        if (!m_long_name.empty()) 
+            if (m_long_name.find('*') != string::npos)
+                // The '*' character means we're long_name
+                // matches only part of the input. So, returning
+                // long name will remove some of the information,
+                // and we have to return the option as specified
+                // in the source.
+                return option;
+            else
+                return m_long_name;
+        else
+            return m_short_name;
     }
 
     const std::string&
@@ -77,6 +113,21 @@ namespace boost { namespace program_options {
         return m_long_name;
     }
 
+    option_description&
+    option_description::set_name(const char* _name)
+    {
+        std::string name(_name);
+        string::size_type n = name.find(',');
+        if (n != string::npos) {
+            assert(n == name.size()-2);
+            m_long_name = name.substr(0, n);
+            m_short_name = '-' + name.substr(n+1,1);
+        } else {
+            m_long_name = name;
+        }
+        return *this;
+    }
+
     const std::string&
     option_description::description() const
     {
@@ -92,17 +143,17 @@ namespace boost { namespace program_options {
     std::string 
     option_description::format_name() const
     {
-        if (!short_name().empty())
-            return string("-").append(short_name()).append(" [ --").
-            append(long_name()).append(" ]");
+        if (!m_short_name.empty())
+            return string(m_short_name).append(" [ --").
+            append(m_long_name).append(" ]");
         else
-            return string("--").append(long_name());
+            return string("--").append(m_long_name);
     }
 
     std::string 
     option_description::format_parameter() const
     {
-        if (!m_value_semantic->zero_tokens())
+        if (m_value_semantic->max_tokens() != 0)
             return m_value_semantic->name();
         else
             return "";
@@ -150,40 +201,32 @@ namespace boost { namespace program_options {
         return *this;
     }
 
-    options_description::options_description()
+    const unsigned options_description::m_default_line_length = 80;
+
+    options_description::options_description(unsigned line_length)
+    : m_line_length(line_length)
     {}
 
-    options_description::options_description(const string& caption)
-    : m_caption(caption)
+    options_description::options_description(const string& caption,
+                                             unsigned line_length)
+    : m_caption(caption), m_line_length(line_length)
     {}
 
     void
     options_description::add(shared_ptr<option_description> desc)
     {
-        const string& s = desc->short_name();
-        const string& l = desc->long_name();
-        assert(!s.empty() || !l.empty());
-        if (!s.empty())
-            if (name2index.count("-" + s) != 0)
-                throw duplicate_option_error("Short name '" + s + "' is already present");
-            else
-                name2index["-" + s] = options.size();
-        if (!l.empty())
-            if (name2index.count(s) != 0)
-                throw duplicate_option_error("Long name '" + s + "' is already present");
-            else
-                name2index[l] = options.size();
-        options.push_back(desc);
+        m_options.push_back(desc);
         belong_to_group.push_back(false);
     }
 
     options_description&
     options_description::add(const options_description& desc)
     {
-        groups.push_back(desc);
+        shared_ptr<options_description> d(new options_description(desc));
+        groups.push_back(d);
 
-        for (size_t i = 0; i < desc.options.size(); ++i) {
-            add(desc.options[i]);
+        for (size_t i = 0; i < desc.m_options.size(); ++i) {
+            add(desc.m_options[i]);
             belong_to_group.back() = true;
         }
 
@@ -196,75 +239,63 @@ namespace boost { namespace program_options {
         return options_description_easy_init(this);
     }
 
-    unsigned
-    options_description::count(const std::string& name) const
-    {
-        return name2index.count(name);
-    }
-
-    unsigned
-    options_description::count_approx(const std::string& prefix) const
-    {
-        approximation_range er = find_approximation(prefix);
-        return distance(er.first, er.second);
-    }
-
     const option_description&
-    options_description::find(const std::string& name) const
+    options_description::find(const std::string& name, bool approx) const
     {
-        assert(this->count(name) != 0);
-        return *options[name2index.find(name)->second];
+        const option_description* d = find_nothrow(name, approx);
+        if (!d)
+            boost::throw_exception(unknown_option(name));
+        return *d;
     }
 
-    const option_description&
-    options_description::find_approx(const std::string& prefix) const
+    const std::vector< shared_ptr<option_description> >& 
+    options_description::options() const
     {
-        approximation_range er = find_approximation(prefix);
-        assert(distance(er.first, er.second) == 1);
-        return *options[er.first->second];
+        return m_options;
     }
 
-    std::set<std::string>
-    options_description::keys() const
+    const option_description*
+    options_description::find_nothrow(const std::string& name, 
+                                      bool approx) const
     {
-        set<string> result;
-        for (map<string, int>::const_iterator i = name2index.begin();
-             i != name2index.end();
-             ++i)
-            result.insert(i->first);
-        return result;
-    }
+        shared_ptr<option_description> found;
+        vector<string> approximate_matches;
+        // We use linear search because matching specified option
+        // name with the declared option name need to take care about
+        // case sensitivity and trailing '*' and so we can't use simple map.
+        for(unsigned i = 0; i < m_options.size(); ++i)
+        {
+            option_description::match_result r = 
+                m_options[i]->match(name, approx);
 
-    std::set<std::string>
-    options_description::primary_keys() const
-    {
-        set<string> result;
-        for (size_t i = 0; i < options.size(); ++i)
-            if (options[i]->long_name().empty())
-                result.insert("-" + options[i]->short_name());
-            else
-                result.insert(options[i]->long_name());
-        return result;
-    }
+            if (r == option_description::no_match)
+                continue;
 
-    std::set<std::string>
-    options_description::approximations(const std::string& prefix) const
-    {
-        approximation_range er = find_approximation(prefix);
-        set<string> result;
-        for (name2index_iterator i = er.first; i != er.second; ++i)
-            result.insert(i->first);
-        return result;
-    }
+            // If we have a full patch, and an approximate match,
+            // ignore approximate match instead of reporting error.
+            // Say, if we have options "all" and "all-chroots", then
+            // "--all" on the command line should select the first one,
+            // without ambiguity.
+            //
+            // For now, we don't check the situation when there are 
+            // two full matches. 
 
-    options_description::approximation_range
-    options_description::find_approximation(const std::string& prefix) const
-    {
-        name2index_iterator b = name2index.lower_bound(prefix);
-        name2index_iterator e = name2index.upper_bound(prefix + char(CHAR_MAX));
-        return make_pair(b, e);
-    }
+            if (r == option_description::full_match)
+            {
+                return m_options[i].get();
+            }
 
+            found = m_options[i];
+            // FIXME: the use of 'key' here might not
+            // be the best approach.
+            approximate_matches.push_back(m_options[i]->key(name));
+        }
+        if (approximate_matches.size() > 1)
+            boost::throw_exception(
+                ambiguous_option(name, approximate_matches));
+
+        return found.get();
+    }
 
     BOOST_PROGRAM_OPTIONS_DECL
     std::ostream& operator<<(std::ostream& os, const options_description& desc)
@@ -274,21 +305,212 @@ namespace boost { namespace program_options {
     }
 
     namespace {
+
+        /* Given a string 'par', that contains no newline characters
+           outputs it to 'os' with wordwrapping, that is, as several
+           line.
+
+           Each output line starts with 'indent' space characters, 
+           following by characters from 'par'. The total length of
+           line is no longer than 'line_length'.
+                                      
+        */
+        void format_paragraph(std::ostream& os,
+                              std::string par,
+                              unsigned indent,
+                              unsigned line_length)
+        {                    
+            // Through reminder of this function, 'line_length' will
+            // be the length available for characters, not including
+            // indent.
+            assert(indent < line_length);
+            line_length -= indent;
+
+            // index of tab (if present) is used as additional indent relative
+            // to first_column_width if paragrapth is spanned over multiple
+            // lines if tab is not on first line it is ignored
+            string::size_type par_indent = par.find('\t');
+
+            if (par_indent == string::npos)
+            {
+                par_indent = 0;
+            }
+            else
+            {
+                // only one tab per paragraph allowed
+                if (count(par.begin(), par.end(), '\t') > 1)
+                {
+                    boost::throw_exception(program_options::error(
+                        "Only one tab per paragraph is allowed"));
+                }
+          
+                // erase tab from string
+                par.erase(par_indent, 1);
+
+                // this assert may fail due to user error or 
+                // environment conditions!
+                assert(par_indent < line_length);
+
+                // ignore tab if not on first line
+                if (par_indent >= line_length)
+                {
+                    par_indent = 0;
+                }            
+            }
+          
+            if (par.size() < line_length)
+            {
+                os << par;
+            }
+            else
+            {
+                string::const_iterator       line_begin = par.begin();
+                const string::const_iterator par_end = par.end();
+
+                bool first_line = true; // of current paragraph!        
+            
+                while (line_begin < par_end)  // paragraph lines
+                {
+                    if (!first_line)
+                    {
+                        // If line starts with space, but second character
+                        // is not space, remove the leading space.
+                        // We don't remove double spaces because those
+                        // might be intentianal.
+                        if ((*line_begin == ' ') &&
+                            ((line_begin + 1 < par_end) &&
+                             (*(line_begin + 1) != ' ')))
+                        {
+                            line_begin += 1;  // line_begin != line_end
+                        }
+                    }
+
+                    // Take care to never increment the iterator past
+                    // the end, since MSVC 8.0 (brokenly), assumes that
+                    // doing that, even if no access happens, is a bug.
+                    unsigned remaining = distance(line_begin, par_end);
+                    string::const_iterator line_end = line_begin + 
+                        ((remaining < line_length) ? remaining : line_length);
+            
+                    // prevent chopped words
+                    // Is line_end between two non-space characters?
+                    if ((*(line_end - 1) != ' ') &&
+                        ((line_end < par_end) && (*line_end != ' ')))
+                    {
+                        // find last ' ' in the second half of the current paragraph line
+                        string::const_iterator last_space =
+                            find(reverse_iterator<string::const_iterator>(line_end),
+                                 reverse_iterator<string::const_iterator>(line_begin),
+                                 ' ')
+                            .base();
+                
+                        if (last_space != line_begin)
+                        {                 
+                            // is last_space within the second half ot the 
+                            // current line
+                            if (unsigned(distance(last_space, line_end)) < 
+                                (line_length - indent) / 2)
+                            {
+                                line_end = last_space;
+                            }
+                        }                                                
+                    } // prevent chopped words
+             
+                    // write line to stream
+                    copy(line_begin, line_end, ostream_iterator<char>(os));
+              
+                    if (first_line)
+                    {
+                        indent += par_indent;
+                        first_line = false;
+                    }
+
+                    // more lines to follow?
+                    if (line_end != par_end)
+                    {
+                        os << '\n';
+                
+                        for(unsigned pad = indent; pad > 0; --pad)
+                        {
+                            os.put(' ');
+                        }                                                        
+                    }
+              
+                    // next line starts after of this line
+                    line_begin = line_end;              
+                } // paragraph lines
+            }          
+        }                              
+        
+        void format_description(std::ostream& os,
+                                const std::string& desc, 
+                                unsigned first_column_width,
+                                unsigned line_length)
+        {
+            // we need to use one char less per line to work correctly if actual
+            // console has longer lines
+            assert(line_length > 1);
+            if (line_length > 1)
+            {
+                --line_length;
+            }
+
+            // line_length must be larger than first_column_width
+            // this assert may fail due to user error or environment conditions!
+            assert(line_length > first_column_width);
+
+            // Note: can't use 'tokenizer' as name of typedef -- borland
+            // will consider uses of 'tokenizer' below as uses of
+            // boost::tokenizer, not typedef.
+            typedef boost::tokenizer<boost::char_separator<char> > tok;
+          
+            tok paragraphs(
+                desc,
+                char_separator<char>("\n", "", boost::keep_empty_tokens));
+          
+            tok::const_iterator       par_iter = paragraphs.begin();                
+            const tok::const_iterator par_end = paragraphs.end();
+
+            while (par_iter != par_end)  // paragraphs
+            {
+                format_paragraph(os, *par_iter, first_column_width, 
+                                 line_length);
+            
+                ++par_iter;
+            
+                // prepair next line if any
+                if (par_iter != par_end)
+                {
+                    os << '\n';
+              
+                    for(unsigned pad = first_column_width; pad > 0; --pad)
+                    {
+                        os.put(' ');
+                    }                    
+                }            
+            }  // paragraphs
+        }
+    
         void format_one(std::ostream& os, const option_description& opt, 
-                        unsigned first_column_width)
+                        unsigned first_column_width, unsigned line_length)
         {
             stringstream ss;
             ss << "  " << opt.format_name() << ' ' << opt.format_parameter();
             
             // Don't use ss.rdbuf() since g++ 2.96 is buggy on it.
             os << ss.str();
-            
-            if (!opt.description().empty()) {
-                
-                for(int pad = first_column_width - ss.str().size(); pad > 0; --pad) {
+
+            if (!opt.description().empty())
+            {
+                for(unsigned pad = first_column_width - ss.str().size(); 
+                    pad > 0; 
+                    --pad)
+                {
                     os.put(' ');
                 }
-                os << " : " << opt.description();
+            
+                format_description(os, opt.description(),
+                                   first_column_width, line_length);
             }
         }
     }
@@ -300,31 +522,34 @@ namespace boost { namespace program_options {
             os << m_caption << ":\n";
 
         /* Find the maximum width of the option column */
-        unsigned width(24);
+        unsigned width(23);
         unsigned i; // vc6 has broken for loop scoping
-        for (i = 0; i < options.size(); ++i)
+        for (i = 0; i < m_options.size(); ++i)
         {
-            const option_description& opt = *options[i];
+            const option_description& opt = *m_options[i];
             stringstream ss;
             ss << "  " << opt.format_name() << ' ' << opt.format_parameter();
-            width = max(width, static_cast<unsigned>(ss.str().size()));            
+            width = (max)(width, static_cast<unsigned>(ss.str().size()));            
         }
-
+        
+        /* add an additional space to improve readability */
+        ++width;
+            
         /* The options formatting style is stolen from Subversion. */
-        for (i = 0; i < options.size(); ++i)
+        for (i = 0; i < m_options.size(); ++i)
         {
             if (belong_to_group[i])
                 continue;
 
-            const option_description& opt = *options[i];
+            const option_description& opt = *m_options[i];
 
-            format_one(os, opt, width);
+            format_one(os, opt, width, m_line_length);
 
             os << "\n";
         }
 
         for (unsigned j = 0; j < groups.size(); ++j) {            
-            os << "\n" << groups[j];
+            os << "\n" << *groups[j];
         }
     }
 

src/parsers.cpp

@@ -17,7 +17,9 @@
 #include <boost/program_options/detail/convert.hpp>
 
 #include <boost/bind.hpp>
+#include <boost/throw_exception.hpp>
 
+#include <cctype>
 
 #if !defined(__GNUC__) || __GNUC__ < 3
 #include <iostream>
@@ -83,118 +85,30 @@ namespace boost { namespace program_options {
     }
 #endif
 
-    namespace detail
-    {
-        void
-        parse_command_line(cmdline& cmd, parsed_options& result);
-    }
-
-    common_command_line_parser::
-    common_command_line_parser(const std::vector<std::string>& args)
-    : m_style(0), m_desc(0), m_positional(0), m_args(args)
-    {}
-
-    parsed_options
-    common_command_line_parser::run() const
-    {
-        parsed_options result(m_desc);
-        detail::cmdline cmd(m_args, m_style);
-        cmd.set_additional_parser(m_ext);
-
-        if (m_desc) {
-            set<string> keys = m_desc->primary_keys();
-            for (set<string>::iterator i = keys.begin(); i != keys.end(); ++i) {
-                const option_description& d = m_desc->find(*i);
-                char s = d.short_name().empty() ? '\0' : d.short_name()[0];
-
-                shared_ptr<const value_semantic> vs = d.semantic();
-                char flags;
-                if (vs->zero_tokens())
-                    flags = '|';
-                else
-                    if (vs->is_implicit()) 
-                        if (vs->is_multitoken())
-                            flags = '*';
-                        else
-                            flags = '?';
-                    else if (vs->is_multitoken())
-                        flags = '+';
-                    else flags = ':';
-
-                cmd.add_option(d.long_name(), s, flags, 1);
-            }
-        }
-
-        detail::parse_command_line(cmd, result);
-
-        if (m_positional)
-        {
-            unsigned position = 0;
-            for (unsigned i = 0; i < result.options.size(); ++i) {
-                option& opt = result.options[i];
-                if (opt.position_key != -1) {
-                    if (position >= m_positional->max_total_count())
-                    {
-                        throw too_many_positional_options_error(
-                            "too much positional options");
-                    }
-                    opt.string_key = m_positional->name_for_position(position);
-                    ++position;
-                }
-            }
-        }
-
-        return result;        
-    }
-
-
-    namespace detail {
-        void
-        parse_command_line(cmdline& cmd, parsed_options& result)
-        {
-            int position(0);
-            
-            while(++cmd) {
-                
-                option n;
-                
-                if (cmd.at_option()) {
-                    if (*cmd.option_name().rbegin() != '*') {
-                        n.string_key = cmd.option_name();
-                    }
-                    else {
-                        n.string_key = cmd.raw_option_name();
-                    }
-                    n.value = cmd.option_values();
-                } else {
-                    n.position_key = position++;
-                    n.value.clear();
-                    n.value.push_back(cmd.argument());
-                }
-                result.options.push_back(n);
-            }
-        }
-    }
-
     template<class charT>
     basic_parsed_options<charT>
     parse_config_file(std::basic_istream<charT>& is, 
-                      const options_description& desc)
+                      const options_description& desc,
+                      bool allow_unregistered)
     {    
         set<string> allowed_options;
-        set<string> pm = desc.primary_keys();
-        for (set<string>::iterator i = pm.begin(); i != pm.end(); ++i) {
-            const option_description& d = desc.find(*i);
+
+        const vector<shared_ptr<option_description> >& options = desc.options();
+        for (unsigned i = 0; i < options.size(); ++i)
+        {
+            const option_description& d = *options[i];
 
             if (d.long_name().empty())
-                throw error("long name required for config file");
+                boost::throw_exception(
+                    error("long name required for config file"));
 
             allowed_options.insert(d.long_name());
         }
 
         // Parser return char strings
         parsed_options result(&desc);        
-        copy(detail::basic_config_file_iterator<charT>(is, allowed_options), 
+        copy(detail::basic_config_file_iterator<charT>(
+                 is, allowed_options, allow_unregistered), 
              detail::basic_config_file_iterator<charT>(), 
              back_inserter(result.options));
         // Convert char strings into desired type.
@@ -204,13 +118,15 @@ namespace boost { namespace program_options {
     template
     BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<char>
     parse_config_file(std::basic_istream<char>& is, 
-                      const options_description& desc);
+                      const options_description& desc,
+                      bool allow_unregistered);
 
 #ifndef BOOST_NO_STD_WSTRING
     template
     BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t>
     parse_config_file(std::basic_istream<wchar_t>& is, 
-                      const options_description& desc);
+                      const options_description& desc,
+                      bool allow_unregistered);
 #endif
     
 // This versio, which accepts any options without validation, is disabled,

src/positional_options.cpp

@@ -17,7 +17,7 @@ namespace boost { namespace program_options {
     positional_options_description::positional_options_description()
     {}
 
-    void
+    positional_options_description&
     positional_options_description::add(const char* name, int max_count)
     {
         assert(max_count != -1 || m_trailing.empty());
@@ -27,14 +27,14 @@ namespace boost { namespace program_options {
         else {
             m_names.resize(m_names.size() + max_count, name);
         }
-        
+        return *this;
     }
 
     unsigned
     positional_options_description::max_total_count() const
     {
         return m_trailing.empty() ? 
-        m_names.size() : std::numeric_limits<unsigned>::max();
+          m_names.size() : (std::numeric_limits<unsigned>::max)();
     }
     
     const std::string& 

src/utf8_codecvt_facet.cpp

@@ -1,346 +1,21 @@
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// utf8_codecvt_facet.cpp
+// Copyright Vladimir Prus 2004.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-// Copyright © 2001 Ronald Garcia, Indiana University (garcia@osl.iu.edu)
-// Andrew Lumsdaine, Indiana University (lums@osl.iu.edu). 
-// Use, modification and distribution is subject to the Boost Software
-// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
-// http://www.boost.org/LICENSE_1_0.txt)
-
-#include <cstdlib> // for multi-byte converson routines
-
-#include <cassert>
 #define BOOST_PROGRAM_OPTIONS_SOURCE
-#include <boost/program_options/detail/utf8_codecvt_facet.hpp>
+#include <boost/program_options/config.hpp>
 
-namespace boost { namespace program_options { namespace detail {
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// implementation for wchar_t
+#define BOOST_UTF8_BEGIN_NAMESPACE \
+     namespace boost { namespace program_options { namespace detail {
 
-// Translate incoming UTF-8 into UCS-4
-std::codecvt_base::result utf8_codecvt_facet_wchar_t::do_in(
-    mbstate_t& state, 
-    const char * from,
-    const char * from_end, 
-    const char * & from_next,
-    wchar_t * to, 
-    wchar_t * to_end, 
-    wchar_t * & to_next
-) const {
-    // Basic algorithm:  The first octet determines how many
-    // octets total make up the UCS-4 character.  The remaining
-    // "continuing octets" all begin with "10". To convert, subtract
-    // the amount that specifies the number of octets from the first
-    // octet.  Subtract 0x80 (1000 0000) from each continuing octet,
-    // then mash the whole lot together.  Note that each continuing
-    // octet only uses 6 bits as unique values, so only shift by
-    // multiples of 6 to combine.
-    while (from != from_end && to != to_end) {
+#define BOOST_UTF8_END_NAMESPACE }}}
+#define BOOST_UTF8_DECL BOOST_PROGRAM_OPTIONS_DECL
 
-        // Error checking   on the first octet
-        if (invalid_leading_octet(*from)){
-            from_next = from;
-            to_next = to;
-            return std::codecvt_base::error;
-        }
+#include "../../detail/utf8_codecvt_facet.cpp"
 
-        // The first octet is   adjusted by a value dependent upon 
-        // the number   of "continuing octets" encoding the character
-        const   int cont_octet_count = get_cont_octet_count(*from);
-        const   wchar_t octet1_modifier_table[] =   {
-            0x00, 0xc0, 0xe0, 0xf0, 0xf8, 0xfc
-        };
 
-        // The unsigned char conversion is necessary in case char is
-        // signed   (I learned this the hard way)
-        wchar_t ucs_result = 
-            (unsigned char)(*from++) - octet1_modifier_table[cont_octet_count];
+#undef BOOST_UTF8_BEGIN_NAMESPACE
+#undef BOOST_UTF8_END_NAMESPACE
+#undef BOOST_UTF8_DECL
 
-        // Invariants   : 
-        //   1) At the start of the loop,   'i' continuing characters have been
-        //    processed 
-        //   2) *from   points to the next continuing character to be processed.
-        int i   = 0;
-        while(i != cont_octet_count && from != from_end) {
-
-            // Error checking on continuing characters
-            if (invalid_continuing_octet(*from)) {
-                from_next   = from;
-                to_next =   to;
-                return std::codecvt_base::error;
-            }
-
-            ucs_result *= (1 << 6); 
-
-            // each continuing character has an extra (10xxxxxx)b attached to 
-            // it that must be removed.
-            ucs_result += (unsigned char)(*from++) - 0x80;
-            ++i;
-        }
-
-        // If   the buffer ends with an incomplete unicode character...
-        if (from == from_end && i   != cont_octet_count) {
-            // rewind "from" to before the current character translation
-            from_next = from - (i+1); 
-            to_next = to;
-            return std::codecvt_base::partial;
-        }
-        *to++   = ucs_result;
-    }
-    from_next = from;
-    to_next = to;
-
-    // Were we done converting or did we run out of destination space?
-    if(from == from_end) return std::codecvt_base::ok;
-    else return std::codecvt_base::partial;
-}
-
-std::codecvt_base::result utf8_codecvt_facet_wchar_t::do_out(
-    mbstate_t& state, 
-    const wchar_t *   from,
-    const wchar_t * from_end, 
-    const wchar_t * & from_next,
-    char * to, 
-    char * to_end, 
-    char * & to_next
-) const
-{
-    // RG - consider merging this table with the other one
-    const wchar_t octet1_modifier_table[] = {
-        0x00, 0xc0, 0xe0, 0xf0, 0xf8, 0xfc
-    };
-
-    while (from != from_end && to != to_end) {
-
-        // Check for invalid UCS-4 character
-        if (*from  > WCHAR_MAX) {
-            from_next = from;
-            to_next = to;
-            return std::codecvt_base::error;
-        }
-
-        int cont_octet_count = get_cont_octet_out_count(*from);
-
-        // RG  - comment this formula better
-        int shift_exponent = (cont_octet_count) *   6;
-
-        // Process the first character
-        *to++ = octet1_modifier_table[cont_octet_count] +
-            (unsigned char)(*from / (1 << shift_exponent));
-
-        // Process the continuation characters 
-        // Invariants: At   the start of the loop:
-        //   1) 'i' continuing octets   have been generated
-        //   2) '*to'   points to the next location to place an octet
-        //   3) shift_exponent is   6 more than needed for the next octet
-        int i   = 0;
-        while   (i != cont_octet_count && to != to_end) {
-            shift_exponent -= 6;
-            *to++ = 0x80 + ((*from / (1 << shift_exponent)) % (1 << 6));
-            ++i;
-        }
-        // If   we filled up the out buffer before encoding the character
-        if(to   == to_end && i != cont_octet_count) {
-            from_next = from;
-            to_next = to - (i+1);
-            return std::codecvt_base::partial;
-        }
-        *from++;
-    }
-    from_next = from;
-    to_next = to;
-    // Were we done or did we run out of destination space
-    if(from == from_end) return std::codecvt_base::ok;
-    else return std::codecvt_base::partial;
-}
-
-// How many char objects can I process to get <= max_limit
-// wchar_t objects?
-int utf8_codecvt_facet_wchar_t::do_length(
-    mbstate_t &,
-    const char * from,
-    const char * from_end, 
-    std::size_t max_limit
-) const
-{ 
-    // RG - this code is confusing!  I need a better way to express it.
-    // and test cases.
-
-    // Invariants:
-    // 1) last_octet_count has the size of the last measured character
-    // 2) char_count holds the number of characters shown to fit
-    // within the bounds so far (no greater than max_limit)
-    // 3) from_next points to the octet 'last_octet_count' before the
-    // last measured character.  
-    int last_octet_count=0;
-    std::size_t char_count = 0;
-    const char* from_next = from;
-    // Use "<" because the buffer may represent incomplete characters
-    while (from_next+last_octet_count <= from_end && char_count <= max_limit) {
-        from_next += last_octet_count;
-        last_octet_count = (get_octet_count(*from_next));
-        ++char_count;
-    }
-    return from_next-from_end;
-}
-
-unsigned int utf8_codecvt_facet_wchar_t::get_octet_count(
-    unsigned char   lead_octet
-){
-    // if the 0-bit (MSB) is 0, then 1 character
-    if (lead_octet <= 0x7f) return 1;
-
-    // Otherwise the count number of consecutive 1 bits starting at MSB
-//    assert(0xc0 <= lead_octet && lead_octet <= 0xfd);
-
-    if (0xc0 <= lead_octet && lead_octet <= 0xdf) return 2;
-    else if (0xe0 <= lead_octet && lead_octet <= 0xef) return 3;
-    else if (0xf0 <= lead_octet && lead_octet <= 0xf7) return 4;
-    else if (0xf8 <= lead_octet && lead_octet <= 0xfb) return 5;
-    else return 6;
-}
-}}}
-
-namespace {
-template<std::size_t s>
-int get_cont_octet_out_count_impl(wchar_t word){
-    if (word < 0x80) {
-        return 0;
-    }
-    if (word < 0x800) {
-        return 1;
-    }
-    return 2;
-}
-
-template<>
-int get_cont_octet_out_count_impl<4>(wchar_t word){
-    if (word < 0x80) {
-        return 0;
-    }
-    if (word < 0x800) {
-        return 1;
-    }
-    if (word < 0x10000) {
-        return 2;
-    }
-    if (word < 0x200000) {
-        return 3;
-    }
-    if (word < 0x4000000) {
-        return 4;
-    }
-    return 5;
-}
-
-} // namespace anonymous
-
-namespace boost { namespace program_options { namespace detail {
-// How many "continuing octets" will be needed for this word
-// ==   total octets - 1.
-int utf8_codecvt_facet_wchar_t::get_cont_octet_out_count(
-    wchar_t word
-) const {
-    return get_cont_octet_out_count_impl<sizeof(wchar_t)>(word);
-}
-}}}
-
-#if 0 // not used?
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// implementation for char
-
-std::codecvt_base::result utf8_codecvt_facet_char::do_in(
-    mbstate_t & state, 
-    const char * from, 
-    const char * from_end, 
-    const char * & from_next,
-    char * to, 
-    char * to_end, 
-    char * & to_next
-) const
-{
-    while(from_next < from_end){
-        wchar_t w;
-        wchar_t *wnext = & w;
-        utf8_codecvt_facet_wchar_t::result ucs4_result;
-        ucs4_result = base_class::do_in(
-            state,
-            from, from_end, from_next,
-            wnext, wnext + 1, wnext
-        );
-        if(codecvt_base::ok != ucs4_result)
-            return ucs4_result;
-        // if the conversion succeeds. 
-        int length = std::wctomb(to_next, w);
-//        assert(-1 != length);
-        to_next += length;
-    }
-    return codecvt_base::ok;
-}
-
-std::codecvt_base::result utf8_codecvt_facet_char::do_out(
-    std::mbstate_t & state, 
-    const char * from,
-    const char * from_end, 
-    const char * & from_next,
-    char * to, 
-    char * to_end, 
-    char * & to_next
-) const
-{
-    while(from_next < from_end){
-        wchar_t w;
-        int result = std::mbtowc(&w, from_next,  MB_LENGTH_MAX);
- //       assert(-1 != result);
-        from_next += result;
-        utf8_codecvt_facet_wchar_t::result ucs4_result;
-
-        const wchar_t *wptr = & w;
-        ucs4_result = base_class::do_out(
-            state,
-            wptr, wptr+1, wptr,
-            to_next, to_end, to_next
-        );
-        if(codecvt_base::ok != ucs4_result)
-            return ucs4_result;     
-    }
-    return codecvt_base::ok;
-}
-
-// How many bytes objects can I process to get <= max_limit
-// char objects?
-int utf8_codecvt_facet_char::do_length(
-    const mbstate_t & initial_state,
-    const char * from_next,
-    const char * from_end, 
-    std::size_t max_limit
-) const
-{
-    int total_length = 0;
-    const char *from = from_next;
-    mbstate_t state = initial_state;
-    while(from_next < from_end){
-        wchar_t w;
-        wchar_t *wnext = & w;
-        utf8_codecvt_facet_wchar_t::result ucs4_result;
-        ucs4_result = base_class::do_in(
-            state,
-            from_next, from_end, from_next,
-            wnext, wnext + 1, wnext
-        );
-
-        if(codecvt_base::ok != ucs4_result)
-            break;
-
-        char carray[MB_LENGTH_MAX];
-        std::size_t count = wctomb(carray, w);
-        if(count > max_limit)
-            break;
-
-        max_limit -= count;
-        total_length = from_next - from;
-    }
-    return total_length;
-}
-}
-#endif

src/value_semantic.cpp

@@ -8,6 +8,8 @@
 #include <boost/program_options/value_semantic.hpp>
 #include <boost/program_options/detail/convert.hpp>
 
+#include <cctype>
+
 namespace boost { namespace program_options {
 
     using namespace std;
@@ -28,7 +30,8 @@ namespace boost { namespace program_options {
             }
             xparse(value_store, local_tokens);
 #else
-            throw std::runtime_error("UTF-8 conversion not supported.");
+            boost::throw_exception(
+                std::runtime_error("UTF-8 conversion not supported."));
 #endif
         } else {
             // Already in local encoding, pass unmodified
@@ -68,15 +71,35 @@ namespace boost { namespace program_options {
     {
         return arg;
     }
+    
+    unsigned 
+    untyped_value::min_tokens() const
+    {
+        if (m_zero_tokens)
+            return 0;
+        else
+            return 1;
+    }
+
+    unsigned 
+    untyped_value::max_tokens() const
+    {
+        if (m_zero_tokens)
+            return 0;
+        else
+            return 1;
+    }
+
 
     void 
     untyped_value::xparse(boost::any& value_store,
                           const std::vector<std::string>& new_tokens) const
     {
         if (!value_store.empty()) 
-            throw multiple_occurences("multiple_occurences");
+            boost::throw_exception(
+                multiple_occurrences("multiple_occurrences"));
         if (new_tokens.size() > 1)
-            throw multiple_values("multiple_values");
+            boost::throw_exception(multiple_values("multiple_values"));
         value_store = new_tokens.empty() ? std::string("") : new_tokens.front();
     }
 
@@ -91,7 +114,7 @@ namespace boost { namespace program_options {
     {
         typed_value<bool>* r = new typed_value<bool>(v);
         r->default_value(0);
-        r->implicit();
+        r->zero_tokens();
 
         return r;
     }
@@ -99,13 +122,13 @@ namespace boost { namespace program_options {
     /* Validates bool value.
         Any of "1", "true", "yes", "on" will be converted to "1".<br>
         Any of "0", "false", "no", "off" will be converted to "0".<br>
-        Case is ignored. Regardless of name passed, parameter will always
-        be optional.
+        Case is ignored. The 'xs' vector can either be empty, in which
+        case the value is 'true', or can contain explicit value.
     */
     BOOST_PROGRAM_OPTIONS_DECL void validate(any& v, const vector<string>& xs,
                        bool*, int)
     {
-        check_first_occurence(v);
+        check_first_occurrence(v);
         string s(get_single_string(xs, true));
 
         for (size_t i = 0; i < s.size(); ++i)
@@ -116,18 +139,19 @@ namespace boost { namespace program_options {
         else if (s == "off" || s == "no" || s == "0" || s == "false")
             v = any(false);
         else
-            throw validation_error("'" + s + "' doesn't look like a bool value.");
+            boost::throw_exception(validation_error(
+                                "'" + s + "' doesn't look like a bool value."));
     }
 
     // This is blatant copy-paste. However, templating this will cause a problem,
     // since wstring can't be constructed/compared with char*. We'd need to
-    // create auxilliary 'widen' routine to convert from char* into 
+    // create auxiliary 'widen' routine to convert from char* into 
     // needed string type, and that's more work.
 #if !defined(BOOST_NO_STD_WSTRING)
     BOOST_PROGRAM_OPTIONS_DECL 
     void validate(any& v, const vector<wstring>& xs, bool*, int)
     {
-        check_first_occurence(v);
+        check_first_occurrence(v);
         wstring s(get_single_string(xs, true));
 
         for (size_t i = 0; i < s.size(); ++i)
@@ -138,17 +162,20 @@ namespace boost { namespace program_options {
         else if (s == L"off" || s == L"no" || s == L"0" || s == L"false")
             v = any(false);
         else
-            throw validation_error("invalid bool value");
+            boost::throw_exception(validation_error("invalid bool value"));
     }
 #endif
     BOOST_PROGRAM_OPTIONS_DECL 
     void validate(any& v, const vector<string>& xs, std::string*, int)
     {
-        check_first_occurence(v);
+        check_first_occurrence(v);
         string s(get_single_string(xs));
-        if (*s.begin() == '\'' && *s.rbegin() == '\'' ||
-            *s.begin() == '"' && *s.rbegin() == '"')
+        if (!s.empty() && (
+                (*s.begin() == '\'' && *s.rbegin() == '\'' ||
+                 *s.begin() == '"' && *s.rbegin() == '"')))
+        {
             v = any(s.substr(1, s.size()-2));
+        }
         else
             v = any(s);
     }
@@ -157,7 +184,7 @@ namespace boost { namespace program_options {
     BOOST_PROGRAM_OPTIONS_DECL 
     void validate(any& v, const vector<wstring>& xs, std::string*, int)
     {
-        check_first_occurence(v);
+        check_first_occurrence(v);
         wstring s(get_single_string(xs));
         if (*s.begin() == L'\'' && *s.rbegin() == L'\'' ||
             *s.begin() == L'"' && *s.rbegin() == L'"')
@@ -170,10 +197,63 @@ namespace boost { namespace program_options {
     namespace validators {
 
         BOOST_PROGRAM_OPTIONS_DECL 
-        void check_first_occurence(const boost::any& value)
+        void check_first_occurrence(const boost::any& value)
         {
             if (!value.empty())
-                throw multiple_occurences("multiple_occurences");
+                boost::throw_exception(
+                    multiple_occurrences("multiple_occurrences"));
+        }
+    }
+
+
+    invalid_option_value::
+    invalid_option_value(const std::string& bad_value)
+    : validation_error(string("invalid option value '")
+                       .append(bad_value).append("'"))
+    {}
+
+#ifndef BOOST_NO_STD_WSTRING
+
+    namespace
+    {
+        std::string convert_value(const std::wstring& s)
+        {
+            try {
+                return to_local_8_bit(s);
+            }
+            catch(const std::exception&) {
+                return "<unrepresentable unicode string>";
+            }
+        }
+    }
+
+    invalid_option_value::
+    invalid_option_value(const std::wstring& bad_value)
+    : validation_error(string("invalid option value '")
+                       .append(convert_value(bad_value))
+                       .append("'"))
+    {}
+#endif                       
+
+
+
+    void validation_error::set_option_name(const std::string& option_name)
+    {
+        m_option_name = option_name;
+    }
+
+    const char* validation_error::what() const throw()
+    {
+        if (!m_option_name.empty())
+        {
+            m_message = "in option '" + m_option_name + "': " 
+                + logic_error::what();
+            return m_message.c_str();
+
+        }
+        else
+        {
+            return logic_error::what();
         }
     }
 

src/variables_map.cpp

@@ -23,6 +23,9 @@ namespace boost { namespace program_options {
     void store(const parsed_options& options, variables_map& xm,
                bool utf8)
     {       
+        // TODO: what if we have different definition
+        // for the same option name during different calls
+        // 'store'.
         assert(options.description);
         const options_description& desc = *options.description;
 
@@ -30,63 +33,90 @@ namespace boost { namespace program_options {
         // variables_map. Ehmm.. messy.
         std::map<std::string, variable_value>& m = xm;
 
-        // The set of existing values that should not be changed.
-        std::set<std::string> final;
-        for (map<string, variable_value>::iterator k = m.begin(); 
-             k != m.end(); 
-             ++k) 
-        {
-            if (!k->second.defaulted()) {
-                // TODO: what if we have different definition
-                // for the same option name during different calls
-                // 'store'.
-                bool composing = desc.count(k->first)
-                    && desc.find(k->first).semantic()->is_composing();
+        std::set<std::string> new_final;
 
-                if (!composing)
-                    final.insert(k->first);
-            }
-        }
+        // Declared once, to please Intel in VC++ mode;
+        unsigned i;
 
         // First, convert/store all given options
-        for (size_t i = 0; i < options.options.size(); ++i) {
+        for (i = 0; i < options.options.size(); ++i) {
 
             const string& name = options.options[i].string_key;
             // Skip positional options without name
             if (name.empty())
                 continue;
 
+            // Ignore unregistered option. The 'unregistered'
+            // field can be true only if user has explicitly asked
+            // to allow unregistered options. We can't store them
+            // to variables map (lacking any information about paring), 
+            // so just ignore them.
+            if (options.options[i].unregistered)
+                continue;
+
             // If option has final value, skip this assignment
-            if (final.count(name))
+            if (xm.m_final.count(name))
                 continue;
 
             // Ignore options which are not described
-            if (desc.count(name) == 0)
-                continue;
+            //TODO: consider this.
+            //if (desc.count(name) == 0)
+            //    continue;
 
-            const option_description& d = desc.find(name);
+            const option_description& d = desc.find(name, false);
 
             variable_value& v = m[name];            
             if (v.defaulted()) {
                 // Explicit assignment here erases defaulted value
                 v = variable_value();
             }
-            d.semantic()->parse(v.value(), options.options[i].value, utf8);
+            
+            try {
+                d.semantic()->parse(v.value(), options.options[i].value, utf8);
+            }
+            catch(validation_error& e)
+            {
+                e.set_option_name(name);
+                throw;
+            }
             v.m_value_semantic = d.semantic();
+            
+            // The option is not composing, and the value is explicitly
+            // provided. Ignore values of this option for subsequent
+            // calls to 'store'. We store this to a temporary set,
+            // so that several assignment inside *this* 'store' call
+            // are allowed.
+            if (!d.semantic()->is_composing())
+                new_final.insert(name);
         }
+        xm.m_final.insert(new_final.begin(), new_final.end());
+
+        
         
         // Second, apply default values.
-        set<string> keys = desc.primary_keys();
-        for (set<string>::const_iterator j = keys.begin(); j != keys.end(); ++j)
-            if (m.count(*j) == 0) {
-                const option_description& d = desc.find(*j);
-
+        const vector<shared_ptr<option_description> >& all = desc.options();
+        for(i = 0; i < all.size(); ++i)
+        {
+            const option_description& d = *all[i];
+            string key = d.key("");
+            // FIXME: this logic relies on knowledge of option_description
+            // internals.
+            // The 'key' is empty if options description contains '*'. 
+            // In that 
+            // case, default value makes no sense at all.
+            if (key.empty())
+            {
+                continue;
+            }
+            if (m.count(key) == 0) {
+            
                 boost::any def;
                 if (d.semantic()->apply_default(def)) {
-                    m[*j] = variable_value(def, true);
-                    m[*j].m_value_semantic = d.semantic();
+                    m[key] = variable_value(def, true);
+                    m[key].m_value_semantic = d.semantic();
                 }
             }        
+        }
     }
 
     BOOST_PROGRAM_OPTIONS_DECL 

src/winmain.cpp

@@ -12,10 +12,12 @@ namespace boost { namespace program_options {
 
     using namespace std;
 
-    // The rules for windows command line are pretty funny, see
+    // Take a command line string and splits in into tokens, according
+    // to the rules windows command line processor uses.
+    // 
+    // The rules are pretty funny, see
     //    http://article.gmane.org/gmane.comp.lib.boost.user/3005
     //    http://msdn.microsoft.com/library/en-us/vccelng/htm/progs_12.asp
-    
     BOOST_PROGRAM_OPTIONS_DECL
     std::vector<std::string> split_winmain(const std::string& input)
     {
@@ -23,7 +25,7 @@ namespace boost { namespace program_options {
 
         string::const_iterator i = input.begin(), e = input.end();
         for(;i != e; ++i)
-            if (!isspace(*i))
+            if (!isspace((unsigned char)*i))
                 break;
        
         if (i != e) {
@@ -55,11 +57,11 @@ namespace boost { namespace program_options {
                         current.append(backslash_count, '\\');
                         backslash_count = 0;
                     }
-                    if (isspace(*i) && !inside_quoted) {
+                    if (isspace((unsigned char)*i) && !inside_quoted) {
                         // Space outside quoted section terminate the current argument
                         result.push_back(current);
                         current.resize(0);
-                        for(;i != e && isspace(*i); ++i)
+                        for(;i != e && isspace((unsigned char)*i); ++i)
                             ;
                         --i;
                     } else {                  
@@ -86,7 +88,7 @@ namespace boost { namespace program_options {
     {
         vector<wstring> result;
         vector<string> aux = split_winmain(to_internal(cmdline));
-        for (unsigned i = 0, e = result.size(); i < e; ++i)
+        for (unsigned i = 0, e = aux.size(); i < e; ++i)
             result.push_back(from_utf8(aux[i]));
         return result;        
     }

test/Jamfile

@@ -1,47 +0,0 @@
-
-subproject libs/program_options/test ;
-
-import testing ;
-
-rule program-options-test ( name )
-{
-    return [ 
-      run $(name).cpp <lib>../build/boost_program_options
-        <lib>../../test/build/boost_test_exec_monitor : :
-        : <include>$(BOOST_ROOT) 
-          std::facet-support std::locale-support ]
-    ;
-}
-
-rule program-options-dll-test ( name )
-{
-    return [ 
-      run $(name).cpp <dll>../build/boost_program_options
-        <lib>../../test/build/boost_test_exec_monitor : :
-        : <include>$(BOOST_ROOT) 
-          <define>BOOST_ALL_DYN_LINK=1
-          <runtime-link>dynamic
-        : $(name)_dll ]
-    ;
-}
-
-
-test-suite program_options : 
-    [ program-options-test options_description_test ]
-    [ program-options-test parsers_test ]
-    [ program-options-test variable_map_test ]
-    [ program-options-test cmdline_test ]
-    [ program-options-test positional_options_test ]
-    [ program-options-test unicode_test ]
-    [ program-options-test winmain ] 
-    [ program-options-dll-test options_description_test ]
-    [ program-options-dll-test parsers_test ]
-    [ program-options-dll-test variable_map_test ]
-    [ program-options-dll-test cmdline_test ]
-    [ program-options-dll-test positional_options_test ]
-    [ program-options-dll-test unicode_test ]
-    [ program-options-dll-test winmain ] 
-    
-    
-    ;
-

test/Jamfile.v2

@@ -1,21 +1,33 @@
 
 project
     : requirements 
-    <library>../build//program_options
-    <library>/boost/test//boost_test_exec_monitor
-    <hardcode-dll-paths>true
+    <library>../build//boost_program_options
+    <library>/boost/test//boost_test_exec_monitor/<link>static
+    <link>static
+    
+#    <define>_GLIBCXX_CONCEPT_CHECKS
+#    <define>_GLIBCXX_DEBUG
     ;
+    
+rule po-test ( source )
+{
+    return
+        [ run $(source) ]
+	[ run $(source) : : : <link>shared <define>BOOST_PROGRAM_OPTIONS_DYN_LINK=1
+	  : $(source:B)_dll ] 
+    ;	
+}    
 
 test-suite program_options :
 
-    [ run options_description_test.cpp ] 
-    [ run parsers_test.cpp ]
-    [ run variable_map_test.cpp ]
-    [ run cmdline_test.cpp ]
-    [ run positional_options_test.cpp ]
-    [ run unicode_test.cpp ] 
-    [ run winmain.cpp ] 
+    [ po-test options_description_test.cpp ] 
+    [ po-test parsers_test.cpp ]
+    [ po-test variable_map_test.cpp ]
+    [ po-test cmdline_test.cpp ]
+    [ po-test positional_options_test.cpp ]
+    [ po-test unicode_test.cpp ] 
+    [ po-test winmain.cpp ] 
     ;
         
-exe test_convert : test_convert.cpp ../build//program_options ;   
+exe test_convert : test_convert.cpp ;   
 

test/cmdline_test.cpp

@@ -3,8 +3,8 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-
 #include <boost/program_options/cmdline.hpp>
+#include <boost/program_options/options_description.hpp>
 #include <boost/program_options/detail/cmdline.hpp>
 using namespace boost::program_options;
 using boost::program_options::detail::cmdline;
@@ -50,47 +50,49 @@ int translate_syntax_error_kind(invalid_command_line_syntax::kind_t k)
     return std::distance(b, i) + 3;
 }
 
-
 struct test_case {
     const char* input;
     int expected_status;
     const char* expected_result;
 };
 
+
 /* Parses the syntax description in 'syntax' and initialized
-   'cmd' accordingly' */
-void apply_syntax(detail::cmdline& cmd, const char* syntax)
+   'cmd' accordingly' 
+   The "boost::program_options" in parameter type is needed because CW9 
+   has std::detail and it causes an ambiguity.
+*/
+void apply_syntax(options_description& desc, 
+                  const char* syntax)
 {
+   
     string s;
     stringstream ss;
     ss << syntax;
     while(ss >> s) {
-        string long_name;
-        char short_name = '\0';
-        char properties = '|';
+        value_semantic* v = 0;
         
         if (*(s.end()-1) == '=') {
-            properties = ':';
+            v = value<string>();
             s.resize(s.size()-1);
         } else if (*(s.end()-1) == '?') {
-            properties = '?';
+            //v = value<string>()->implicit();
+            v = value<string>();
             s.resize(s.size()-1);
         } else if (*(s.end()-1) == '*') {
-            properties = '*';
+            v = value<vector<string> >()->multitoken();
             s.resize(s.size()-1);
         } else if (*(s.end()-1) == '+') {
-            properties = '+';
+            v = value<vector<string> >()->multitoken();
             s.resize(s.size()-1);
         }
-        string::size_type n = s.find(',');
-        if (n == string::npos) {
-            long_name = s;
+        if (v) {
+            desc.add_options()
+                (s.c_str(), v, "");
         } else {
-            assert(n == s.size()-2);
-            long_name = s.substr(0, s.size()-2);
-            short_name = *s.rbegin();
+            desc.add_options()
+                (s.c_str(), "");
         }
-        cmd.add_option(long_name, short_name, properties, 1);
     }
 }
 
@@ -109,30 +111,36 @@ void test_cmdline(const char* syntax,
                 xinput.push_back(s);
             }
         }
-        detail::cmdline cmd(xinput, style);
+        options_description desc;
+        apply_syntax(desc, syntax);
+
+        cmdline cmd(xinput);
+        cmd.style(style);
+        cmd.set_options_description(desc);
 
-        apply_syntax(cmd, syntax);
 
         string result;
         int status = 0;
 
         try {
-            while(++cmd) {
-                if (cmd.at_argument()) {
+            vector<option> options = cmd.run();
+
+            for(unsigned i = 0; i < options.size(); ++i)
+            {
+                option opt = options[i];
+
+                if (opt.position_key != -1) {
                     if (!result.empty())
                         result += " ";
-                    result += cmd.argument();
+                    result += opt.value[0];
                 } else {
                     if (!result.empty())
                         result += " ";
-                    if (*cmd.option_name().rbegin() != '*')
-                        result += cmd.option_name() + ":";
-                    else
-                        result += cmd.raw_option_name() + ":";
-                    for (size_t i = 0; i < cmd.option_values().size(); ++i) {
-                        if (i != 0)
+                    result += opt.string_key + ":";
+                    for (size_t j = 0; j < opt.value.size(); ++j) {
+                        if (j != 0)
                             result += "-";
-                        result += cmd.option_values()[i];
+                        result += opt.value[j];
                     }                    
                 }
             }
@@ -172,34 +180,28 @@ void test_long_options()
         {"--foo=13", s_extra_parameter, ""},
 
         // Test option with required parameter
-
         {"--bar=", s_empty_adjacent_parameter, ""},
         {"--bar", s_missing_parameter, ""},
-        {"--bar=123", s_success, "bar:123"},
 
-        // Test option with optional parameter
-        {"--baz", s_success, "baz:"},
-        {"--baz=7", s_success, "baz:7"},
+        {"--bar=123", s_success, "bar:123"},
         {0}
     };
-    test_cmdline("foo bar= baz?", style, test_cases1);
+    test_cmdline("foo bar=", style, test_cases1);
+
 
     style = cmdline::style_t(
         allow_long | long_allow_next);
 
     test_case test_cases2[] = {
-        {"--foo", s_success, "foo:"},
-        {"--bar=10", s_long_adjacent_not_allowed, ""},
         {"--bar 10", s_success, "bar:10"},
         {"--bar", s_missing_parameter,  ""},
-        {"--bar --foo", s_missing_parameter, ""},
-        {"--baz", s_success, "baz:"},
-        {"--baz 10", s_success, "baz:10"},
-        {"--baz --foo", s_success, "baz: foo:"},
+        // Since --bar accepts a parameter, --foo is
+        // considered a value, even though it looks like
+        // an option.
+        {"--bar --foo", s_success, "bar:--foo"},
         {0}
     };
-    test_cmdline("foo bar= baz?", style, test_cases2);
-
+    test_cmdline("foo bar=", style, test_cases2);
     style = cmdline::style_t(
         allow_long | long_allow_adjacent
         | long_allow_next);
@@ -207,17 +209,16 @@ void test_long_options()
     test_case test_cases3[] = {
         {"--bar=10", s_success, "bar:10"},
         {"--bar 11", s_success, "bar:11"},
-        {"--baz=12", s_success, "baz:12"},
-        {"--baz 13", s_success, "baz:13"},
-        {"--baz --foo", s_success, "baz: foo:"},
         {0}
     };
-    test_cmdline("foo bar= baz?", style, test_cases3);
+    test_cmdline("foo bar=", style, test_cases3);
 
     style = cmdline::style_t(
         allow_long | long_allow_adjacent
-        | long_allow_next | case_insentitive);
+        | long_allow_next | case_insensitive);
 
+// FIXME: restore
+#if 0
     // Test case insensitive style.
     // Note that option names are normalized to lower case.
     test_case test_cases4[] = {
@@ -229,6 +230,7 @@ void test_long_options()
         {0}
     };
     test_cmdline("foo bar= baz? Giz", style, test_cases4);
+#endif
 }
 
 void test_short_options()
@@ -243,14 +245,14 @@ void test_short_options()
     test_case test_cases1[] = {
         {"-d d /bar", s_success, "-d: d /bar"},
         // This is treated as error when long options are disabled
-        {"--foo", s_long_not_allowed, ""},
+        {"--foo", s_success, "--foo"},
         {"-d13", s_extra_parameter, ""},
         {"-f14", s_success, "-f:14"},
         {"-g -f1", s_success, "-g: -f:1"},
         {"-f", s_missing_parameter, ""},
         {0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases1);
+    test_cmdline(",d ,f= ,g", style, test_cases1);
 
     style = cmdline::style_t(
         allow_short | allow_dash_for_short
@@ -260,18 +262,11 @@ void test_short_options()
         {"-f 13", s_success, "-f:13"},
         {"-f -13", s_success, "-f:-13"},
         {"-f", s_missing_parameter, ""},
-        {"-f --foo", s_missing_parameter, ""},
         {"-f /foo", s_success, "-f:/foo"},
         {"-f -d", s_success, "-f:-d"},
-        {"-g 13", s_success, "-g:13"},
-        {"-g", s_success, "-g:"},
-        {"-g --foo", s_long_not_allowed, "-g:"},
-        {"-g /foo", s_success, "-g:/foo"},
-        {"-g -d", s_success, "-g: -d:"},
-        {"-f12", s_short_adjacent_not_allowed, ""},
         {0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases2);
+    test_cmdline(",d ,f=", style, test_cases2);
 
     style = cmdline::style_t(
         allow_short | short_allow_next
@@ -281,12 +276,9 @@ void test_short_options()
         {"-f10", s_success, "-f:10"},
         {"-f 10", s_success, "-f:10"},
         {"-f -d", s_success, "-f:-d"},
-        {"-g10", s_success, "-g:10"},
-        {"-g 10", s_success, "-g:10"},
-        {"-g -d", s_success, "-g: -d:"},
         {0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases3);
+    test_cmdline(",d ,f=", style, test_cases3);
 
     style = cmdline::style_t(
         allow_short | short_allow_next
@@ -295,14 +287,14 @@ void test_short_options()
 
     test_case test_cases4[] = {
         {"-de", s_success, "-d: -e:"},
-        {"-dg", s_success, "-d: -g:"},
-        {"-dg10", s_success, "-d: -g:10"},
-        {"-d12", s_extra_parameter, ""},
-        {"-gd", s_success, "-g:d"},
+        {"-df10", s_success, "-d: -f:10"},
+        // FIXME: review
+        //{"-d12", s_extra_parameter, ""},
+        {"-f12", s_success, "-f:12"},
         {"-fe", s_success, "-f:e"},
         {0}
     };
-    test_cmdline(",d ,f= ,g? ,e", style, test_cases4);
+    test_cmdline(",d ,f= ,e", style, test_cases4);
 
 }
 
@@ -318,15 +310,13 @@ void test_dos_options()
 
     test_case test_cases1[] = {
         {"/d d -bar", s_success, "-d: d -bar"},
-        // This is treated as disallowed long option
-        {"--foo", s_long_not_allowed, ""},
+        {"--foo", s_success, "--foo"},
         {"/d13", s_extra_parameter, ""},
         {"/f14", s_success, "-f:14"},
-        {"/g /f1", s_success, "-g: -f:1"},
         {"/f", s_missing_parameter, ""},
         {0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases1);
+    test_cmdline(",d ,f=", style, test_cases1);
 
     style = cmdline::style_t(
         allow_short 
@@ -335,14 +325,14 @@ void test_dos_options()
 
     test_case test_cases2[] = {
         {"/de", s_extra_parameter, ""},
-        {"/gd", s_success, "-g:d"},
         {"/fe", s_success, "-f:e"},
         {0}
     };
-    test_cmdline(",d ,f= ,g? ,e", style, test_cases2);
+    test_cmdline(",d ,f= ,e", style, test_cases2);
 
 }
 
+
 void test_disguised_long()
 {
     using namespace command_line_style;
@@ -442,43 +432,176 @@ void test_prefix()
     test_cmdline("foo*=", style, test_cases1);
 }
 
-void test_multiple()
+
+pair<string, string> at_option_parser(string const&s)
 {
-    using namespace command_line_style;
-    cmdline::style_t style;
-
-    style = cmdline::style_t(
-        unix_style | long_allow_next);
-
-    test_case test_cases1[] = {
-        {"--value 1 2 3 4 --help", s_success, "value:1-2-3-4 help:"},
-        {"--value 1 2 3 4 --", s_success, "value:1-2-3-4"},
-        {0}
-    };
-
-    test_cmdline("value+ help", style, test_cases1);
+    if ('@' == s[0])
+        return std::make_pair(string("response-file"), s.substr(1));
+    else
+        return pair<string, string>();
 }
 
-void test_style_errors()
+pair<string, string> at_option_parser_broken(string const&s)
 {
-    using namespace command_line_style;
-    char* argv[] = {"program"};
+    if ('@' == s[0])
+        return std::make_pair(string("some garbage"), s.substr(1));
+    else
+        return pair<string, string>();
+}
 
-    BOOST_CHECK_THROW(cmdline cmd(1, (const char*const *)argv, allow_long),
-                      invalid_command_line_style);
 
-    BOOST_CHECK_THROW(cmdline cmd(1, (const char*const *)argv, allow_short),
-                      invalid_command_line_style);
 
-    BOOST_CHECK_THROW(cmdline cmd(1, (const char*const *)argv, allow_short | 
-                                  short_allow_next),
-                      invalid_command_line_style);
+void test_additional_parser()
+{
+    options_description desc;
+    desc.add_options()
+        ("response-file", value<string>(), "response file")
+        ("foo", value<int>(), "foo")
+        ;
+
+    vector<string> input;
+    input.push_back("@config");
+    input.push_back("--foo=1");
+
+    cmdline cmd(input);
+    cmd.set_options_description(desc);
+    cmd.set_additional_parser(at_option_parser);
+
+    vector<option> result = cmd.run();
+
+    BOOST_REQUIRE(result.size() == 2);
+    BOOST_CHECK_EQUAL(result[0].string_key, "response-file");
+    BOOST_CHECK_EQUAL(result[0].value[0], "config");
+    BOOST_CHECK_EQUAL(result[1].string_key, "foo");
+    BOOST_CHECK_EQUAL(result[1].value[0], "1");    
+
+    // Test that invalid options returned by additional style
+    // parser are detected.
+    cmdline cmd2(input);
+    cmd2.set_options_description(desc);
+    cmd2.set_additional_parser(at_option_parser_broken);
+
+    BOOST_CHECK_THROW(cmd2.run(), unknown_option);
+
+}
+
+vector<option> at_option_parser2(vector<string>& args)
+{
+    vector<option> result;
+    if ('@' == args[0][0]) {
+        // Simulate reading the response file.
+        result.push_back(option("foo", vector<string>(1, "1")));
+        result.push_back(option("bar", vector<string>(1, "1")));
+        args.erase(args.begin());
+    }
+    return result;
+}
+
+
+void test_style_parser()
+{
+    options_description desc;
+    desc.add_options()
+        ("foo", value<int>(), "foo")
+        ("bar", value<int>(), "bar")
+        ;
+
+    vector<string> input;
+    input.push_back("@config");
+
+    cmdline cmd(input);
+    cmd.set_options_description(desc);
+    cmd.extra_style_parser(at_option_parser2);
+
+    vector<option> result = cmd.run();
+
+    BOOST_REQUIRE(result.size() == 2);
+    BOOST_CHECK_EQUAL(result[0].string_key, "foo");
+    BOOST_CHECK_EQUAL(result[0].value[0], "1");    
+    BOOST_CHECK_EQUAL(result[1].string_key, "bar");
+    BOOST_CHECK_EQUAL(result[1].value[0], "1");    
+}
+
+void test_unregistered()
+{
+    // Check unregisted option when no options are registed at all.
+    options_description desc;
+
+    vector<string> input;
+    input.push_back("--foo=1");
+    input.push_back("--bar");
+    input.push_back("1");
+    input.push_back("-b");
+    input.push_back("-biz");
+
+    cmdline cmd(input);
+    cmd.set_options_description(desc);
+    cmd.allow_unregistered();
+    
+    vector<option> result = cmd.run();
+    BOOST_REQUIRE(result.size() == 5);
+    // --foo=1
+    BOOST_CHECK_EQUAL(result[0].string_key, "foo");
+    BOOST_CHECK_EQUAL(result[0].unregistered, true);
+    BOOST_CHECK_EQUAL(result[0].value[0], "1");
+    // --bar
+    BOOST_CHECK_EQUAL(result[1].string_key, "bar");
+    BOOST_CHECK_EQUAL(result[1].unregistered, true);
+    BOOST_CHECK(result[1].value.empty());
+    // '1' is considered a positional option, not a value to
+    // --bar
+    BOOST_CHECK(result[2].string_key.empty());
+    BOOST_CHECK(result[2].position_key == 0);
+    BOOST_CHECK_EQUAL(result[2].unregistered, false);
+    BOOST_CHECK_EQUAL(result[2].value[0], "1");
+    // -b
+    BOOST_CHECK_EQUAL(result[3].string_key, "-b");
+    BOOST_CHECK_EQUAL(result[3].unregistered, true);
+    BOOST_CHECK(result[3].value.empty());
+    // -biz
+    BOOST_CHECK_EQUAL(result[4].string_key, "-b");
+    BOOST_CHECK_EQUAL(result[4].unregistered, true);
+    BOOST_CHECK_EQUAL(result[4].value[0], "iz");
+
+    // Check sticky short options together with unregisted options.
+    
+    desc.add_options()
+        ("help,h", "")
+        ("magic,m", value<string>(), "")
+        ;
+
+    input.clear();
+    input.push_back("-hc");
+    input.push_back("-mc");
+
+
+    cmdline cmd2(input);
+    cmd2.set_options_description(desc);
+    cmd2.allow_unregistered();
+    
+    result = cmd2.run();
+
+    BOOST_REQUIRE(result.size() == 3);
+    BOOST_CHECK_EQUAL(result[0].string_key, "help");
+    BOOST_CHECK_EQUAL(result[0].unregistered, false);
+    BOOST_CHECK(result[0].value.empty());
+    BOOST_CHECK_EQUAL(result[1].string_key, "-c");
+    BOOST_CHECK_EQUAL(result[1].unregistered, true);
+    BOOST_CHECK(result[1].value.empty());
+    BOOST_CHECK_EQUAL(result[2].string_key, "magic");
+    BOOST_CHECK_EQUAL(result[2].unregistered, false);
+    BOOST_CHECK_EQUAL(result[2].value[0], "c");
+
+    // CONSIDER:
+    // There's a corner case:
+    //   -foo
+    // when 'allow_long_disguise' is set. Should this be considered
+    // disguised long option 'foo' or short option '-f' with value 'oo'?
+    // It's not clear yet, so I'm leaving the decision till later.
 }
 
 int test_main(int ac, char* av[])
 {
-// ###     detail::test_cmdline_detail();
-
     test_long_options();
     test_short_options();
     test_dos_options();
@@ -486,31 +609,9 @@ int test_main(int ac, char* av[])
     test_guessing();
     test_arguments();
     test_prefix();
-    test_multiple();
-    test_style_errors();
-
-    cmdline cmd((int)ac, (const char*const *)av, 
-                int(command_line_style::unix_style));
-    cmd.add_option("version", 'v');
-    cmd.add_option("help", 'h');
-    cmd.add_option("verbose", 'V');
-    cmd.add_option("magic", 'm');
-    cmd.add_option("output", 'o', ':');
-
-    try {
-        while(++cmd) {
-
-            if (cmd.at_argument()) {
-                cout << "Argument : " << cmd.argument() << "\n";
-            } else {
-                cout << "Option : " << cmd.option_name()
-                     << "(" << cmd.option_value() << ")\n";
-            } 
-        }
-    }
-    catch(exception& e) {
-        cout << e.what() << "\n";
-    }
+    test_additional_parser();
+    test_style_parser();
+    test_unregistered();
 
     return 0;
 }

test/options_description_test.cpp

@@ -14,85 +14,73 @@ using namespace boost;
 #include <boost/test/test_tools.hpp>
 
 #include <utility>
+#include <string>
+#include <sstream>
 using namespace std;
 
-/*  This is very wierd test case -- it tests trivial things. After writing it,
-    I think that XP folks must be somehow wrong.
-*/
-void test_option_description_construction()
-{
-    option_description d1("a", new untyped_value(), "desc1");
-    BOOST_TEST(d1.long_name() == "a");
-    BOOST_TEST(d1.description() == "desc1");
-    BOOST_TEST(d1.semantic()->name() == "arg");
-
-    // It is not possible to compare boost::function
-    #if 0
-    function<string, string> f1;
-    BOOST_TEST(&option_description("x", "y", "z").
-               validator(f1).validator() ==
-               &f1);
-    function<void, string> f2;
-    BOOST_TEST(&option_description("x", "y", "z").
-               notify(f2).notify() ==
-               &f2);
-    #endif
-
-    option_description d4("foo,f", new untyped_value(), "desc1");
-    BOOST_CHECK(d4.long_name() == "foo");
-    BOOST_CHECK(d4.short_name() == "f");
-}
-
-void test_options_description()
+void test_type()
 {
     options_description desc;
-
-    shared_ptr<option_description> d1(
-        new option_description("first,f", new untyped_value(), ""));
-    desc.add(d1);
-    BOOST_TEST(desc.count("first") == 1);
-    BOOST_TEST(desc.count("-f") == 1);
-    BOOST_TEST(desc.keys().size() == 2);
-    BOOST_TEST(desc.keys().count("first") == 1);
-    BOOST_TEST(desc.keys().count("-f") == 1);
-
     desc.add_options()
-        ("second,s", new untyped_value())
-        ("third,t", new untyped_value())
+        ("foo", value<int>(), "")
+        ("bar", value<std::string>(), "")
         ;
-    BOOST_TEST(desc.count("second") == 1);
-    BOOST_TEST(desc.count("-s") == 1);
+    
+    const typed_value_base* b = dynamic_cast<const typed_value_base*>
+        (desc.find("foo", false).semantic().get());
+    BOOST_CHECK(b);
+    BOOST_CHECK(b->value_type() == typeid(int));
 
-    desc.add_options()
-        (",x", new untyped_value)
-        ;
-    BOOST_TEST(desc.primary_keys().size() == 4);
-    BOOST_TEST(desc.primary_keys().count("first") == 1);
-    BOOST_TEST(desc.primary_keys().count("second") == 1);
-    BOOST_TEST(desc.primary_keys().count("third") == 1);
-    BOOST_TEST(desc.primary_keys().count("-x") == 1);
+    const typed_value_base* b2 = dynamic_cast<const typed_value_base*>
+        (desc.find("bar", false).semantic().get());
+    BOOST_CHECK(b2);
+    BOOST_CHECK(b2->value_type() == typeid(std::string));
 }
 
 void test_approximation()
 {
     options_description desc;
     desc.add_options()
-    ("foo", new untyped_value())
-    ("fee", new untyped_value())
-    ("baz", new untyped_value());
+        ("foo", new untyped_value())
+        ("fee", new untyped_value())
+        ("baz", new untyped_value())
+        ("all-chroots", new untyped_value())
+        ("all-sessions", new untyped_value())
+        ("all", new untyped_value())
+        ;
 
-    BOOST_TEST(desc.count_approx("f") == 2);
-    BOOST_TEST(desc.count_approx("foo") == 1);
-    set<string> a = desc.approximations("f");
-    BOOST_TEST(a.size() == 2);
-    BOOST_TEST(*a.begin() == "fee");
-    BOOST_TEST(*(++a.begin()) == "foo");
+    BOOST_CHECK_EQUAL(desc.find("fo", true).long_name(), "foo");
+
+    BOOST_CHECK_EQUAL(desc.find("all", true).long_name(), "all");
+    BOOST_CHECK_EQUAL(desc.find("all-ch", true).long_name(), "all-chroots");
+
+
+//    BOOST_CHECK(desc.count_approx("foo") == 1);
+//    set<string> a = desc.approximations("f");
+//    BOOST_CHECK(a.size() == 2);
+//    BOOST_CHECK(*a.begin() == "fee");
+//    BOOST_CHECK(*(++a.begin()) == "foo");
+}
+
+void test_formatting()
+{
+    // Long option descriptions used to crash on MSVC-8.0.
+    options_description desc;
+    desc.add_options()(
+        "test", new untyped_value(),
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo"
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo"
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo"
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo");
+
+    stringstream ss;
+    ss << desc;
 }
 
 int test_main(int, char* [])
 {
-    test_option_description_construction();
-    test_options_description();
+    test_type();
     test_approximation();
+    test_formatting();
     return 0;
 }

test/parsers_test.cpp

@@ -6,6 +6,7 @@
 
 #include <boost/program_options/parsers.hpp>
 #include <boost/program_options/options_description.hpp>
+#include <boost/program_options/variables_map.hpp>
 using namespace boost::program_options;
 // We'll use po::value everywhere to workaround vc6 bug.
 namespace po = boost::program_options;
@@ -17,9 +18,14 @@ using namespace boost;
 #include <boost/test/test_tools.hpp>
 
 #include <sstream>
+#include <iostream>
 using namespace std;
 
+#if defined(__sun)
+#include <stdlib.h> // for putenv on solaris
+#else
 #include <cstdlib> // for putenv
+#endif
 
 #define TEST_CHECK_THROW(expression, exception, description) \
     try \
@@ -52,13 +58,6 @@ void check_value(const option& option, const char* name, const char* value)
     BOOST_CHECK(option.value.front() == value);
 }
 
-void check_value(const woption& option, const char* name, const wchar_t* value)
-{
-    BOOST_CHECK(option.string_key == name);
-    BOOST_REQUIRE(option.value.size() == 1);
-    BOOST_CHECK(option.value.front() == value);
-}
-
 vector<string> sv(char* array[], unsigned size)
 {
     vector<string> r;
@@ -67,15 +66,11 @@ vector<string> sv(char* array[], unsigned size)
     return r;
 }
 
-vector<wstring> sv(wchar_t* array[], unsigned size)
+pair<string, string> additional_parser(const std::string&)
 {
-    vector<wstring> r;
-    for (unsigned i = 0; i < size; ++i)
-        r.push_back(array[i]);
-    return r;
+    return pair<string, string>();
 }
 
-
 void test_command_line()
 {
     // The following commented out blocks used to test parsing
@@ -90,14 +85,14 @@ void test_command_line()
         parse_command_line(cmdline1,
                            cmdline1 + sizeof(cmdline1)/sizeof(cmdline1[0]));
 
-    BOOST_CRITICAL_TEST(a1.options().size() == 4);
-    BOOST_TEST(a1.options()[0] == msp("a", ""));
-    BOOST_TEST(a1.options()[1] == msp("b", "12"));
-    BOOST_TEST(a1.options()[2] == msp("-f", ""));
-    BOOST_TEST(a1.options()[3] == msp("-g", "4"));
-    BOOST_CRITICAL_TEST(a1.arguments().size() == 2);
-    BOOST_TEST(a1.arguments()[0] == "-");
-    BOOST_TEST(a1.arguments()[1] == "file");
+    BOOST_REQUIRE(a1.options().size() == 4);
+    BOOST_CHECK(a1.options()[0] == msp("a", ""));
+    BOOST_CHECK(a1.options()[1] == msp("b", "12"));
+    BOOST_CHECK(a1.options()[2] == msp("-f", ""));
+    BOOST_CHECK(a1.options()[3] == msp("-g", "4"));
+    BOOST_REQUIRE(a1.arguments().size() == 2);
+    BOOST_CHECK(a1.arguments()[0] == "-");
+    BOOST_CHECK(a1.arguments()[1] == "file");
 
     char* cmdline2[] = { "--a", "--", "file" };
 
@@ -105,56 +100,55 @@ void test_command_line()
         parse_command_line(cmdline2,
                            cmdline2 + sizeof(cmdline2)/sizeof(cmdline2[0]));
 
-    BOOST_CRITICAL_TEST(a2.options().size() == 1);
-    BOOST_TEST(a2.options()[0] == msp("a", ""));
-    BOOST_TEST(a2.arguments().size() == 1);
-    BOOST_TEST(a2.arguments()[0] == "file");
+    BOOST_REQUIRE(a2.options().size() == 1);
+    BOOST_CHECK(a2.options()[0] == msp("a", ""));
+    BOOST_CHECK(a2.arguments().size() == 1);
+    BOOST_CHECK(a2.arguments()[0] == "file");
     #endif
     
     options_description desc;
     desc.add_options()
         ("foo,f", new untyped_value(), "")
         // Explicit qualification is a workaround for vc6
-        ("bar,b", po::value<std::string>()->implicit(), "")
+        ("bar,b", po::value<std::string>(), "")
         ("baz", new untyped_value())
         ("plug*", new untyped_value())
         ;
-    char* cmdline3_[] = { "--foo=12", "-f4", "--bar=11", "--bar", "-b4", "-b",
-                         "--plug3=10"};
+    char* cmdline3_[] = { "--foo=12", "-f4", "--bar=11", "-b4",
+                          "--plug3=10"};
     vector<string> cmdline3 = sv(cmdline3_,
                                  sizeof(cmdline3_)/sizeof(cmdline3_[0]));
     vector<option> a3 = 
         command_line_parser(cmdline3).options(desc).run().options;
                        
-    BOOST_CRITICAL_TEST(a3.size() == 7);
+    BOOST_CHECK_EQUAL(a3.size(), 5u);
 
     check_value(a3[0], "foo", "12");
     check_value(a3[1], "foo", "4");
     check_value(a3[2], "bar", "11");
+    check_value(a3[3], "bar", "4");
+    check_value(a3[4], "plug3", "10");
 
-    BOOST_TEST(a3[3].string_key == "bar");
-    BOOST_CRITICAL_TEST(a3[3].value.size() == 0);
+    // Regression test: check that '0' as style is interpreted as 
+    // 'default_style'
+    vector<option> a4 = 
+        parse_command_line(5, cmdline3_, desc, 0, additional_parser).options;
 
-    check_value(a3[4], "bar", "4");
+    BOOST_CHECK_EQUAL(a4.size(), 4u);
+    check_value(a4[0], "foo", "4");
+    check_value(a4[1], "bar", "11");
 
-    BOOST_TEST(a3[5].string_key == "bar");
-    BOOST_CRITICAL_TEST(a3[5].value.size() == 0);
+    // Check that we don't crash on empty values of type 'string'
+    char* cmdline4[] = {"", "--open", ""};
+    options_description desc2;
+    desc2.add_options()
+        ("open", po::value<string>())
+        ;
+    variables_map vm;
+    po::store(po::parse_command_line(3, cmdline4, desc2), vm);
 
-    check_value(a3[6], "plug3", "10");
 
-    // Check Unicode, 
-    wchar_t* cmdline4_[] = { L"--foo=1\u0FF52", L"-f4", L"--bar=11", L"--bar", 
-                             L"-b4", L"-b", L"--plug3=10"};
-    vector<wstring> cmdline4 = sv(cmdline4_,
-                                  sizeof(cmdline4_)/sizeof(cmdline4_[0]));
-    vector<woption> a4 = 
-        wcommand_line_parser(cmdline4).options(desc).run().options;
 
-    BOOST_CRITICAL_TEST(a3.size() == 7);
-
-    check_value(a4[0], "foo", L"1\u0FF52");
-    check_value(a4[1], "foo", L"4");
-    check_value(a4[2], "bar", L"11");
 }
 
 void test_config_file()
@@ -181,7 +175,7 @@ void test_config_file()
 
     stringstream ss(content1);
     vector<option> a1 = parse_config_file(ss, desc).options;
-    BOOST_CRITICAL_TEST(a1.size() == 5);
+    BOOST_REQUIRE(a1.size() == 5);
     check_value(a1[0], "gv1", "0");
     check_value(a1[1], "plug3", "7");
     check_value(a1[2], "b", "true");
@@ -214,11 +208,63 @@ void test_environment()
     // which already has a value.
 }
 
+void test_unregistered()
+{
+    options_description desc;
+
+    char* cmdline1_[] = { "--foo=12", "--bar", "1"};
+    vector<string> cmdline1 = sv(cmdline1_,
+                                 sizeof(cmdline1_)/sizeof(cmdline1_[0]));
+    vector<option> a1 = 
+        command_line_parser(cmdline1).options(desc).allow_unregistered().run()
+        .options;
+
+    BOOST_REQUIRE(a1.size() == 3);
+    BOOST_CHECK(a1[0].string_key == "foo");
+    BOOST_CHECK(a1[0].unregistered == true);
+    BOOST_REQUIRE(a1[0].value.size() == 1);
+    BOOST_CHECK(a1[0].value[0] == "12");
+    BOOST_CHECK(a1[1].string_key == "bar");
+    BOOST_CHECK(a1[1].unregistered == true);
+    BOOST_CHECK(a1[2].string_key == "");
+    BOOST_CHECK(a1[2].unregistered == false);
+    
+
+    vector<string> a2 = collect_unrecognized(a1, include_positional);
+    BOOST_CHECK(a2[0] == "--foo=12");
+    BOOST_CHECK(a2[1] == "--bar");
+    BOOST_CHECK(a2[2] == "1");
+
+    // Test that storing unregisted options has no effect
+    variables_map vm;
+    
+    store(command_line_parser(cmdline1).options(desc).
+          allow_unregistered().run(),
+          vm);
+
+    BOOST_CHECK_EQUAL(vm.size(), 0u);   
+
+
+    const char content1[] =
+    "gv1 = 0\n"
+    "[m1]\n"
+    "v1 = 1\n"
+    ;
+
+    stringstream ss(content1);
+    vector<option> a3 = parse_config_file(ss, desc, true).options;
+    BOOST_REQUIRE(a3.size() == 2);
+    cout << "XXX" << a3[0].value.front() << "\n";
+    check_value(a3[0], "gv1", "0");
+    check_value(a3[1], "m1.v1", "1");
+}
+
 int test_main(int, char* [])
 {
     test_command_line();
     test_config_file();
     test_environment();
+    test_unregistered();
     return 0;
 }
 

test/positional_options_test.cpp

@@ -34,7 +34,7 @@ void test_positional_options()
 
     p.add("third", -1);
 
-    BOOST_CHECK_EQUAL(p.max_total_count(), std::numeric_limits<unsigned>::max());
+    BOOST_CHECK_EQUAL(p.max_total_count(), (std::numeric_limits<unsigned>::max)());
     BOOST_CHECK_EQUAL(p.name_for_position(0), "first");
     BOOST_CHECK_EQUAL(p.name_for_position(1), "second");
     BOOST_CHECK_EQUAL(p.name_for_position(2), "second");
@@ -49,28 +49,31 @@ void test_parsing()
         ("first", po::value<int>())
         ("second", po::value<int>())
         ("input-file", po::value< vector<string> >())
+        ("some-other", po::value<string>())
     ;
 
     positional_options_description p;
-    p.add("input-file", 2);
+    p.add("input-file", 2).add("some-other", 1);
 
     vector<string> args;
     args.push_back("--first=10");
     args.push_back("file1");
     args.push_back("--second=10");
     args.push_back("file2");
+    args.push_back("file3");
 
     // Check that positional options are handled.
     parsed_options parsed = 
         command_line_parser(args).options(desc).positional(p).run();
 
-    BOOST_REQUIRE(parsed.options.size() == 4);
+    BOOST_REQUIRE(parsed.options.size() == 5);
     BOOST_CHECK_EQUAL(parsed.options[1].string_key, "input-file");
     BOOST_CHECK_EQUAL(parsed.options[1].value[0], "file1");
     BOOST_CHECK_EQUAL(parsed.options[3].string_key, "input-file");
     BOOST_CHECK_EQUAL(parsed.options[3].value[0], "file2");
+    BOOST_CHECK_EQUAL(parsed.options[4].value[0], "file3");
 
-    args.push_back("file3");
+    args.push_back("file4");
 
     // Check that excessive number of positional options is detected.
     BOOST_CHECK_THROW(command_line_parser(args).options(desc).positional(p)

test/test_convert.cpp

@@ -3,11 +3,11 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+#include <cassert>
 #include <string>
 #include <fstream>
 #include <sstream>
 #include <iostream>
-#include <cassert>
 #include <boost/progress.hpp>
 #include <boost/bind.hpp>
 #include <boost/ref.hpp>
@@ -15,6 +15,8 @@
 #include <boost/program_options/detail/convert.hpp>
 #include <boost/program_options/detail/utf8_codecvt_facet.hpp>
 
+#include <boost/test/test_tools.hpp>
+
 using namespace std;
 
 string file_content(const string& filename)
@@ -75,7 +77,7 @@ std::wstring from_8_bit_2(const std::string& s,
 void test_convert(const std::string& input, 
                   const std::string& expected_output)
 {
-    boost::program_options::detail::utf8_codecvt_facet<wchar_t, char> facet;
+    boost::program_options::detail::utf8_codecvt_facet facet;
     
     std::wstring output;
     { 
@@ -94,7 +96,7 @@ void test_convert(const std::string& input,
                 facet);
     }
 
-    assert(output.size()*2 == expected_output.size());
+    BOOST_CHECK(output.size()*2 == expected_output.size());
 
     for(unsigned i = 0; i < output.size(); ++i) {
 
@@ -103,20 +105,20 @@ void test_convert(const std::string& input,
             low &= 0xFF;
             unsigned low2 = expected_output[2*i];
             low2 &= 0xFF;
-            assert(low == low2);
+            BOOST_CHECK(low == low2);
         }
         {        
             unsigned high = output[i];
             high >>= 8;
             high &= 0xFF;
             unsigned high2 = expected_output[2*i+1];            
-            assert(high == high2);
+            BOOST_CHECK(high == high2);
         }
     }
 
     string ref = boost::to_8_bit(output, facet);
 
-    assert(ref == input);
+    BOOST_CHECK(ref == input);
 }
 
 int test_main(int ac, char* av[])

test/unicode_test.cpp

@@ -32,12 +32,12 @@ void test_unicode_to_unicode()
         ;
 
     vector<wstring> args;
-    args.push_back(L"--foo=\u044F");
+    args.push_back(L"--foo=\x044F");
 
     variables_map vm;
     store(wcommand_line_parser(args).options(desc).run(), vm);
 
-    BOOST_CHECK(vm["foo"].as<wstring>() == L"\u044F");           
+    BOOST_CHECK(vm["foo"].as<wstring>() == L"\x044F");           
 }
 
 // Test that unicode input is property converted into
@@ -46,7 +46,7 @@ void test_unicode_to_unicode()
 void test_unicode_to_native()
 {
     std::codecvt<wchar_t, char, mbstate_t>* facet = 
-        new boost::program_options::detail::utf8_codecvt_facet<wchar_t, char>;
+        new boost::program_options::detail::utf8_codecvt_facet;
     locale::global(locale(locale(), facet));
 
     options_description desc;
@@ -56,18 +56,18 @@ void test_unicode_to_native()
         ;
 
     vector<wstring> args;
-    args.push_back(L"--foo=\u044F");
+    args.push_back(L"--foo=\x044F");
 
     variables_map vm;
     store(wcommand_line_parser(args).options(desc).run(), vm);
 
-    BOOST_TEST(vm["foo"].as<string>() == "\xD1\x8F");    
+    BOOST_CHECK(vm["foo"].as<string>() == "\xD1\x8F");    
 }
 
 void test_native_to_unicode()
 {
     std::codecvt<wchar_t, char, mbstate_t>* facet = 
-        new boost::program_options::detail::utf8_codecvt_facet<wchar_t, char>;
+        new boost::program_options::detail::utf8_codecvt_facet;
     locale::global(locale(locale(), facet));
 
     options_description desc;
@@ -82,7 +82,48 @@ void test_native_to_unicode()
     variables_map vm;
     store(command_line_parser(args).options(desc).run(), vm);
 
-    BOOST_TEST(vm["foo"].as<wstring>() == L"\u044F");    
+    BOOST_CHECK(vm["foo"].as<wstring>() == L"\x044F");    
+}
+
+
+vector<wstring> sv(wchar_t* array[], unsigned size)
+{
+    vector<wstring> r;
+    for (unsigned i = 0; i < size; ++i)
+        r.push_back(array[i]);
+    return r;
+}
+
+void check_value(const woption& option, const char* name, const wchar_t* value)
+{
+    BOOST_CHECK(option.string_key == name);
+    BOOST_REQUIRE(option.value.size() == 1);
+    BOOST_CHECK(option.value.front() == value);
+}
+
+void test_command_line()
+{
+    options_description desc;
+    desc.add_options()
+        ("foo,f", new untyped_value(), "")
+        // Explicit qualification is a workaround for vc6
+        ("bar,b", po::value<std::string>(), "")
+        ("baz", new untyped_value())
+        ("plug*", new untyped_value())
+        ;
+
+    wchar_t* cmdline4_[] = { L"--foo=1\u0FF52", L"-f4", L"--bar=11",
+                             L"-b4", L"--plug3=10"};
+    vector<wstring> cmdline4 = sv(cmdline4_,
+                                  sizeof(cmdline4_)/sizeof(cmdline4_[0]));
+    vector<woption> a4 = 
+        wcommand_line_parser(cmdline4).options(desc).run().options;
+
+    BOOST_REQUIRE(a4.size() == 5);
+
+    check_value(a4[0], "foo", L"1\u0FF52");
+    check_value(a4[1], "foo", L"4");
+    check_value(a4[2], "bar", L"11");
 }
 
 // Since we've already tested conversion between parser encoding and
@@ -91,7 +132,7 @@ void test_native_to_unicode()
 void test_config_file()
 {
     std::codecvt<wchar_t, char, mbstate_t>* facet = 
-        new boost::program_options::detail::utf8_codecvt_facet<wchar_t, char>;
+        new boost::program_options::detail::utf8_codecvt_facet;
     locale::global(locale(locale(), facet));
 
     options_description desc;
@@ -100,12 +141,12 @@ void test_config_file()
         ("foo", po::value<string>(), "unicode option")
         ;
 
-    std::wstringstream stream(L"foo = \u044F");
+    std::wstringstream stream(L"foo = \x044F");
 
     variables_map vm;
     store(parse_config_file(stream, desc), vm);
 
-    BOOST_TEST(vm["foo"].as<string>() == "\xD1\x8F");    
+    BOOST_CHECK(vm["foo"].as<string>() == "\xD1\x8F");    
 }
 
 int test_main(int, char* [])
@@ -113,6 +154,7 @@ int test_main(int, char* [])
     test_unicode_to_unicode();
     test_unicode_to_native();
     test_native_to_unicode();
+    test_command_line();
     test_config_file();
     return 0;
 }

test/variable_map_test.cpp

@@ -45,8 +45,8 @@ void test_variable_map()
     options_description desc;
     desc.add_options()
         ("foo,f", new untyped_value)
-        ("bar,b", po::value<string>()->implicit())
-        ("biz,z", po::value<string>()->implicit())
+        ("bar,b", po::value<string>())
+        ("biz,z", po::value<string>())
         ("baz", new untyped_value())
         ("output,o", new untyped_value(), "")
         ;
@@ -57,21 +57,20 @@ void test_variable_map()
     variables_map vm;
     store(a3, vm);
     notify(vm);
-    BOOST_CRITICAL_TEST(vm.size() == 4);
-    BOOST_TEST(vm["foo"].as<string>() == "'12'");
-    BOOST_TEST(vm["bar"].as<string>() == "11");
-    BOOST_TEST(vm.count("biz") == 1);
-    BOOST_TEST(vm["biz"].as<string>() == "3");
-    BOOST_TEST(vm["output"].as<string>() == "foo");
+    BOOST_REQUIRE(vm.size() == 4);
+    BOOST_CHECK(vm["foo"].as<string>() == "'12'");
+    BOOST_CHECK(vm["bar"].as<string>() == "11");
+    BOOST_CHECK(vm.count("biz") == 1);
+    BOOST_CHECK(vm["biz"].as<string>() == "3");
+    BOOST_CHECK(vm["output"].as<string>() == "foo");
 
     int i;
     desc.add_options()
     ("zee", bool_switch(), "")
-    ("zoo", bool_switch(), "")
     ("zak", po::value<int>(&i), "")
     ("opt", bool_switch(), "");
 
-    char* cmdline4_[] = { "--zee=On", "--zoo", "--zak=13" };
+    char* cmdline4_[] = { "--zee", "--zak=13" };
     vector<string> cmdline4 = sv(cmdline4_,
                                  sizeof(cmdline4_)/sizeof(cmdline4_[0]));
     parsed_options a4 = command_line_parser(cmdline4).options(desc).run();
@@ -79,12 +78,11 @@ void test_variable_map()
     variables_map vm2;
     store(a4, vm2);
     notify(vm2);
-    BOOST_CRITICAL_TEST(vm2.size() == 4);
-    BOOST_TEST(vm2["zee"].as<bool>() == true);
-    BOOST_TEST(vm2["zoo"].as<bool>() == true);
-    BOOST_TEST(vm2["zak"].as<int>() == 13);
-    BOOST_TEST(vm2["opt"].as<bool>() == false);
-    BOOST_TEST(i == 13);
+    BOOST_REQUIRE(vm2.size() == 3);
+    BOOST_CHECK(vm2["zee"].as<bool>() == true);
+    BOOST_CHECK(vm2["zak"].as<int>() == 13);
+    BOOST_CHECK(vm2["opt"].as<bool>() == false);
+    BOOST_CHECK(i == 13);
 
     options_description desc2;
     desc2.add_options()
@@ -100,10 +98,29 @@ void test_variable_map()
     variables_map vm3;
     store(a5, vm3);
     notify(vm3);
-    BOOST_CRITICAL_TEST(vm3.size() == 3);
-    BOOST_TEST(vm3["vee"].as<string>() == "42");
-    BOOST_TEST(vm3["voo"].as<string>() == "1");
-    BOOST_TEST(vm3["iii"].as<int>() == 123);
+    BOOST_REQUIRE(vm3.size() == 3);
+    BOOST_CHECK(vm3["vee"].as<string>() == "42");
+    BOOST_CHECK(vm3["voo"].as<string>() == "1");
+    BOOST_CHECK(vm3["iii"].as<int>() == 123);
+
+    options_description desc3;
+    desc3.add_options()
+    ("imp", po::value<int>()->implicit_value(100))
+    ("iim", po::value<int>()->implicit_value(200)->default_value(201))
+    ("mmp,m", po::value<int>()->implicit_value(123)->default_value(124))
+    ;
+    char* cmdline6_[] = {  "--imp=1", "-m" };
+    vector<string> cmdline6 = sv(cmdline6_,
+                                 sizeof(cmdline6_)/sizeof(cmdline6_[0]));
+    parsed_options a6 = command_line_parser(cmdline6).options(desc3).run();
+
+    variables_map vm4;
+    store(a6, vm4);
+    notify(vm4);
+    BOOST_REQUIRE(vm4.size() == 3);
+    BOOST_CHECK(vm4["imp"].as<int>() == 1);
+    BOOST_CHECK(vm4["iim"].as<int>() == 201);
+    BOOST_CHECK(vm4["mmp"].as<int>() == 123);
 }
 
 int stored_value;
@@ -161,7 +178,7 @@ void test_semantic_values()
     
     options.push_back(option("bar", vector<string>(1, "2")));
     variables_map vm3;
-    BOOST_CHECK_THROW(store(parsed, vm3), multiple_occurences);
+    BOOST_CHECK_THROW(store(parsed, vm3), multiple_occurrences);
 
     options = saved_options;
     // Now try passing two int in one 'argv' element.
@@ -229,13 +246,54 @@ void test_priority()
     BOOST_CHECK_EQUAL(vm["include"].as< vector<int> >()[1], 7);
 }
 
+void test_multiple_assignments_with_different_option_description()
+{
+    // Test that if we store option twice into the same variable_map,
+    // and some of the options stored the first time are not present
+    // in the options descrription provided the second time, we don't crash.
 
+    options_description desc1("");    
+    desc1.add_options()
+        ("help,h", "")
+        ("includes", po::value< vector<string> >()->composing(), "");
+        ;
+
+    options_description desc2("");
+    desc2.add_options()
+        ("output,o", "");
+
+    vector<string> input1;
+    input1.push_back("--help");
+    input1.push_back("--includes=a");
+    parsed_options p1 = command_line_parser(input1).options(desc1).run();
+
+    vector<string> input2;
+    input1.push_back("--output");
+    parsed_options p2 = command_line_parser(input2).options(desc2).run();
+
+    vector<string> input3;
+    input3.push_back("--includes=b");
+    parsed_options p3 = command_line_parser(input3).options(desc1).run();
+
+
+    variables_map vm;
+    store(p1, vm);
+    store(p2, vm);
+    store(p3, vm);
+
+    BOOST_REQUIRE(vm.count("help") == 1);
+    BOOST_REQUIRE(vm.count("includes") == 1);
+    BOOST_CHECK_EQUAL(vm["includes"].as< vector<string> >()[0], "a");
+    BOOST_CHECK_EQUAL(vm["includes"].as< vector<string> >()[1], "b");
+
+} 
 
 int test_main(int, char* [])
 {
     test_variable_map();
     test_semantic_values();
     test_priority();
+    test_multiple_assignments_with_different_option_description();
     return 0;
 }
 

test/winmain.cpp

@@ -3,7 +3,7 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-#ifdef _WIN32
+#if defined(_WIN32)
 #include <string>
 #include <vector>
 #include <cctype>
@@ -22,11 +22,11 @@ void test_winmain()
 #define TEST(input, expected) \
     char* BOOST_PP_CAT(e, __LINE__)[] = expected;\
     vector<string> BOOST_PP_CAT(v, __LINE__) = split_winmain(input);\
-    BOOST_REQUIRE(BOOST_PP_CAT(v, __LINE__).size() == \
-            sizeof(BOOST_PP_CAT(e, __LINE__))/sizeof(char*));\
     BOOST_CHECK_EQUAL_COLLECTIONS(BOOST_PP_CAT(v, __LINE__).begin(),\
                                   BOOST_PP_CAT(v, __LINE__).end(),\
-                                  BOOST_PP_CAT(e, __LINE__));    
+                                  BOOST_PP_CAT(e, __LINE__),\
+                                  BOOST_PP_CAT(e, __LINE__) + \
+                        sizeof(BOOST_PP_CAT(e, __LINE__))/sizeof(char*));    
 
 // The following expectations were obtained in Win2000 shell:
     TEST("1 ", {"1"});