/syscmdline

C++ Advanced Command Line Parser

Primary LanguageC++MIT LicenseMIT

SysCmdLine

C++ Advanced Command Line Parser.

Inspired by Qt QCommandLineParser and C# System.CommandLine.

Introduction

To be in line with the principle of "don't learn anything new if you don't need to", on the one hand, syscmdline contains as many common features as possible, on the other hand, it's simple enough to be easy to understand.

Therefore, the project is designed to be configurable, but it's not intended to be as complex as a framework.

Features

  • Support sub-commands
  • Support case-insensitive parsing
  • Support global options
  • Support mutually exclusive options
  • Support short options and group flags
  • Support help text customization
  • Support localization
  • Simple tips for typo correction
  • Special implementations for Windows
  • Highly configurable
  • Friendly interface

Simple Example

A simple mv command:

#include <iostream>
#include <syscmdline/parser.h>

namespace SCL = SysCmdLine;

int main(int argc, char *argv[]) {
    SCL::Command cmd("mv", "move files to directory");
    cmd.addArguments({
        SCL::Argument("files", "Source files").multi(),
        SCL::Argument("dir", "Destination directory"),
    });
    cmd.addHelpOption();
    cmd.setHandler([](const SCL::ParseResult &result) -> int {
        std::cout << "[Sources]" << std::endl;
        for (const auto &item : result.values("files")) {
            std::cout << item.toString() << std::endl;
        }
        std::cout << "[Destination]" << std::endl;
        std::cout <<  result.value("dir").toString() << std::endl;
        return 0;
    });
    return SCL::Parser(cmd).invoke(argc, argv);
}

Running the code:

> ./mv --help
Description:
    move files to directory

Usage:
    mv <files>... <dir> [options]

Arguments:
    <files>    Source files
    <dir>      Destination directory

Options:
    -h, --help    Show help information
> ./mv 1 2
[Sources]
1
[Destination]
2
>./mv 1 2 3
[Sources]
1        
2        
[Destination]
3

Quick Start

Concepts

If you are confused about some of the concepts of command line programs, you can learn the following, which will help you use this project.

See Concepts to learn more.

More Examples

See Examples to learn more.

CMake Intergration

Build & Install

cmake -B build -G Ninja
cmake --build build --target all
cmake --build build --target install

Import

find_package(syscmdline REQUIRED)
target_link_libraries(my_project PRIVATE syscmdline::syscmdline)

Notice

  • Minimize Size

    • In order to achieve more functionalities, this project contains a large amount of codes so that the binary size may be relatively large compared with other libraries. Therefore, this implementation uses STL templates as little as possible.
    • It's suggested to enable size optimizing option for your compiler when building executables.
  • Validity Check

    • The root command must be valid, otherwise the parsing result is undefined and may even cause crash.
    • Validity checking is enabled if SYSCMDLINE_ENABLE_VALIDITY_CHECK is defined, which reduces parsing performance. Therefore, this macro is enabled only in debug mode.

Thanks

Other Projects

Contributors

License

This project is licensed under the MIT License.