API Reference ============= This section provides comprehensive documentation for all public types, procedures, and constants in the fclap library. Main Public Interface --------------------- fclap Module ~~~~~~~~~~~~ The main entry point module that re-exports all public symbols. .. code-block:: fortran use fclap, only: ArgumentParser, Namespace This is the only module users need to import for most use cases. It re-exports all public types, constants, and procedures from the internal modules. Core Types ---------- ArgumentParser ~~~~~~~~~~~~~~ The main parser type for defining and parsing command-line arguments. The core class for parsing command line arguments. This class handles the registration of arguments, parsing of the command line, and generation of help messages. It supports positional arguments, optional flags, subcommands, argument groups, and mutually exclusive options. **Type Components:** .. list-table:: :widths: 25 75 :header-rows: 1 * - Component - Description * - ``prog`` - Program name displayed in help/usage (character, allocatable) * - ``description`` - Description text shown before arguments (character, allocatable) * - ``epilog`` - Text shown after arguments in help (character, allocatable) * - ``version`` - Version string for ``--version`` flag (character, allocatable) * - ``add_help`` - Whether to add ``-h/--help`` automatically (logical, default: .true.) **Type-Bound Procedures:** ``init(self, prog, description, epilog, add_help, version)`` Initialize the parser with optional configuration. - ``self``: The ArgumentParser instance - ``prog``: Optional program name (defaults to argv(0)) - ``description``: Optional description for help output - ``epilog``: Optional text after arguments in help - ``add_help``: Whether to add -h/--help (default: .true.) - ``version``: Optional version string for --version ``init_with_parents(self, parents, prog, description, epilog, add_help, version)`` Initialize parser inheriting from parent parsers. - ``self``: The ArgumentParser instance - ``parents``: Array of parent parsers to inherit arguments from - ``prog``: Optional program name - ``description``: Optional description text - ``epilog``: Optional epilog text - ``add_help``: Whether to add help argument - ``version``: Optional version string ``add_argument(self, name1, name2, name3, name4, action, nargs, type_name, default_val, choices, required, help, metavar, dest, status, visible)`` Add a new argument to the parser. - ``self``: The ArgumentParser instance - ``name1``: First option string or positional name - ``name2-4``: Optional additional option strings - ``action``: Action type (store, store_true, store_false, count, append, help, version) - ``nargs``: Number of arguments to consume (integer or ARG_* constant) - ``type_name``: Value type (string, int, real, logical) - ``default_val``: Default value if not provided - ``choices``: Array of valid choices - ``required``: Whether argument is required - ``help``: Help text for the argument - ``metavar``: Display name in usage - ``dest``: Destination name for storage - ``status``: Argument status (STATUS_ACTIVE, STATUS_DEPRECATED, STATUS_REMOVED) - ``visible``: Whether to show in help output ``add_argument_group(self, title, description)`` Create a new argument group for organizing help output. Returns the index of the created group (integer). ``add_mutually_exclusive_group(self, required)`` Create a mutually exclusive group. Returns the index of the created mutex group (integer). ``add_subparsers(self, title, description, dest)`` Enable subparser (subcommand) support. ``add_parser(self, name, help_text)`` Add a subparser (subcommand). ``parse_args(self)`` Parse command line arguments from the system. Returns a Namespace containing parsed values. ``parse_args_array(self, argv)`` Parse arguments from an array of strings. Returns a Namespace containing parsed values. ``print_help(self)`` Print the help message to stdout. ``print_usage(self)`` Print the usage message to stdout. ``format_usage(self)`` Format and return the usage string. ``format_help(self)`` Format and return the full help text. Namespace ~~~~~~~~~ Container for parsed argument values. Provides dictionary-like access to results. The Namespace type stores the results of ``parse_args()``. It behaves similarly to a dictionary or Python's argparse.Namespace object, providing type-safe getter methods for retrieving argument values. **Type-Bound Procedures:** ``get_string(self, key, default)`` Retrieve a string value by key. - ``key``: The argument destination name - ``default``: Optional default if key not found - Returns: The string value (character, allocatable) ``get_integer(self, key, default)`` Retrieve an integer value by key. - ``key``: The argument destination name - ``default``: Optional default if key not found (integer) - Returns: The integer value ``get_real(self, key, default)`` Retrieve a real value by key. - ``key``: The argument destination name - ``default``: Optional default if key not found (real) - Returns: The real value ``get_logical(self, key, default)`` Retrieve a logical value by key. - ``key``: The argument destination name - ``default``: Optional default if key not found (logical) - Returns: The logical value ``get_string_list(self, key, values, count)`` Retrieve a string list by key. - ``key``: The argument destination name - ``values``: Output array for the values - ``count``: Output number of values retrieved ``get_integer_list(self, key, values, count)`` Retrieve an integer list by key. ``has_key(self, key)`` Check if a key exists and has a value. Returns: ``.true.`` if the key exists and has a value ``show(self, unit)`` Print namespace contents for debugging. - ``unit``: Optional output unit (default: stdout) Action ~~~~~~ Represents a single argument definition with all its properties. The Action type encapsulates everything about an argument: how it appears on the command line, what type of value it expects, how many values it consumes, and what happens when it's encountered. **Type Components:** .. list-table:: :widths: 25 75 :header-rows: 1 * - Component - Description * - ``dest`` - Destination name for storage * - ``option_strings`` - Array of option flags (e.g., "-v", "--verbose") * - ``nargs`` - Number of arguments to consume * - ``help_text`` - Help description * - ``required`` - Whether argument is required * - ``default_value`` - Default value container * - ``metavar`` - Display name in usage * - ``choices`` - Array of valid choices * - ``value_type`` - Expected value type * - ``is_positional`` - Whether positional argument * - ``action_type`` - Type of action to perform Supporting Types ---------------- ValueContainer ~~~~~~~~~~~~~~ Generic container for storing argument values of different types. ValueContainer provides polymorphic storage for string, integer, real, and logical values. It also supports list storage for arguments that accept multiple values. **Type Components:** - ``value_type`` - Type indicator (TYPE_STRING, TYPE_INTEGER, etc.) - ``string_value`` - String storage - ``integer_value`` - Integer storage - ``real_value`` - Real storage - ``logical_value`` - Logical storage - ``string_list`` - String array storage (for append/nargs) - ``integer_list`` - Integer array storage - ``real_list`` - Real array storage - ``list_count`` - Number of items in list - ``is_set`` - Whether value has been set ArgumentGroup ~~~~~~~~~~~~~ Organizes related arguments in the help output. ArgumentGroup allows you to organize arguments into logical groups that appear together in the help output with a custom title and description. **Type Components:** - ``title`` - Group title - ``description`` - Group description - ``required`` - Whether group is required MutuallyExclusiveGroup ~~~~~~~~~~~~~~~~~~~~~~ Ensures only one argument from the group can be used. A MutuallyExclusiveGroup ensures that only one of its member arguments can be used at a time. If the user specifies more than one, a parsing error will occur. **Type Components:** - ``title`` - Group title - ``required`` - Whether one option must be chosen fclap_error ~~~~~~~~~~~ Error handling type for parser errors. Stores error information including a message, the related argument name, and a flag indicating whether an error has occurred. **Type Components:** - ``message`` - Error message - ``argument`` - Related argument name - ``has_error`` - Error state flag **Type-Bound Procedures:** ``init(self, message, argument)`` Initialize error with message and optional argument. ``report(self, unit)`` Report error to output unit. ``clear(self)`` Clear the error state. Constants --------- Nargs Specifiers ~~~~~~~~~~~~~~~~ Control how many command-line arguments are consumed: .. code-block:: fortran integer, parameter :: ARG_OPTIONAL = -1 ! '?' - zero or one argument integer, parameter :: ARG_ZERO_OR_MORE = -2 ! '*' - zero or more arguments integer, parameter :: ARG_ONE_OR_MORE = -3 ! '+' - one or more arguments integer, parameter :: ARG_PARSER = -4 ! For subparser mode integer, parameter :: ARG_REMAINDER = -5 ! '...' - all remaining arguments integer, parameter :: ARG_SINGLE = 1 ! Single argument (default) Type Specifiers ~~~~~~~~~~~~~~~ Identify the expected value type: .. code-block:: fortran integer, parameter :: TYPE_STRING = 1 ! Character string values integer, parameter :: TYPE_INTEGER = 2 ! Integer values integer, parameter :: TYPE_REAL = 3 ! Real/floating-point values integer, parameter :: TYPE_LOGICAL = 4 ! Boolean values Action Types ~~~~~~~~~~~~ Specify what action to perform when argument is encountered: .. code-block:: fortran integer, parameter :: ACT_STORE = 1 ! Store single value (default) integer, parameter :: ACT_STORE_TRUE = 2 ! Store .true. when flag present integer, parameter :: ACT_STORE_FALSE = 3 ! Store .false. when flag present integer, parameter :: ACT_COUNT = 4 ! Count flag occurrences integer, parameter :: ACT_APPEND = 5 ! Append value to list integer, parameter :: ACT_HELP = 6 ! Print help and exit integer, parameter :: ACT_VERSION = 7 ! Print version and exit Argument Status ~~~~~~~~~~~~~~~ Control argument lifecycle: .. code-block:: fortran integer, parameter :: STATUS_ACTIVE = 0 ! Normal active argument integer, parameter :: STATUS_DEPRECATED = 1 ! Deprecated with warning integer, parameter :: STATUS_REMOVED = 2 ! Removed, will error Group Types ~~~~~~~~~~~ Identify argument group types: .. code-block:: fortran integer, parameter :: GROUP_STANDARD = 1 ! Standard group for organization integer, parameter :: GROUP_MUTEX = 2 ! Mutually exclusive group Special Values ~~~~~~~~~~~~~~ .. code-block:: fortran character(len=*), parameter :: SUPPRESS = "==SUPPRESS==" ! Suppress default/help display Utility Functions ----------------- ``get_prog_name(override)`` Get program name from command line. - ``override``: Optional custom program name to use - Returns: The program name string ``get_fclap_version(major, minor, patch)`` Get fclap version components. - ``major``: Major version number (output) - ``minor``: Minor version number (output) - ``patch``: Patch version number (output) ``fclap_version_compact()`` Get compact version string (e.g., "1.2.3"). ``fclap_version_string()`` Get full version string (e.g., "fclap version 1.2.3").