cmdr-cxx {#mainpage}

cmdr-cxx ^pre-release^ is a C++17 header-only command-line arguments parser, config manager, and application framework. As a member of #cmdr series, it provides a fully-functional Option Store (Configuration Manager) for your hierarchical configuration data.

See also golang version: cmdr.

Features

• POSIX-Compliant command-line argument parser

  • supports long flag (REQUIRED, --help, short flag (-h), and aliases (--usage, --info, ...)
  • supports multi-level sub-commands
  • supports short flag compat: -vab == -v -a -b, -r3ap1zq == -r 3 -ap 1 -z -q
  • supports passthrough flag: -- will terminate the parsing
  • supports lots of data types for a flag: bool, int, uint, float, string, array, chrono duration, ...
    • allows user-custom data types
  • automated help-screen printing (-hhh to print the hidden items)

• Robust Interfaces

  • Hooks or Actions:

    • global: pre/post-invoke
    • flags: on_hit
    • commands: on_hit, pre/post-invoke, invoke

  • Supports non-single-char short flag: -ap 1

  • Supports for -D+, -D- to enable/disable a bool option

  • Supports sortable command/flag groups

  • Supports toggleable flags - just like a radio button group

  • Free style flags arrangements: $ app main sub4 bug-bug2 zero-sub3 -vqb2r1798b2r 234 --sub4-retry1 913 --bug-bug2-shell-name=fish ~~debug --int 67 -DDD --string 'must-be' --long 789

  • Smart suggestions for wrong command and flags

    based on Jaro-Winkler distance. See Snapshot

  • Builtin commands and flags

    • Help: -h, -?, --help, --info, --usage, ...
      • help command: app help server pause == app server pause --help.
    • Version & Build Info: --version/--ver/-V, --build-info/-#
    • version/versions command available.
    • Simulating version at runtime with —-version-sim 1.9.1

  • ~~tree: lists all commands and sub-commands.

    • ~~debug: print the debugging info
    • --no-color: disable terminal color in outputting
    • --config <location>: specify the location of the root config file. [only for yaml-loader]

  • Verbose & Debug: —verbose/-v, —debug/-D, —quiet/-q

  • Supports -I/usr/include -I=/usr/include -I /usr/include -I:/usr option argument specifications Automatically allows those formats (applied to long option too):

    • -I file, -Ifile, and -I=files
    • -I 'file', -I'file', and -I='files'
    • -I "file", -I"file", and -I="files"

  • Envvars overrides: HELP=1 ./bin/test-app2-c2 server pause is the equivalent of ./bin/test-app2-c2 server pause --help

  • Extensible external loaders: cli.set_global_on_loading_externals(...);

  • Extending internal actions for special operations auch as printing help screen...

• Hierarchical Data Manager - Option Store

  • various data types supports
  • accusing the item with its dotted path key (such as server.tls.certs.cert-bundle)
  • See also Fast Doc section.

Status

• v0.5.9 - fixed deps-cmdr11.cmake for you, added CMDR_NO_3RDPARTY option to disable importing and linking with 3rd-party libraries
• v0.5.8 - fixed unused requires in cmdr-chrono.hh
• v0.5.7 - fixed all builds on c++20 (unused param; ambiguous operator << for time_point/duration; ...)
• v0.5.5 - fixed importing cmdr11(-cxx) via cmake ExternalProject_Add
• v0.5.3 - fixed upload-artifact in last release

  actions/upload-artifact and download-artifact must be same major version (such as v4, both)

• v0.5.2 [incomplete] - fixed upload/download-artifact in last release; compliant with c++20 or higher
• v0.5.1 [incomplete] - security patch the workflow script; fixed it;
• v0.5.0 - upgraded to compliant with cxx20 and later
• v0.3.1 - bugs fixed and added constexpr compiler_name and a new test: test-compiler;
• v0.3.0 - bugs fixed and sync codes for main compilers;
• v0.2.27 - LICENSE Changed to Apache 2.0; better adaptive in cmake import;
• v0.2.25 - follow windows virtual environment changed in adaptation; format codes with better style
• v0.2.23 - improved ci scripts, traits, detections, and more for better cross-platform portability;
• v0.2.21 - bug fixed; add more utilities: mmap, thread pool, factory, pipeable, ...;
• v0.2.20 - changed OS_xxx macros; added more portability;
• v0.2.19 - bug fixed
• v0.2.17 - added to homebrew.
• v0.2.15 - bug fixed
• v0.2.13 - any kind of fixes; added priority-queue; added ASSERTIONS_ONLY, NO_ASSERTIONS_ONLY; added is_iterable, added vector_to_string(vec); defer<T> & defer<bool>; many improvements merged;
• v0.2.11 - maintained
• v0.2.10 - MSVC (Build Tool 16.7.2+, VS2019 passed), and others improvements (bash completion, ...)
• v0.2.9 - various fixes, improvements
• v0.2.8 - fixed cmdr11Config.cmake for importing transparently
• v0.2.7 - auto &cli = cmdr::create(...)
• v0.2.5 - public release starts

CXX 17/20 Compilers

• gcc 10+: passed
• clang 12+: passed
• msvc build tool:
  • 17.2.32505.173 (VS2022 or Build Tool) passed
  • OLD: 16.7.2, 16.8.5 (VS2019 or Build Tool) passed
  • NEW: VS2022 passed

Snapshots

cmdr-cxx prints an evident, clear, and logical help-screen. Please proceed the more snapshots at #1 - Gallery.

Bonus

• golang: cmdr
• .netCore: Cmdr.Core

Usages

Local Deployment

Homebrew

cmdr-cxx can be installed from homebrew:

brew install hedzr/brew/cmdr-cxx

CMake Standard

cmdr-cxx is findable via CMake Modules.

You could install cmdr-cxx manually:

git clone https://github.com/hedzr/cmdr-cxx.git
cd cmdr-cxx
cmake -DCMAKE_VERBOSE_DEBUG=ON -DCMAKE_AUTOMATE_TESTS=OFF -S . -B build/ -G Ninja
# Or:
#    cmake -S . -B build/
cmake --build build/
cmake --install build/
# Or:
#   cmake --build build/ --target install
#
# Sometimes sudo it:
#   sudo cmake --build build/ --target install
# Or:
#   cmake --install build/ --prefix ./dist/install --strip
#   sudo cp -R ./dist/install/include/* /usr/local/include/
#   sudo cp -R ./dist/install/lib/cmake/cmdr11 /usr/local/lib/cmake/
rm -rf ./build
cd ..

More cmake commands:

# clean (all targets files, but the immedieted files)
cmake --build build/ --target clean
# clean and build (just relinking all targets without recompiling)
cmake --build build/ --clean-first

# clean deeply
rm -rf build/

# clean deeply since cmake 3.24.0
# (your custom settings from command-line will lost.
#   For example, if you ever run `cmake -DCMAKE_VERBOSE_DEBUG=ON -S . -B build',
#   and now cmake --fresh -B build/ will ignore `CMAKE_VERBOSE_DEBUG = ON' 
#   and reconfigure to default state.
# )
cmake --fresh -B build/

# recompiling and relinking (simply passing `-B' to `make')
cmake --build build/ -- -B

# reconfigure
rm ./build/CMakeCache.txt && cmake -DENABLE_AUTOMATE_TESTS=OFF -S . -B build/

# print compiling command before exeuting them
cmake --build build/ -- VERBOSE=1
# Or:
VERBOSE=1 cmake --build build/
# Or:
cmake --build build --verbose

dependencies

To build cmdr-cxx, please install these components at first:

• yaml-cpp

The typical install command could be brew install yaml-cpp, For more information, please refer to the chapter Others.

It can be disabled by CMDR_NO_3RDPARTY while building cmdr-cxx:

cmake -DCMDR_NO_3RDPARTY:BOOL=ON -DCMAKE_BUILD_TYPE:STRING=Release -S . -B build-release/

CMake ExternalProject

Adding cmdr11 with ExternalProject is possible. A deps-cmdr11.cmake could be:

#
# FOR CMDR11
#

# message(STATUS "cmdr-cxx: defined macro add_cmdr_cxx_to")
macro(add_cmdr_cxx_to target)
    find_package(cmdr11)

    set(CMDR_CXX_STAGE_DIR "${CMAKE_CURRENT_BINARY_DIR}/cmdr-cxx-stage")

    option(CMAKE_VERBOSE_DEBUG "for cmdr-cxx, enable CMAKE_VERBOSE_MAKEFILE to print command line before execute them" OFF)
    option(CMDR_NO_3RDPARTY "for cmdr-cxx, disable source codes and targets alternate to yaml-cpp and others" ON)

    if(${CMDR11_FOUND})
        message(STATUS "cmdr-cxx: package FOUND at ${CMDR11_INCLUDE_DIR}, ${CMDR11_VERSION}")
        message(STATUS "cmdr-cxx: add cmdr-cxx v${CMDR11_VERSION_STRING} module to '${target}' from CMake Modules registry.")
        target_link_libraries(${target}
            PRIVATE
            ${CMDR11_LIBRARIES}
        )
    else()
        message(STATUS "cmdr-cxx: not found, try pulling a local one...")

        set(CMDR_CXX_TGT_NAME "third-cmdr-cxx")
        include(ExternalProject)
        ExternalProject_Add(${CMDR_CXX_TGT_NAME}
            GIT_REPOSITORY https://github.com/hedzr/cmdr-cxx
            GIT_TAG origin/master # v0.3.13
            GIT_SHALLOW 1
            GIT_PROGRESS ON

            # STEP_TARGETS build
            # SOURCE_DIR "${PROJECT_SOURCE_DIR}/third-party/cmdr-cxx-src"
            # BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/cmdr-cxx-build"
            CMAKE_ARGS
            -DCMAKE_VERBOSE_DEBUG:BOOL=${CMAKE_VERBOSE_DEBUG}
            -DCMDR_NO_3RDPARTY:BOOL=${CMDR_NO_3RDPARTY}
            -DENABLE_TESTS:BOOL=OFF
            -DENABLE_CLI_APP:BOOL=OFF
            -DENABLE_AUTOMATE_TESTS:BOOL=OFF
            -DBUILD_DOCUMENTATION:BOOL=OFF
            -DBUILD_EXAMPLES:BOOL=OFF
            --no-warn-unused-cli
            -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
            -DCMAKE_INSTALL_PREFIX:PATH=${CMDR_CXX_STAGE_DIR}

            # -DCMAKE_INSTALL_PREFIX:PATH=${CMAKE_INSTALL_PREFIX}
            # -DCMAKE_INSTALL_PREFIX:PATH=${EXECUTABLE_OUTPUT_PATH}
            BUILD_COMMAND ${CMAKE_COMMAND} -E echo "[cmdr-cxx] Starting $<CONFIG> build, install_prefix: ${CMAKE_INSTALL_PREFIX} or ${CMDR_CXX_STAGE_DIR}, BINARY_DIR: <BINARY_DIR>"

            # COMMAND ${CMAKE_COMMAND} -E sudo "chmod a+w /usr/local/lib"
            COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
            COMMAND ${CMAKE_COMMAND} -E echo "[cmdr-cxx] $<CONFIG> build complete"
        )

        message(STATUS "cmdr-cxx: add '${CMDR_CXX_TGT_NAME}' module to '${target}' from building dir.")
        message(STATUS "cmdr-cxx:    CI_RUNNING = $ENV{CI_RUNNING}")
        message(STATUS "cmdr-cxx: add_dependencies")
        add_dependencies(${target} ${CMDR_CXX_TGT_NAME})

        set(CMDR11_INCLUDE_DIR ${CMDR_CXX_STAGE_DIR}/include)
        set(CMDR11_LIB_DIR ${CMDR_CXX_STAGE_DIR}/lib)
    endif()

    target_include_directories(${target} PRIVATE
        $<BUILD_INTERFACE:${CMAKE_GENERATED_DIR}>
        $<INSTALL_INTERFACE:include>
        /usr/local/include
        /opt/homebrew/include

        # ${CMDR_CXX_STAGE_DIR}/include
        ${CMDR11_INCLUDE_DIR}
    )
    target_link_directories(${target} PRIVATE
        /usr/local/lib

        # ${CMDR_CXX_STAGE_DIR}/lib
        ${CMDR11_LIBRARY_DIR}

        # ${CMAKE_CURRENT_BINARY_DIR}/${CMDR_CXX_TGT_NAME}-prefix/src/${CMDR_CXX_TGT_NAME}-build
    )
    message(STATUS "cmdr-cxx: include-dir = ${CMDR11_INCLUDE_DIR}")
endmacro()

And the only things you need to do in your CMakeLists.txt are:

project(cmdr-cli-demo)
add_executable(${PROJECT_NAME} cmdr_main.cc)
target_include_directories(${PROJECT_NAME} PRIVATE
	$<BUILD_INTERFACE:${CMAKE_GENERATED_DIR}>
)
include(deps-cmdr11) # include our deps-cmdr11.cmake
add_cmdr_cxx_to(${PROJECT_NAME})

That's all.

Integrate to your cmake script

After installed at local cmake repository (Modules), cmdr-cxx can be integrated as your CMake module. So we might find and use it:

find_package(cmdr11 REQUIRED)

add_executable(my-app)
target_link_libraries(my-app PRIVATE cmdr11::cmdr11)
set_target_properties(${PROJECT_NAME}  PROPERTIES
    CXX_STANDARD 17
    CXX_STANDARD_REQUIRED ON
    CXX_EXTENSIONS ON
    )

Or you can download deps-cmdr11.cmake and include it:

add_executable(my-app)

include(deps-cmdr11)     # put deps-cmdr11.cmake into your cmake module path at first
add_cmdr_cxx_to(my-app)

Short example

#include <cmdr11/cmdr11.hh>
#include "version.h" // xVERSION_STRING

int main(int argc, char *argv[]) {

  auto &cli = cmdr::cli("app2", xVERSION_STRING, "hedzr",
                        "Copyright © 2021 by hedzr, All Rights Reserved.",
                        "A demo app for cmdr-cxx library.",
                        "$ ~ --help");

  try {
    using namespace cmdr::opt;

    cli += sub_cmd{}("server", "s", "svr")
      .description("server operations for listening")
      .group("TCP/UDP/Unix");
    {
      auto &t1 = *cli.last_added_command();

      t1 += opt{(int16_t)(8)}("retry", "r")
      .description("set the retry times");

      t1 += opt{(uint64_t) 2}("count", "c")
      .description("set counter value");

      t1 += opt{"localhost"}("host", "H", "hostname", "server-name")
      .description("hostname or ip address")
        .group("TCP")
        .placeholder("HOST[:IP]")
        .env_vars("HOST");

      t1 += opt{(int16_t) 4567}("port", "p")
      .description("listening port number")
        .group("TCP")
        .placeholder("PORT")
        .env_vars("PORT", "SERVER_PORT");

      t1 += sub_cmd{}("start", "s", "startup", "run")
      .description("start the server as a daemon service, or run it at foreground")
        .on_invoke([](cmdr::opt::cmd const &c, string_array const &remain_args) -> int {
          UNUSED(c, remain_args);
          std::cout << c.title() << " invoked.\n";
          return 0;
        });
      auto &s1 = *t1.last_added_command();
      s1 += cmdr::opt::opt{}("foreground", "f")
      .description("run at fg");

      t1 += sub_cmd{}("stop", "t", "shutdown")
      .description("stop the daemon service, or stop the server");

      t1 += sub_cmd{}("pause", "p")
      .description("pause the daemon service");

      t1 += sub_cmd{}("resume", "re")
      .description("resume the paused daemon service");
      t1 += sub_cmd{}("reload", "r")
      .description("reload the daemon service");
      t1 += sub_cmd{}("hot-reload", "hr")
      .description("hot-reload the daemon service without stopping the process");
      t1 += sub_cmd{}("status", "st", "info", "details")
      .description("display the running status of the daemon service");
    }

  } catch (std::exception &e) {
    std::cerr << "Exception caught for duplicated cmds/args: " << e.what() << '\n';
    CMDR_DUMP_STACK_TRACE(e);
  }

  return cli.run(argc, argv);
}

It is a simple program.

Fast Document

Lookup a command and its flags

The operator () (cli("cmd1.sub-cmd2.sub-sub-cmd") ) could be used for retrieving a command (cmdr::opt::cmd& cc) from cli:

auto &cc = cli("server");
CMDR_ASSERT(cc.valid());
CMDR_ASSERT(cc["count"].valid());     // the flag of 'server'
CMDR_ASSERT(cc["host"].valid());
CMDR_ASSERT(cc("status").valid());    // the sub-command of 'server'
CMDR_ASSERT(cc("start").valid());     // sub-command: 'start'
CMDR_ASSERT(cc("run", true).valid()); // or alias: 'run'

Once cc is valid, use [] to extract its flags.

The dotted key is allowed. For example: cc["start.port"].valid().

CMDR_ASSERT(cli("server.start").valid());
CMDR_ASSERT(cli("server.start.port").valid());

// get flag 'port' of command 'server.start':
CMDR_ASSERT(cc["start.port"].valid());

Extract the matched information of a flag

While a flag given from command-line is matched ok, it holds some hit info. Such as:

auto &cc = cli("server");  // get 'server' command object
CMDR_ASSERT(cc.valid());   // got ok?

CMDR_ASSERT(cc["count"].valid());
CMDR_ASSERT(cc["count"].hit_long()); 	          // if `--count` given
CMDR_ASSERT(cc["count"].hit_long() == false); 	// if `-c` given
CMDR_ASSERT(cc["count"].hit_count() == 1);     	// if `--count` given
CMDR_ASSERT(cc["count"].hit_title() == "c");   	// if `-c` given

CMDR_ASSERT(cli["verbose"].hit_count() == 3);   // if `-vvv` given

// hit_xxx are available for a command too
CMDR_ASSERT(cc.hit_title() == "server");        // if 'server' command given

The value of a flag from command-line will be saved into Option Store, and extracted by shortcut cmdr::get_for_cli() . For example:

auto verbose = cmdr::get_for_cli<bool>("verbose");
auto hostname = cmdr::get_for_cli<std::string>("server.host");

In Option Store, the flag value will be prefixed by "app.cli.", and get_for_cli wraps transparently.

The normal entries in Options Store are prefixed by string "app.". You could define another one of course.

To extract the normal configuration data, cmdr::set and cmdr::get are best choices. They will wrap and unwrap the prefix app transparently.

auto verbose = cmdr::get<bool>("cli.verbose");
auto hostname = cmdr::get<std::string>("cli.server.host");

If you wanna extract them directly:

auto verbose = cmdr::get_store().get_raw<bool>("app.cli.verbose");
auto hostname = cmdr::get_store().get_raw<std::string>("app.cli.server.host");

auto verbose = cmdr::get_store().get_raw_p<bool>("app.cli", "verbose");
auto hostname = cmdr::get_store().get_raw_p<std::string>("app.cli", "server.host");

Set the value of a config item

Every entry in Option Store that we call it a config item. The entries are hierarchical. So we locate it with a dotted key path string.

A config item is free for data type dynamically. That is saying, you could change the data type of a item at runtime. Such as setting one entry to integer array, from integer originally.

But it is hard for coding while you're working for a c++ program.

cmdr::set("wudao.count", 1);
cmdr::set("wudao.string", "str");
cmdr::set("wudao.float", 3.14f);
cmdr::set("wudao.double", 2.7183);
cmdr::set("wudao.array", std::vector{"a", "b", "c"});
cmdr::set("wudao.bool", false);

std::cout << cmdr::get<int>("wudao.count") << '\n';
auto const &aa = cmdr::get< std::vector<char const*> >("wudao.array");
std::cout << cmdr::string::join(aa, ", ", "[", "]") << '\n';

// Or: maybe you will like to stream out a `variable` with standard format.
cmdr::vars::variable& ab = cmdr::get_app().get("wudao.array");
std::cout << ab << '\n';

cmdr::vars::variable

cmdr-cxx provides stream-io on lots of types via cmdr::vars::variable, take a look for further.

Bundled Utilities or Helpers

There are some common cross-platform helper classes. Its can be found in these headers:

• cmdr_defs.hh

• cmdr_types.hh

• cmdr_type_checks.hh

• cmdr_utils.hh

---

• cmdr_dbg.hh

• cmdr_log.gg

---

• cmdr_chrono.hh

• cmdr_if.hh

• cmdr_ios.hh

• cmdr_mmap.hh

• cmdr_os_io_redirect.hh

• cmdr_path.hh

• cmdr_process.hh

• cmdr_pool.hh

• cmdr_priority_queue.hh

• cmdr_string.hh

• cmdr_terminal.hh

Features to improve your app arch

cmdr-cxx provides some debugging features or top view to improve you design at CLI-side.

Default Action

We've been told that we can bind an action (via on_invoke) to a (sub-)command:

t1 += sub_cmd{}("start", "s", "startup", "run")
  .description("start the server as a daemon service, or run it at foreground")
  .on_invoke([](cmdr::opt::cmd const &c, string_array const &remain_args) -> int {
    UNUSED(c, remain_args);
    std::cout << c.title() << " invoked.\n";
    return 0;
  });

For those commands without binding to on_invoke, cmdr-cxx will invoke a default one, For example:

t1 += sub_cmd{}("pause", "p")
  .description("pause the daemon service");

While the end-user is typing and they will got:

❯ ./bin/test-app2-c2 server pause
INVOKING: "pause, p", remains: .
command "pause, p" hit.

Simple naive? Dislike it? The non-hooked action can be customized.

User-custom non-hooked action

Yes you can:

#if CMDR_TEST_ON_COMMAND_NOT_HOOKED
cli.set_global_on_command_not_hooked([](cmdr::opt::cmd const &, string_array const &) {
  cmdr::get_store().dump_full_keys(std::cout);
  cmdr::get_store().dump_tree(std::cout);
  return 0;
});
#endif

~~debug

Special flag has the leading sequence chars ~~.

~~debug can disable the command action and print the internal hitting information.

❯ ./bin/test-app2-c2 server pause -r 5 -c 3 -p 1357 -vvv ~~debug
command "pause, p" hit.
 - 1 hits: "--port=PORT, -p" (hit title: "p", spec:0, long:0, env:0) => 1357
 - 1 hits: "--retry, -r" (hit title: "r", spec:0, long:0, env:0) => 5
 - 1 hits: "--count, -c" (hit title: "c", spec:0, long:0, env:0) => 3
 - 3 hits: "--verbose, -v" (hit title: "v", spec:0, long:0, env:0) => true
 - 1 hits: "--debug, -D, --debug-mode" (hit title: "debug", spec:true, long:true, env:false) => true

Another one in Gallary:

-DDD

Triple D means --debug --debug --debug. In ~~debug mode, triple D can dump more underlying value structure inside Option Store.

The duplicated-flag exception there among others, is expecting because we're in testing.

~~debug --cli -DDD

The values of CLI flags are ignored but ~~cli can make them raised when dumping. See the snapshot at #1 - Gallary.

~~tree

This flag will print the command hierarchical structure:

Remove the cmdr-cxx tail line

By default a citation line(s) will be printed at the ends of help screen:

I knew this option is what you want:

    auto &cli = cmdr::cli("app2", CMDR_VERSION_STRING, "hedzr",
                         "Copyright © 2021 by hedzr, All Rights Reserved.",
                         "A demo app for cmdr-c11 library.",
                         "$ ~ --help")
            // remove "Powered by cmdr-cxx" line
            .set_no_cmdr_endings(true)
            // customize the last line except cmdr endings
            // .set_tail_line("")
            .set_no_tail_line(true);

The "Type ... ..." line could be customized by set_tail_line(str), so called tail line,. Or, you can disable the tail line by set_no_tail_line(bool).

The Powered by ... line can be disabled by set_no_cmdr_ending, so-called cmdr-ending line.

External Loaders

There is a builtin addon yaml-loader for loading the external config files in the pre-defined directory locations. As a sample to show you how to write a external loader, yaml-loader will load and parse the yaml config file and merge it into Option Store.

TODO: conf.d not processed now.

test-app-c1 demonstrates how to use it:

{
  using namespace cmdr::addons::loaders;
  cli.set_global_on_loading_externals(yaml_loader{}());
}

The coresponding cmake fragment might be:

#
# For test-app-c1, loading the dependency to yaml-cpp
#
include(loaders/yaml_loader)
add_yaml_loader(test-app2-c1)

This add-on needs a third-part library,yaml-cpp, presented.

Specials

Inside cmdr-cxx, there are many optimizable points and some of them in working.

• enable dim text in terminal

  CMDR_DIM=1 ./bin/test-app2-c2 main sub4 bug-bug2

• --no-color: do NOT print colorful text with Terminal Escaped Sequences, envvars PLAIN or NO_COLOR available too.

  ./bin/test-app2-c2 --no-color
  PLAIN=1 ./bin/test-app-c2

• enable very verbose debugging

  #define CMDR_ENABLE_VERBOSE_LOG 1
  #include <cmdr11/cmdr11.hh>

• enable unhandled exception handler

  cmdr::debug::UnhandledExceptionHookInstaller _ueh{}; // for c++ exceptions
  cmdr::debug::SigSegVInstaller _ssi{};                // for SIGSEGV ...
  return cli.run(argc, argv);

• -hhh (i.e. --help --help --help) will print the help screen with those invisible items (the hidden commands and flags).

• Tab-stop position is adjustable based the options automatically

• The right-side of a line, in the help screen, command/flag decriptions usually, can be wrapped and aligned along the tab-stop width.

• More...

Use cmdr-cxx As A New App Skeletion

That's very appreciated!

PROs

• cmdr-like programmatical interface.
  • See also Short example and Fast Document
  • See also test app sources
• A fully functional Hierarchical Configurable Data Management Mechanism (so called Option Store) is ready for box.
• Uses debug outputting macros: cmdr_print, cmdr_debug, cmdr_trace (while CMDR_ENABLE_VERBOSE_LOG defined), see cmdr_log.hh

Contributions

Build

gcc 10+: passed

clang 12+: passed

msvc build tool 16.7.2, 16.8.5 (VS2019 or Build Tool) passed

# configure
cmake -DENABLE_AUTOMATE_TESTS=OFF -S . -B build/
# build
cmake --build build/
# install
cmake --build build/ --target install
# sometimes maybe sudo: sudo cmake --build build/ --target install

For msvs build tool, vcpkg should be present, so cmake configure command is:

cmake -DENABLE_AUTOMATE_TESTS=OFF -S . -B build/ -DCMAKE_TOOLCHAIN_FILE=%USERPROFILE%/work/vcpkg/scripts/buildsystems/vcpkg.cmake

If you clone vcvpkg source and bootstrap it at: %USERPROFILE%/work/vcpkg.

Windows Server 2019 Core & VSBT

set VCPKG_DEFAULT_TRIPLET=x64-windows

mkdir %USERPROFILE%/work
cd %USERPROFILE%/work
git clone ...

REM launch `vsbt` build env
SETX PATH "%PATH%;C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\Common7\Tools"
LaunchDevCmd.bat

cd cmdr-cxx
cmake -DENABLE_AUTOMATE_TESTS=OFF -S . -B build/ -DCMAKE_TOOLCHAIN_FILE=%USERPROFILE%/work/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build/

ninja, [Optional]

We use ninja for faster building. That's safe to build cmdr-cxx without it.

ccache, [Optional]

We use ccache for faster building. That's safe to build cmdr-cxx without it.

Other Options

1. BUILD_DOCUMENTATION=OFF
2. ENABLE_TESTS=OFF

Prerequisites

To run all automated tests, or, you're trying to use yaml-loader add-on, some dependencies need to prepared at first, by youself, maybe.

Catch2

If the tests are enabled, Catch2 will be downloaded while cmake configuring and building automatically. If you have a local cmake-findable Catch2 copy, more attentions would be appreciated.

Others

In our tests, test-app2-c1 and yaml-loader will request yaml-cpp is present.

Optional

Linux

sudo apt install -y libyaml-cpp-dev

For CentOS or RedHat: sudo dnf install yaml-cpp yaml-cpp-devel yaml-cpp-static

macOS

brew install yaml-cpp

Windows

vcpkg install yaml-cpp

NOTE that vcpkg want to inject the control file for cmake building, see also Using vcpkg with CMake

Run the examples

The example executables can be found in ./bin after built. For example:

# print command tree (with hidden commands)
./bin/cmdr11-cli -hhh ~~tree

1. You will get them from release page.
2. TODO: we will build a docker release later.
3. Run me from a online CXX IDE.

Hooks in cmdr-cxx

1. auto & cli = cmdr::get_app()

2. Register actions:

   void register_action(opt::Action action, opt::types::on_internal_action const &fn);

   In your pre_invoke handler, some actions called internal actions could by triggered via the returned Action code.

   The Action codes is extensible, followed by a on_internal_action handler user-customized.

3. Hooks

   xxx_handlers or s(_externals) means you can specify it multiple times.

   1. set_global_on_arg_added_handlers, set_global_on_cmd_added_handlers

   2. set_global_on_arg_matched_handlers, set_global_on_cmd_matched_handlers

   3. set_global_on_loading_externals

   4. set_global_on_command_not_hooked

      cmdr prints some hitting info for a sub-command while no on_invoke handler associated with it.

      Or, you can specify one yours via set_global_on_command_not_hooked.

   5. set_global_on_post_run_handlers

   6. set_on_handle_exception_ptr

   7. set_global_pre_invoke_handler, set_global_post_invoke_handler

Thanks to JODL

Thanks to JetBrains for donating product licenses to help develop cmdr-cxx

LICENSE

Apache 2.0