Class: Gem::Command

Class | Gem::Command
In: | lib/rubygems/command.rb
Parent: | Object

Base class for all Gem commands. When creating a new gem command, define new, 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

### Methods

add_common_option add_extra_args add_option add_specific_extra_args arguments begins? build_args build_args= common_options defaults_str description execute extra_args extra_args= get_all_gem_names get_one_gem_name get_one_optional_argument handle_options handles? invoke merge_options new remove_option show_help specific_extra_args specific_extra_args_hash usage when_invoked wrap

### Included Modules

Gem::UserInteraction

### Attributes

command | [R] | The name of the command.
defaults | [RW] | The default options for the command.
options | [R] | The options for the command.
program_name | [RW] | The name of the command for command-line invocation.
summary | [RW] | A short description of the command.

### Public Class methods

add_common_option(*args, &handler)
add_specific_extra_args(cmd,args)

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

build_args()

Arguments used when building gems

build_args=(value)
common_options()
extra_args()
extra_args=(value)
new(command, summary=nil, defaults={})

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]`.

specific_extra_args(cmd)

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

specific_extra_args_hash()

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

### Public Instance methods

add_extra_args(args)

Adds extra args from ~/.gemrc

add_option(*opts) {|value, options| ...}

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

See 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.

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 ...]"
      end

      def arguments
        "FILE          name of file to find"
      end

begins?(long, short)

True if `long` begins with the characters from `short`.

defaults_str()

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
      end

description()

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

execute()

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()

Get all gem names from the command line.

get_one_gem_name()

Get the 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_one_optional_argument()

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_options(args)

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

handles?(args)

True if the command handles the given argument list.

invoke(*args)

Invoke the command with the given list of arguments.

merge_options(new_options)

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

remove_option(name)

Remove previously defined command-line argument `name`.

show_help()

Display the help message for the command.

usage()

Override to display the usage for an individual gem command.

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

when_invoked(&block)

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.

### Private Instance methods

wrap(text, width)

Wraps `text` to `width`

[Validate]