class Bundler::Thor

Constants

DynamicTask: A dynamic command that handles method missing scenarios.
HELP_MAPPINGS: Shortcuts for help.
HiddenTask: A command that is hidden in help messages but still invocable.
TEMPLATE_EXTNAME
THOR_RESERVED_WORDS: Bundler::Thor methods that should not be overwritten by the user.
Task
VERSION

Public Class Methods

check_unknown_options!(options = {}) click to toggle source

Extend check unknown options to accept a hash of conditions.

Parameters¶ ↑

options<Hash>: A hash containing :only and/or :except keys

# File bundler/vendor/thor/lib/thor.rb, line 255
def check_unknown_options!(options = {})
  @check_unknown_options ||= {}
  options.each do |key, value|
    if value
      @check_unknown_options[key] = Array(value)
    else
      @check_unknown_options.delete(key)
    end
  end
  @check_unknown_options
end

command_help(shell, command_name) click to toggle source

Prints help information for the given command.

Parameters¶ ↑

shell<Bundler::Thor::Shell> command_name<String>

# File bundler/vendor/thor/lib/thor.rb, line 172
def command_help(shell, command_name)
  meth = normalize_command_name(command_name)
  command = all_commands[meth]
  handle_no_command_error(meth) unless command

  shell.say "Usage:"
  shell.say "  #{banner(command).split("\n").join("\n  ")}"
  shell.say
  class_options_help(shell, nil => command.options.values)
  if command.long_description
    shell.say "Description:"
    shell.print_wrapped(command.long_description, :indent => 2)
  else
    shell.say command.description
  end
end

Also aliased as: task_help

default_command(meth = nil) click to toggle source

Sets the default command when thor is executed without an explicit command to be called.

Parameters¶ ↑

meth<Symbol>: name of the default command

# File bundler/vendor/thor/lib/thor.rb, line 21
def default_command(meth = nil)
  if meth
    @default_command = meth == :none ? "help" : meth.to_s
  else
    @default_command ||= from_superclass(:default_command, "help")
  end
end

Also aliased as: default_task

default_task(meth = nil)

Alias for: default_command

desc(usage, description, options = {}) click to toggle source

Defines the usage and the description of the next command.

Parameters¶ ↑

usage<String> description<String> options<String>

# File bundler/vendor/thor/lib/thor.rb, line 54
def desc(usage, description, options = {})
  if options[:for]
    command = find_and_refresh_command(options[:for])
    command.usage = usage             if usage
    command.description = description if description
  else
    @usage = usage
    @desc = description
    @hide = options[:hide] || false
  end
end

disable_required_check!(*command_names) click to toggle source

Disable the check for required options for the given commands. This is useful if you have a command that does not need the required options to work, like help.

Parameters¶ ↑

Symbol …: A list of commands that should be affected.

# File bundler/vendor/thor/lib/thor.rb, line 339
def disable_required_check!(*command_names)
  disable_required_check.merge(command_names)
end

help(shell, subcommand = false) click to toggle source

Prints help information for this class.

Parameters¶ ↑

shell<Bundler::Thor::Shell>

# File bundler/vendor/thor/lib/thor.rb, line 195
def help(shell, subcommand = false)
  list = printable_commands(true, subcommand)
  Bundler::Thor::Util.thor_classes_in(self).each do |klass|
    list += klass.printable_commands(false)
  end
  list.sort! { |a, b| a[0] <=> b[0] }

  if defined?(@package_name) && @package_name
    shell.say "#{@package_name} commands:"
  else
    shell.say "Commands:"
  end

  shell.print_table(list, :indent => 2, :truncate => true)
  shell.say
  class_options_help(shell)
end

long_desc(long_description, options = {}) click to toggle source

Defines the long description of the next command.

Parameters¶ ↑

long description<String>

# File bundler/vendor/thor/lib/thor.rb, line 71
def long_desc(long_description, options = {})
  if options[:for]
    command = find_and_refresh_command(options[:for])
    command.long_description = long_description if long_description
  else
    @long_desc = long_description
  end
end

map(mappings = nil, **kw) click to toggle source

Maps an input to a command. If you define:

map "-T" => "list"

Running:

thor -T

Will invoke the list command.

Parameters¶ ↑

Hash[String|Array => Symbol]: Maps the string or the strings in the array to the given command.

# File bundler/vendor/thor/lib/thor.rb, line 93
def map(mappings = nil, **kw)
  @map ||= from_superclass(:map, {})

  if mappings && !kw.empty?
    mappings = kw.merge!(mappings)
  else
    mappings ||= kw
  end
  if mappings
    mappings.each do |key, value|
      if key.respond_to?(:each)
        key.each { |subkey| @map[subkey] = value }
      else
        @map[key] = value
      end
    end
  end

  @map
end

method_option(name, options = {}) click to toggle source

Adds an option to the set of method options. If :for is given as option, it allows you to change the options from a previous defined command.

def previous_command
  # magic
end

method_option :foo => :bar, :for => :previous_command

def next_command
  # magic
end

Parameters¶ ↑

name<Symbol>: The name of the argument.
options<Hash>: Described below.

Options¶ ↑

:desc - Description for the argument. :required - If the argument is required or not. :default - Default value for this argument. It cannot be required and have default values. :aliases - Aliases for this option. :type - The type of the argument, can be :string, :hash, :array, :numeric or :boolean. :banner - String to show on usage notes. :hide - If you want to hide this option from the help.

# File bundler/vendor/thor/lib/thor.rb, line 155
def method_option(name, options = {})
  scope = if options[:for]
    find_and_refresh_command(options[:for]).options
  else
    method_options
  end

  build_option(name, options, scope)
end

Also aliased as: option

method_options(options = nil) click to toggle source

Declares the options for the next command to be declared.

Parameters¶ ↑

Hash[Symbol => Object]: The hash key is the name of the option and the value

is the type of the option. Can be :string, :array, :hash, :boolean, :numeric or :required (string). If you give a value, the type of the value is used.

# File bundler/vendor/thor/lib/thor.rb, line 121
def method_options(options = nil)
  @method_options ||= {}
  build_options(options, @method_options) if options
  @method_options
end

Also aliased as: options

option(name, options = {})

Alias for: method_option

options(options = nil)

Alias for: method_options

package_name(name, _ = {}) click to toggle source

Allows for custom “Command” package naming.

Parameters¶ ↑

name<String> options<Hash>

# File bundler/vendor/thor/lib/thor.rb, line 12
def package_name(name, _ = {})
  @package_name = name.nil? || name == "" ? nil : name
end

printable_commands(all = true, subcommand = false) click to toggle source

Returns commands ready to be printed.

# File bundler/vendor/thor/lib/thor.rb, line 214
def printable_commands(all = true, subcommand = false)
  (all ? all_commands : commands).map do |_, command|
    next if command.hidden?
    item = []
    item << banner(command, false, subcommand)
    item << (command.description ? "# #{command.description.gsub(/\s+/m, ' ')}" : "")
    item
  end.compact
end

Also aliased as: printable_tasks

printable_tasks(all = true, subcommand = false)

Alias for: printable_commands

Registers another Bundler::Thor subclass as a command.

Parameters¶ ↑

klass<Class>: Bundler::Thor subclass to register
command<String>: Subcommand name to use
usage<String>: Short usage for the subcommand
description<String>: Description for the subcommand

# File bundler/vendor/thor/lib/thor.rb, line 37
def register(klass, subcommand_name, usage, description, options = {})
  if klass <= Bundler::Thor::Group
    desc usage, description, options
    define_method(subcommand_name) { |*args| invoke(klass, args) }
  else
    desc usage, description, options
    subcommand subcommand_name, klass
  end
end

stop_on_unknown_option!(*command_names) click to toggle source

Stop parsing of options as soon as an unknown option or a regular argument is encountered. All remaining arguments are passed to the command. This is useful if you have a command that can receive arbitrary additional options, and where those additional options should not be handled by Bundler::Thor.

Example¶ ↑

To better understand how this is useful, let’s consider a command that calls an external command. A user may want to pass arbitrary options and arguments to that command. The command itself also accepts some options, which should be handled by Bundler::Thor.

class_option "verbose",  :type => :boolean
stop_on_unknown_option! :exec
check_unknown_options!  :except => :exec

desc "exec", "Run a shell command"
def exec(*args)
  puts "diagnostic output" if options[:verbose]
  Kernel.exec(*args)
end

Here exec can be called with --verbose to get diagnostic output, e.g.:

$ thor exec --verbose echo foo
diagnostic output
foo

But if --verbose is given after echo, it is passed to echo instead:

$ thor exec echo --verbose foo
--verbose foo

Parameters¶ ↑

Symbol …: A list of commands that should be affected.

# File bundler/vendor/thor/lib/thor.rb, line 325
def stop_on_unknown_option!(*command_names)
  stop_on_unknown_option.merge(command_names)
end

subcommand(subcommand, subcommand_class) click to toggle source

# File bundler/vendor/thor/lib/thor.rb, line 234
def subcommand(subcommand, subcommand_class)
  subcommands << subcommand.to_s
  subcommand_class.subcommand_help subcommand
  subcommand_classes[subcommand.to_s] = subcommand_class

  define_method(subcommand) do |*args|
    args, opts = Bundler::Thor::Arguments.split(args)
    invoke_args = [args, opts, {:invoked_via_subcommand => true, :class_options => options}]
    invoke_args.unshift "help" if opts.delete("--help") || opts.delete("-h")
    invoke subcommand_class, *invoke_args
  end
  subcommand_class.commands.each do |_meth, command|
    command.ancestor_name = subcommand
  end
end

Also aliased as: subtask

subcommand_classes() click to toggle source

# File bundler/vendor/thor/lib/thor.rb, line 230
def subcommand_classes
  @subcommand_classes ||= {}
end

subcommands() click to toggle source

# File bundler/vendor/thor/lib/thor.rb, line 225
def subcommands
  @subcommands ||= from_superclass(:subcommands, [])
end

Also aliased as: subtasks

subtask(subcommand, subcommand_class)

Alias for: subcommand

subtasks()

Alias for: subcommands

task_help(shell, command_name)

Alias for: command_help

Protected Class Methods

banner(command, namespace = nil, subcommand = false) click to toggle source

The banner for this class. You can customize it if you are invoking the thor class by another ways which is not the Bundler::Thor::Runner. It receives the command that is going to be invoked and a boolean which indicates if the namespace should be displayed as arguments.

# File bundler/vendor/thor/lib/thor.rb, line 407
def banner(command, namespace = nil, subcommand = false)
  $thor_runner ||= false
  command.formatted_usage(self, $thor_runner, subcommand).split("\n").map do |formatted_usage|
    "#{basename} #{formatted_usage}"
  end.join("\n")
end

find_command_possibilities(meth) click to toggle source

this is the logic that takes the command name passed in by the user and determines whether it is an unambiguous substrings of a command or alias name.

# File bundler/vendor/thor/lib/thor.rb, line 484
def find_command_possibilities(meth)
  len = meth.to_s.length
  possibilities = all_commands.merge(map).keys.select { |n| meth == n[0, len] }.sort
  unique_possibilities = possibilities.map { |k| map[k] || k }.uniq

  if possibilities.include?(meth)
    [meth]
  elsif unique_possibilities.size == 1
    unique_possibilities
  else
    possibilities
  end
end

Also aliased as: find_task_possibilities

find_task_possibilities(meth)

Alias for: find_command_possibilities

subcommand_help(cmd) click to toggle source

# File bundler/vendor/thor/lib/thor.rb, line 499
    def subcommand_help(cmd)
      desc "help [COMMAND]", "Describe subcommands or one specific subcommand"
      class_eval "
        def help(command = nil, subcommand = true); super; end
"
    end

Also aliased as: subtask_help

subtask_help(cmd)

Alias for: subcommand_help

Public Instance Methods

help(command = nil, subcommand = false) click to toggle source

# File bundler/vendor/thor/lib/thor.rb, line 513
def help(command = nil, subcommand = false)
  if command
    if self.class.subcommands.include? command
      self.class.subcommand_classes[command].help(shell, true)
    else
      self.class.command_help(shell, command)
    end
  else
    self.class.help(shell, subcommand)
  end
end