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);