class Gem::Command
Base class for allGem commands. When creating a new gem command, define initialize,execute,arguments,defaults_str,description andusage (as appropriate). See the above mentioned methods for details.
A very good example to look at isGem::Commands::ContentsCommand
Attributes
The name of the command.
The default options for the command.
The options for the command.
The name of the command for command-line invocation.
A short description of the command.
Public Class Methods
Source
# File lib/rubygems/command.rb, line 65defself.add_common_option(*args,&handler)Gem::Command.common_options<< [args,handler]end
Source
# File lib/rubygems/command.rb, line 94defself.add_specific_extra_args(cmd,args)args =args.split(/\s+/)ifargs.is_a?Stringspecific_extra_args_hash[cmd] =argsend
Add a list of extra arguments for the given command.args may be an array or a string to be split on white space.
Source
# File lib/rubygems/command.rb, line 53defself.build_args@build_args||= []end
Arguments used when building gems
Source
# File lib/rubygems/command.rb, line 57defself.build_args=(value)@build_args =valueend
Source
# File lib/rubygems/command.rb, line 61defself.common_options@common_options||= []end
Source
# File lib/rubygems/command.rb, line 73defself.extra_args=(value)casevaluewhenArray@extra_args =valuewhenString@extra_args =value.split(" ")endend
Source
# File lib/rubygems/command.rb, line 120definitialize(command,summary =nil,defaults = {})@command =command@summary =summary@program_name ="gem #{command}"@defaults =defaults@options =defaults.dup@option_groups =Hash.new {|h,k|h[k] = [] }@deprecated_options = {command=> {} }@parser =nil@when_invoked =nilend
Initializes a generic gem command namedcommand.summary is a short description displayed in ‘gem help commands`.defaults are the default options. Defaults should be mirrored indefaults_str, unless there are none.
When defining a new command subclass, useadd_option to add command-line switches.
Unhandled arguments (gem names, files, etc.) are left inoptions[:args].
Source
# File lib/rubygems/command.rb, line 86defself.specific_extra_args(cmd)specific_extra_args_hash[cmd]end
Return an array of extra arguments for the command. The extra arguments come from the gem configuration file read at program startup.
Source
# File lib/rubygems/command.rb, line 102defself.specific_extra_args_hash@specific_extra_args_hash||=Hash.newdo|h,k|h[k] =Array.newendend
Accessor for the specific extra args hash (self initializing).
Public Instance Methods
Source
# File lib/rubygems/command.rb, line 451defadd_extra_args(args)result = []s_extra =Gem::Command.specific_extra_args(@command)extra =Gem::Command.extra_args+s_extrauntilextra.empty?doex = []ex<<extra.shiftex<<extra.shiftif/^[^-]/.match?(extra.first.to_s)result<<exifhandles?(ex)endresult.flatten!result.concat(args)resultend
Adds extra args from ~/.gemrc
Source
# File lib/rubygems/command.rb, line 358defadd_option(*opts,&handler)# :yields: value, optionsgroup_name =Symbol===opts.first?opts.shift::optionsraise"Do not pass an empty string in opts"ifopts.include?("")@option_groups[group_name]<< [opts,handler]end
Add a command-line option and handler to the command.
See Gem::OptionParser#make_switch for an explanation ofopts.
handler will be called with two values, the value of the argument and the options hash.
If the first argument ofadd_option is aSymbol, it’s used to group options in output. See ‘gem help list` for an example.
Source
# File lib/rubygems/command.rb, line 258defarguments""end
Override to provide details of the arguments a command takes. It should return a left-justified string, one argument per line.
For example:
defusage"#{program_name} FILE [FILE ...]"enddefarguments"FILE name of file to find"end
Source
# File lib/rubygems/command.rb, line 135defbegins?(long,short)returnfalseifshort.nil?long[0,short.length]==shortend
True iflong begins with the characters fromshort.
Source
# File lib/rubygems/command.rb, line 397defcheck_deprecated_options(options)options.eachdo|option|nextunlessoption_is_deprecated?(option)deprecation =@deprecated_options[command][option]version_to_expire =deprecation["rg_version_to_expire"]deprecate_option_msg =ifversion_to_expire"The \"#{option}\" option has been deprecated and will be removed in Rubygems #{version_to_expire}."else"The \"#{option}\" option has been deprecated and will be removed in future versions of Rubygems."endextra_msg =deprecation["extra_msg"]deprecate_option_msg+=" #{extra_msg}"ifextra_msgalert_warning(deprecate_option_msg)endend
Source
# File lib/rubygems/command.rb, line 272defdefaults_str""end
Override to display the default values of the command options. (similar toarguments, but displays the default values).
For example:
def defaults_str --no-gems-first --no-allend
Source
# File lib/rubygems/command.rb, line 393defdeprecate_option(name,version:nil,extra_msg:nil)@deprecated_options[command].merge!({name=> {"rg_version_to_expire"=>version,"extra_msg"=>extra_msg } })end
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 ...end
you would need to explicitly add a call to ‘deprecate_option` for every version of the option you want to deprecate, like
deprecate_option('-t')deprecate_option('--test')deprecate_option('--no-test')
Source
# File lib/rubygems/command.rb, line 279defdescriptionnilend
Override to display a longer description of what this command does.
Source
# File lib/rubygems/command.rb, line 149defexecuteraiseGem::Exception,"generic command has no actions"end
Override to provide command handling.
options will be filled in with your parsed options, unparsed options will be left inoptions[:args].
See also:get_all_gem_names,get_one_gem_name,get_one_optional_argument
Source
# File lib/rubygems/command.rb, line 185defget_all_gem_namesargs =options[:args]ifargs.nil?||args.empty?raiseGem::CommandLineError,"Please specify at least one gem name (e.g. gem build GEMNAME)"endargs.reject {|arg|arg.start_with?("-") }end
Get all gem names from the command line.
Source
# File lib/rubygems/command.rb, line 201defget_all_gem_names_and_versionsget_all_gem_names.mapdo|name|extract_gem_name_and_version(name)endend
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.
Source
# File lib/rubygems/command.rb, line 219defget_one_gem_nameargs =options[:args]ifargs.nil?||args.empty?raiseGem::CommandLineError,"Please specify a gem name on the command line (e.g. gem build GEMNAME)"endifargs.size>1raiseGem::CommandLineError,"Too many gem names (#{args.join(", ")}); please specify only one"endargs.firstend
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.
Source
# File lib/rubygems/command.rb, line 239defget_one_optional_argumentargs =options[:args]|| []args.firstend
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 440defhandle_options(args)args =add_extra_args(args)check_deprecated_options(args)@options =Marshal.loadMarshal.dump@defaults# deep copyparser.parse!(args)@options[:args] =argsend
Handle the given list of arguments by parsing them and recording the results.
Source
# File lib/rubygems/command.rb, line 429defhandles?(args)parser.parse!(args.dup)truerescueStandardErrorfalseend
True if the command handles the given argument list.
Source
# File lib/rubygems/command.rb, line 303definvoke(*args)invoke_with_build_argsargs,nilend
Invoke the command with the given list of arguments.
Source
# File lib/rubygems/command.rb, line 311definvoke_with_build_args(args,build_args)handle_optionsargsoptions[:build_args] =build_argsifoptions[:silent]old_ui =uiself.ui =ui =Gem::SilentUI.newendifoptions[:help]show_helpelsif@when_invoked@when_invoked.calloptionselseexecuteendensureifuiself.ui =old_uiui.closeendend
Invoke the command with the given list of normal arguments and additional build arguments.
Source
# File lib/rubygems/command.rb, line 421defmerge_options(new_options)@options =@defaults.clonenew_options.each {|k,v|@options[k] =v }end
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 369defremove_option(name)@option_groups.eachdo|_,option_list|option_list.reject! {|args,_|args.any? {|x|x.is_a?(String)&&x=~/^#{name}/ } }endend
Remove previously defined command-line argumentname.
Source
# File lib/rubygems/command.rb, line 295defshow_helpparser.program_name =usagesayparserend
Display the help message for the command.
Source
# File lib/rubygems/command.rb, line 157defshow_lookup_failure(gem_name,version,errors,suppress_suggestions =false,required_by =nil)gem ="'#{gem_name}' (#{version})"msg =String.new"Could not find a valid gem #{gem}"iferrors&&!errors.empty?msg<<", here is why:\n"errors.each {|x|msg<<" #{x.wordy}\n" }elseifrequired_by&&gem!=required_bymsg<<" (required by #{required_by}) in any repository"elsemsg<<" in any repository"endendalert_errormsgunlesssuppress_suggestionssuggestions =Gem::SpecFetcher.fetcher.suggest_gems_from_name(gem_name,:latest,10)unlesssuggestions.empty?alert_error"Possible alternatives: #{suggestions.join(", ")}"endendend
Display to the user that a gem couldn’t be found and reasons why
Source
# File lib/rubygems/command.rb, line 288defusageprogram_nameend
Override to display the usage for an individual gem command.
The text “[options]” is automatically appended to the usage text.
Source
# File lib/rubygems/command.rb, line 343defwhen_invoked(&block)@when_invoked =blockend
Call the given block when invoked.
Normal command invocations just executes theexecute 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
Source
# File lib/rubygems/command.rb, line 510defadd_parser_run_info(title,content)returnifcontent.empty?@parser.separatornil@parser.separator" #{title}:"content.each_linedo|line|@parser.separator" #{line.rstrip}"endend
Adds a section withtitle andcontent to the parser help view. Used for adding command arguments and default arguments.
Source
# File lib/rubygems/command.rb, line 556defconfigure_options(header,option_list)returnifoption_list.nil?||option_list.empty?header =header.to_s.empty??"":"#{header} "@parser.separator" #{header}Options:"option_list.eachdo|args,handler|@parser.on(*args)do|value|handler.call(value,@options)endend@parser.separator""end
Source
# File lib/rubygems/command.rb, line 542defcreate_option_parser@parser =Gem::OptionParser.newadd_parser_options@parser.separatornilconfigure_options"Common",Gem::Command.common_optionsadd_parser_run_info"Arguments",argumentsadd_parser_summaryadd_parser_descriptionadd_parser_run_info"Defaults",defaults_strend
Creates an option parser and fills it in with the help info for the command.
Source
# File lib/rubygems/command.rb, line 475defoption_is_deprecated?(option)@deprecated_options[command].key?(option)end
Source
# File lib/rubygems/command.rb, line 533defparsercreate_option_parserif@parser.nil?@parserend
Create on demand parser.
Source
# File lib/rubygems/command.rb, line 574defwrap(text,width)# :doc:text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/,"\\1\\3\n")end
Wrapstext towidth