Base class for all Gem commands. When creating a new gem command, define initialize, execute, arguments, defaults_str, description and usage (as appropriate). See the above mentioned methods for details.

A very good example to look at is Gem::Commands::ContentsCommand


The name of the command.


The options for the command.

Read & Write

The default options for the command.

Read & Write

The name of the command for command-line invocation.

Read & Write

A short description of the command.

Class Methods
No documentation available

Add a list of extra arguments for the given command. args may be an array or a string to be split on white space.

Arguments used when building gems

No documentation available
No documentation available
No documentation available
No documentation available

Initializes a generic gem command named command. summary is a short description displayed in ‘gem help commands`. defaults are the default options. Defaults should be mirrored in defaults_str, unless there are none.

When defining a new command subclass, use add_option to add command-line switches.

Unhandled arguments (gem names, files, etc.) are left in options[:args].

Return an array of extra arguments for the command. The extra arguments come from the gem configuration file read at program startup.

Accessor for the specific extra args hash (self initializing).

Instance Methods

Adds extra args from ~/.gemrc

Add a command-line option and handler to the command.

See Gem::OptionParser#make_switch for an explanation of opts.

handler will be called with two values, the value of the argument and the options hash.

If the first argument of add_option is a Symbol, it’s used to group options in output. See ‘gem help list` for an example.

Adds a section with title and content to the parser help view. Used for adding command arguments and default arguments.

Override to provide details of the arguments a command takes. It should return a left-justified string, one argument per line.

For example:

def usage
  "#{program_name} FILE [FILE ...]"

def arguments
  "FILE          name of file to find"

True if long begins with the characters from short.

No documentation available
No documentation available

Creates an option parser and fills it in with the help info for the command.

Override to display the default values of the command options. (similar to arguments, but displays the default values).

For example:

def defaults_str
  --no-gems-first --no-all

Mark a command-line option as deprecated, and optionally specify a deprecation horizon.

Note that with the current implementation, every version of the option needs to be explicitly deprecated, so to deprecate an option defined as

add_option('-t', '--[no-]test', 'Set test mode') do |value, options|
  # ... stuff ...

you would need to explicitly add a call to ‘deprecate_option` for every version of the option you want to deprecate, like

No documentation available

Override to display a longer description of what this command does.

Override to provide command handling.

options will be filled in with your parsed options, unparsed options will be left in options[:args].

See also: get_all_gem_names, get_one_gem_name, get_one_optional_argument

Get all gem names from the command line.

Get all [gem, version] from the command line.

An argument in the form gem:ver is pull apart into the gen name and version, respectively.

Get a single gem name from the command line. Fail if there is no gem name or if there is more than one gem name given.

Get a single optional argument from the command line. If more than one argument is given, return only the first. Return nil if none are given.

Handle the given list of arguments by parsing them and recording the results.

True if the command handles the given argument list.

Invoke the command with the given list of arguments.

Invoke the command with the given list of normal arguments and additional build arguments.

Merge a set of command options with the set of default options (without modifying the default option hash).

No documentation available

Create on demand parser.

Remove previously defined command-line argument name.

Display the help message for the command.

Display to the user that a gem couldn’t be found and reasons why

Override to display the usage for an individual gem command.

The text “[options]” is automatically appended to the usage text.

Call the given block when invoked.

Normal command invocations just executes the execute method of the command. Specifying an invocation block allows the test methods to override the normal action of a command to determine that it has been invoked correctly.

Wraps text to width