Skip to content
Newer
Older
100644 135 lines (96 sloc) 4.25 KB
4bf4c10 @ddfreyne initial import
authored
1 Cri
2 ===
3
c7f60d4 @ddfreyne added usage documentation to readme
authored
4 Cri is a library for building easy-to-use commandline tools with support for
5 nested commands.
6
7 Usage
8 -----
9
10 The central concept in Cri is the _command_, which has option definitions as
11 well as code for actually executing itself. In Cri, the commandline tool
12 itself is a command as well.
13
14 Here’s a sample command definition:
15
16 command = Cri::Command.define do
17 name 'dostuff'
18 usage 'dostuff [options]'
18ccaa9 @ddfreyne documented aliases and subcommands
authored
19 aliases :ds, :stuff
c7f60d4 @ddfreyne added usage documentation to readme
authored
20 summary 'does stuff'
21 description 'This command does a lot of stuff. I really mean a lot.'
22
23 flag :h, :help, 'show help for this command' do |value, cmd|
24 puts cmd.help
25 exit 0
26 end
27 flag :m, :more, 'do even more stuff'
28 option :s, :stuff, 'specify stuff to do', :argument => :required
29
30 run do |opts, args, cmd|
31 stuff = opts[:stuff] || 'generic stuff'
32 puts "Doing #{stuff}!"
33
34 if opts[:more]
35 puts 'Doing it even more!'
36 end
37 end
38 end
39
40 To run this command, invoke the `#run` method with the raw arguments. For
41 example, for a root command (the commandline tool itself), the command could
42 be called like this:
43
44 command.run(ARGS)
45
46 Each command has automatically generated help. This help can be printed using
47 {Cri::Command#help}; something like this will be shown:
48
49 usage: dostuff [options]
50
51 does stuff
52
53 This command does a lot of stuff. I really mean a lot.
54
55 options:
56
57 -h --help show help for this command
58 -m --more do even more stuff
59 -s --stuff specify stuff to do
60
18ccaa9 @ddfreyne documented aliases and subcommands
authored
61 Let’s disect the command definition and start with the first five lines:
c7f60d4 @ddfreyne added usage documentation to readme
authored
62
63 name 'dostuff'
64 usage 'dostuff [options]'
18ccaa9 @ddfreyne documented aliases and subcommands
authored
65 aliases :ds, :stuff
c7f60d4 @ddfreyne added usage documentation to readme
authored
66 summary 'does stuff'
67 description 'This command does a lot of stuff. I really mean a lot.'
68
18ccaa9 @ddfreyne documented aliases and subcommands
authored
69 These lines of the command definition specify the name of the command (or the
70 commandline tool, if the command is the root command), the usage, a list of
71 aliases that can be used to call this command, a one-line summary and a (long)
72 description. The usage should not include a “usage:” prefix nor the name of
73 the supercommand, because the latter will be automatically prepended.
74
75 Aliases don’t make sense for root commands, but for subcommands they do.
c7f60d4 @ddfreyne added usage documentation to readme
authored
76
77 The next few lines contain the command’s option definitions:
78
79 flag :h, :help, 'show help for this command' do |value, cmd|
80 puts cmd.help
81 exit 0
82 end
83 flag :m, :more, 'do even more stuff'
84 option :s, :stuff, 'specify stuff to do', :argument => :required
85
86 Options can be defined using the following methods:
87
18ccaa9 @ddfreyne documented aliases and subcommands
authored
88 * {Cri::CommandDSL#option} or {Cri::CommandDSL#opt}
c7f60d4 @ddfreyne added usage documentation to readme
authored
89 * {Cri::CommandDSL#flag} (implies forbidden argument)
90 * {Cri::CommandDSL#required} (implies required argument)
91 * {Cri::CommandDSL#optional} (implies optional argument)
92
93 Each of the above methods also take a block, which will be executed when the
94 option is found. The argument to the block are the option value (`true` in
95 case the option does not have an argument) and the command.
96
97 The last part of the command defines the execution itself:
98
99 run do |opts, args, cmd|
100 stuff = opts[:stuff] || 'generic stuff'
101 puts "Doing #{stuff}!"
102
103 if opts[:more]
104 puts 'Doing it even more!'
105 end
106 end
107
108 The {Cri::CommandDSL#run} method takes a block with the actual code to
109 execute. This block takes three arguments: the options, any arguments passed
110 to the command, and the command itself.
f3364c5 @ddfreyne added toon willems to list of contributors
authored
111
9b0b7ca @ddfreyne added support for runners
authored
112 Instead of defining a run block, it is possible to declare a class, the
113 _command runner_ class ({Cri::CommandRunner}) that will perform the actual
114 execution of the command. This makes it easier to break up large run blocks
115 into manageable pieces.
116
18ccaa9 @ddfreyne documented aliases and subcommands
authored
117 Commands can have subcommands. For example, the `git` commandline tool would be represented by a command that has subcommands named `commit`, `add`, and so on. Commands with subcommands do not use a run block; execution will always be dispatched to a subcommand (or none, if no subcommand is found).
118
e3f6e63 @ddfreyne fixed erroneous #add_subcommand in readme
authored
119 To add a command as a subcommand to another command, use the {Cri::Command#add_command} method, like this:
18ccaa9 @ddfreyne documented aliases and subcommands
authored
120
121 root_cmd.add_command cmd_add
122 root_cmd.add_command cmd_commit
123 root.cmd.add_command cmd_init
124
f3364c5 @ddfreyne added toon willems to list of contributors
authored
125 Contributors
126 ------------
127
128 (In alphabetical order)
129
130 * Toon Willems
d8de060 @ddfreyne added injekt to thanks section in readme
authored
131
d615c03 @ddfreyne fixed link to Slop in readme
authored
132 Thanks for Lee “injekt” Jarvis for [Slop][1], which has inspired the design of Cri 2.0.
d8de060 @ddfreyne added injekt to thanks section in readme
authored
133
134 [1]: https://github.com/injekt/slop
Something went wrong with that request. Please try again.