Class: Gem::Command (Ruby 2.7.2)
Description: Class : Gem::Command - Ruby 2.7.2

### Home Classes Methods

### In Files

- rubygems/command.rb
- rubygems/command_manager.rb
- rubygems/commands/help_command.rb

### Parent

Object

### Methods

- ::add_common_option
- ::add_specific_extra_args
- ::build_args
- ::build_args=
- ::common_options
- ::extra_args
- ::extra_args=
- ::new
- ::specific_extra_args
- ::specific_extra_args_hash
- #add_extra_args
- #add_option
- #arguments
- #begins?
- #check_deprecated_options
- #defaults_str
- #deprecate_option
- #description
- #execute
- #get_all_gem_names
- #get_all_gem_names_and_versions
- #get_one_gem_name
- #get_one_optional_argument
- #handle_options
- #handles?
- #invoke
- #invoke_with_build_args
- #merge_options
- #remove_option
- #show_help
- #show_lookup_failure
- #usage
- #when_invoked
- #wrap

### Included Modules

- Gem::UserInteraction

### Class/Module Index

Quicksearch

- Bundler
- Gem::AvailableSet
- Gem::BasicSpecification
- Gem::BundlerVersionFinder
- Gem::Command
- Gem::CommandLineError
- Gem::CommandManager
- Gem::Commands
- Gem::Commands::BuildCommand
- Gem::Commands::CertCommand
- Gem::Commands::CheckCommand
- Gem::Commands::CleanupCommand
- Gem::Commands::ContentsCommand
- Gem::Commands::DependencyCommand
- Gem::Commands::EnvironmentCommand
- Gem::Commands::FetchCommand
- Gem::Commands::GenerateIndexCommand
- Gem::Commands::HelpCommand
- Gem::Commands::InfoCommand
- Gem::Commands::InstallCommand
- Gem::Commands::ListCommand
- Gem::Commands::LockCommand
- Gem::Commands::MirrorCommand
- Gem::Commands::OpenCommand
- Gem::Commands::OutdatedCommand
- Gem::Commands::OwnerCommand
- Gem::Commands::PristineCommand
- Gem::Commands::PushCommand
- Gem::Commands::QueryCommand
- Gem::Commands::RdocCommand
- Gem::Commands::SearchCommand
- Gem::Commands::ServerCommand
- Gem::Commands::SetupCommand
- Gem::Commands::SetupCommand::MakeDirs
- Gem::Commands::SigninCommand
- Gem::Commands::SignoutCommand
- Gem::Commands::SourcesCommand
- Gem::Commands::SpecificationCommand
- Gem::Commands::StaleCommand
- Gem::Commands::UninstallCommand
- Gem::Commands::UnpackCommand
- Gem::Commands::UpdateCommand
- Gem::Commands::WhichCommand
- Gem::Commands::YankCommand
- Gem::ConfigFile
- Gem::ConflictError
- Gem::ConsoleUI
- Gem::DefaultUserInteraction
- Gem::Dependency
- Gem::DependencyError
- Gem::DependencyInstaller
- Gem::DependencyList
- Gem::DependencyRemovalException
- Gem::DependencyResolutionError
- Gem::Deprecate
- Gem::Doctor
- Gem::DocumentError
- Gem::EndOfYAMLException
- Gem::ErrorReason
- Gem::Exception
- Gem::Ext
- Gem::Ext::BuildError
- Gem::Ext::Builder
- Gem::Ext::CmakeBuilder
- Gem::Ext::ConfigureBuilder
- Gem::Ext::ExtConfBuilder
- Gem::Ext::RakeBuilder
- Gem::FakeFetcher
- Gem::FilePermissionError
- Gem::FormatException
- Gem::GemNotFoundException
- Gem::GemNotInHomeException
- Gem::GemRunner
- Gem::GemcutterUtilities
- Gem::ImpossibleDependenciesError
- Gem::Indexer
- Gem::InstallError
- Gem::InstallUpdateOptions
- Gem::Installer
- Gem::Installer::FakePackage
- Gem::InstallerTestCase
- Gem::InvalidSpecificationException
- Gem::Licenses
- Gem::List
- Gem::LoadError
- Gem::LocalRemoteOptions
- Gem::MissingSpecError
- Gem::MissingSpecVersionError
- Gem::MockGemUi
- Gem::MockGemUi::InputEOFError
- Gem::MockGemUi::SystemExitException
- Gem::MockGemUi::TTY
- Gem::MockGemUi::TermError
- Gem::NameTuple
- Gem::NoAliasYAMLTree
- Gem::OperationNotSupportedError
- Gem::Package::DigestIO
- Gem::Package::Error
- Gem::Package::FormatError
- Gem::Package::NonSeekableIO
- Gem::Package::Old
- Gem::Package::PathError
- Gem::Package::TarHeader
- Gem::Package::TarInvalidError
- Gem::Package::TarReader
- Gem::Package::TarReader::Entry
- Gem::Package::TarReader::UnexpectedEOF
- Gem::Package::TarTestCase
- Gem::Package::TarWriter
- Gem::Package::TarWriter::BoundedStream
- Gem::Package::TarWriter::FileOverflow
- Gem::Package::TarWriter::RestrictedStream
- Gem::Package::TooLongFileName
- Gem::PackageTask
- Gem::PathSupport
- Gem::Platform
- Gem::PlatformMismatch
- Gem::RemoteError
- Gem::RemoteFetcher
- Gem::RemoteFetcher::FetchError
- Gem::RemoteFetcher::UnknownHostError
- Gem::RemoteInstallationCancelled
- Gem::RemoteInstallationSkipped
- Gem::RemoteSourceException
- Gem::Request::ConnectionPools
- Gem::Request::ConnectionPools::Net
- Gem::RequestSet
- Gem::RequestSet::GemDependencyAPI
- Gem::RequestSet::Lockfile
- Gem::RequestSet::Lockfile::ParseError
- Gem::RequestSet::Lockfile::Parser
- Gem::RequestSet::Lockfile::Tokenizer
- Gem::Requirement
- Gem::Requirement::BadRequirementError
- Gem::Resolver
- Gem::Resolver::APISet
- Gem::Resolver::APISpecification
- Gem::Resolver::ActivationRequest
- Gem::Resolver::BestSet
- Gem::Resolver::ComposedSet
- Gem::Resolver::Conflict
- Gem::Resolver::CurrentSet
- Gem::Resolver::DependencyRequest
- Gem::Resolver::GitSet
- Gem::Resolver::GitSpecification
- Gem::Resolver::IndexSet
- Gem::Resolver::IndexSpecification
- Gem::Resolver::InstalledSpecification
- Gem::Resolver::InstallerSet
- Gem::Resolver::LocalSpecification
- Gem::Resolver::LockSet
- Gem::Resolver::LockSpecification
- Gem::Resolver::Molinillo
- Gem::Resolver::Molinillo::CircularDependencyError
- Gem::Resolver::Molinillo::Delegates
- Gem::Resolver::Molinillo::Delegates::ResolutionState
- Gem::Resolver::Molinillo::Delegates::SpecificationProvider
- Gem::Resolver::Molinillo::DependencyGraph
- Gem::Resolver::Molinillo::DependencyGraph::Action
- Gem::Resolver::Molinillo::DependencyGraph::AddEdgeNoCircular
- Gem::Resolver::Molinillo::DependencyGraph::DeleteEdge
- Gem::Resolver::Molinillo::DependencyGraph::DetachVertexNamed
- Gem::Resolver::Molinillo::DependencyGraph::Log
- Gem::Resolver::Molinillo::DependencyGraph::Tag
- Gem::Resolver::Molinillo::DependencyGraph::Vertex
- Gem::Resolver::Molinillo::DependencyState
- Gem::Resolver::Molinillo::NoSuchDependencyError
- Gem::Resolver::Molinillo::PossibilityState
- Gem::Resolver::Molinillo::ResolutionState
- Gem::Resolver::Molinillo::Resolver
- Gem::Resolver::Molinillo::Resolver::Resolution
- Gem::Resolver::Molinillo::ResolverError
- Gem::Resolver::Molinillo::SpecificationProvider
- Gem::Resolver::Molinillo::UI
- Gem::Resolver::Molinillo::VersionConflict
- Gem::Resolver::RequirementList
- Gem::Resolver::Set
- Gem::Resolver::SourceSet
- Gem::Resolver::SpecSpecification
- Gem::Resolver::Specification
- Gem::Resolver::Stats
- Gem::Resolver::VendorSet
- Gem::Resolver::VendorSpecification
- Gem::RubyVersionMismatch
- Gem::RuntimeRequirementNotMetError
- Gem::S3URISigner
- Gem::S3URISigner::ConfigurationError
- Gem::S3URISigner::InstanceProfileError
- Gem::SafeYAML
- Gem::Security
- Gem::Security::Exception
- Gem::Security::Policy
- Gem::Security::Signer
- Gem::Security::TrustDir
- Gem::SecurityOption
- Gem::Server
- Gem::SilentUI
- Gem::Source
- Gem::Source::Git
- Gem::Source::Installed
- Gem::Source::Local
- Gem::Source::Lock
- Gem::Source::SpecificFile
- Gem::Source::Vendor
- Gem::SourceFetchProblem
- Gem::SourceList
- Gem::SpecFetcher
- Gem::SpecificGemNotFoundException
- Gem::Specification
- Gem::SpecificationPolicy
- Gem::StreamUI
- Gem::StreamUI::SilentDownloadReporter
- Gem::StreamUI::SilentProgressReporter
- Gem::StreamUI::SimpleProgressReporter
- Gem::StreamUI::ThreadedDownloadReporter
- Gem::StreamUI::VerboseProgressReporter
- Gem::StubSpecification
- Gem::SystemExitException
- Gem::TestCase
- Gem::TestCase::SpecFetcherSetup
- Gem::TestCase::StaticSet
- Gem::Text
- Gem::UninstallError
- Gem::Uninstaller
- Gem::UnsatisfiableDependencyError
- Gem::UriFormatter
- Gem::UriParser
- Gem::UriParsing
- Gem::UserInteraction
- Gem::Util
- Gem::Validator
- Gem::VerificationError
- Gem::Version
- Gem::VersionOption
- Kernel
- Object
- OpenSSL
- TempIO
- YAML::Syck
- YAML::Syck

No matching classes.

# 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) click to toggle source

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

add_specific_extra_args(cmd,args) click to toggle source

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

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

build_args() click to toggle source

Arguments used when building gems

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

build_args=(value) click to toggle source

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

common_options() click to toggle source

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

extra_args() click to toggle source

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

extra_args=(value) click to toggle source

                   # File rubygems/command.rb, line 75
    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={}) click to toggle source

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

                   # File rubygems/command.rb, line 122
    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

specific_extra_args(cmd) click to toggle source

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

                   # File rubygems/command.rb, line 88
    def self.specific_extra_args(cmd)
      specific_extra_args_hash[cmd]
    end

specific_extra_args_hash() click to toggle source

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

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

### Public Instance Methods

add_extra_args(args) click to toggle source

Adds extra args from ~/.gemrc

                   # File 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 extra.first.to_s =~ /^[^-]/
        result << ex if handles?(ex)
      end

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

add_option(*opts) click to toggle source

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.

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

      @option_groups[group_name] << [opts, handler]
    end

arguments() click to toggle source

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

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

begins?(long, short) click to toggle source

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

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

check_deprecated_options(options) click to toggle source

                   # File rubygems/command.rb, line 394
    def check_deprecated_options(options)
      options.each do |option|
        if 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
    end

defaults_str() click to toggle source

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

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

deprecate_option(name, version: nil, extra_msg: nil) click to toggle source

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

                   # File rubygems/command.rb, line 390
    def deprecate_option(name, version: nil, extra_msg: nil)
      @deprecated_options[command].merge!({ name => { "rg_version_to_expire" => version, "extra_msg" => extra_msg } })
    end

description() click to toggle source

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

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

execute() click to toggle source

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

                   # File rubygems/command.rb, line 151
    def execute
      raise Gem::Exception, "generic command has no actions"
    end

get_all_gem_names() click to toggle source

Get all gem names from the command line.

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

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

      args.select { |arg| arg !~ /^-/ }
    end

get_all_gem_names_and_versions() click to toggle source

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.

                   # File rubygems/command.rb, line 204
    def get_all_gem_names_and_versions
      get_all_gem_names.map do |name|
        if /\A(.*):(#{Gem::Requirement::PATTERN_RAW})\z/ =~ name
          [$1, $2]
        else
          [name]
        end
      end
    end

get_one_gem_name() click to toggle source

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.

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

      if args.nil? or 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_one_optional_argument() click to toggle source

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.

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

handle_options(args) click to toggle source

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

                   # File 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

handles?(args) click to toggle source

True if the command handles the given argument list.

                   # File rubygems/command.rb, line 427
    def handles?(args)
      begin
        parser.parse!(args.dup)
        return true
      rescue
        return false
      end
    end

invoke(*args) click to toggle source

Invoke the command with the given list of arguments.

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

invoke_with_build_args(args, build_args) click to toggle source

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

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

      options[:build_args] = build_args

      if options[:silent]
        old_ui = self.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

merge_options(new_options) click to toggle source

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

                   # File rubygems/command.rb, line 419
    def merge_options(new_options)
      @options = @defaults.clone
      new_options.each { |k,v| @options[k] = v }
    end

remove_option(name) click to toggle source

Remove previously defined command-line argument `name`.

                   # File rubygems/command.rb, line 366
    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

show_help() click to toggle source

Display the help message for the command.

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

show_lookup_failure(gem_name, version, errors, suppress_suggestions = false, required_by = nil) click to toggle source

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

                   # File rubygems/command.rb, line 159
    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 and !errors.empty?
        msg << ", here is why:\n"
        errors.each { |x| msg << "          #{x.wordy}\n" }
      else
        if required_by and 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

        unless suggestions.empty?
          alert_error "Possible alternatives: #{suggestions.join(", ")}"
        end
      end
    end

usage() click to toggle source

Override to display the usage for an individual gem command.

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

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

when_invoked(&block) click to toggle source

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.

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

### Private Instance Methods

wrap(text, width) click to toggle source

Wraps `text` to `width`

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