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
/// @{
/// * <a href="#balcl-purpose"> Purpose</a>
/// * <a href="#balcl-mnemonic"> Mnemonic </a>
/// * <a href="#balcl-description"> Description </a>
///   * <a href="#balcl-overview"> Overview </a>
///   * <a href="#balcl-option-attributes"> Option Attributes </a>
///   * <a href="#balcl-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#balcl-component-synopsis"> Component Synopsis </a>
///
/// # 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`.
/// Full details can be found in the documentation of @ref balcl_commandline  and
/// the other components of this package.
///
/// ## Overview {#balcl-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
///    @ref balcl-option-attributes ).
///
/// ## Option Attributes {#balcl-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 {#balcl-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 {#balcl-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.
///
/// @}
/** @} */