Full merge from trunk at revision 41356 of entire boost-root tree.

[SVN r41370]

Author: Beman

build/Jamfile.v2

@@ -17,12 +17,4 @@ lib boost_program_options
     <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 ;
+boost-install boost_program_options ;

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/howto.xml

@@ -412,7 +412,7 @@ $ export LC_CTYPE=ru_RU.KOI8-R
       method of that class:
       <programlisting>
 parsed_options parsed = 
-    command_line_parser(argv, argc).options(desc).allow_unregistered().run();      
+    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, 
@@ -427,7 +427,7 @@ parsed_options parsed =
       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_arguments(parsed.option, include_positional);
+vector&lt;string&gt; to_pass_further = collect_unrecognized(parsed.options, include_positional);
       </programlisting>
 
       </para>     

doc/overview.xml

@@ -181,7 +181,7 @@ options_description desc;
 desc.add_options()
     ("help", "produce help message")
     ("compression", value<string>(), "compression level")
-    ("verbose", value<string>()->zero_token(), "verbosity level")
+    ("verbose", value<string>()->zero_tokens(), "verbosity level")
     ("email", value<string>()->multitoken(), "email to send to")
     ;
       </programlisting>
@@ -478,7 +478,45 @@ notify(vm);
     <title>Specific parsers</title>
 
     <section>
-      <title>Environment variables</title>
+      <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

doc/program_options.xml

@@ -83,5 +83,5 @@
   <xi:include href="design.xml"/>
   <xi:include href="acknowledgements.xml"/>    
 
-  <xi:include href="autodoc.boostbook"/> 
+  <xi:include href="autodoc.xml"/> 
 </library>

doc/todo.txt

@@ -1,4 +1,6 @@
 
+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. 

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)
     {

src/cmdline.cpp

@@ -290,8 +290,8 @@ namespace boost { namespace program_options { namespace detail {
 
         // First check that the option is valid, and get its description.
         // TODO: case-sensitivity.
-        const option_description* xd = 
-            m_desc->find_nothrow(opt.string_key, (m_style & allow_guessing));
+        const option_description* xd = m_desc->find_nothrow(opt.string_key, 
+                (m_style & allow_guessing) ? true : false);
 
         if (!xd)
         {
@@ -329,6 +329,14 @@ namespace boost { namespace program_options { namespace detail {
 
             max_tokens -= opt.value.size();
 
+            // A value is optional if min_tokens == 0, but max_tokens > 0.
+            // If a value is optional, it must appear in opt.value (because
+            // it was 'adjacent'.  Otherwise, remove the expectation of a
+            // non-adjacent value.  (For now, we just check max_tokens == 1,
+            // as there is no current support for max_tokens>1)
+            if (min_tokens == 0 && max_tokens == 1 && opt.value.empty())
+                --max_tokens;
+
             // Everything's OK, move the values to the result.            
             for(;!other_tokens.empty() && max_tokens--; ) {
                 opt.value.push_back(other_tokens[0]);
@@ -462,7 +470,8 @@ namespace boost { namespace program_options { namespace detail {
              ((m_style & allow_slash_for_short) && tok[0] == '/')))            
         {
             if (m_desc->find_nothrow(tok.substr(1, tok.find('=')-1), 
-                                     m_style & allow_guessing)) {
+                                     (m_style & allow_guessing) ? true : false)) 
+            {
                 args[0].insert(0, "-");
                 if (args[0][1] == '/')
                     args[0][1] = '-';

src/config_file.cpp

@@ -21,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(); 
@@ -100,7 +102,8 @@ 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))
+                    bool registered = allowed_option(name);
+                    if (!registered && !m_allow_unregistered)
                         boost::throw_exception(unknown_option(name));
 
                     if (value.empty())
@@ -110,6 +113,7 @@ namespace boost { namespace program_options { namespace detail {
                     this->value().string_key = name;
                     this->value().value.clear();
                     this->value().value.push_back(value);
+                    this->value().unregistered = !registered;
                     break;
 
                 } else {

src/options_description.cpp

@@ -201,6 +201,8 @@ namespace boost { namespace program_options {
         return *this;
     }
 
+    const unsigned options_description::m_default_line_length = 80;
+
     options_description::options_description(unsigned line_length)
     : m_line_length(line_length)
     {}
@@ -252,11 +254,12 @@ namespace boost { namespace program_options {
         return m_options;
     }
 
-    const option_description* 
+    const option_description*
     options_description::find_nothrow(const std::string& name, 
                                       bool approx) const
     {
-        int found = -1;
+        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.
@@ -276,31 +279,22 @@ namespace boost { namespace program_options {
             //
             // For now, we don't check the situation when there are 
             // two full matches. 
-                            
+
             if (r == option_description::full_match)
             {
-                return m_options[i].get();                
+                return m_options[i].get();
             }
 
-            if (found != -1)
-            {
-                vector<string> alts;
-                // FIXME: the use of 'key' here might not
-                // be the best approach.
-                alts.push_back(m_options[found]->key(name));
-                alts.push_back(m_options[i]->key(name));
-                boost::throw_exception(ambiguous_option(name, alts));
-            }
-            else
-            {
-                found = i;
-            }
-        }
-        if (found != -1) {
-            return m_options[found].get();
-        } else {
-            return 0;
+            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
@@ -412,9 +406,9 @@ namespace boost { namespace program_options {
 
                         if (last_space != line_begin)
                         {                 
-                            // is last_space within the second half of the 
+                            // is last_space within the second half ot the 
                             // current line
-                            if ((unsigned)std::distance(last_space, line_end) < 
+                            if ((unsigned)distance(last_space, line_end) < 
                                 (line_length - indent) / 2)
                             {
                                 line_end = last_space;