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

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

- 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::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
- 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