cmdparse

class CmdParse::CommandParser

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 main_command, a 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.

Usage ↑

After initialization some optional information is expected to be set on the Command#options of the main_command:

banner

A banner that appears in the help output before anything else.

program_name

The name of the program. If not set, this value is computed from $0.

version

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 add_command method.

Once everything is set up, the parse method is used for parsing the command line.

Attributes

current_command[R]

The command that is being executed. Only available during parsing of the command line arguments.

data[RW]

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.

handle_exceptions[R]

Should exceptions be handled gracefully? I.e. by printing error message and the help screen?

See ::new for possible values.

help_desc_indent[RW]

The indentation used for, among other things, command descriptions.

help_indent[RW]

The amount of spaces to indent the content of help sections.

help_line_width[RW]

The maximum width of the help lines.

main_command[R]

The top level command representing the program itself.

Public Class Methods

new(handle_exceptions: false, takes_commands: true)

Creates a new CommandParser object.

Options:

handle_exceptions

Set to true if exceptions should be handled gracefully by showing the error and a help message, or to false if 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.

takes_commands

Specifies whether the main program takes any commands.

Public Instance Methods

add_command(*args, **kws, &block)

Adds a top level command.

See Command#add_command for detailed invocation information.

global_options → OptionParser instance
gloabl_options {|opts| ...} → opts (OptionParser instance)

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.

main_options → OptionParser instance
main_options {|opts| ...} → opts (OptionParser instance)

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.

parse(argv = ARGV) { |level, command_name| ... }

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.