class Commander::Runner

Attributes

commands[R]

Array of commands.

help_formatter_aliases[R]

Hash of help formatter aliases.

options[R]

Global options.

Public Class Methods

instance() click to toggle source

Return singleton Runner instance.

# File lib/commander/runner.rb, line 43
def self.instance
  @singleton ||= new
end
new(args = ARGV) click to toggle source

Initialize a new command runner. Optionally supplying args for mocking, or arbitrary usage.

# File lib/commander/runner.rb, line 33
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_command(command) click to toggle source

Add a command object to this runner.

# File lib/commander/runner.rb, line 186
def add_command command
  @commands[command.name] = command
end
alias?(name) click to toggle source

Check if command name is an alias.

# File lib/commander/runner.rb, line 193
def alias? name
  @aliases.include? name.to_s
end
alias_command(alias_name, name, *args) click to toggle source

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 170
def alias_command alias_name, name, *args
  @commands[alias_name.to_s] = command name
  @aliases[alias_name.to_s] = args
end
command(name) { |add_command(command)| ... } click to toggle source

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 147
def command name, &block
  yield add_command(Commander::Command.new(name)) if block
  @commands[name.to_s]
end
command_exists?(name) click to toggle source

Check if a command name exists.

# File lib/commander/runner.rb, line 200
def command_exists? name
  @commands[name.to_s]
end
default_command(name) click to toggle source

Default command name to be used when no other command is found in the arguments.

# File lib/commander/runner.rb, line 179
def default_command name
  @default_command = name
end
global_option(*args, &block) click to toggle source

Add a global option; follows the same syntax as Commander::Command#option This would be used for switches such as –version, –trace, etc.

# File lib/commander/runner.rb, line 156
def global_option *args, &block
  switches, description = Runner.separate_switches_from_description *args
  @options << {
    :args => args,
    :proc => block,
    :switches => switches,
    :description => description,
  }
end
program(key, *args, &block) click to toggle source

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 117
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!() click to toggle source

Run command parsing and execution process.

# File lib/commander/runner.rb, line 50
def run!
  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 }
  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
      abort "error: #{e}. Use --trace to view backtrace"
    end
  else
    run_active_command
  end
end
version() click to toggle source

Return program version.

# File lib/commander/runner.rb, line 85
def version
  '%s %s' % [program(:name), program(:version)]
end