123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238 |
- 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():
- > maybe it can be replaced by something from string_algorithms
- > library. AFAIK the library should be in 1.32.
- > 24. the documentation may contain info what source files are needed
- > for which feature or whether they need to be included always all.
- The program_options.reference.html may contain one-liner
- overview for every header and every class/typedef/function
- listed here - just for quick browsing and overview.
- > > > 5. Maybe more overcommented code examples can be added into
- > > > docs, each exploring single feature of library.
- > > >
- > > > Some people learn mostly from such examples.
- > > >
- > > > Later note: definitely would be useful, IMO.
- > >
- > > Maybe. Do you have specific ideas what the examples can be about?
- >
- > 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
|