dimcli

Branch	MSVC 2015, 2017, 2019, 2022 / CLANG 6, 9-17 / GCC 7-13	Test Coverage
master
dev

C++ command line parser toolkit for kids of all ages.

GNU style command lines (-o, --output=FILE, etc.)
Parses directly to any supplied (or implicitly created) variable that is:
- Default constructible
- Copyable
- Either assignable or constructible from string, has an istream extraction operator, or has a specialization of Cli::Convert::fromString<T>().
Render help text
Option definitions can be scattered across multiple files.
Git style subcommands.
Response files (requires <filesystem> support).
Convert argv to/from command line with Windows, Posix, or GNU semantics.
Wordwrap arbitrary paragraphs and simple text tables for console.
Works whether or not exceptions and RTTI are disabled.
Distributed under the Boost Software License, Version 1.0.

Sample Usage

Check out the complete documentation, contains many examples, and the quick reference.

#include "dimcli/cli.h"
#include <iostream>
#include <string>
using namespace std;

int main(int argc, char * argv[]) {
    Dim::Cli cli;

    // Define option that populates an existing variable.
    int count;
    cli.opt(&count, "c n count", 1).desc("Times to say hello.");

    // Or, define option without referencing an existing variable. The variable
    // to populate is then implicitly allocated and the returned object is used
    // like a smart pointer to access it.
    auto & name = cli.opt<string>("name", "Unknown")
        .desc("Who to greet.");

    // Parse command line.
    if (!cli.parse(argc, argv))
        return cli.printError(cerr);

    // Access the options.
    if (!name)
        cout << "Greeting the unknown." << endl;
    for (int i = 0; i < count; ++i)
        cout << "Hello " << *name << "!" << endl;
    return 0;
}

What it does when run:

$ a.out -x
Error: Unknown option: -x
$ a.out --help
Usage: a.out [OPTIONS]

Options:
  -c, -n, --count=NUM  Times to say hello. (default: 1)
  --name=STRING        Who to greet. (default: Unknown)

  --help               Show this message and exit.
$ a.out --count=2
Greeting the unknown.
Hello Unknown!
Hello Unknown!
$ a.out --name John
Hello John!

Include in Your Project

Copy source directly into your project

All you need is:

libs/dimcli/cli.h
libs/dimcli/cli.cpp

Using vcpkg

vcpkg install dimcli

Using cmake

Get the latest dimcli release.

Build it (this example uses Visual C++ 2015 to install a 64-bit build to c:\dimcli on a windows machine):

md build & cd build
cmake .. -DCMAKE_INSTALL_PREFIX=c:\dimcli -G "Visual Studio 14 2015 Win64"
cmake --build .
ctest -C Debug
cmake --build . --target install

Working on the dimcli Project

Prerequisites
- install cmake >= 3.6
- install Visual Studio >= 2015
  - include the "Github Extension for Visual Studio" (if you care)
  - include git
Make the library (assuming VS 2015)
- git clone https://github.com/gknowles/dimcli.git
- cd dimcli
- git submodule update --init
- md build & cd build
- cmake .. -G "Visual Studio 14 2015 Win64"
- cmake . --build
Test
- ctest -C Debug
Visual Studio
- open dimcli\build\dimcli.sln

Random Thoughts

Why not a single header file?

On large projects with many binaries (tests, utilities, etc) it's good for compile times to move as much stuff out of the headers as you easily can.
Inflicting <Windows.h> (and to a much lesser extent <termios.h> & <unistd.h>) on all clients seems a bridge too far.

Sources of inspiration:

LLVM CommandLine module
click - Python command line interface creation kit
My own bad experiences

Things that were harder than expected:

Parsing command lines with bash style quoting
Response files - because of the need to transcode UTF-16 on Windows
Password prompting - there's no standard way to disable console echo :(
Build system - you can do a lot with CMake, but it's not always easy

Other interesting C++ command line parsers:

program_options - from boost
gflags - from google
tclap - header only
args - single header
cxxopts - single header
CLI11 - header only

gknowles/dimcli