Command-Line Programs in C++

// src/main.cpp -- CLI11 v2.7.2 (not compiled while this page was written)
#include <CLI/CLI.hpp>

#include <algorithm>
#include <cctype>
#include <cstddef>
#include <print>
#include <string>

namespace {

// A custom validator: returns an empty string on success, a message on failure.
// It may also rewrite the value, here to strip hyphens.
const CLI::Validator isbn13{
    [](std::string& value) -> std::string {
        std::string digits;
        for (char c : value) {
            if (c != '-') digits += c;
        }
        const bool numeric = std::all_of(digits.begin(), digits.end(),
                                         [](unsigned char c) { return std::isdigit(c) != 0; });
        if (digits.size() != 13 || !numeric) return "an ISBN-13 has 13 digits";
        int sum = 0;
        for (std::size_t i = 0; i < 13; ++i) {
            sum += (digits[i] - '0') * (i % 2 == 0 ? 1 : 3);
        }
        if (sum % 10 != 0) return "the ISBN-13 check digit is wrong";
        value = digits;
        return {};
    },
    "ISBN-13", "isbn13"};

}  // namespace

int main(int argc, char** argv) {
    CLI::App app{"Bookshelf catalogue", "shelf"};
    app.set_version_flag("--version", "shelf 1.0.0");
    app.set_config("--config", "shelf.toml", "Read options from a TOML file");
    app.require_subcommand(1);

    // shelf list [--author NAME] [--limit N] [--json]
    auto* list = app.add_subcommand("list", "List books");
    std::string author;
    int limit = 20;
    bool json = false;
    list->add_option("-a,--author", author, "Only books by this author");
    list->add_option("-n,--limit", limit, "Maximum number of rows")
        ->check(CLI::Range(1, 1000))
        ->envname("SHELF_LIMIT")
        ->capture_default_str();
    list->add_flag("--json", json, "Print JSON instead of a table");

    // shelf add TITLE --isbn ISBN
    auto* add = app.add_subcommand("add", "Add a book to the catalogue");
    std::string title;
    std::string isbn;
    add->add_option("title", title, "Title of the book")->required();
    add->add_option("--isbn", isbn, "ISBN-13, hyphens allowed")->required()->check(isbn13);

    // shelf loan ISBN --to MEMBER
    auto* loan = app.add_subcommand("loan", "Lend a book to a member");
    std::string loan_isbn;
    std::string member;
    loan->add_option("isbn", loan_isbn, "ISBN-13 of the book")->required()->check(isbn13);
    loan->add_option("--to", member, "Member who borrows the book")->required();

    CLI11_PARSE(app, argc, argv);

    if (list->parsed()) {
        std::println("list: author='{}' limit={} json={}", author, limit, json);
    } else if (add->parsed()) {
        std::println("add: '{}' ({})", title, isbn);
    } else if (loan->parsed()) {
        std::println("loan: {} to {}", loan_isbn, member);
    }
    return 0;
}

# shelf.toml
[list]
limit = 50

// list.cpp -- cxxopts v3.3.1 (not compiled while this page was written)
#include <cxxopts.hpp>

#include <exception>
#include <iostream>
#include <print>
#include <string>

int main(int argc, char** argv) {
    cxxopts::Options options("shelf list", "List the books in the catalogue");
    options.add_options()
        ("a,author", "Only books by this author", cxxopts::value<std::string>())
        ("n,limit", "Maximum number of rows", cxxopts::value<int>()->default_value("20"))
        ("json", "Print JSON instead of a table")
        ("h,help", "Print usage");

    try {
        const auto result = options.parse(argc, argv);
        if (result.count("help") > 0) {
            std::cout << options.help() << '\n';
            return 0;
        }
        const int limit = result["limit"].as<int>();
        if (limit < 1 || limit > 1000) {
            std::println(stderr, "shelf: --limit must be between 1 and 1000");
            return 2;
        }
        const std::string author = result.count("author") > 0 ? result["author"].as<std::string>() : "";
        std::println("list: author='{}' limit={} json={}", author, limit, result.count("json") > 0);
        return 0;
    } catch (const std::exception& e) {
        std::println(stderr, "shelf: {}", e.what());
        return 2;
    }
}

// list.cpp -- Boost 1.92 Program_options (not compiled while this page was written)
#include <boost/program_options.hpp>

#include <iostream>
#include <print>
#include <string>

namespace po = boost::program_options;

int main(int argc, char** argv) {
    po::options_description desc("Options");
    desc.add_options()
        ("help,h", "print usage")
        ("author,a", po::value<std::string>(), "only books by this author")
        ("limit,n", po::value<int>()->default_value(20), "maximum number of rows")
        ("json", po::bool_switch(), "print JSON instead of a table");

    po::variables_map vm;
    try {
        // The first source stored wins: command line, then environment (SHELF_LIMIT).
        po::store(po::parse_command_line(argc, argv, desc), vm);
        po::store(po::parse_environment(desc, "SHELF_"), vm);
        po::notify(vm);
    } catch (const po::error& e) {
        std::println(stderr, "shelf: {}", e.what());
        return 2;
    }

    if (vm.count("help") > 0) {
        std::cout << desc << '\n';
        return 0;
    }
    const std::string author = vm.count("author") > 0 ? vm["author"].as<std::string>() : "";
    std::println("list: author='{}' limit={} json={}", author, vm["limit"].as<int>(), vm["json"].as<bool>());
    return 0;
}

#include <format>
#include <print>
#include <string>

int main() {
    std::println("{:<28} {:<18} {:>4}", "Title", "Author", "Year");      // aligned columns
    std::println("{:<28} {:<18} {:>4}", "Dune", "Frank Herbert", 1965);
    std::println(stderr, "shelf: {} books skipped", 2);                  // diagnostics on stderr
    const std::string line = std::format("{:>6.1f}%", 99.5);             // a string, not printed
    std::println("{}", line);
}

// shelf_main.cpp -- build: c++ -std=c++23 shelf_main.cpp -o shelf
#include <cstdio>
#include <cstdlib>
#include <exception>
#include <filesystem>
#include <format>
#include <print>
#include <stdexcept>
#include <string>
#include <string_view>

#ifdef _WIN32
#  include <io.h>
#  define SHELF_ISATTY(f) _isatty(_fileno(f))
#else
#  include <unistd.h>
#  define SHELF_ISATTY(f) isatty(fileno(f))
#endif

namespace fs = std::filesystem;

enum ExitCode : int { ok = 0, failure = 1, usage = 2, not_found = 3 };

struct UsageError : std::runtime_error {
    using std::runtime_error::runtime_error;
};

static bool use_colour(std::FILE* stream) {
    if (const char* v = std::getenv("NO_COLOR"); v != nullptr && *v != '\0') return false;
    if (const char* v = std::getenv("FORCE_COLOR"); v != nullptr && *v != '\0') return true;
    if (const char* t = std::getenv("TERM"); t != nullptr && std::string_view{t} == "dumb") return false;
    return SHELF_ISATTY(stream) != 0;
}

// path::string() uses the ANSI code page on Windows; go through UTF-8 instead.
static std::string utf8(const fs::path& p) {
    const auto u = p.generic_u8string();
    return {u.begin(), u.end()};
}

static int run(int argc, char** argv) {
    if (argc < 2) throw UsageError{"missing command (try: shelf list)"};
    const std::string_view command = argv[1];
    if (command != "list") throw UsageError{std::format("unknown command '{}'", command)};

    const fs::path catalogue = argc > 2 ? fs::path{argv[2]} : fs::path{"data"} / "books.csv";
    if (!fs::exists(catalogue)) {
        std::println(stderr, "shelf: no such catalogue: {}", utf8(catalogue));
        return not_found;
    }
    const bool colour = use_colour(stdout);
    const std::string_view heading = colour ? "\x1b[1m" : "";
    const std::string_view reset = colour ? "\x1b[0m" : "";
    std::println("{}Catalogue{} {} ({} bytes)", heading, reset, utf8(catalogue),
                 fs::file_size(catalogue));
    return ok;
}

int main(int argc, char** argv) {
    try {
        return run(argc, argv);
    } catch (const UsageError& e) {
        std::println(stderr, "shelf: {}", e.what());
        return usage;
    } catch (const fs::filesystem_error& e) {
        std::println(stderr, "shelf: {}: {}", utf8(e.path1()), e.code().message());
        return failure;
    } catch (const std::exception& e) {
        std::println(stderr, "shelf: internal error: {}", e.what());
        return failure;
    } catch (...) {
        std::println(stderr, "shelf: unknown internal error");
        return failure;
    }
}

$ ./shelf list
Catalogue data/books.csv (4 bytes)
$ FORCE_COLOR=1 ./shelf list | cat -v
^[[1mCatalogue^[[0m data/books.csv (4 bytes)
$ ./shelf list | cat -v
Catalogue data/books.csv (4 bytes)
$ ./shelf zap; echo "status=$?"
shelf: unknown command 'zap'
status=2
$ ./shelf list nope; echo "status=$?"
shelf: no such catalogue: nope
status=3

# CMakeLists.txt
cmake_minimum_required(VERSION 3.25)
project(shelf VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

find_package(CLI11 CONFIG REQUIRED)
# cxxopts: find_package(cxxopts CONFIG REQUIRED)       -> cxxopts::cxxopts
# Boost:   find_package(Boost REQUIRED COMPONENTS program_options) -> Boost::program_options

add_executable(shelf src/main.cpp)
target_link_libraries(shelf PRIVATE CLI11::CLI11)

install(TARGETS shelf RUNTIME DESTINATION bin)

{
  "name": "shelf",
  "version": "1.0.0",
  "dependencies": ["cli11", "fmt"]
}

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build build

[requires]
cli11/[>=2.7 <3]

[generators]
CMakeDeps
CMakeToolchain

conan install . --output-folder=build --build=missing -s build_type=Release
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake
cmake --build build