Class: Gem::Command

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.

Use add_option to add command-line switches.

[Source]

    # File lib/rubygems/command.rb, line 40
40:     def initialize(command, summary=nil, defaults={})
41:       @command = command
42:       @summary = summary
43:       @program_name = "gem #{command}"
44:       @defaults = defaults
45:       @options = defaults.dup
46:       @option_groups = Hash.new { |h,k| h[k] = [] }
47:       @parser = nil
48:       @when_invoked = nil
49:     end

add_extra_args(args)

[Source]

     # File lib/rubygems/command.rb, line 195
195:     def add_extra_args(args)
196:       result = []
197:       s_extra = Command.specific_extra_args(@command)
198:       extra = Command.extra_args + s_extra
199:       while ! extra.empty?
200:         ex = []
201:         ex << extra.shift
202:         ex << extra.shift if extra.first.to_s =~ /^[^-]/
203:         result << ex if handles?(ex)
204:       end
205:       result.flatten!
206:       result.concat(args)
207:       result
208:     end

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.

[Source]

     # File lib/rubygems/command.rb, line 156
156:     def add_option(*opts, &handler) # :yields: value, options
157:       group_name = Symbol === opts.first ? opts.shift : :options
158: 
159:       @option_groups[group_name] << [opts, handler]
160:     end

arguments()

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

[Source]

     # File lib/rubygems/command.rb, line 101
101:     def arguments
102:       ""
103:     end

begins?(long, short)

True if long begins with the characters from short.

[Source]

    # File lib/rubygems/command.rb, line 52
52:     def begins?(long, short)
53:       return false if short.nil?
54:       long[0, short.length] == short
55:     end

defaults_str()

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

[Source]

     # File lib/rubygems/command.rb, line 108
108:     def defaults_str
109:       ""
110:     end

description()

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

[Source]

     # File lib/rubygems/command.rb, line 113
113:     def description
114:       nil
115:     end

execute()

Override to provide command handling.

[Source]

    # File lib/rubygems/command.rb, line 58
58:     def execute
59:       fail "Generic command has no actions"
60:     end

get_all_gem_names()

Get all gem names from the command line.

[Source]

    # File lib/rubygems/command.rb, line 63
63:     def get_all_gem_names
64:       args = options[:args]
65: 
66:       if args.nil? or args.empty? then
67:         raise Gem::CommandLineError,
68:               "Please specify at least one gem name (e.g. gem build GEMNAME)"
69:       end
70: 
71:       gem_names = args.select { |arg| arg !~ /^-/ }
72:     end

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.

[Source]

    # File lib/rubygems/command.rb, line 76
76:     def get_one_gem_name
77:       args = options[:args]
78: 
79:       if args.nil? or args.empty? then
80:         raise Gem::CommandLineError,
81:              "Please specify a gem name on the command line (e.g. gem build GEMNAME)"
82:       end
83: 
84:       if args.size > 1 then
85:         raise Gem::CommandLineError,
86:               "Too many gem names (#{args.join(', ')}); please specify only one"
87:       end
88: 
89:       args.first
90:     end

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.

[Source]

    # File lib/rubygems/command.rb, line 94
94:     def get_one_optional_argument
95:       args = options[:args] || []
96:       args.first
97:     end

handle_options(args)

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

[Source]

     # File lib/rubygems/command.rb, line 188
188:     def handle_options(args)
189:       args = add_extra_args(args)
190:       @options = @defaults.clone
191:       parser.parse!(args)
192:       @options[:args] = args
193:     end

handles?(args)

True if the command handles the given argument list.

[Source]

     # File lib/rubygems/command.rb, line 177
177:     def handles?(args)
178:       begin
179:         parser.parse!(args.dup)
180:         return true
181:       rescue
182:         return false
183:       end
184:     end

invoke(*args)

Invoke the command with the given list of arguments.

[Source]

     # File lib/rubygems/command.rb, line 129
129:     def invoke(*args)
130:       handle_options(args)
131:       if options[:help]
132:         show_help
133:       elsif @when_invoked
134:         @when_invoked.call(options)
135:       else
136:         execute
137:       end
138:     end

merge_options(new_options)

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

[Source]

     # File lib/rubygems/command.rb, line 171
171:     def merge_options(new_options)
172:       @options = @defaults.clone
173:       new_options.each do |k,v| @options[k] = v end
174:     end

remove_option(name)

Remove previously defined command-line argument name.

[Source]

     # File lib/rubygems/command.rb, line 163
163:     def remove_option(name)
164:       @option_groups.each do |_, option_list|
165:         option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
166:       end
167:     end

show_help()

Display the help message for the command.

[Source]

     # File lib/rubygems/command.rb, line 123
123:     def show_help
124:       parser.program_name = usage
125:       say parser
126:     end

usage()

Override to display the usage for an individual gem command.

[Source]

     # File lib/rubygems/command.rb, line 118
118:     def usage
119:       program_name
120:     end

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.

[Source]

     # File lib/rubygems/command.rb, line 146
146:     def when_invoked(&block)
147:       @when_invoked = block
148:     end

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.

Methods

Included Modules

Attributes

Public Class methods

Public Instance methods