class Bundler::Thor - bundler-1.9.9 Documentation

# class Bundler::Thor

### Constants

AmbiguousTaskError
DynamicTask
HELP_MAPPINGS

  Shortcuts for help.

HiddenTask
TEMPLATE_EXTNAME
THOR_RESERVED_WORDS

  Bundler::Thor methods that should not be overwritten by the user.

Task
UndefinedTaskError
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 lib/bundler/vendor/thor/lib/thor.rb, line 244
    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 lib/bundler/vendor/thor/lib/thor.rb, line 165
    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)}"
      shell.say
      class_options_help(shell, nil => command.options.map { |_, o| o })
      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 lib/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 lib/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, @desc, @hide = usage, description, options[:hide] || false
      end
    end

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

Prints help information for this class.

#### Parameters¶ ↑

shell<Bundler::Thor::Shell>

    # File lib/bundler/vendor/thor/lib/thor.rb, line 188
    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 lib/bundler/vendor/thor/lib/thor.rb, line 69
    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) 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 lib/bundler/vendor/thor/lib/thor.rb, line 91
    def map(mappings = nil)
      @map ||= from_superclass(:map, {})

      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 lib/bundler/vendor/thor/lib/thor.rb, line 148
    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 lib/bundler/vendor/thor/lib/thor.rb, line 114
    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, options = {}) click to toggle source

Allows for custom “Command” package naming.

### Parameters¶ ↑

name<String> options<Hash>

    # File lib/bundler/vendor/thor/lib/thor.rb, line 12
    def package_name(name, options = {})
      @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 lib/bundler/vendor/thor/lib/thor.rb, line 207
    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
register(klass, subcommand_name, usage, description, options = {}) click to toggle source

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 lib/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 lib/bundler/vendor/thor/lib/thor.rb, line 314
    def stop_on_unknown_option!(*command_names)
      stop_on_unknown_option.merge(command_names)
    end

subcommand(subcommand, subcommand_class) click to toggle source

    # File lib/bundler/vendor/thor/lib/thor.rb, line 227
    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)
        args.unshift("help") if opts.include? "--help" or opts.include? "-h"
        invoke subcommand_class, args, opts, :invoked_via_subcommand => true, :class_options => options
      end
    end

Also aliased as: subtask
subcommand_classes() click to toggle source

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

subcommands() click to toggle source

    # File lib/bundler/vendor/thor/lib/thor.rb, line 218
    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 lib/bundler/vendor/thor/lib/thor.rb, line 367
    def banner(command, namespace = nil, subcommand = false)
      "#{basename} #{command.formatted_usage(self, $thor_runner, subcommand)}"
    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 lib/bundler/vendor/thor/lib/thor.rb, line 444
    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 lib/bundler/vendor/thor/lib/thor.rb, line 459
        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 lib/bundler/vendor/thor/lib/thor.rb, line 473
    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