Package balcl

Modules
	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.

Detailed Description

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:

• 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.

 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.