Shortcuts for help.
Thor methods that should not be overwritten by the user.
Extend check unknown options to accept a hash of conditions.
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
Prints help information for the given command.
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
Sets the default command when thor is executed without an explicit command to be called.
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
Defines the usage and the description of the next command.
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
Prints help information for this class.
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
Defines the long description of the next command.
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
Maps an input to a command. If you define:
map "-T" => "list"
Running:
thor -T
Will invoke the list command.
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
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
name<Symbol> |
The name of the argument. |
options<Hash> |
Described below. |
: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
Declares the options for the next command to be declared.
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
Allows for custom “Command” package naming.
name<String> options<Hash>
# File lib/thor.rb, line 12 def package_name(name, options = {}) @package_name = name.nil? || name == "" ? nil : name end
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
Registers another Thor subclass as a command.
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 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.
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
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
# 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
# File lib/thor.rb, line 223 def subcommand_classes @subcommand_classes ||= {} end
# File lib/thor.rb, line 218 def subcommands @subcommands ||= from_superclass(:subcommands, []) end
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
# 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
# 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
Generated with the Darkfish Rdoc Generator 2.