class Commander::Runner
Attributes
Array
of commands.
Hash of help formatter aliases.
Global options.
Public Class Methods
Return singleton Runner
instance.
# File lib/commander/runner.rb, line 42 def self.instance @singleton ||= new end
Initialize a new command runner. Optionally supplying args for mocking, or arbitrary usage.
# File lib/commander/runner.rb, line 32 def initialize args = ARGV @args, @commands, @aliases, @options = args, {}, {}, [] @help_formatter_aliases = help_formatter_alias_defaults @program = program_defaults create_default_commands end
Public Instance Methods
Add a command object to this runner.
# File lib/commander/runner.rb, line 205 def add_command command @commands[command.name] = command end
Check if command name is an alias.
# File lib/commander/runner.rb, line 212 def alias? name @aliases.include? name.to_s end
Alias command name with alias_name. Optionally args may be passed as if they were being passed straight to the original command via the command-line.
# File lib/commander/runner.rb, line 189 def alias_command alias_name, name, *args @commands[alias_name.to_s] = command name @aliases[alias_name.to_s] = args end
Enable tracing on all executions (bypasses –trace)
# File lib/commander/runner.rb, line 95 def always_trace! @always_trace = true @never_trace = false end
Creates and yields a command instance when a block is passed. Otherwise attempts to return the command, raising InvalidCommandError
when it does not exist.
Examples¶ ↑
command :my_command do |c| c.when_called do |args| # Code end end
# File lib/commander/runner.rb, line 166 def command name, &block yield add_command(Commander::Command.new(name)) if block @commands[name.to_s] end
Check if a command name exists.
# File lib/commander/runner.rb, line 219 def command_exists? name @commands[name.to_s] end
Default command name to be used when no other command is found in the arguments.
# File lib/commander/runner.rb, line 198 def default_command name @default_command = name end
Add a global option; follows the same syntax as Command#option
This would be used for switches such as –version, –trace, etc.
# File lib/commander/runner.rb, line 175 def global_option *args, &block switches, description = Runner.separate_switches_from_description *args @options << { :args => args, :proc => block, :switches => switches, :description => description, } end
Hide the trace option from the help menus and don't add it as a global option
# File lib/commander/runner.rb, line 103 def never_trace! @never_trace = true @always_trace = false end
Assign program information.
Examples¶ ↑
# Set data program :name, 'Commander' program :version, Commander::VERSION program :description, 'Commander utility program.' program :help, 'Copyright', '2008 TJ Holowaychuk' program :help, 'Anything', 'You want' program :int_message 'Bye bye!' program :help_formatter, :compact program :help_formatter, Commander::HelpFormatter::TerminalCompact # Get data program :name # => 'Commander'
Keys¶ ↑
:version (required) Program version triple, ex: '0.0.1' :description (required) Program description :name Program name, defaults to basename of executable :help_formatter Defaults to Commander::HelpFormatter::Terminal :help Allows addition of arbitrary global help blocks :int_message Message to display when interrupted (CTRL + C)
# File lib/commander/runner.rb, line 136 def program key, *args, &block if key == :help and !args.empty? @program[:help] ||= {} @program[:help][args.first] = args.at(1) elsif key == :help_formatter && !args.empty? @program[key] = (@help_formatter_aliases[args.first] || args.first) elsif block @program[key] = block else unless args.empty? @program[key] = (args.count == 1 && args[0]) || args end @program[key] end end
Run command parsing and execution process.
# File lib/commander/runner.rb, line 49 def run! trace = @always_trace || false require_program :version, :description trap('INT') { abort program(:int_message) } if program(:int_message) trap('INT') { program(:int_block).call } if program(:int_block) global_option('-h', '--help', 'Display help documentation') do args = @args - %w[-h --help] command(:help).run(*args) return end global_option('-v', '--version', 'Display version information') { say version; return } global_option('-t', '--trace', 'Display backtrace when an error occurs') { trace = true } unless @never_trace || @always_trace parse_global_options remove_global_options options, @args unless trace begin run_active_command rescue InvalidCommandError => e abort "#{e}. Use --help for more information" rescue \ OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument => e abort e.to_s rescue => e if @never_trace abort "error: #{e}." else abort "error: #{e}. Use --trace to view backtrace" end end else run_active_command end end
Return program version.
# File lib/commander/runner.rb, line 88 def version '%s %s' % [program(:name), program(:version)] end