balcl.txt @PURPOSE: Provide facility to parse process command-line arguments. @MNEMONIC: Basic Application Library Command Line (balcl) @DESCRIPTION: The 'balcl' package provides a set of components that enable users to access information from the process's command line via a value-semantic class, 'balcl::CommandLine'. An {Overview} is provided below. Full details can be found in the documentation of {'balcl_commandline'} and the other components of this package. /Overview /-------- There are several steps to using 'balcl::CommandLine': : 1 Specify the set of command-line options (and their attributes) that are : allowed on the command line by creation of a table of 'balcl::OptionInfo' : or 'balcl::Option' objects. See {Option Attributes} below. : : 2 Create a 'balcl::CommandLine' object from the command-line-option : specification table. : : 3 Pass command-line information (i.e., 'argv') to the 'parse' method of the : 'balcl::CommandLine' object. : : 4 If the 'parse' method is successful, use 'balcl::CommandLine' accessors or : the accessors of a returned 'balcl::CommandLineOptionsHandle' object. Note : that options that were defined by the user but did not appear in the : command line (i.e., the input to 'parse') are left in a "null" state unless : the user also defined a default value for the option (see {Option : Attributes}). /Option Attributes /----------------- This package provides a rich set of features for users to define their allowed options. These include: : o The names by which the option can be specified on the command line (a long : tag name and, optionally, a short tag name) as well as a separate name by : which, after a successful parse, the value of the option can be : programmatically accessed. : : o A description that is later used by the 'printUsage' method. : : o Whether or not the option must appear on the command line for a successful : parse. : : o Whether or not the option description will be included in the output : of the 'printUsage' method. : : o Is the option a simple "flag" (a boolean option, either present on the : command line or not) or does the option have a value? : : o If the option has a value, the user can specify: : o The type of the option value. : o Whether the option value is scalar or an array. : o Optionally: A default value for the option. : o Optionally: A user-supplied functor (a "constraint") to validate the : value. : : o Optionally, the user can supply the address of a variable that is "linked" : to the option. If so, after a successful parse, the option value can be : obtained from the variable (an alternative to using the : 'balcl::CommandLine' accessors). /Hierarchical Synopsis /--------------------- The 'balcl' package currently has 8 components having 6 levels of physical dependency. The list below shows the hierarchical ordering of the components. The order of components within each level is not architecturally significant, just alphabetical. .. 6. balcl_commandline 5. balcl_option 4. balcl_optioninfo 3. balcl_occurrenceinfo balcl_typeinfo 2. balcl_optionvalue 1. balcl_constraint balcl_optiontype .. /Component Synopsis /------------------ : 'balcl_commandline': : Provide command line parsing, validation, and access. : : 'balcl_constraint': : Define constraint function signatures for supported value types. : : 'balcl_occurrenceinfo': : Provide a type describing requirement and default value of option. : : 'balcl_option': : Provide an allocator-aware command-line-option descriptor class. : : 'balcl_optioninfo': : Provide a POD command-line-option descriptor 'struct'. : : 'balcl_optiontype': : Enumerate the types supported for command-line-option values. : : 'balcl_optionvalue': : Provide a variant type for command-line-option values. : : 'balcl_typeinfo': : Provide a class describing an option's type and other attributes.