Class: Thor

Inherits:
Object
  • Object
show all
Includes:
Base
Defined in:
lib/thor.rb,
lib/thor/base.rb,
lib/thor/util.rb,
lib/thor/error.rb,
lib/thor/shell.rb,
lib/thor/actions.rb,
lib/thor/command.rb,
lib/thor/version.rb,
lib/thor/invocation.rb,
lib/thor/shell/html.rb,
lib/thor/line_editor.rb,
lib/thor/rake_compat.rb,
lib/thor/shell/basic.rb,
lib/thor/shell/color.rb,
lib/thor/parser/option.rb,
lib/thor/parser/options.rb,
lib/thor/parser/argument.rb,
lib/thor/parser/arguments.rb,
lib/thor/actions/directory.rb,
lib/thor/line_editor/basic.rb,
lib/thor/actions/create_file.rb,
lib/thor/actions/create_link.rb,
lib/thor/line_editor/readline.rb,
lib/thor/parser/shared_option.rb,
lib/thor/core_ext/ordered_hash.rb,
lib/thor/actions/empty_directory.rb,
lib/thor/actions/inject_into_file.rb,
lib/thor/actions/file_manipulation.rb,
lib/thor/core_ext/hash_with_indifferent_access.rb

Direct Known Subclasses

Runner

Defined Under Namespace

Modules: Actions, Base, CoreExt, Invocation, LineEditor, RakeCompat, Sandbox, Shell, Util Classes: AmbiguousCommandError, Argument, Arguments, Command, ConflictingArgumentError, DynamicCommand, Error, Execution, Group, HiddenCommand, InvocationError, MalformattedArgumentError, Option, Options, ProhibitedArgumentError, RequiredArgumentMissingError, Runner, SharedOption, UndefinedCommandError, UnknownArgumentError

Constant Summary collapse

HELP_MAPPINGS =

Shortcuts for help.

%w(-h -? --help -D)
THOR_RESERVED_WORDS =

Thor methods that should not be overwritten by the user.

%w(invoke shell options behavior root destination_root
relative_root action add_file create_file in_root
inside run run_ruby_script)
TEMPLATE_EXTNAME = 
".tt"
UndefinedTaskError = 
UndefinedCommandError
AmbiguousTaskError = 
AmbiguousCommandError
Task = 
Command
HiddenTask = 
HiddenCommand
DynamicTask = 
DynamicCommand
ROOT =

Absolute, expanded path to the gem’s root directory.

Returns:

  • (Pathname) 
Pathname.new( __dir__ ).join( '..', '..' ).expand_path
VERSION =

Gem version string.

See versioning for details.

Returns:

  • (String) 
'0.1.3'
THOR_VERSION =

The version of Thor that Atli is up to date with.

Right now, it’s the version of Thor that was forked, but if I’m able to merge Thor updates in and end up doing so, I intend to update this to reflect it.

See versioning for details.

Returns:

  • (String) 
'0.1.3'

Instance Attribute Summary

Attributes included from Base

#args, #options, #parent_options

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Base

included, #initialize, #on_run_error, register_klass_file, subclass_files, subclasses

Class Method Details

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.

Parameters:

  • command (Thor::Command) —

    The command to render the banner for.

  • namespace (nil | ?) (defaults to: nil) —

    Atli: this argument is not used at all. I don’t know what it could or should be, but it doesn’t seem like it matters at all :/

  • subcommand (Boolean) (defaults to: false) —

    Should be true if the command was invoked as a sub-command; passed on to Thor::Command#formatted_usage so it can render correctly.

Returns:

  • (String) —

    The banner for the command.



616
617
618
 
# File 'lib/thor.rb', line 616

def banner(command, namespace = nil, subcommand = false)
  "#{basename} #{command.formatted_usage(self, $thor_runner, subcommand)}"
end

.baseclass ⇒ Object (protected)

:nodoc:



621
622
623
 
# File 'lib/thor.rb', line 621

def baseclass #:nodoc:
  Thor
end

.build_shared_option(name, options) ⇒ Object (protected)

Build a Thor::SharedOption and add it to Thor.shared_method_options.

The Thor::SharedOption is returned.

Parameters

name<Symbol>

The name of the argument.

options<Hash>

Described in both class_option and method_option, with the additional ‘:groups` shared option keyword.



760
761
762
763
764
765
 
# File 'lib/thor.rb', line 760

def build_shared_option(name, options)
  shared_method_options[name] = Thor::SharedOption.new(
    name,
    options.merge(:check_default_type => check_default_type?)
  )
end

.check_unknown_options!(options = {}) ⇒ Object

Extend check unknown options to accept a hash of conditions.

Parameters

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



284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/thor.rb', line 284

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

.check_unknown_options?(config) ⇒ Boolean

Overwrite check_unknown_options? to take subcommands and options into account.

Returns:

  • (Boolean) 


298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/thor.rb', line 298

def check_unknown_options?(config) #:nodoc:
  options = check_unknown_options
  return false unless options

  command = config[:current_command]
  return true unless command

  name = command.name

  if subcommands.include?(name)
    false
  elsif options[:except]
    !options[:except].include?(name.to_sym)
  elsif options[:only]
    options[:only].include?(name.to_sym)
  else
    true
  end
end

.command_help(shell, command_name, subcommand = false) ⇒ void Also known as: task_help

This method returns an undefined value.

Prints help information for the given command.

Parameters:

  • shell (Thor::Shell)
  • command_name (String)
  • subcommand (Boolean) (defaults to: false) —

    Alti addition - passed from #help when that command is being invoked as a subcommand.

    The values is passed through to banner and eventually Thor::Command#formatted_usage so that it can properly display the usage message

    basename subcmd cmd ARGS...

    versus what it did when I found it:

    basename cmd ARGS...

    which, of course, doesn’t work if cmd is inside subcmd.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/thor.rb', line 196

def command_help(shell, command_name, subcommand = false)
  meth = normalize_command_name(command_name)
  command = all_commands[meth]
  handle_no_command_error(meth) unless command

  shell.say "Usage:"
  shell.say "  #{banner(command, nil, subcommand)}"
  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

.create_command(meth) ⇒ Object (protected) Also known as: create_task

:nodoc:



629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
 
# File 'lib/thor.rb', line 629

def create_command(meth) #:nodoc:
  @usage ||= nil
  @desc ||= nil
  @long_desc ||= nil
  @hide ||= nil

  if @usage && @desc
    base_class = @hide ? Thor::HiddenCommand : Thor::Command
    commands[meth] = base_class.new(
      meth,
      @desc,
      @long_desc,
      @usage,
      method_options
    )
    @usage, @desc, @long_desc, @method_options, @hide = nil
    true
  elsif all_commands[meth] || meth == "method_missing"
    true
  else
    puts "[WARNING] Attempted to create command #{meth.inspect} without usage or description. " \
         "Call desc if you want this method to be available as command or declare it inside a " \
         "no_commands{} block. Invoked from #{caller[1].inspect}."
    false
  end
end

.default_command(meth = nil) ⇒ Object Also known as: default_task

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

Parameters

meth<Symbol>

name of the default command



27
28
29
30
31
32
33
 
# File 'lib/thor.rb', line 27

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

.desc(usage, description, options = {}) ⇒ Object

Defines the usage and the description of the next command.

Parameters

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



60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/thor.rb', line 60

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

help command has the required check disabled by default.



555
556
557
 
# File 'lib/thor.rb', line 555

def disable_required_check #:nodoc:
  @disable_required_check ||= Set.new([:help])
end

.disable_required_check!(*command_names) ⇒ Object

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.



369
370
371
 
# File 'lib/thor.rb', line 369

def disable_required_check!(*command_names)
  disable_required_check.merge(command_names)
end

.disable_required_check?(command) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


373
374
375
 
# File 'lib/thor.rb', line 373

def disable_required_check?(command) #:nodoc:
  command && disable_required_check.include?(command.name.to_sym)
end

.dispatch(meth, given_args, given_opts, config) {|instance| ... } ⇒ Object (protected)

The method responsible for dispatching given the args.

Yields:

  • (instance) 


560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
 
# File 'lib/thor.rb', line 560

def dispatch(meth, given_args, given_opts, config) #:nodoc: # rubocop:disable MethodLength
  meth ||= retrieve_command_name(given_args)
  command = all_commands[normalize_command_name(meth)]

  if !command && config[:invoked_via_subcommand]
    # We're a subcommand and our first argument didn't match any of our
    # commands. So we put it back and call our default command.
    given_args.unshift(meth)
    command = all_commands[normalize_command_name(default_command)]
  end

  if command
    args, opts = Thor::Options.split(given_args)
    if stop_on_unknown_option?(command) && !args.empty?
      # given_args starts with a non-option, so we treat everything as
      # ordinary arguments
      args.concat opts
      opts.clear
    end
  else
    args = given_args
    opts = nil
    command = dynamic_command_class.new(meth)
  end

  opts = given_opts || opts || []
  config[:current_command] = command
  config[:command_options] = command.options

  instance = new(args, opts, config)
  yield instance if block_given?
  args = instance.args
  trailing = args[Range.new(arguments.size, -1)]
  instance.invoke_command(command, trailing || [])
end

.dynamic_command_class ⇒ Object (protected)

:nodoc:



625
626
627
 
# File 'lib/thor.rb', line 625

def dynamic_command_class #:nodoc:
  Thor::DynamicCommand
end

.find_command_possibilities(meth) ⇒ Object (protected) Also known as: find_task_possibilities

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.



701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
 
# File 'lib/thor.rb', line 701

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

.find_shared_method_options(*names, groups: nil) ⇒ Hash<Symbol, Thor::SharedOption> Also known as: find_shared_options

Find shared options given names and groups.

Parameters:

  • names (*<Symbol>) —

    Individual shared option names to include.

  • groups: (nil | Symbol | Enumerable<Symbol>) (defaults to: nil) —

    Single or list of shared option groups to include.

Returns:

  • (Hash<Symbol, Thor::SharedOption>) —

    Hash mapping option names (as Symbol) to instances.



416
417
418
419
420
421
422
423
 
# File 'lib/thor.rb', line 416

def find_shared_method_options *names, groups: nil
  groups_set = Set[*groups]
  
  shared_method_options.
    select { |name, option|
      names.include?( name ) || !(option.groups & groups_set).empty?
    }
end

.help(shell, subcommand = false) ⇒ Object

Prints help information for this class.

Parameters

shell<Thor::Shell>



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/thor.rb', line 219

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

.include_method_options(*names, groups: nil) ⇒ Hash<Symbol, Thor::SharedOption> Also known as: include_options

Add the SharedOption instances with names and in groups to the next defined command method.

Parameters:

  • names (*<Symbol>) —

    Individual shared option names to include.

  • groups: (nil | Symbol | Enumerable<Symbol>) (defaults to: nil) —

    Single or list of shared option groups to include.

Returns:

  • (Hash<Symbol, Thor::SharedOption>) —

    Hash mapping option names (as Symbol) to instances.



535
536
537
538
539
540
 
# File 'lib/thor.rb', line 535

def include_method_options *names, groups: nil
  find_shared_method_options( *names, groups: groups ).
    each do |name, option|
      method_options[name] = option
    end
end

.initialize_added ⇒ Object (protected)

:nodoc:



657
658
659
660
 
# File 'lib/thor.rb', line 657

def initialize_added #:nodoc:
  class_options.merge!(method_options)
  @method_options = nil
end

.long_desc(long_description, options = {}) ⇒ Object

Defines the long description of the next command.

Parameters

long description<String>



77
78
79
80
81
82
83
84
 
# File 'lib/thor.rb', line 77

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

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.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/thor.rb', line 100

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 = {}) ⇒ Object Also known as: option

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.



159
160
161
162
163
164
165
166
167
 
# File 'lib/thor.rb', line 159

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

.method_options(options = nil) ⇒ Object Also known as: options

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.



123
124
125
126
127
 
# File 'lib/thor.rb', line 123

def method_options(options = nil)
  @method_options ||= {}
  build_options(options, @method_options) if options
  @method_options
end

.normalize_command_name(meth) ⇒ Object (protected) Also known as: normalize_task_name

receives a (possibly nil) command name and returns a name that is in the commands hash. In addition to normalizing aliases, this logic will determine if a shortened command is an unambiguous substring of a command or alias.

normalize_command_name also converts names like animal-prison into animal_prison.



676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
 
# File 'lib/thor.rb', line 676

def normalize_command_name(meth) #:nodoc:
  return default_command.to_s.tr("-", "_") unless meth

  possibilities = find_command_possibilities(meth)
  
  if possibilities.size > 1
    raise AmbiguousTaskError,
      "Ambiguous command #{meth} matches [#{possibilities.join(', ')}]"
  end

  if possibilities.empty?
    meth ||= default_command
  elsif map[meth]
    meth = map[meth]
  else
    meth = possibilities.first
  end

  meth.to_s.tr("-", "_") # treat foo-bar as foo_bar
end

.package_name(name, _ = {}) ⇒ Object

Allows for custom “Command” package naming.

Parameters

name<String> options<Hash>



17
18
19
 
# File 'lib/thor.rb', line 17

def package_name(name, _ = {})
  @package_name = name.nil? || name == "" ? nil : name
end

.printable_commands(all = true, subcommand = false) ⇒ Object Also known as: printable_tasks

Returns commands ready to be printed.



238
239
240
241
242
243
244
245
246
247
 
# File 'lib/thor.rb', line 238

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

.register(klass, subcommand_name, usage, description, options = {}) ⇒ Object

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



43
44
45
46
47
48
49
50
51
 
# File 'lib/thor.rb', line 43

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

.retrieve_command_name(args) ⇒ Object (protected) Also known as: retrieve_task_name

Retrieve the command name from given args.



663
664
665
666
 
# File 'lib/thor.rb', line 663

def retrieve_command_name(args) #:nodoc:
  meth = args.first.to_s unless args.empty?
  args.shift if meth && (map[meth] || meth !~ /^\-/)
end

.shared_method_option(name, **options) ⇒ Object Also known as: shared_option

Declare a shared method option with an optional groups that can then be added by name or group to commands.

The shared options can then be added to methods individually by name and collectively as groups with include_method_options.

Examples:

class MyCLI < Thor

  # Declare a shared option:
  shared_option :force,
    groups: :write,
    desc: "Force the operation",
    type: :boolean

  # ...

  desc            "write [OPTIONS] path",
                  "Write to a path"

  # Add the shared options to the method:
  include_options groups: :write

  def write       path

    # Get a slice of `#options` with any of the `:write` group options
    # that were provided and use it in a method call:
    MyModule.write path, **option_kwds( groups: :write )

  end
end

Parameters:

  • name (Symbol) —

    The name of the option.

  • options (**<Symbol, V>) —

    Keyword args used to initialize the SharedOption.

    All **options are optional.

Options Hash (**options):

  • :groups (Symbol | Array<Symbol>) —

    One or more shared option group that the new option will belong to.

    Examples:

    groups: :read
groups: [:read, :write]

    NOTE The keyword is groups with an s! Option already has

    a +group+ string attribute that, as far as I can tell, is only
  • :desc (String) —

    Description for the option for help and feedback.

  • :required (Boolean) —

    If the option is required or not.

  • :default (Object) —

    Default value for this argument.

    It cannot be required and have default values.

  • :aliases (String | Array<String>) —

    Aliases for this option.

    Examples:

    aliases: '-s'
aliases: '--other-name'
aliases: ['-s', '--other-name']
  • :type (:string | :hash | :array | :numeric | :boolean) —

    Type of acceptable values, see types for method options in the Thor wiki.

  • :banner (String) —

    String to show on usage notes.

  • :hide (Boolean) —

    If you want to hide this option from the help.



512
513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/thor.rb', line 512

def shared_method_option name, **options
  # Don't think the `:for` option makes sense... that would just be a
  # regular method option, right? I guess `:for` could be an array and
  # apply the option to each command, but it seems like that would just
  # be better as an extension to the {.method_option} behavior.
  # 
  # So, we raise if we see it
  if options.key? :for
    raise ArgumentError,
      ".shared_method_option does not accept the `:for` option"
  end
  
  build_shared_option(name, options)
end

.shared_method_options(options = nil) ⇒ Hash<Symbol, Thor::SharedOption] Get all shared options Also known as: shared_options

Returns Hash<Symbol, Thor::SharedOption] Get all shared options.

Returns:



383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/thor.rb', line 383

def shared_method_options(options = nil)
  @shared_method_options ||= begin
    # Reach up the inheritance chain, if there's anyone there
    if superclass.respond_to? __method__
      superclass.send( __method__ ).dup
    else
      # Or just default to empty
      {}
    end
  end
  
  if options
    # We don't support this (yet at least)
    raise NotImplementedError,
      "Bulk set not supported, use .shared_method_option"
    # build_shared_options(options, @shared_method_options)
  end
  @shared_method_options
end

.stop_on_unknown_option ⇒ Object (protected) 



550
551
552
 
# File 'lib/thor.rb', line 550

def stop_on_unknown_option #:nodoc:
  @stop_on_unknown_option ||= Set.new
end

.stop_on_unknown_option!(*command_names) ⇒ Object

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.



355
356
357
 
# File 'lib/thor.rb', line 355

def stop_on_unknown_option!(*command_names)
  stop_on_unknown_option.merge(command_names)
end

.stop_on_unknown_option?(command) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


359
360
361
 
# File 'lib/thor.rb', line 359

def stop_on_unknown_option?(command) #:nodoc:
  command && stop_on_unknown_option.include?(command.name.to_sym)
end

.subcommand(subcommand, subcommand_class) ⇒ Object Also known as: subtask 



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/thor.rb', line 259

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

.subcommand_classes ⇒ Object 



255
256
257
 
# File 'lib/thor.rb', line 255

def subcommand_classes
  @subcommand_classes ||= {}
end

.subcommand_help(cmd) ⇒ Object (protected) Also known as: subtask_help 



718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
 
# File 'lib/thor.rb', line 718

def subcommand_help(cmd)
  logger.trace __method__.to_s,
    cmd: cmd,
    caller: caller
  
  desc "help [COMMAND]", "Describe subcommands or one specific subcommand"
  
  # Atli -  This used to be {#class_eval} (maybe to support really old
  #         Rubies? Who knows...) but that made it really hard to find in
  #         stack traces, so I switched it to {#define_method}.
  # 
  define_method :help do |*args|
    
    # Add the `is_subcommand = true` trailing arg
    case args[-1]
    when true
      # pass
    when false
      # Weird, `false` was explicitly passed... whatever, set it to `true`
      args[-1] = true
    else
      # "Normal" case, append it
      args << true
    end
    
    super( *args )
  end
  
end

.subcommands ⇒ Object Also known as: subtasks 



250
251
252
 
# File 'lib/thor.rb', line 250

def subcommands
  @subcommands ||= from_superclass(:subcommands, [])
end

Instance Method Details

#help(*args) ⇒ Object 



812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
 
# File 'lib/thor.rb', line 812

def help(*args)
  is_subcommand = case args[-1]
  when true, false
    args.pop
  else
    false
  end
  
  # Will be the {String} command (get help on that command)
  # or `nil` (get help on this class)
  command = args.shift
  
  # Possibly empty array of string subcommands from something like
  # 
  #     myexe help sub cmd
  # 
  # in which case it would end up being `['cmd']` and we actually are just
  # passing through and want to get help on the `cmd` subcommand.
  # 
  subcommands = args
  
  logger.trace "#help",
    args: args,
    command: command,
    is_subcommand: is_subcommand,
    subcommands: subcommands
  
  if command
    if self.class.subcommands.include? command
      if subcommands.empty?
        # Get help on a subcommand *class*
        self.class.subcommand_classes[command].help(shell, true)
      else
        # Atli addition - handle things like `myexe help sub cmd`
        # Want help on something (class or command) further down the line
        invoke  self.class.subcommand_classes[command],
                ['help', *subcommands],
                {},
                {:invoked_via_subcommand => true, :class_options => options}
      end
    else
      # Want help on a *command* of this class
      # 
      # Atli -  Now that we've modified {.command_help} to accept
      #         `subcommand`, pass it (it seems to have already been getting
      #         the correct value to here).
      self.class.command_help(shell, command, is_subcommand)
    end
  else
    # We want help on *this class itself* (list available commands)
    self.class.help(shell, is_subcommand)
  end
end

#option_kwds(*names, groups: nil) ⇒ Hash<Symbol, V> (protected)

Get a Hash mapping option name symbols to their values ready for ** usage in a method call for the option names and shared option groups.

Parameters:

  • names (*<Symbol>) —

    Individual shared option names to include.

  • groups: (nil | Symbol | Enumerable<Symbol>) (defaults to: nil) —

    Single or list of shared option groups to include.

Returns:

  • (Hash<Symbol, V>) —

    Map of option name to value.



784
785
786
787
788
789
790
791
792
793
794
795
796
 
# File 'lib/thor.rb', line 784

def option_kwds *names, groups: nil
  # Transform names into a set of strings
  name_set = Set.new names.map( &:to_s )
  
  # Add groups (if any)
  if groups
    self.class.find_shared_options( groups: groups ).each do |name, option|
      name_set << name.to_s
    end
  end
  
  options.slice( *name_set ).sym_keys
end