Class: Thor

### Home Classes Methods

### In Files

- lib/thor.rb
- lib/thor/actions.rb
- lib/thor/actions/create_file.rb
- lib/thor/actions/create_link.rb
- lib/thor/actions/directory.rb
- lib/thor/actions/empty_directory.rb
- lib/thor/actions/file_manipulation.rb
- lib/thor/actions/inject_into_file.rb
- lib/thor/base.rb
- lib/thor/command.rb
- lib/thor/core_ext/hash_with_indifferent_access.rb
- lib/thor/core_ext/ordered_hash.rb
- lib/thor/error.rb
- lib/thor/invocation.rb
- lib/thor/line_editor.rb
- lib/thor/line_editor/basic.rb
- lib/thor/line_editor/readline.rb
- lib/thor/parser/argument.rb
- lib/thor/parser/arguments.rb
- lib/thor/parser/option.rb
- lib/thor/parser/options.rb
- lib/thor/rake_compat.rb
- lib/thor/shell.rb
- lib/thor/shell/basic.rb
- lib/thor/shell/color.rb
- lib/thor/shell/html.rb
- lib/thor/util.rb
- lib/thor/version.rb

### Parent

Object

### Namespace

- MODULE Thor::Actions
- MODULE Thor::Base
- MODULE Thor::Invocation
- MODULE Thor::LineEditor
- MODULE Thor::RakeCompat
- MODULE Thor::Shell
- MODULE Thor::Util
- CLASS Thor::AmbiguousCommandError
- CLASS Thor::Command
- CLASS Thor::DynamicCommand
- CLASS Thor::Error
- CLASS Thor::Group
- CLASS Thor::HiddenCommand
- CLASS Thor::InvocationError
- CLASS Thor::MalformattedArgumentError
- CLASS Thor::RequiredArgumentMissingError
- CLASS Thor::UndefinedCommandError
- CLASS Thor::UnknownArgumentError

### Methods

- ::banner
- ::check_unknown_options!
- ::command_help
- ::default_command
- ::default_task
- ::desc
- ::find_command_possibilities
- ::find_task_possibilities
- ::help
- ::long_desc
- ::map
- ::method_option
- ::method_options
- ::option
- ::options
- ::package_name
- ::printable_commands
- ::printable_tasks
- ::register
- ::stop_on_unknown_option!
- ::subcommand
- ::subcommand_classes
- ::subcommand_help
- ::subcommands
- ::subtask
- ::subtask_help
- ::subtasks
- ::task_help
- #help

### Included Modules

- Thor::Base

### Class/Module Index

Quicksearch

- Thor
- Thor::Actions
- Thor::Actions::ClassMethods
- Thor::AmbiguousCommandError
- Thor::Base
- Thor::Base::ClassMethods
- Thor::Command
- Thor::DynamicCommand
- Thor::Error
- Thor::Group
- Thor::HiddenCommand
- Thor::Invocation
- Thor::Invocation::ClassMethods
- Thor::InvocationError
- Thor::LineEditor
- Thor::LineEditor::Basic
- Thor::LineEditor::Readline
- Thor::LineEditor::Readline::PathCompletion
- Thor::MalformattedArgumentError
- Thor::RakeCompat
- Thor::RequiredArgumentMissingError
- Thor::Shell
- Thor::Shell::Basic
- Thor::Shell::Color
- Thor::Shell::HTML
- Thor::UndefinedCommandError
- Thor::UnknownArgumentError
- Thor::Util
- Object

No matching classes.

# Thor

### Constants

AmbiguousTaskError
DynamicTask
HELP_MAPPINGS

  Shortcuts for help.

HiddenTask
TEMPLATE_EXTNAME
THOR_RESERVED_WORDS

  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/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<Thor::Shell> command_name<String>

    # File 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/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) click to toggle source
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/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<Thor::Shell>

    # File lib/thor.rb, line 188
    def help(shell, subcommand = false)
      list = printable_commands(true, subcommand)
      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/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/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/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/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 = {}) click to toggle source
Alias for: method_option
options(options = nil) click to toggle source
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/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/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) click to toggle source
Alias for: printable_commands
register(klass, subcommand_name, usage, description, options = {}) click to toggle source

Registers another Thor subclass as a command.

#### Parameters

klass<Class> | 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/thor.rb, line 37
    def register(klass, subcommand_name, usage, description, options = {})
      if klass <= 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 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 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/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/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 = 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/thor.rb, line 223
    def subcommand_classes
      @subcommand_classes ||= {}
    end

subcommands() click to toggle source

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

Also aliased as: subtasks
subtask(subcommand, subcommand_class) click to toggle source
Alias for: subcommand
subtasks() click to toggle source
Alias for: subcommands
task_help(shell, command_name) click to toggle source
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 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/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/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) click to toggle source
Alias for: find_command_possibilities
subcommand_help(cmd) click to toggle source

    # File 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) click to toggle source
Alias for: subcommand_help

### Public Instance Methods

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

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.