Cri is a library for building easy-to-use command-line tools with support for nested commands.
Requirements
Cri requires Ruby 2.1 or newer.
Usage
The central concept in Cri is the command, which has option definitions as well as code for actually executing itself. In Cri, the command-line tool itself is a command as well.
Here’s a sample command definition:
command = Cri::Command.define do
name 'dostuff'
usage 'dostuff [options]'
aliases :ds, :stuff
summary 'does stuff'
description 'This command does a lot of stuff. I really mean a lot.'
flag :h, :help, 'show help for this command' do |value, cmd|
puts cmd.help
exit 0
end
flag nil, :more, 'do even more stuff'
option :s, :stuff, 'specify stuff to do', argument: :required
run do |opts, args, cmd|
stuff = opts.fetch(:stuff, 'generic stuff')
puts "Doing #{stuff}!"
if opts[:more]
puts 'Doing it even more!'
end
end
end
To run this command, invoke the #run
method with the raw arguments. For
example, for a root command (the command-line tool itself), the command could
be called like this:
command.run(ARGV)
Each command has automatically generated help. This help can be printed using
Cri::Command#help
; something like this will be shown:
usage: dostuff [options]
does stuff
This command does a lot of stuff. I really mean a lot.
options:
-h --help show help for this command
--more do even more stuff
-s --stuff specify stuff to do
General command metadata
Let’s disect the command definition and start with the first five lines:
name 'dostuff'
usage 'dostuff [options]'
aliases :ds, :stuff
summary 'does stuff'
description 'This command does a lot of stuff. I really mean a lot.'
These lines of the command definition specify the name of the command (or the command-line tool, if the command is the root command), the usage, a list of aliases that can be used to call this command, a one-line summary and a (long) description. The usage should not include a “usage:” prefix nor the name of the supercommand, because the latter will be automatically prepended.
Aliases don’t make sense for root commands, but for subcommands they do.
Command-line options
The next few lines contain the command’s option definitions:
flag :h, :help, 'show help for this command' do |value, cmd|
puts cmd.help
exit 0
end
flag nil, :more, 'do even more stuff'
option :s, :stuff, 'specify stuff to do', argument: :required
Options can be defined using the following methods:
-
Cri::CommandDSL#option
orCri::CommandDSL#opt
-
Cri::CommandDSL#flag
(implies no arguments passed to option) -
Cri::CommandDSL#required
(implies required argument) -
Cri::CommandDSL#optional
(implies optional argument)
All these methods take these arguments:
-
a short option
-
a long option
-
a description
-
optional extra parameters
Either the short or the long form can be nil, but not both (because that
would not make any sense). In the example above, the --more
option has no
short form.
Each of the above methods also take a block, which will be executed when the
option is found. The argument to the block are the option value (true
in
case the option does not have an argument) and the command.
Options with default values
The :default
parameter sets the option value that will be used if no explicit value is provided:
optional :a, :animal, 'add animal', default: 'giraffe'
In the example above, the value for the --animal
option will be the string
"giraffe"
, unless otherwise specified:
OPTIONS
-a --animal[=<value>] add animal (default: giraffe)
Multivalued options
Each of these four methods take a :multiple
parameter. When set to true, multiple
option valus are accepted, and the option values will be stored in an array.
For example, to parse the command line options string -o foo.txt -o bar.txt
into an array, so that options[:output]
contains [ 'foo.txt', 'bar.txt' ]
,
you can use an option definition like this:
option :o, :output, 'specify output paths', argument: :required, multiple: true
This can also be used for flags (options without arguments). In this case, the length of the options array is relevant.
For example, you can allow setting the verbosity level using -v -v -v
. The
value of options[:verbose].size
would then be the verbosity level (three in
this example). The option definition would then look like this:
flag :v, :verbose, 'be verbose (use up to three times)', multiple: true
Skipping option parsing
If you want to skip option parsing for your command or subcommand, you can add
the skip_option_parsing
method to your command definition and everything on your
command line after the command name will be passed to your command as arguments.
command = Cri::Command.define do
name 'dostuff'
usage 'dostuff [args]'
aliases :ds, :stuff
summary 'does stuff'
description 'This command does a lot of stuff, but not option parsing.'
skip_option_parsing
run do |opts, args, cmd|
puts args.inspect
end
end
When executing this command with dostuff --some=value -f yes
, the opts
hash
that is passed to your run
block will be empty and the args
array will be
["--some=value", "-f", "yes"]
.
The run block
The last part of the command defines the execution itself:
run do |opts, args, cmd|
stuff = opts.fetch(:stuff, 'generic stuff')
puts "Doing #{stuff}!"
if opts[:more]
puts 'Doing it even more!'
end
end
The Cri::CommandDSL#run method takes a block with the actual code to execute. This block takes three arguments: the options, any arguments passed to the command, and the command itself.
Instead of defining a run block, it is possible to declare a class, the
command runner class (Cri::CommandRunner
) that will perform the actual
execution of the command. This makes it easier to break up large run blocks
into manageable pieces.
Subcommands
Commands can have subcommands. For example, the git
command-line 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).
To add a command as a subcommand to another command, use the
Cri::Command#add_command
method, like this:
root_cmd.add_command(cmd_add)
root_cmd.add_command(cmd_commit)
root.cmd.add_command(cmd_init)
You can specify a default subcommand. This subcommand will be executed when the command has subcommands, and no subcommands are otherwise explicitly specified:
default_subcommand 'compile'
Contributors
-
Bart Mesuere
-
Ken Coar
-
Tim Sharpe
-
Toon Willems
Thanks for Lee “injekt” Jarvis for Slop, which has inspired the design of Cri 2.0.