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 241 def check_unknown_options!(options={}) @check_unknown_options ||= Hash.new 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 168 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) @default_command = case meth when :none 'help' when nil @default_command || from_superclass(:default_command, 'help') else meth.to_s end end
Defines the usage and the description of the next command.
usage<String> description<String> options<String>
# File lib/thor.rb, line 57 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 191 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 @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 72 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 94 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 151 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 117 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 210 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 40 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 311 def stop_on_unknown_option!(*command_names) @stop_on_unknown_option ||= Set.new @stop_on_unknown_option.merge(command_names) end
# File lib/thor.rb, line 226 def subcommand(subcommand, subcommand_class) self.subcommands << subcommand.to_s subcommand_class.subcommand_help subcommand define_method(subcommand) do |*args| args, opts = Thor::Arguments.split(args) invoke subcommand_class, args, opts, :invoked_via_subcommand => true, :class_options => options end end
# File lib/thor.rb, line 221 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 440 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 455 def subcommand_help(cmd) desc "help [COMMAND]", "Describe subcommands or one specific subcommand" class_eval def help(command = nil, subcommand = true); super; end end
Generated with the Darkfish Rdoc Generator 2.