Main Class for Creating a
Command Based CLI Program¶ ↑
This class can directly be used (or sub-classed, if need be) to create a command based CLI program.
The CLI program itself is represented by the
Command instance (as are all commands and sub-commands). This main command can either hold sub-commands (the normal use case) which represent the programs top level commands or take no commands in which case it acts similar to a simple OptionParser based program (albeit with better help functionality).
Parsing the command line for commands is done by this class, option parsing is delegated to the battle tested OptionParser of the Ruby standard library.
After initialization some optional information is expected to be set on the
Command#options of the
A banner that appears in the help output before anything else.
The name of the program. If not set, this value is computed from $0.
The version string of the program.
In addition to the main command's options instance (which represents the top level options that need to be specified before any command name), there is also a
global_options instance which represents options that can be specified anywhere on the command line.
Top level commands can be added to the main command by using the
Once everything is set up, the
parse method is used for parsing the command line.
The command that is being executed. Only available during parsing of the command line arguments.
A data store (initially an empty Hash) that can be used for storing anything. For example, it can be used to store global option values. cmdparse itself doesn't do anything with it.
Should exceptions be handled gracefully? I.e. by printing error message and the help screen?
::new for possible values.
The indentation used for, among other things, command descriptions.
The amount of spaces to indent the content of help sections.
The maximum width of the help lines.
The top level command representing the program itself.
Public Class Methods
Creates a new
trueif exceptions should be handled gracefully by showing the error and a help message, or to
falseif exception should not be handled at all. If this options is set to :no_help, the exception is handled but no help message is shown.
Specifies whether the main program takes any commands.
Public Instance Methods
Adds a top level command.
Command#add_command for detailed invocation information.
Yields the global options if a block is given and returns them.
The global options are those options that can be used on the top level and with any command.
Yields the main options (that are only available directly after the program name) if a block is given and returns them.
The main options are also used for setting the program name, version and banner.
Parses the command line arguments.
If a block is given, the current hierarchy level and the name of the current command is yielded after the option parsing is done but before a command is executed.