123456789_123456789_123456789_123456789_123456789_

Class: Gem::Commands::HelpCommand

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
Inherits: Gem::Command
Defined in: lib/rubygems/commands/help_command.rb

Constant Summary

  • EXAMPLES = Internal use only
    # File 'lib/rubygems/commands/help_command.rb', line 6
    <<-EOF.freeze
    Some examples of 'gem' usage.
    
    * Install 'rake', either from local directory or remote server:
    
      gem install rake
    
    * Install 'rake', only from remote server:
    
      gem install rake --remote
    
    * Install 'rake', but only version 0.3.1, even if dependencies
    are not met, and into a user-specific directory:
    
      gem install rake --version 0.3.1 --force --user-install
    
    * List local gems whose name begins with 'D':
    
      gem list D
    
    * List local and remote gems whose name contains 'log':
    
      gem search log --both
    
    * List only remote gems whose name contains 'log':
    
      gem search log --remote
    
    * Uninstall 'rake':
    
      gem uninstall rake
    
    * Create a gem:
    
      See https://guides.rubygems.org/make-your-own-gem/
    
    * See information about RubyGems:
    
      gem environment
    
    * Update all gems on your system:
    
      gem update
    
    * Update your local version of RubyGems
    
      gem update --system
    EOF
  • GEM_DEPENDENCIES = Internal use only
    # File 'lib/rubygems/commands/help_command.rb', line 55
    <<-EOF.freeze
    A gem dependencies file allows installation of a consistent set of gems across
    multiple environments.  The RubyGems implementation is designed to be
    compatible with Bundler's Gemfile format.  You can see additional
    documentation on the format at:
    
    http://bundler.io
    
    RubyGems automatically looks for these gem dependencies files:
    
    * gem.deps.rb
    * Gemfile
    * Isolate
    
    These files are looked up automatically using `gem install -g`, or you can
    specify a custom file.
    
    When the RUBYGEMS_GEMDEPS environment variable is set to a gem dependencies
    file the gems from that file will be activated at startup time.  Set it to a
    specific filename or to "-" to have RubyGems automatically discover the gem
    dependencies file by walking up from the current directory.
    
    You can also activate gem dependencies at program startup using
    Gem.use_gemdeps.
    
    NOTE: Enabling automatic discovery on multiuser systems can lead to execution
    of arbitrary code when used from directories outside your control.
    
    Gem Dependencies
    ================
    
    Use #gem to declare which gems you directly depend upon:
    
    gem 'rake'
    
    To depend on a specific set of versions:
    
    gem 'rake', '~> 10.3', '>= 10.3.2'
    
    RubyGems will require the gem name when activating the gem using
    the RUBYGEMS_GEMDEPS environment variable or Gem::use_gemdeps.  Use the
    require: option to override this behavior if the gem does not have a file of
    that name or you don't want to require those files:
    
    gem 'my_gem', require: 'other_file'
    
    To prevent RubyGems from requiring any files use:
    
    gem 'my_gem', require: false
    
    To load dependencies from a .gemspec file:
    
    gemspec
    
    RubyGems looks for the first .gemspec file in the current directory.  To
    override this use the name: option:
    
    gemspec name: 'specific_gem'
    
    To look in a different directory use the path: option:
    
    gemspec name: 'specific_gem', path: 'gemspecs'
    
    To depend on a gem unpacked into a local directory:
    
    gem 'modified_gem', path: 'vendor/modified_gem'
    
    To depend on a gem from git:
    
    gem 'private_gem', git: 'git@my.company.example:private_gem.git'
    
    To depend on a gem from github:
    
    gem 'private_gem', github: 'my_company/private_gem'
    
    To depend on a gem from a github gist:
    
    gem 'bang', gist: '1232884'
    
    Git, github and gist support the ref:, branch: and tag: options to specify a
    commit reference or hash, branch or tag respectively to use for the gem.
    
    Setting the submodules: option to true for git, github and gist dependencies
    causes fetching of submodules when fetching the repository.
    
    You can depend on multiple gems from a single repository with the git method:
    
    git 'https://github.com/rails/rails.git' do
      gem 'activesupport'
      gem 'activerecord'
    end
    
    Gem Sources
    ===========
    
    RubyGems uses the default sources for regular `gem install` for gem
    dependencies files.  Unlike bundler, you do need to specify a source.
    
    You can override the sources used for downloading gems with:
    
    source 'https://gem_server.example'
    
    You may specify multiple sources.  Unlike bundler the prepend: option is not
    supported. Sources are used in-order, to prepend a source place it at the
    front of the list.
    
    Gem Platform
    ============
    
    You can restrict gem dependencies to specific platforms with the #platform
    and #platforms methods:
    
    platform :ruby_21 do
      gem 'debugger'
    end
    
    See the bundler Gemfile manual page for a list of platforms supported in a gem
    dependencies file.:
    
    http://bundler.io/v1.6/man/gemfile.5.html
    
    Ruby Version and Engine Dependency
    ==================================
    
    You can specify the version, engine and engine version of ruby to use with
    your gem dependencies file.  If you are not running the specified version
    RubyGems will raise an exception.
    
    To depend on a specific version of ruby:
    
    ruby '2.1.2'
    
    To depend on a specific ruby engine:
    
    ruby '1.9.3', engine: 'jruby'
    
    To depend on a specific ruby engine version:
    
    ruby '1.9.3', engine: 'jruby', engine_version: '1.7.11'
    
    Grouping Dependencies
    =====================
    
    Gem dependencies may be placed in groups that can be excluded from install.
    Dependencies required for development or testing of your code may be excluded
    when installed in a production environment.
    
    A #gem dependency may be placed in a group using the group: option:
    
    gem 'minitest', group: :test
    
    To install dependencies from a gemfile without specific groups use the
    `--without` option for `gem install -g`:
    
    $ gem install -g --without test
    
    The group: option also accepts multiple groups if the gem fits in multiple
    categories.
    
    Multiple groups may be excluded during install by comma-separating the groups for `--without` or by specifying `--without` multiple times.
    
    The #group method can also be used to place gems in groups:
    
    group :test do
      gem 'minitest'
      gem 'minitest-emoji'
    end
    
    The #group method allows multiple groups.
    
    The #gemspec development dependencies are placed in the :development group by
    default.  This may be overridden with the :development_group option:
    
    gemspec development_group: :other
    
    EOF
  • PLATFORMS = Internal use only
    # File 'lib/rubygems/commands/help_command.rb', line 232
    <<-'EOF'.freeze
    RubyGems platforms are composed of three parts, a CPU, an OS, and a
    version.  These values are taken from values in rbconfig.rb.  You can view
    your current platform by running `gem environment`.
    
    RubyGems matches platforms as follows:
    
    * The CPU must match exactly unless one of the platforms has
      "universal" as the CPU or the local CPU starts with "arm" and the gem's
      CPU is exactly "arm" (for gems that support generic ARM architecture).
    * The OS must match exactly.
    * The versions must match exactly unless one of the versions is nil.
    
    For commands that install, uninstall and list gems, you can override what
    RubyGems thinks your platform is with the --platform option.  The platform
    you pass must match "#{cpu}-#{os}" or "#{cpu}-#{os}-#{version}".  On mswin
    platforms, the version is the compiler version, not the OS version.  (Ruby
    compiled with VC6 uses "60" as the compiler version, VC8 uses "80".)
    
    For the ARM architecture, gems with a platform of "arm-linux" should run on a
    reasonable set of ARM CPUs and not depend on instructions present on a limited
    subset of the architecture.  For example, the binary should run on platforms
    armv5, armv6hf, armv6l, armv7, etc.  If you use the "arm-linux" platform
    please test your gem on a variety of ARM hardware before release to ensure it
    functions correctly.
    
    Example platforms:
    
    x86-freebsd        # Any FreeBSD version on an x86 CPU
    universal-darwin-8 # Darwin 8 only gems that run on any CPU
    x86-mswin32-80     # Windows gems compiled with VC8
    armv7-linux        # Gem complied for an ARMv7 CPU running linux
    arm-linux          # Gem compiled for any ARM CPU running linux
    
    When building platform gems, set the platform in the gem specification to
    Gem::Platform::CURRENT.  This will correctly mark the gem with your ruby's
    platform.
    EOF
  • SUBCOMMANDS = Internal use only

    NOTE when updating also update Gem::Command::HELP

    # File 'lib/rubygems/commands/help_command.rb', line 273
    [
      ["commands",         :show_commands],
      ["options",          Gem::Command::HELP],
      ["examples",         EXAMPLES],
      ["gem_dependencies", GEM_DEPENDENCIES],
      ["platforms",        PLATFORMS],
    ].freeze

::Gem::Command - Inherited

HELP

Class Attribute Summary

::Gem::Command - Inherited

.build_args

Arguments used when building gems.

.build_args=, .extra_args, .extra_args=

Class Method Summary

::Gem::Command - Inherited

.add_common_option,
.add_specific_extra_args

Add a list of extra arguments for the given command.

.common_options,
.new

Initializes a generic gem command named command.

.specific_extra_args

Return an array of extra arguments for the command.

.specific_extra_args_hash

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

Instance Attribute Summary

::Gem::Command - Inherited

#command

The name of the command.

#defaults

The default options for the command.

#deprecated?,
#options

The options for the command.

#program_name

The name of the command for command-line invocation.

#summary

A short description of the command.

::Gem::DefaultUserInteraction - Included

Instance Method Summary

::Gem::Command - Inherited

#add_extra_args

Adds extra args from ~/.gemrc.

#add_option

Add a command-line option and handler to the command.

#arguments

Override to provide details of the arguments a command takes.

#begins?

True if long begins with the characters from short.

#check_deprecated_options,
#defaults_str

Override to display the default values of the command options.

#deprecate_option

Mark a command-line option as deprecated, and optionally specify a deprecation horizon.

#description

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

#execute

Override to provide command handling.

#get_all_gem_names

Get all gem names from the command line.

#get_all_gem_names_and_versions

Get all [gem, version] from the command line.

#get_one_gem_name

Get a single gem name from the command line.

#get_one_optional_argument

Get a single optional argument from the command line.

#handle_options

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

#handles?

True if the command handles the given argument list.

#invoke

Invoke the command with the given list of arguments.

#invoke_with_build_args

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

#merge_options

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

#remove_option

Remove previously defined command-line argument name.

#show_help

Display the help message for the command.

#show_lookup_failure

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

#usage

Override to display the usage for an individual gem command.

#when_invoked

Call the given block when invoked.

#add_parser_run_info

Adds a section with title and content to the parser help view.

#configure_options,
#create_option_parser

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

#option_is_deprecated?,
#parser

Create on demand parser.

#wrap

Wraps text to width

#add_parser_description, #add_parser_options, #add_parser_summary

::Gem::UserInteraction - Included

#alert

Displays an alert statement.

#alert_error

Displays an error statement to the error output location.

#alert_warning

Displays a warning statement to the warning output location.

#ask

Asks a question and returns the answer.

#ask_for_password

Asks for a password with a prompt

#ask_yes_no

Asks a yes or no question.

#choose_from_list

Asks the user to answer question with an answer from the given list.

#say

Displays the given statement on the standard output (or equivalent).

#terminate_interaction

Terminates the RubyGems process with the given exit_code

#verbose

Calls say with msg or the results of the block if really_verbose is true.

::Gem::DefaultUserInteraction - Included

::Gem::Text - Included

#clean_text

Remove any non-printable characters and make the text suitable for printing.

#format_text

Wraps text to wrap characters and optionally indents by indent characters.

#levenshtein_distance

This code is based directly on the ::Gem::Text gem implementation Returns a value representing the “cost” of transforming str1 into str2.

#truncate_text, #min3

Constructor Details

.newHelpCommand

[ GitHub ]

  
# File 'lib/rubygems/commands/help_command.rb', line 282

def initialize
  super 'help', "Provide help on the 'gem' command"

  @command_manager = Gem::CommandManager.instance
end

Instance Method Details

#execute

[ GitHub ]

  
# File 'lib/rubygems/commands/help_command.rb', line 292

def execute
  arg = options[:args][0]

  _, help = SUBCOMMANDS.find do |command,|
    begins? command, arg
  end

  if help
    if Symbol === help
      send help
    else
      say help
    end
    return
  end

  if options[:help]
    show_help

  elsif arg
    show_command_help arg

  else
    say Gem::Command::HELP
  end
end

#show_command_help(command_name)

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/help_command.rb', line 360

def show_command_help(command_name) # :nodoc:
  command_name = command_name.downcase

  possibilities = @command_manager.find_command_possibilities command_name

  if possibilities.size == 1
    command = @command_manager[possibilities.first]
    command.invoke("--help")
  elsif possibilities.size > 1
    alert_warning "Ambiguous command #{command_name} (#{possibilities.join(', ')})"
  else
    alert_warning "Unknown command #{command_name}. Try: gem help commands"
  end
end

#show_commands

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/help_command.rb', line 319

def show_commands # :nodoc:
  out = []
  out << "GEM commands are:"
  out << nil

  margin_width = 4

  desc_width = @command_manager.command_names.map {|n| n.size }.max + 4

  summary_width = 80 - margin_width - desc_width
  wrap_indent = ' ' * (margin_width + desc_width)
  format = "#{' ' * margin_width}%-#{desc_width}s%s"

  @command_manager.command_names.each do |cmd_name|
    command = @command_manager[cmd_name]

    next if command.deprecated?

    summary =
      if command
        command.summary
      else
        "[No command found for #{cmd_name}]"
      end

    summary = wrap(summary, summary_width).split "\n"
    out << sprintf(format, cmd_name, summary.shift)
    until summary.empty? do
      out << "#{wrap_indent}#{summary.shift}"
    end
  end

  out << nil
  out << "For help on a particular command, use 'gem help COMMAND'."
  out << nil
  out << "Commands may be abbreviated, so long as they are unambiguous."
  out << "e.g. 'gem i rake' is short for 'gem install rake'."

  say out.join("\n")
end

#usage

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/help_command.rb', line 288

def usage # :nodoc:
  "#{program_name} ARGUMENT"
end