CLInok

clinok is a tool for parsing command line options. To create a cli interface for your program, you need to:

1. create a file with a description of the options

file format is a list of option declarations.

Option without default value considered as required (note: TAG default value is always false):

Supported declarations listed below

# TAG is an option which is true if present and has no value.
# for example: git --version
TAG(name, "description")

# supports custom user types
OPTION(type, name, "description", default("default_str_passed_into_parse"))
OPTION(type, name, "description") # without default

# shortcut for OPTION(bool, name, "description", ...)
# value parsed as true for "on", "ON", "1", "yes", "YES", "true"
# and as false for  "off", "OFF", "0", "no", "NO", "false"
BOOLEAN(name, "description", default("false"))
BOOLEAN(name, "description")

# shortcut for OPTION(std::string_view, ...)
STRING(name, "description", default("default string"))
STRING(name, "description")

# shortcut for OPTION(std::int_least64_t, ...)
INTEGER(name, "description", default("42"))
INTEGER(name, "description")

# aliases to other options declared before
# Note: program always supports 'help' option and
# answers autogenerated text when --help present, even if parsing error happen
ALIAS(h, help)
# Note: alias not required to be single character
# alias to alias supported
ALIAS(longalias, option_name)

# declares string enum for using in code/option file itself
DECLARE_STRING_ENUM(color_e, red, blue, green)
OPTION(color_e,  color, "description", default("blue"))

# changes name for option
# useful, when name of option cannot be cpp identifier name, e.g. contains '-' or keyword
RENAME(old_name, "new-name")

# may be presented in declarations file only once
# if present, allows to pass additional arguments in Ninja style
# here 'abc' 'def' and 'lll' are additional arguments, not options.
# stored in cli::option.additional_args
# ninja -C abc def lll
ALLOW_ADDITIONAL_ARGS

3. set generation options

generation options:

• program_options_file: required. file with a list of options in declarative form.
• CLINOK_NAMESPACE_NAME: optional. Value by default: cli. May be used to generate several different cli interfaces, for example if you want to make an interface similar to git status <...options> / git branch <...options> / git stash <...options>

3. #include <clinok/cli_interface.hpp> that generates the options struct, code for parsing options and --help message

example

program_options.def file:

DECLARE_STRING_ENUM(color_e, black, green, red, blue)
// default value is "black", possible values "black", "green", "red", "blue"
OPTION(color_e,  color, "text color", default("black"))

INTEGER(count, "count of lines", default("2"))

ALIAS(h, help)
ALIAS(c, color)

main.cpp file:

#define program_options_file "path/to/program_options.def"
#include <clinok/cli_interface.hpp>

int main(int argc, char* argv[]) {
  cli::error_code ec;
  cli::options o = cli::parse(argc, argv, ec);
  if (ec) {
    cli::print_err(ec);
    return -1;
  }
  your_logic(o.color, o.count);
  return 0;
}

Output:

>name.exe --help

 --color <string>  default: "black", text color. Possible values: [black, green, red, blue]
 --count <int>     default: "2", count of lines
 --help            list of all options
 -h is an alias to help
 -c is an alias to color

>name.exe --colar "red"
unknown option "--colar" you probably meant "--color" option

>name.exe -c "red"
<your logic output>

Notes:

• option is required if has no default value (TAG always have default value)
• if there are several values ​​of one option in the list, the last one replaces the previous one
• program always supports the --help option, if help or alias to help listed in options, help message printed even if parse error happens and program execution ends (std::exit)
• parsing stops on error
• OPTION supports user-defined types, name, parsing and other things may be specialized both for type and for concrete option
• alias to alias possible and supported, e.g. A alias for B, B alias for C => A alias for C
• unix style alias collapsing is not supported to avoid misinterpretation of typos example which situation this library avoids:

misspelled option --force typed as -force may be interpreted by linux cli as
—force —overwrite —remove —critical —entries

in clinok its just "may be you meant --force"