class Gem::Command - Documentation for Ruby 3.4
Description: class Gem::Command: Base class for all Gem commands. When creating a new gem command, define #initialize, #execute, #arguments, #defaults_str, #description and #usage (as
Keywords: ruby,class,Gem::Command

# class Gem::Command

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`

### 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)
Source

    # File lib/rubygems/command.rb, line 65
    def self.add_common_option(*args, &handler)
      Gem::Command.common_options << [args, handler]
    end

add_specific_extra_args (cmd,args)
Source

    # File lib/rubygems/command.rb, line 94
    def self.add_specific_extra_args(cmd,args)
      args = args.split(/\s+/) if args.is_a? String
      specific_extra_args_hash[cmd] = args
    end

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

    # File lib/rubygems/command.rb, line 53
    def self.build_args
      @build_args ||= []
    end

Arguments used when building gems

build_args= (value)
Source

    # File lib/rubygems/command.rb, line 57
    def self.build_args=(value)
      @build_args = value
    end

common_options ()
Source

    # File lib/rubygems/command.rb, line 61
    def self.common_options
      @common_options ||= []
    end

extra_args ()
Source

    # File lib/rubygems/command.rb, line 69
    def self.extra_args
      @extra_args ||= []
    end

extra_args= (value)
Source

    # File lib/rubygems/command.rb, line 73
    def self.extra_args=(value)
      case value
      when Array
        @extra_args = value
      when String
        @extra_args = value.split(" ")
      end
    end

new (command, summary=nil, defaults={})
Source

    # File lib/rubygems/command.rb, line 120
    def initialize(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 = nil
    end

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

    # File lib/rubygems/command.rb, line 86
    def self.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.

specific_extra_args_hash ()
Source

    # File lib/rubygems/command.rb, line 102
    def self.specific_extra_args_hash
      @specific_extra_args_hash ||= Hash.new do |h,k|
        h[k] = Array.new
      end
    end

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

### Public Instance Methods

add_extra_args (args)
Source

    # File lib/rubygems/command.rb, line 451
    def add_extra_args(args)
      result = []

      s_extra = Gem::Command.specific_extra_args(@command)
      extra = Gem::Command.extra_args + s_extra

      until extra.empty? do
        ex = []
        ex << extra.shift
        ex << extra.shift if /^[^-]/.match?(extra.first.to_s)
        result << ex if handles?(ex)
      end

      result.flatten!
      result.concat(args)
      result
    end

Adds extra args from ~/.gemrc

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

    # File lib/rubygems/command.rb, line 358
    def add_option(*opts, &handler) # :yields: value, options
      group_name = Symbol === opts.first ? opts.shift : :options

      raise "Do not pass an empty string in opts" if opts.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 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 ()
Source

    # File lib/rubygems/command.rb, line 258
    def arguments
      ""
    end

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

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

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

check_deprecated_options (options)
Source

    # File lib/rubygems/command.rb, line 397
    def check_deprecated_options(options)
      options.each do |option|
        next unless option_is_deprecated?(option)
        deprecation = @deprecated_options[command][option]
        version_to_expire = deprecation["rg_version_to_expire"]

        deprecate_option_msg = if version_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."
        end

        extra_msg = deprecation["extra_msg"]

        deprecate_option_msg += " #{extra_msg}" if extra_msg

        alert_warning(deprecate_option_msg)
      end
    end

defaults_str ()
Source

    # File lib/rubygems/command.rb, line 272
    def defaults_str
      ""
    end

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

deprecate_option (name, version: nil, extra_msg: nil)
Source

    # File lib/rubygems/command.rb, line 393
    def deprecate_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')

deprecated? ()
Source

    # File lib/rubygems/command.rb, line 469
    def deprecated?
      false
    end

description ()
Source

    # File lib/rubygems/command.rb, line 279
    def description
      nil
    end

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

execute ()
Source

    # File lib/rubygems/command.rb, line 149
    def execute
      raise Gem::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 in `options[:args]`.

See also: `get_all_gem_names`, `get_one_gem_name`, `get_one_optional_argument`

get_all_gem_names ()
Source

    # File lib/rubygems/command.rb, line 185
    def get_all_gem_names
      args = options[:args]

      if args.nil? || args.empty?
        raise Gem::CommandLineError,
              "Please specify at least one gem name (e.g. gem build GEMNAME)"
      end

      args.reject {|arg| arg.start_with?("-") }
    end

Get all gem names from the command line.

get_all_gem_names_and_versions ()
Source

    # File lib/rubygems/command.rb, line 201
    def get_all_gem_names_and_versions
      get_all_gem_names.map do |name|
        extract_gem_name_and_version(name)
      end
    end

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

    # File lib/rubygems/command.rb, line 219
    def get_one_gem_name
      args = options[:args]

      if args.nil? || args.empty?
        raise Gem::CommandLineError,
              "Please specify a gem name on the command line (e.g. gem build GEMNAME)"
      end

      if args.size > 1
        raise Gem::CommandLineError,
              "Too many gem names (#{args.join(", ")}); please specify only one"
      end

      args.first
    end

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

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

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

    # File lib/rubygems/command.rb, line 440
    def handle_options(args)
      args = add_extra_args(args)
      check_deprecated_options(args)
      @options = Marshal.load Marshal.dump @defaults # deep copy
      parser.parse!(args)
      @options[:args] = args
    end

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

handles? (args)
Source

    # File lib/rubygems/command.rb, line 429
    def handles?(args)
      parser.parse!(args.dup)
      true
    rescue StandardError
      false
    end

True if the command handles the given argument list.

invoke (*args)
Source

    # File lib/rubygems/command.rb, line 303
    def invoke(*args)
      invoke_with_build_args args, nil
    end

Invoke the command with the given list of arguments.

invoke_with_build_args (args, build_args)
Source

    # File lib/rubygems/command.rb, line 311
    def invoke_with_build_args(args, build_args)
      handle_options args

      options[:build_args] = build_args

      if options[:silent]
        old_ui = ui
        self.ui = ui = Gem::SilentUI.new
      end

      if options[:help]
        show_help
      elsif @when_invoked
        @when_invoked.call options
      else
        execute
      end
    ensure
      if ui
        self.ui = old_ui
        ui.close
      end
    end

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

merge_options (new_options)
Source

    # File lib/rubygems/command.rb, line 421
    def merge_options(new_options)
      @options = @defaults.clone
      new_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).

remove_option (name)
Source

    # File lib/rubygems/command.rb, line 369
    def remove_option(name)
      @option_groups.each do |_, option_list|
        option_list.reject! {|args, _| args.any? {|x| x.is_a?(String) && x =~ /^#{name}/ } }
      end
    end

Remove previously defined command-line argument `name`.

show_help ()
Source

    # File lib/rubygems/command.rb, line 295
    def show_help
      parser.program_name = usage
      say parser
    end

Display the help message for the command.

show_lookup_failure (gem_name, version, errors, suppress_suggestions = false, required_by = nil)
Source

    # File lib/rubygems/command.rb, line 157
    def show_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}"

      if errors && !errors.empty?
        msg << ", here is why:\n"
        errors.each {|x| msg << "          #{x.wordy}\n" }
      else
        if required_by && gem != required_by
          msg << " (required by #{required_by}) in any repository"
        else
          msg << " in any repository"
        end
      end

      alert_error msg

      unless suppress_suggestions
        suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name(gem_name, :latest, 10)
        unless suggestions.empty?
          alert_error "Possible alternatives: #{suggestions.join(", ")}"
        end
      end
    end

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

usage ()
Source

    # File lib/rubygems/command.rb, line 288
    def usage
      program_name
    end

Override to display the usage for an individual gem command.

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

when_invoked (&block)
Source

    # File lib/rubygems/command.rb, line 343
    def when_invoked(&block)
      @when_invoked = block
    end

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

add_parser_run_info (title, content)
Source

    # File lib/rubygems/command.rb, line 510
    def add_parser_run_info(title, content)
      return if content.empty?

      @parser.separator nil
      @parser.separator "  #{title}:"
      content.each_line do |line|
        @parser.separator "    #{line.rstrip}"
      end
    end

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

configure_options (header, option_list)
Source

    # File lib/rubygems/command.rb, line 556
    def configure_options(header, option_list)
      return if option_list.nil? || option_list.empty?

      header = header.to_s.empty? ? "" : "#{header} "
      @parser.separator "  #{header}Options:"

      option_list.each do |args, handler|
        @parser.on(*args) do |value|
          handler.call(value, @options)
        end
      end

      @parser.separator ""
    end

create_option_parser ()
Source

    # File lib/rubygems/command.rb, line 542
    def create_option_parser
      @parser = Gem::OptionParser.new

      add_parser_options

      @parser.separator nil
      configure_options "Common", Gem::Command.common_options

      add_parser_run_info "Arguments", arguments
      add_parser_summary
      add_parser_description
      add_parser_run_info "Defaults", defaults_str
    end

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

option_is_deprecated? (option)
Source

    # File lib/rubygems/command.rb, line 475
    def option_is_deprecated?(option)
      @deprecated_options[command].key?(option)
    end

parser ()
Source

    # File lib/rubygems/command.rb, line 533
    def parser
      create_option_parser if @parser.nil?
      @parser
    end

Create on demand parser.

wrap (text, width)
Source

    # File lib/rubygems/command.rb, line 574
    def wrap(text, width) # :doc:
      text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
    end

Wraps `text` to `width`