cmdparse

class CmdParse::Command

Base class for commands ↑

This class implements all needed methods so that it can be used by the CommandParser class.

Commands can either be created by sub-classing or on the fly when using the add_command method. The latter allows for a more terse specification of a command while the sub-class approach allows to customize all aspects of a command by overriding methods.

Basic example for sub-classing:

class TestCommand < CmdParse::Command
  def initialize
    super('test', takes_commands: false)
    options.on('-m', '--my-opt', 'My option') { 'Do something' }
  end
end

parser = CmdParse::CommandParser.new
parser.add_command(TestCommand.new)
parser.parse

Basic example for on the fly creation:

parser = CmdParse::CommandParser.new
parser.add_command('test') do |cmd|
  takes_commands(false)
  options.on('-m', '--my-opt', 'My option') { 'Do something' }
end
parser.parse

Basic Properties ↑

The only thing that is mandatory to set for a Command is its name. If the command does not take any sub-commands, then additionally an action block needs to be specified or the execute method overridden.

However, there are several other methods that can be used to configure the behavior of a command:

takes_commands

For specifying whether sub-commands are allowed.

options

For specifying command specific options.

add_command

For specifying sub-commands if the command takes them.

Help Related Methods ↑

Many of this class' methods are related to providing useful help output. While the most common methods can directly be invoked to set or retrieve information, many other methods compute the needed information dynamically and therefore need to be overridden to customize their return value.

short_desc

For a short description of the command (getter/setter).

long_desc

For a detailed description of the command (getter/setter).

argument_desc

For describing command arguments (setter).

help, help_banner, help_short_desc, help_long_desc, help_commands, help_arguments, help_options

For outputting the general command help or individual sections of the command help (getter).

usage, usage_options, usage_arguments, usage_commands

For outputting the usage line or individual parts of it (getter).

Built-in Commands ↑

cmdparse ships with two built-in commands:

Attributes

commands[R]

Returns the mapping of command name to command for all sub-commands of this command.

data[RW]

A data store (initially an empty Hash) that can be used for storing anything. For example, it can be used to store option values. cmdparse itself doesn't do anything with it.

default_command[R]

Returns the name of the default sub-command or nil if there isn't any.

name[R]

The name of the command.

super_command[RW]

Sets or returns the super-command of this command. The super-command is either a Command instance for normal commands or a CommandParser instance for the main command (ie. CommandParser#main_command).

Public Class Methods

new(name, takes_commands: true)

Initializes the command called name.

Options:

takes_commands

Specifies whether this command can take sub-commands.

Public Instance Methods

<=>(other)

For sorting commands by name.

action(&block)

Sets the given block as the action block that is used on when executing this command.

If a sub-class is created for specifying a command, then the execute method should be overridden instead of setting an action block.

See also: execute

add_command(other_command, default: false) {|cmd| ... } → command
add_command('other', default: false) {|cmd| ...} → command

Adds a command to the command list.

The argument command can either be a Command object or a String in which case a new Command object is created. In both cases the Command object is yielded.

If the optional argument default is true, then the command is used when no other sub-command is specified on the command line.

If this command takes no other commands, an error is raised.

argument_desc(name → desc, ...)

Sets the descriptions for one or more arguments using name-description pairs.

The used names should correspond to the names used in usage_arguments.

arity()

Returns the number of arguments required for the execution of the command, i.e. the number of arguments the action block or the execute method takes.

If the returned number is negative, it means that the minimum number of arguments is -n-1.

See: Method#arity, Proc#arity

command_chain → [top_level_command, super_command, ..., command]

Returns the command chain, i.e. a list containing this command and all of its super-commands, starting at the top level command.

command_parser()

Returns the associated CommandParser instance for this command or nil if no command parser is associated.

execute(*args)

Invokes the action block with the parsed arguments.

This method is called by the CommandParser instance if this command was specified on the command line to be executed.

Sub-classes can either specify an action block or directly override this method (the latter is preferred).

help()

Returns a string containing the help message for the command.

help_arguments()

Returns the formatted arguments of this command.

For the output format see cond_format_help_section

help_banner()

Returns the banner (including the usage line) of the command.

The usage line is command specific but the rest is the same for all commands and can be set via command_parser.main_options.banner.

help_commands()

Returns the formatted sub-commands of this command.

For the output format see cond_format_help_section

help_long_desc()

Returns the formatted detailed description.

For the output format see cond_format_help_section

help_options(title, options)

Returns the formatted option descriptions for the given OptionParser instance.

The section title needs to be specified with the title argument.

For the output format see cond_format_help_section

help_short_desc()

Returns the formatted short description.

For the output format see cond_format_help_section

long_desc(*val)

Sets the detailed description of the command if an argument is given. Always returns the detailed description.

This may be a single string or an array of strings for multiline description. Each string is ideally shorter than 76 characters.

Also aliased as: long_desc=
long_desc=(*val)
Alias for: long_desc
on_after_add()

This hook method is called when the command (or one of its super-commands) is added to another Command instance that has an associated command parser (see command_parser).

It can be used, for example, to add global options.

options {|opts| ...} → opts
options → opts

Yields the OptionParser instance that is used for parsing the options of this command (if a block is given) and returns it.

short_desc(*val)

Sets the short description of the command if an argument is given. Always returns the short description.

The short description is ideally shorter than 60 characters.

Also aliased as: short_desc=
short_desc=(*val)
Alias for: short_desc
takes_arguments?()

Returns true if the command can take one or more arguments.

takes_commands(val)

Sets whether this command can take sub-command.

The argument val needs to be true or false.

Also aliased as: takes_commands=
takes_commands=(val)
Alias for: takes_commands
takes_commands?()

Return true if this command can take sub-commands.

usage()

Returns the usage line for the command.

The usage line is automatically generated from the available information. If this is not suitable, override this method to provide a command specific usage line.

Typical usage lines looks like the following:

Usage: program [options] command [options] {sub_command1 | sub_command2}
Usage: program [options] command [options] ARG1 [ARG2] [REST...]

See: usage_options, usage_arguments, usage_commands

usage_arguments()

Returns a string describing the arguments for the command for use in the usage line.

By default the names of the action block or execute method arguments are used (done via Ruby's reflection API). If this is not wanted, override this method.

A typical return value would look like the following:

ARG1 [ARG2] [REST...]

See: usage, argument_desc

usage_commands()

Returns a string describing the sub-commands of the commands for use in the usage line.

Override this method for providing a command specific specialization.

A typical return value would look like the following:

{command | other_command | another_command }
usage_options()

Returns a string describing the options of the command for use in the usage line.

If there are any options, the resulting string also includes a leading space!

A typical return value would look like the following:

[options]

See: usage

Protected Instance Methods

cond_format_help_section(title, *lines, condition: true, indent: true, preformatted: false)

Conditionally formats a help section.

Returns either the formatted help section if the condition is true or an empty string otherwise.

The help section starts with a title and the given lines are indented to easily distinguish different sections.

A typical help section would look like the following:

Summary:
    help - Provide help for individual commands

Options:

condition

The formatted help section is only returned if the condition is true.

indent

Whether the lines should be indented with CommandParser#help_indent spaces.

preformatted

Assume that the given lines are already correctly formatted and don't try to reformat them.

format(content, width: command_parser.help_line_width, indent: command_parser.help_indent, indent_first_line: false)

Returns the text in content formatted so that no line is longer than width characters.

Options:

width

The maximum width of a line. If not specified, the CommandParser#help_line_width value is used.

indent

This option specifies the amount of spaces prepended to each line. If not specified, the CommandParser#help_indent value is used.

indent_first_line

If this option is true, then the first line is also indented.