balcl.h

Go to the documentation of this file.

/// @file balcl.h
///
///
/// @defgroup balcl Package balcl
/// @brief  Basic Application Library Command Line (balcl)
/// @addtogroup bal
/// @{
/// @addtogroup balcl
/// [balcl]: group__balcl.html
/// @{
///
/// # Purpose {#balcl-purpose}
/// Provide facility to parse process command-line arguments.
///
/// # Mnemonic {#balcl-mnemonic}
/// Basic Application Library Command Line (balcl)
///
/// # Description {#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 {@ref 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:
///
///  * 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.
/// 
///  * A description that is later used by the 'printUsage' method.
/// 
///  * Whether or not the option must appear on the command line for a successful
///    parse.
/// 
///  * Whether or not the option description will be included in the output
///    of the 'printUsage' method.
/// 
///  * Is the option a simple "flag" (a boolean option, either present on the
///    command line or not) or does the option have a value?
/// 
///  * If the option has a value, the user can specify:
///    * The type of the option value.
///    * Whether the option value is scalar or an array.
///    * Optionally: A default value for the option.
///    * Optionally: A user-supplied functor (a "constraint") to validate the
///      value.
/// 
///  * 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.
/// @code
///  6. balcl_commandline
///
///  5. balcl_option
///
///  4. balcl_optioninfo
///
///  3. balcl_occurrenceinfo
///     balcl_typeinfo
///
///  2. balcl_optionvalue
///
///  1. balcl_constraint
///     balcl_optiontype
/// @endcode
///
/// ## Component Synopsis
///
///  @ref balcl_commandline :
///       Provide command line parsing, validation, and access.
/// 
///  @ref balcl_constraint :
///       Define constraint function signatures for supported value types.
/// 
///  @ref balcl_occurrenceinfo :
///       Provide a type describing requirement and default value of option.
/// 
///  @ref balcl_option :
///       Provide an allocator-aware command-line-option descriptor class.
/// 
///  @ref balcl_optioninfo :
///       Provide a POD command-line-option descriptor `struct`.
/// 
///  @ref balcl_optiontype :
///       Enumerate the types supported for command-line-option values.
/// 
///  @ref balcl_optionvalue :
///       Provide a variant type for command-line-option values.
/// 
///  @ref balcl_typeinfo :
///       Provide a class describing an option's type and other attributes.
///
/// @}
/** @} */