Class: Gem::Commands::HelpCommand

Inherits:
Gem::Command show all
Defined in:
lib/rubygems/commands/help_command.rb

Constant Summary collapse

EXAMPLES =

:stopdoc:

"Some examples of 'gem' usage.\n\n* Install 'rake', either from local directory or remote server:\n\n  gem install rake\n\n* Install 'rake', only from remote server:\n\n  gem install rake --remote\n\n* Install 'rake', but only version 0.3.1, even if dependencies\nare not met, and into a user-specific directory:\n\n  gem install rake --version 0.3.1 --force --user-install\n\n* List local gems whose name begins with 'D':\n\n  gem list D\n\n* List local and remote gems whose name contains 'log':\n\n  gem search log --both\n\n* List only remote gems whose name contains 'log':\n\n  gem search log --remote\n\n* Uninstall 'rake':\n\n  gem uninstall rake\n\n* Create a gem:\n\n  See https://guides.rubygems.org/make-your-own-gem/\n\n* See information about RubyGems:\n\n  gem environment\n\n* Update all gems on your system:\n\n  gem update\n\n* Update your local version of RubyGems\n\n  gem update --system\n"
GEM_DEPENDENCIES = 
"A gem dependencies file allows installation of a consistent set of gems across\nmultiple environments.  The RubyGems implementation is designed to be\ncompatible with Bundler's Gemfile format.  You can see additional\ndocumentation on the format at:\n\nhttps://bundler.io\n\nRubyGems automatically looks for these gem dependencies files:\n\n* gem.deps.rb\n* Gemfile\n* Isolate\n\nThese files are looked up automatically using `gem install -g`, or you can\nspecify a custom file.\n\nWhen the RUBYGEMS_GEMDEPS environment variable is set to a gem dependencies\nfile the gems from that file will be activated at startup time.  Set it to a\nspecific filename or to \"-\" to have RubyGems automatically discover the gem\ndependencies file by walking up from the current directory.\n\nYou can also activate gem dependencies at program startup using\nGem.use_gemdeps.\n\nNOTE: Enabling automatic discovery on multiuser systems can lead to execution\nof arbitrary code when used from directories outside your control.\n\nGem Dependencies\n================\n\nUse #gem to declare which gems you directly depend upon:\n\ngem 'rake'\n\nTo depend on a specific set of versions:\n\ngem 'rake', '~> 10.3', '>= 10.3.2'\n\nRubyGems will require the gem name when activating the gem using\nthe RUBYGEMS_GEMDEPS environment variable or Gem::use_gemdeps.  Use the\nrequire: option to override this behavior if the gem does not have a file of\nthat name or you don't want to require those files:\n\ngem 'my_gem', require: 'other_file'\n\nTo prevent RubyGems from requiring any files use:\n\ngem 'my_gem', require: false\n\nTo load dependencies from a .gemspec file:\n\ngemspec\n\nRubyGems looks for the first .gemspec file in the current directory.  To\noverride this use the name: option:\n\ngemspec name: 'specific_gem'\n\nTo look in a different directory use the path: option:\n\ngemspec name: 'specific_gem', path: 'gemspecs'\n\nTo depend on a gem unpacked into a local directory:\n\ngem 'modified_gem', path: 'vendor/modified_gem'\n\nTo depend on a gem from git:\n\ngem 'private_gem', git: 'git@my.company.example:private_gem.git'\n\nTo depend on a gem from github:\n\ngem 'private_gem', github: 'my_company/private_gem'\n\nTo depend on a gem from a github gist:\n\ngem 'bang', gist: '1232884'\n\nGit, github and gist support the ref:, branch: and tag: options to specify a\ncommit reference or hash, branch or tag respectively to use for the gem.\n\nSetting the submodules: option to true for git, github and gist dependencies\ncauses fetching of submodules when fetching the repository.\n\nYou can depend on multiple gems from a single repository with the git method:\n\ngit 'https://github.com/rails/rails.git' do\n  gem 'activesupport'\n  gem 'activerecord'\nend\n\nGem Sources\n===========\n\nRubyGems uses the default sources for regular `gem install` for gem\ndependencies files.  Unlike bundler, you do need to specify a source.\n\nYou can override the sources used for downloading gems with:\n\nsource 'https://gem_server.example'\n\nYou may specify multiple sources.  Unlike bundler the prepend: option is not\nsupported. Sources are used in-order, to prepend a source place it at the\nfront of the list.\n\nGem Platform\n============\n\nYou can restrict gem dependencies to specific platforms with the #platform\nand #platforms methods:\n\nplatform :ruby_21 do\n  gem 'debugger'\nend\n\nSee the bundler Gemfile manual page for a list of platforms supported in a gem\ndependencies file.:\n\nhttps://bundler.io/v2.5/man/gemfile.5.html\n\nRuby Version and Engine Dependency\n==================================\n\nYou can specify the version, engine and engine version of ruby to use with\nyour gem dependencies file.  If you are not running the specified version\nRubyGems will raise an exception.\n\nTo depend on a specific version of ruby:\n\nruby '2.1.2'\n\nTo depend on a specific ruby engine:\n\nruby '1.9.3', engine: 'jruby'\n\nTo depend on a specific ruby engine version:\n\nruby '1.9.3', engine: 'jruby', engine_version: '1.7.11'\n\nGrouping Dependencies\n=====================\n\nGem dependencies may be placed in groups that can be excluded from install.\nDependencies required for development or testing of your code may be excluded\nwhen installed in a production environment.\n\nA #gem dependency may be placed in a group using the group: option:\n\ngem 'minitest', group: :test\n\nTo install dependencies from a gemfile without specific groups use the\n`--without` option for `gem install -g`:\n\n$ gem install -g --without test\n\nThe group: option also accepts multiple groups if the gem fits in multiple\ncategories.\n\nMultiple groups may be excluded during install by comma-separating the groups for `--without` or by specifying `--without` multiple times.\n\nThe #group method can also be used to place gems in groups:\n\ngroup :test do\n  gem 'minitest'\n  gem 'minitest-emoji'\nend\n\nThe #group method allows multiple groups.\n\nThe #gemspec development dependencies are placed in the :development group by\ndefault.  This may be overridden with the :development_group option:\n\ngemspec development_group: :other\n\n"
PLATFORMS = 
"RubyGems platforms are composed of three parts, a CPU, an OS, and a\nversion.  These values are taken from values in rbconfig.rb.  You can view\nyour current platform by running `gem environment`.\n\nRubyGems matches platforms as follows:\n\n* The CPU must match exactly unless one of the platforms has\n  \"universal\" as the CPU or the local CPU starts with \"arm\" and the gem's\n  CPU is exactly \"arm\" (for gems that support generic ARM architecture).\n* The OS must match exactly.\n* The versions must match exactly unless one of the versions is nil.\n\nFor commands that install, uninstall and list gems, you can override what\nRubyGems thinks your platform is with the --platform option.  The platform\nyou pass must match \"\#{cpu}-\#{os}\" or \"\#{cpu}-\#{os}-\#{version}\".  On mswin\nplatforms, the version is the compiler version, not the OS version.  (Ruby\ncompiled with VC6 uses \"60\" as the compiler version, VC8 uses \"80\".)\n\nFor the ARM architecture, gems with a platform of \"arm-linux\" should run on a\nreasonable set of ARM CPUs and not depend on instructions present on a limited\nsubset of the architecture.  For example, the binary should run on platforms\narmv5, armv6hf, armv6l, armv7, etc.  If you use the \"arm-linux\" platform\nplease test your gem on a variety of ARM hardware before release to ensure it\nfunctions correctly.\n\nExample platforms:\n\nx86-freebsd        # Any FreeBSD version on an x86 CPU\nuniversal-darwin-8 # Darwin 8 only gems that run on any CPU\nx86-mswin32-80     # Windows gems compiled with VC8\narmv7-linux        # Gem complied for an ARMv7 CPU running linux\narm-linux          # Gem compiled for any ARM CPU running linux\n\nWhen building platform gems, set the platform in the gem specification to\nGem::Platform::CURRENT.  This will correctly mark the gem with your ruby's\nplatform.\n"
SUBCOMMANDS =

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

[
  ["commands",         :show_commands],
  ["options",          Gem::Command::HELP],
  ["examples",         EXAMPLES],
  ["gem_dependencies", GEM_DEPENDENCIES],
  ["platforms",        PLATFORMS],
].freeze

Instance Attribute Summary

Attributes inherited from Gem::Command

#command, #defaults, #options, #program_name, #summary

Instance Method Summary collapse

Methods inherited from Gem::Command

add_common_option, #add_extra_args, #add_option, add_specific_extra_args, #arguments, #begins?, build_args, build_args=, #check_deprecated_options, common_options, #defaults_str, #deprecate_option, #deprecated?, #description, extra_args, extra_args=, #extract_gem_name_and_version, #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, specific_extra_args, specific_extra_args_hash, #when_invoked

Methods included from UserInteraction

#alert, #alert_error, #alert_warning, #ask, #ask_for_password, #ask_yes_no, #choose_from_list, #say, #terminate_interaction, #verbose

Methods included from DefaultUserInteraction

ui, #ui, ui=, #ui=, use_ui, #use_ui

Methods included from Text

#clean_text, #format_text, #levenshtein_distance, #min3, #truncate_text

Constructor Details

#initialize ⇒ HelpCommand

:startdoc:


283
284
285
286
287
 
# File 'lib/rubygems/commands/help_command.rb', line 283

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

  @command_manager = Gem::CommandManager.instance
end

Instance Method Details

#execute ⇒ Object 


293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/rubygems/commands/help_command.rb', line 293

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) ⇒ Object

:nodoc:


361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/rubygems/commands/help_command.rb', line 361

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 ⇒ Object

:nodoc:


320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/rubygems/commands/help_command.rb', line 320

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

  margin_width = 4

  desc_width = @command_manager.command_names.map(&: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 << format(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 ⇒ Object

:nodoc:


289
290
291
 
# File 'lib/rubygems/commands/help_command.rb', line 289

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