program_options/doc/options_description.xml

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
     "/home/ghost/Work/boost/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>