dcli.program_commands

Handles program commands, which are arguments passed to a program that are not prefixed with - or --. So that you handle programs that can be executed in this format:

$ ./program -v --global-option=7 command1 --parameter="yo" sub-command --another-parameter=42

Usage:

The basic idea is to create a ProgramCommands structure and then define a number of Commands that it can handle and optionally, a set of $(DDOX_NAMED_REF dcli.program_options, `ProgramOptions`) that it can handle. Each Command can in turn have it's own ProgramCommands.

Handlers:

Handlers are provided to be able to eacily handle when a command is encountered. This will allow you to structure your program with a module based architecture, where each "handler" can e.g. pass the commands to a module that is build specifically for handling that command.

E.g.:

1 // install.d
2 void commandHandler(T)(T commands) {
3     writeln(commands.install); // prints true
4 }
5 // main.d
6 static import install, build;
7 void main(string[] args) {
8     auto commands = ProgramCommands!(
9         Command!"build".handler!(build.commandHandler)
10         Command!"install".handler!(install.commandHandler)
11     )();
12     commands.parse(args);
13     commands.executeHandlers();
14 }
15 // Run it
16 $ ./program install
17 $ >> true
More...

Alias This

_args

Members

Structs

ProgramCommands
struct ProgramCommands(Commands...)

You can configure a ProgramCommands object with a number of Commands and then use it to parse an list of command line arguments

Templates

Command
template Command(string name)

Represents one program command which identified the expected string on the command line. One of more of these can be given to a ProgramCommands object as template arguments.

Detailed Description

Inner ProgramOptions

The first argument to a ProgramCommands object can optionally be a $(DDOX_NAMED_REF dcli.program_options, `ProgramOptions`) object. In this case, the program options are accessible with an internal variable named options

E.g.:

1 auto commands = ProgramCommands!(
2     ProgramOptions!(Options!("opt1", string)),
3     Command!"command1",
4     Command!"command2".args!(
5         ProgramOptions!(Options!("opt2", string))
6     )
7 )();
8 
9 commands.options.opt1; // access the option
10 commands.command1; // access the command
11 commands.command2.op2; // access the options of command2

Inner ProgramCommands

You can also pass in sub commands to a Command object in the args parameter:

1 auto commands = ProgramCommands!(
2     ProgramOptions!(Options!("opt1", string)),
3     Command!"command1".args!(
4         ProgramCommands!(
5             ProgramOptions!(Options!("opt2", string)),
6             Command!"sub-command1",
7         ),
8     ),
9 )();
10 
11 commands.options.opt1; // access the option
12 commands.command1.subCommand1; // access the command
13 commands.command1.options.op2; // access the options of command2

Examples

1     alias MainCommands = ProgramCommands!(
2         ProgramOptions!(
3             Option!("glob1", string).shortName!"a".description!"desc",
4         ),
5         Command!"cmd1"
6             .args!(
7                 ProgramOptions!(
8                     Option!("opt1", string).shortName!"b".description!"desc",
9                 ),
10         ),
11         Command!"cmd2"
12             .handler!(Fixtures.handleCommand2)
13             .description!"desc",
14         Command!"cmd3"
15             .args!(
16                 ProgramCommands!(
17                     ProgramOptions!(
18                         Option!("opt3", string).shortName!"d".description!"desc",
19                     ),
20                     Command!"sub1"
21                         .args!(
22                             ProgramOptions!(
23                                 Option!("opt4", string).shortName!"e".description!"desc",
24                             ),
25                         )
26                         .handler!(Fixtures.handleCommand3)
27                         .description!"desc",
28                 ),
29             )
30             .handler!(Fixtures.handleCommand3Sub1)
31             .description!"desc",
32     );
33 
34     auto commands = MainCommands();
35 
36     commands.parse([
37         "-ayo",
38         "cmd3",
39         "-d",
40         "hi",
41         "sub1",
42         "-e",
43         "boo",
44     ]);
45 
46     assert(cast(bool)commands.cmd1 == false);
47     assert(cast(bool)commands.cmd2 == false);
48     assert(cast(bool)commands.cmd3 == true);
49 
50     assert(commands.options.glob1 == "yo");
51     assert(commands.cmd3.options.opt3 == "hi");
52     assert(commands.cmd3.sub1.opt4 == "boo");
53 
54     assert(commands.helpText ==
55 `Options:
56   -a  --glob1   desc
57 Commands:
58   cmd1
59   cmd2  desc
60   cmd3  desc`
61   );
62 
63     commands.executeHandlers;
64 
65     assert(!Fixtures.checkResetHandledCommand2);
66     assert( Fixtures.checkResetHandledCommand3);
67     assert( Fixtures.checkResetHandledCommand3Sub1);

Meta