DOCSEARCHbyAlgolia
Submit Docs

CLI11 Documentation

repository·main·Indexed 26 days ago

https://github.com/cliutils/cli11

A powerful, header-only command line parser for C++11 and beyond. CLI11 provides an intuitive API for handling options, nested subcommands, validators, and configuration files (INI, TOML). It supports direct value binding, environment variables, and standard shell idioms, with no external dependencies. Compatible with GCC 4.8+, Clang 3.4+, AppleClang 7+, NVCC 7.0+, and MSVC 2015+.

Tokens
29.7K
Snippets
55
Records
206
Agent score
87%

What's inside CLI11

  1. Overview of CLI11 features and requirements

    main

    CLI11 is a powerful, header-only command line parser for C++11 and better. It is designed to be easy to include with no external dependencies and works across Linux, macOS, and Windows.

    Key Features

    • Minimal Syntax: Easy to define command line variables.
    • Subcommands: Supports multiple, nested subcommands and option groups.
    • Configuration Files: Supports TOML, INI, and custom formats for both reading and producing config files.
    • Type Support: Works with common types, simple custom types, and is extensible to exotic types.
    • Standard Idioms: Supports standard shell idioms like grouping flags and positional separators.
    • Direct Value Access: Produces real values that can be used directly in code.

    Supported Compilers

    • GCC 4.8+
    • Clang 3.4+
    • AppleClang 7+
    • NVCC 7.0+
    • MSVC 2015+

  2. Overview of CLI11 core classes

    main

    CLI11 is a C++11 command line parser. The library's functionality is centered around several key classes:

    • CLI::App: Represents the main application or a subcommand.
    • CLI::Option: Represents individual options stored within an App.
    • CLI::Validator: Used to perform checks on option values, which can influence the displayed type name.
    • CLI::Formatter: A subclassable class used to customize how help messages are printed.
    • CLI::ExitCode: A scoped enum providing standard exit codes.
    • CLI::Timer: A timer class located in CLI/Timer.hpp (not included in the main CLI11.hpp header).
    • CLI::AutoTimer: A timer that automatically prints its duration upon destruction.

  4. Advanced CLI11 features

    main

    CLI11 supports a wide range of advanced command-line patterns:

    • Subcommands: Supports infinitely nested subcommands. Each subcommand is a full App instance and can support callback lambda functions when parsed.
    • Configuration Files: Supports reading and producing .ini files for configuration.
    • Environment Variables: Can use environment variables as input for options.
    • Argument Types: Supports positional arguments, flags, fixed or unlimited repeating options, and interdependent options.
    • Shell Idioms: Supports standard shell idioms like -- to signal the end of command options.

  5. Use transform and check validators

    main

    CLI11 provides two types of validators:

    1. transform validators: Mutating validators that can modify the input string. They use the signature std::string(std::string&) and should return an empty string if valid, or an error message if invalid. If an error occurs, you can also throw a CLI::ValidationError.
    2. check validators: Non-mutating validators (recommended). They use the signature std::string(const std::string&) or a subclass of CLI::Validator.

    Use ->transform(validator) to apply a mutating validator and ->check(validator) to apply a non-mutating one.

    // Example of a mutating transform validator
auto transform_validator = CLI::Validator(
        [](std::string &input) {
            if (input == "error") {
                return "error is not a valid value";
            } else if (input == "unexpected") {
                throw CLI::ValidationError{"Unexpected error"};
            }
            input = "new string";
            return "";
        }, "VALIDATOR DESCRIPTION", "Validator name");

cli_global.add_option("option")->transform(transform_validator);

  6. Use Subcommands

    main

    Subcommands allow you to create nested command structures (like git add). Each subcommand is an App instance that can have its own options and further subcommands.

    Key Subcommand Features:

    • Creation: Use add_subcommand("name", "description").
    • Case/Underscore Insensitivity: Use ->ignore_case() or ->ignore_underscore() on a subcommand.
    • Requirements: Use .require_subcommand(min, max) on the parent app to enforce subcommand usage. A single negative value N sets "up to N" allowed subcommands.
    • Detection: Use ->parsed() (or cast to bool) to check if a subcommand was triggered. Use get_subcommands() to list active subcommands, or got_subcommand(name_or_ptr) to check for a specific one.
    • Callbacks: Every app supports callbacks. You can use parse_complete_callback() (runs before config files) or final_callback() (runs after config files).

  7. Basic usage of CLI11

    main

    CLI11 provides a clean and intuitive syntax for defining command-line arguments. It handles help messages, incorrect arguments, and clean exits automatically. You can define options that map directly to local variables, avoiding the need for manual lookups after parsing.

    To compile a simple example with GCC, use the C++11 standard:

    c++ -std=c++11 intro.cpp

  8. Enable Windows-style options

    main

    To support Windows-style command line syntax, call app->allow_windows_style_options(). This allows the following formats:

    • /a (flag)
    • /f filename (option)
    • /long (long flag)
    • /file filename (option with space)
    • /file:filename (option with colon)
    • /long_flag:false (long flag with colon to override default)

    Note: Windows-style options do not support combining short options (like -abc) or values immediately following a short option without a space. Standard Linux-style -- and - options will still work if defined using add_* functions.

  9. Combine and invert Validators

    main

    Validators can be combined using logical operators:

    • & (AND)
    • | (OR)
    • ! (NOT)

    Example: ->check(CLI::Range(0,10)|CLI::Range(20,30)) ensures a value is in either the 0-10 or 20-30 range.

    ->check(CLI::Range(0,10)|CLI::Range(20,30));

// Invert a validator
->check(!CLI::PositiveNumber);

  10. Manage Validator availability via macros

    main

    CLI11 includes several validators that can be enabled or disabled to control binary size or compilation time.

    • To disable non-essential validators, define: #define CLI11_DISABLE_EXTRA_VALIDATORS 1.
    • To enable extra validators, define: #define CLI11_ENABLE_EXTRA_VALIDATORS 1.

    Note: In version 3.0, extra validators will likely be disabled by default and require explicit enablement.

    #define CLI11_DISABLE_EXTRA_VALIDATORS 1

  11. Compile and run a simple CLI11 program

    main

    Assuming CLI11.hpp is in your current directory, you can compile a simple CLI11 program using g++ with the c++11 standard. To view the automatically generated help message, run the executable with the -h or --help flag.

    g++ -std=c++11 simplest.cpp
./a.out -h