LibCppCmdLine

A cross-platform C++ library for parsing command line arguments

Description

LibCppCmdLine is a modern, lightweight, cross-platform C++ command line parsing library. It provides a set of classes for parsing command line arguments passed to a program via the main() function and populating command line parameters with values as a result of parsing.

A program that uses this library will:

1. Define and create command line parameters.
2. Create a new command line parser.
3. Add the command line parameters to the parser.
4. Parse the command line arguments with the parser.
5. Examine the parameters that were populated by the parser.

The library uses the C++ Standard Template Library (STL) and therefore has no major external dependencies. It is lightweight enough to be added directly to a program's code base, though it can also be precompiled and linked statically or dynamically if desired. The library uses exceptions only to enforce class invariants and prevent programming errors. In practice, exceptions are only generated if parameters are defined incorrectly or duplicate parameters are added, so consumer code typically does not need try/catch blocks.

Note

The tests for this library do have an external dependency: GoogleTest. However, the tests are only needed when testing changes to the library itself and are not needed for a program that simply includes the library as-is.

Features

• Lightweight.
• Cross-platform.
• No external dependencies.
• Designed to be added and compiled straight into your program's code base.
• Supports two types of options and two types of positional parameters.
• Options can have either the Windows or Unix-style prefix.
• Standard options act like simple switches.
• Value options support multiple values and their own option parameters.
• Positional parameters come in single-value or multi-value varieties.
• The parser can generate usage and help information based on the parameters.

Limitations

• Only supports ASCII command line arguments.
• Not designed for programs with a highly complex command line use case.

Namespace

Everything in this library is contained within the CmdLine namespace.

The CmdLine namespace encapsulates all objects and functions related to command line argument parsing. Command line arguments are the string arguments passed to the main() function from the operating system, typically from a command line interface (CLI).

Key Classes

The following classes are necessary to parse command line arguments.

Class	Purpose
CmdLine::Parser	Parses command line arguments
CmdLine::Param (base)	A variable that stores data from the command line
CmdLine::ArgParam (base)	A CmdLine::Param populated by command line arguments
CmdLine::ProgParam	A CmdLine::ArgParam populated by the program name argument
CmdLine::Option	A CmdLine::ArgParam that represents an option
CmdLine::ValueOption	A CmdLine::Option populated with values
CmdLine::OptionParam	Provides parameters for CmdLine::ValueOption values
CmdLine::PosParam	A positional CmdLine::ArgParam
CmdLine::MultiPosParam	A multi-value positional CmdLine::ArgParam

Key Structs

The following structs are necessary to define command line parameters.

Struct	Purpose
CmdLine::ProgParam::Definition	Used to construct a CmdLine::ProgParam
CmdLine::Option::Definition	Used to construct a CmdLine::Option
CmdLine::ValueOption::Definition	Used to construct a CmdLine::ValueOption
CmdLine::OptionParam::Definition	Used to construct a CmdLine::OptionParam
CmdLine::PosParam::Definition	Used to construct a CmdLine::PosParam
CmdLine::MultiPosParam::Definition	Used to construct a CmdLine::MultiPosParam

Including the Library in Your Project

LibCppCmdLine builds a CMake target named LibCppCmdLine. After adding the library to your project, link that target to your executable or library:

target_link_libraries(YourTarget PRIVATE LibCppCmdLine)

Option 1: Add It as a Git Submodule

Add the repository as a submodule inside your project:

git submodule add https://github.com/stephenbonar/LibCppCmdLine external/LibCppCmdLine
git submodule update --init --recursive

Then include it from your top-level CMakeLists.txt:

cmake_minimum_required(VERSION 3.12)
project(YourProject)
 
set(LIBCPPCMDLINE_BUILD_TESTS OFF CACHE BOOL "" FORCE)
add_subdirectory(external/LibCppCmdLine)
 
add_executable(YourTarget src/main.cpp)
target_link_libraries(YourTarget PRIVATE LibCppCmdLine)

Use this approach when you want the library source checked into your repository and versioned alongside your project.

Option 2: Fetch It During CMake Configure

If you do not want to keep the library in your source tree, you can have CMake fetch it directly from Git during configuration with FetchContent:

cmake_minimum_required(VERSION 3.14)
project(YourProject)
 
include(FetchContent)
 
set(LIBCPPCMDLINE_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 
FetchContent_Declare(
        LibCppCmdLine
        GIT_REPOSITORY https://github.com/stephenbonar/LibCppCmdLine.git
        GIT_TAG main
)
 
FetchContent_MakeAvailable(LibCppCmdLine)
 
add_executable(YourTarget src/main.cpp)
target_link_libraries(YourTarget PRIVATE LibCppCmdLine)

If you want a reproducible build, replace GIT_TAG main with a specific tag, branch, or commit hash.

Header Include

Once linked, include the main library header in your source file:

#include "LibCppCmdLine.h"

Notes

• Set LIBCPPCMDLINE_BUILD_TESTS to OFF when embedding the library so your project does not also build this repository's GoogleTest-based test suite.
• The library target publishes its public include directory, so no extra target_include_directories() call is needed in the consuming target.

Examples

The example source files live in examples/ and are built when LIBCPPCMDLINE_BUILD_EXAMPLES=ON (default).

cmake -S . -B build -DLIBCPPCMDLINE_BUILD_EXAMPLES=ON
cmake --build build --target basic_example
cmake --build build --target value_option_example

Run them from the build output directory:

./build/examples/basic_example --help
./build/examples/value_option_example --help

Basic Parsing Example

This example shows how to define a program parameter, a standard option, and a required positional parameter, then parse argv.

#include <iostream>
#include <vector>
#include "LibCppCmdLine.h"
 
int main(int argc, char* argv[])
{
    using namespace CmdLine;
 
    ProgParam::Definition programDef;
    programDef.name = "filesearch";
    programDef.description = "searches files for lines that contain a pattern";
 
    Option::Definition ignoreCaseDef;
    ignoreCaseDef.shortName = 'i';
    ignoreCaseDef.longName = "ignore-case";
    ignoreCaseDef.description = "ignores case when searching";
 
    PosParam::Definition patternDef;
    patternDef.name = "pattern";
    patternDef.description = "the text to search for";
    patternDef.isMandatory = true;
 
    ProgParam program(programDef);
    Option ignoreCase(ignoreCaseDef);
    PosParam pattern(patternDef);
 
    std::vector<std::string> args(argv, argv + argc);
    Parser parser(&program, args);
 
    parser.Add(&ignoreCase);
    parser.Add(&pattern);
 
    if (parser.Parse() != Parser::Status::Success)
    {
        std::cerr << parser.GenerateUsage() << '\n';
        return 1;
    }
 
    if (parser.BuiltInHelpOptionIsSpecified())
    {
        std::cout << parser.GenerateHelp() << '\n';
        return 0;
    }
 
    std::cout << "pattern: " << pattern.Value() << '\n';
    std::cout << "ignore case: " << std::boolalpha
              << ignoreCase.IsSpecified() << '\n';
}

Example command lines:

filesearch test-pattern
filesearch --ignore-case test-pattern
filesearch -i test-pattern

Value Option Example

This example shows how to use a ValueOption with OptionParam objects to handle commands such as --edit artist=The Beatles --edit album=Revolver.

#include <iostream>
#include <vector>
#include "LibCppCmdLine.h"
 
int main(int argc, char* argv[])
{
    using namespace CmdLine;
 
    ProgParam::Definition programDef;
    programDef.name = "mediaedit";
    programDef.description = "prints and edits tags in media files";
 
    ValueOption::Definition editDef;
    editDef.shortName = 'e';
    editDef.longName = "edit";
    editDef.description = "edits the specified fields";
 
    OptionParam::Definition artistDef;
    artistDef.name = "artist";
    artistDef.description = "the song artist";
 
    OptionParam::Definition albumDef;
    albumDef.name = "album";
    albumDef.description = "the album of the song";
 
    MultiPosParam::Definition filesDef;
    filesDef.name = "filenames";
    filesDef.description = "the media files to process";
    filesDef.isMandatory = true;
 
    ProgParam program(programDef);
    ValueOption edit(editDef);
    OptionParam artist(artistDef);
    OptionParam album(albumDef);
    MultiPosParam files(filesDef);
 
    edit.Add(&artist);
    edit.Add(&album);
 
    std::vector<std::string> args(argv, argv + argc);
    Parser parser(&program, args);
 
    parser.Add(&edit);
    parser.Set(&files);
 
    if (parser.Parse() != Parser::Status::Success)
    {
        std::cerr << parser.GenerateUsage() << '\n';
        return 1;
    }
 
    for (const auto& value : edit.Values())
    {
        std::cout << "edit value: " << value << '\n';
    }
 
    if (artist.IsSpecified())
    {
        std::cout << "artist: " << artist.Value() << '\n';
    }
 
    if (album.IsSpecified())
    {
        std::cout << "album: " << album.Value() << '\n';
    }
 
    for (const auto& file : files.Values())
    {
        std::cout << "file: " << file << '\n';
    }
}

Example command line:

mediaedit --edit artist=The Beatles --edit album=Revolver track01.mp3 track02.mp3

API Documentation

The full documentation for the library is available here