Quick Start

#include<structopt/app.hpp>structOptions {// positional argument//   e.g., ./main <file>   std::string config_file;// optional argument//   e.g., -b "192.168.5.3"//   e.g., --bind_address "192.168.5.3"//// options can be delimited with `=` or `:`// note: single dash (`-`) is enough for short & long option//   e.g., -bind_address=localhost//   e.g., -b:192.168.5.3//// the long option can also be provided in kebab case://   e.g., --bind-address 192.168.5.3   std::optional<std::string> bind_address;// flag argument// Use `std::optional<bool>` and provide a default value.//   e.g., -v//   e.g., --verbose//   e.g., -verbose   std::optional<bool> verbose =false;// directly define and use enum classes to limit user choice//   e.g., --log-level debug//   e.g., -l errorenumclassLogLevel { debug, info, warn, error, critical };   std::optional<LogLevel> log_level = LogLevel::info;// pair argument// e.g., -u <first> <second>// e.g., --user <first> <second>   std::optional<std::pair<std::string, std::string>> user;// use containers like std::vector// to collect "remaining arguments" into a list   std::vector<std::string> files;};STRUCTOPT(Options, config_file, bind_address, verbose, log_level, user, files);

intmain(int argc,char *argv[]) {try {// Line of code that does all the work:auto options =structopt::app("my_app").parse<Options>(argc, argv);// Print out parsed arguments:// std::cout << "config_file  = " << options.config_file << "\n";// std::cout << "bind_address = " << options.bind_address.value_or("not provided") << "\n";// std::cout << "verbose      = " << std::boolalpha << options.verbose.value() << "\n";// ...  }catch (structopt::exception& e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main config.csv file5.csv file6.jsonconfig_file  = config.csvbind_address = not providedverbose      = falselog_level    = 1user         = not providedfiles        = { file5.csv file6.json }foo@bar:~$./main config.csv --bind-address localhost:9000 -v -log-level error file1.txt file2.txtconfig_file  = config.csvbind_address = localhost:9000verbose      = truelog_level    = 3user         = not providedfiles        = { file1.txt file2.txt }foo@bar:~$./main config_2.csv --bind-address 192.168.7.3 -log-level debug file1.txt file3.txt file4.txt --user"John Doe""john.doe@foo.com"config_file  = config_2.csvbind_address = 192.168.7.3verbose      = falselog_level    = 0user         = John Doe<john.doe@foo.com>files        = { file1.txt file3.txt file4.txt }

Table of Contents

Getting Started

Positional Arguments

#include<structopt/app.hpp>structFileOptions {// Positional arguments// ./main <input_file> <output_file>  std::string input_file;  std::string output_file;};STRUCTOPT(FileOptions, input_file, output_file);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<FileOptions>(argc, argv);// Print parsed arguments:    std::cout <<"\nInput file  :" << options.input_file <<"\n";    std::cout <<"Output file :" << options.output_file <<"\n";  }catch (structopt::exception& e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main foo.txt bar.csvInput file  : foo.txtOutput file : bar.csvfoo@bar:~$./main foo.csvError: expected value for positional argument `output_file`.USAGE: ./my_app input_file output_fileARGS:    input_file    output_file

Optional Arguments

#include<structopt/app.hpp>structGccOptions {// language standard// e.g., -std=c++17// e.g., --std c++20  std::optional<std::string> std ="c++11";// verbosity enabled with `-v` or `--verbose`// or `-verbose`  std::optional<bool> verbose =false;// enable all warnings with `-Wall`  std::optional<bool> Wall =false;// produce only the compiled code// e.g., gcc -C main.c  std::optional<bool> Compile =false;// produce output with `-o <exec_name>`  std::optional<std::string> output ="a.out";  std::string input_file;};STRUCTOPT(GccOptions, std, verbose, Wall, Compile, output, input_file);intmain(int argc,char *argv[]) {try {auto options =structopt::app("gcc").parse<GccOptions>(argc, argv);// Print parsed arguments    std::cout <<"std        :" << options.std.value() <<"\n";    std::cout <<"verbose    :" << std::boolalpha << options.verbose.value() <<"\n";    std::cout <<"Wall       :" << std::boolalpha << options.Wall.value() <<"\n";    std::cout <<"Compile    :" << std::boolalpha << options.Compile.value() <<"\n";    std::cout <<"Output     :" << options.output.value() <<"\n";    std::cout <<"Input file :" << options.input_file <<"\n";  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main -C main.cppstd        : c++11verbose    : falseWall       : falseCompile    : trueOutput     : a.outInput file : main.cppfoo@bar:~$./main -std=c++17 -o main main.cppstd        : c++17verbose    : falseWall       : falseCompile    : falseOutput     : mainInput file : main.cppfoo@bar:~$./main main.cpp -v -std:c++14 --output:main -Wallstd        : c++14verbose    : trueWall       : trueCompile    : falseOutput     : mainInput file : main.cpp

Double dash (--) Argument

#include<structopt/app.hpp>structGrepOptions {// reverse the matching// enable with `-v`  std::optional<bool> v =false;// positional arguments  std::string search;  std::string pathspec;};STRUCTOPT(GrepOptions, v, search, pathspec);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<GrepOptions>(argc, argv);if (options.v ==true) {      std::cout <<"`-v` provided - Matching is now reversed\n";    }    std::cout <<"Search   :" << options.search <<"\n";    std::cout <<"Pathspec :" << options.pathspec <<"\n";  }catch (structopt::exception& e) {    std::cout << e.what();    std::cout << e.help();  }}

foo@bar:~$./main -v foo bar.txt`-v` provided - Matching is now reversedSearch   : fooPathspec : bar.txtfoo@bar:~$./main -- -v bar.txtSearch   : -vPathspec : bar.txt

Flag Arguments

#include<structopt/app.hpp>structOptions {// verbosity flag// -v, --verbose// remember to provide a default value  std::optional<bool> verbose =false;};STRUCTOPT(Options, verbose);intmain(int argc,char *argv[]) {auto options =structopt::app("my_app").parse<Options>(argc, argv);if (options.verbose ==true) {    std::cout <<"Verbosity enabled\n";  }}

foo@bar:~$./mainfoo@bar:~$./main -vVerbosity enabledfoo@bar:~$./main --verboseVerbosity enabled

Enum Class Arguments

#include<structopt/app.hpp>structStyleOptions {enumclassColor {red, green, blue};// e.g., `--color red`  std::optional<Color> color = Color::red;};STRUCTOPT(StyleOptions, color);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<StyleOptions>(argc, argv);// Use parsed argument `options.color`if (options.color == StyleOptions::Color::red) {        std::cout <<"#ff0000\n";    }elseif (options.color == StyleOptions::Color::blue) {        std::cout <<"#0000ff\n";    }elseif (options.color == StyleOptions::Color::green) {        std::cout <<"#00ff00\n";    }  }catch (structopt::exception& e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main --color red#ff0000foo@bar:~$./main -c blue#0000fffoo@bar:~$./main --color green#00ff00foo@bar:~$./main -c blackError: unexpected input `black` provided for enum argument `color`. Allowed values are {red, green, blue}USAGE: ./my_app [OPTIONS]OPTIONS:    -c, --color <color>

Tuple Arguments

#include<structopt/app.hpp>structCalculatorOptions {// types of operations supportedenumclassoperation { add, subtract, multiply, divide };// single tuple positional argument  std::tuple<operation,int,int> input;};STRUCTOPT(CalculatorOptions, input);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<CalculatorOptions>(argc, argv);auto op = std::get<0>(options.input);auto lhs = std::get<1>(options.input);auto rhs = std::get<2>(options.input);switch(op)    {case CalculatorOptions::operation::add:            std::cout << lhs + rhs <<"\n";break;case CalculatorOptions::operation::subtract:            std::cout << lhs - rhs <<"\n";break;case CalculatorOptions::operation::multiply:            std::cout << lhs * rhs <<"\n";break;case CalculatorOptions::operation::divide:            std::cout << lhs / rhs <<"\n";break;    }  }catch (structopt::exception& e) {    std::cout << e.what();    std::cout << e.help();  }}

foo@bar:~$./main add 1 23foo@bar:~$./main subtract 5 9-4foo@bar:~$./main multiply 16 580foo@bar:~$./main divide 1331 11121foo@bar:~$./main add 5Error: failed to correctly parse tuple `input`. Expected 3 arguments, 2 provided.USAGE: my_app inputARGS:    input

Vector Arguments

$ compiler file1 file2 file3

#include<structopt/app.hpp>structCompilerOptions {// Language standard// e.g., --std c++17  std::optional<std::string> std;// remaining arguments// e.g., ./compiler file1 file2 file3  std::vector<std::string> files{};};STRUCTOPT(CompilerOptions, std, files);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<CompilerOptions>(argc, argv);    std::cout <<"Standard :" << options.std.value_or("not provided") <<"\n";    std::cout <<"Files    : {";std::copy(options.files.begin(), options.files.end(),              std::ostream_iterator<std::string>(std::cout,""));    std::cout <<"}" << std::endl;  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./mainStandard : not providedFiles    : { }foo@bar:~$./main file1.cpp file2.cppStandard : not providedFiles    : { file1.cpp file2.cpp }foo@bar:~$./main file1.cpp file2.cpp --std=c++17Standard : c++17Files    : { file1.cpp file2.cpp }foo@bar:~$./main --std:c++20 file1.cpp file2.cppStandard : c++20Files    : { file1.cpp file2.cpp }

Compound Arguments

#include<structopt/app.hpp>structOptions {// Flag arguments  std::optional<bool> a =false;  std::optional<bool> b =false;// Optional argument// e.g., -c 1.1 2.2  std::optional<std::array<float,2>> c = {};};STRUCTOPT(Options, a, b, c);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<Options>(argc, argv);// Print parsed arguments:    std::cout << std::boolalpha <<"a =" << options.a.value()              <<", b =" << options.b.value() <<"\n";if (options.c.has_value()) {      std::cout <<"c = [" << options.c.value()[0] <<"," << options.c.value()[1]                <<"]\n";    }  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main -ac 3.14 2.718a = true, b = falsec = [3.14, 2.718]foo@bar:~$./main -baa = true, b = truefoo@bar:~$./main -c 1.5 3.0 -aba = true, b = truec = [1.5, 3]

Parsing Numbers

Integer Literals

#include<structopt/app.hpp>structIntegerLiterals {  std::vector<int> numbers;};STRUCTOPT(IntegerLiterals, numbers);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<IntegerLiterals>(argc, argv);for (auto &n : options.numbers)      std::cout << n <<"\n";  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main 1 0x5B 071 0b0101 -35 +98191575-3598

Floating point Literals

#include<structopt/app.hpp>structFloatLiterals {  std::vector<float> numbers;};STRUCTOPT(FloatLiterals, numbers);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<FloatLiterals>(argc, argv);for (auto &n : options.numbers)      std::cout << n <<"\n";  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main -3.15 +2.717 2E-4 0.1e2 .5 -.3 +5.999-3.152.7170.0002100.5-0.35.999

Nested Structures

#include<structopt/app.hpp>structGit {// Subcommand: git configstructConfig : structopt::sub_command {// flag argument `--global`    std::optional<bool> global =false;// key-value pair, e.g., `user.name "John Doe"`    std::array<std::string,2> name_value_pair{};  };  Config config;// Subcommand: git initstructInit : structopt::sub_command {// required argument// repository name    std::string name;  };  Init init;};STRUCTOPT(Git::Config, global, name_value_pair);STRUCTOPT(Git::Init, name);STRUCTOPT(Git, config, init);intmain(int argc,char *argv[]) {try {auto options =structopt::app("my_app").parse<Git>(argc, argv);if (options.config.has_value()) {// config was invoked      std::cout <<"You invoked `git config`:\n";      std::cout <<"Global :" << std::boolalpha << options.config.global.value() <<"\n";      std::cout <<"Input  : (" << options.config.name_value_pair[0] <<"," << options.config.name_value_pair[1] <<")\n";    }elseif (options.init.has_value()) {// init was invoked      std::cout <<"You invoked `git init`:\n";      std::cout <<"Repository name :" << options.init.name <<"\n";    }  }catch (structopt::exception& e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main config user.email"john.doe@foo.com"You invoked `git config`:Global : falseInput  : (user.email, john.doe@foo.com)foo@bar:~$./main config user.name"John Doe" --globalYou invoked `git config`:Global : trueInput  : (user.name, John Doe)foo@bar:~$./main init my_repoYou invoked `git init`:Repository name : my_repofoo@bar:~$./main -hUSAGE: my_app [OPTIONS] [SUBCOMMANDS]OPTIONS:    -h, --help <help>    -v, --version <version>SUBCOMMANDS:    config    initfoo@bar:~$./main config -hUSAGE: config [FLAGS] [OPTIONS] name_value_pairFLAGS:    -g, --globalOPTIONS:    -h, --help <help>    -v, --version <version>ARGS:    name_value_pairfoo@bar:~$./main init -hUSAGE: init [OPTIONS] nameOPTIONS:    -h, --help <help>    -v, --version <version>ARGS:    name

foo@bar:~$./main config user.name"John Doe" init my_repoError: failed to invoke sub-command `init` because a different sub-command, `config`, has already been invoked.

Sub-Commands, Vector Arguments, and Delimited Positional Arguments

#include<structopt/app.hpp>structCommandOptions {structSed : structopt::sub_command {// --trace    std::optional<bool> trace =false;// remaining args    std::vector<std::string> args;// pattern    std::string pattern;// file    std::string file;  };  Sed sed;};STRUCTOPT(CommandOptions::Sed, trace, args, pattern, file);STRUCTOPT(CommandOptions, sed);intmain(int argc,char *argv[]) {auto app =structopt::app("my_app");try {auto options = app.parse<CommandOptions>(argc, argv);if (options.sed.has_value()) {// sed has been invokedif (options.sed.trace ==true) {        std::cout <<"Trace enabled!\n";      }      std::cout <<"Args    :";for (auto& a : options.sed.args) std::cout << a <<"";       std::cout <<"\n";      std::cout <<"Pattern :" << options.sed.pattern <<"\n";      std::cout <<"File    :" << options.sed.file <<"\n";    }else {      std::cout << app.help();    }  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./mainUSAGE: my_app [OPTIONS] [SUBCOMMANDS]OPTIONS:    -h, --help <help>    -v, --version <version>SUBCOMMANDS:    sedfoo@bar:~$./main sed --trace X=1 Y=2 Z=3 --'s/foo/bar/g' foo.txtTrace enabled!Args    : X=1 Y=2 Z=3Pattern : s/foo/bar/gFile    : foo.txt

Printing Help

#include<structopt/app.hpp>structOptions {// positional arguments  std::string input_file;  std::string output_file;// optional arguments  std::optional<std::string> bind_address;// remaining arguments  std::vector<std::string> files;};STRUCTOPT(Options, input_file, output_file, bind_address, files);intmain(int argc,char *argv[]) {auto options =structopt::app("my_app","1.0.3").parse<Options>(argc, argv);}

foo@bar:~$./main -hUSAGE: my_app [OPTIONS] input_file output_file filesOPTIONS:    -b, --bind-address <bind_address>    -h, --help <help>    -v, --version <version>ARGS:    input_file    output_file    filesfoo@bar:~$./main -v1.0.3

Printing CUSTOM Help

#include<structopt/app.hpp>structOptions {// positional arguments  std::string input_file;  std::string output_file;// optional arguments  std::optional<std::string> bind_address;// remaining arguments  std::vector<std::string> files;};STRUCTOPT(Options, input_file, output_file, bind_address, files);intmain(int argc,char *argv[]) {try {const std::string& custom_help ="Usage: ./my_app input_file output_file [--bind-address BIND_ADDRESS] [files...]\n";auto options =structopt::app("my_app","1.0.3", custom_help).parse<Options>(argc, argv);  }catch (structopt::exception &e) {    std::cout << e.what() <<"\n";    std::cout << e.help();  }}

foo@bar:~$./main -hUsage: ./my_app input_file output_file [--bind-address BIND_ADDRESS] [files...]

Building Samples and Tests

git clone https://github.com/p-ranav/structoptcd structoptmkdir build&&cd buildcmake -DSTRUCTOPT_SAMPLES=ON -DSTRUCTOPT_TESTS=ON ..make

WinLibs + MinGW

foo@bar:~$mkdir build&&cd buildfoo@bar:~$cmake -G"MinGW Makefiles" -DCMAKE_CXX_COMPILER="C:/WinLibs/mingw64/bin/g++.exe" -DSTRUCTOPT_SAMPLES=ON -DSTRUCTOPT_TESTS=ON ..foo@bar:~$makefoo@bar:~$.\tests\structopt_tests.exe[doctest] doctest version is "2.3.5"[doctest] run with "--help" for options===============================================================================[doctest] test cases:     54 |     54 passed |      0 failed |      0 skipped[doctest] assertions:    393 |    393 passed |      0 failed |[doctest] Status: SUCCESS!

Compiler Compatibility

Generating Single Header

python3 utils/amalgamate/amalgamate.py -c single_include.json -s.

Contributing

License