commandr

Preview

FAQ

• Does it use templates/compile-time magic?

No, at least currently not. Right now everything is done at runtime, so there’s not much overhead on compilation time resources. In the future I’ll probably look into generation of compile-time struct.

The reason is that I want it to be rather simple and easy to learn, and having a lot of generated code hurts e.g. generated documentation and some minor things such as IDE auto-complete (even right now mixin-s cause some problems).

• Are the results typesafe? / Does it use UDA?

No, parsed arguments are returned in a ProgramArgs class instance that allow to fetch parsed data,

However it should be possible to generate program definition from struct/class with UDA and then fill the parsed data into struct instance, but it is currently out of scope of this project (at least for now).

Getting Started

Subcommands

You can create subcommands in your program or command using .add. You can nest commands.

Adding subcommands adds a virtual required argument at the end to your program. This makes you unable to declare repeating or optional arguments (because you cannot have required argument past these).

Default command can be set with .defaultCommand(name) call after defining all commands.

After parsing, every subcommand gets its own ProgramArgs instance, forming a hierarchy. Nested args inherit arguments from parent, so that options defined higher in hierarchy are copied. ProgramArgs defines a helper method on, that allows to dispatch method on specified command.

auto args = new Program("test", "1.0")
      .add(new Flag("v", null, "turns on more verbose output")
          .name("verbose")
          .repeating)
      .add(new Command("greet")
          .add(new Argument("name", "name of person to greet")))
      .add(new Command("farewell")
          .add(new Argument("name", "name of person to say farewell")))
      .parse(args);

args
  .on("greet", (args) {
    // args.flag("verbose") works
    writefln("Hello %s!", args.arg("name"));
  })
  .on("farewell", (args) {
    writefln("Bye %s!", args.arg("name"));
  });

Delegate passed to on function receives ProgramArgs instance for that subcommand. Because it is also ProgramArgs, on chain can be nested, as in:

// assuming program has nested subcommands

a.on("branch", (args) {
  args
    .on("add", (args) {
      writefln("adding branch %s", args.arg("name"));
    })
    .on("rm", (args) {
      writefln("removing branch %s", args.arg("name"));
    });
});

Validation

You can attach one or more validators to options and arguments with validate method. Every validator has its own helper function that simplifies adding it do option (usually starting with accepts):

new Program("test")
  // adding validator manually
  .add(new Option("s", "scope", "")
      .validate(new EnumValidator(["local", "global", "system"]))
  )
  // helper functionnew Program("test")
  .add(new Option("s", "scope", "")
      .acceptsValues(["local", "global", "system"]));

Built-in validators

• EnumValidator - Allows to pass values from white-list.

Helpers: .acceptsValues(values)

• FileSystemValidator - Verifies whenever passed values are files/directories or just exist (depending on configuration).

Helpers: .acceptsFiles(), .acceptsDirectories(), .acceptsPaths(bool existing)

• DelegateValidator - Verifies whenever passed values with user-defined delegate.

Helpers: .validateWith(delegate), validateEachWith(delegate)

You can create custom validators either by implementing IValidator interface, or by using DelegateValidator:

new Program("test")
  // adding validator manually
  .add(new Option("s", "scope", "")
      .validateEachWith(opt => opt.isDirectory, "must be a valid directory")
  );

Printing help

You can print help for program or any subcommand with printHelp() function:

program.printHelp(); // prints program help
program.commands["test"].printHelp();

To customise help output, pass HelpOutput struct instance:

HelpOutput helpOptions;
helpOptions.colors = false;
helpOptions.optionsLimit = 2;

program.printHelp(helpOptions);

Configuration

TODO

Cheat-Sheet

Defining entries

Overview of available entries that can be added to program or command with .add method:

What	Type	Example	Definition
Flag	bool	--verbose	new Flag(abbrev?, full?, summary?)
Option	string[]	--db=test	new Option(abbrev?, full?, summary?)
Argument	string[]	123	new Argument(name, summary?)

Reading values

Shows how to access values after parsing args.

Examples assume args variable contains result of parse() or parseArgs() function calls (an instance of ProgramArgs)

ProgramArgs args = program.parse(args);

What	Type	Fetch
Flag	bool	args.flag(name)
Flag	int	args.occurencesOf(name)
Option	string	args.option(name)
Option	string[]	args.options(name)
Argument	string	args.arg(name)
Argument	string[]	args.args(name)

Property Matrix

Table below shows which fields exist and which don’t (or should not be used).

Column name contains name of the method to set the value. All methods return this to allow chaining.

Name	Program	Command	Flag	Option	Argument
.name	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:
.version_	:heavy_check_mark:	:heavy_check_mark:	❌	️❌	❌
.summary	:heavy_check_mark:️	️:heavy_check_mark:	❌	️❌	❌
.description	❌	️❌	:heavy_check_mark:	️:heavy_check_mark:	:heavy_check_mark:
.abbrev	❌	❌	:heavy_check_mark:	:heavy_check_mark:	❌
.full	❌	❌	:heavy_check_mark:️	️:heavy_check_mark:	❌
.tag	❌	❌	❌	️:heavy_check_mark:	:heavy_check_mark:️
.defaultValue	❌	❌	❌	️:heavy_check_mark:	:heavy_check_mark:️
.required	❌	❌	❌	️:heavy_check_mark:	:heavy_check_mark:️
.optional	❌	❌	❌	️:heavy_check_mark:	:heavy_check_mark:️
.repeating	❌	❌	:heavy_check_mark:	️:heavy_check_mark:	:heavy_check_mark:️
.topic	❌	:heavy_check_mark:	❌	️❌	❌
.topicGroup	:heavy_check_mark:	:heavy_check_mark:	❌	️❌	❌
.authors	:heavy_check_mark:	❌	❌	️❌	❌
.binaryName	:heavy_check_mark:	❌	❌	️❌	❌

Roadmap

Current major missing features are:

• Command/Option aliases
• Combined short flags/options (e.g. -qLob)
• EnumValidator/FileSystemValidator auto-completion hinting

See the open issues for a list of proposed features (and known issues).