class SimpleCommander::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/simple_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/simple_commander/runner.rb, line 31
def initialize(args = ARGV)
  @args, @commands, @aliases, @options = args, {}, {}, []
  @help_formatter_aliases = help_formatter_alias_defaults
  @program = program_defaults
  @always_trace = false
  @never_trace = false
  create_default_commands
end

Public Instance Methods

add_command(command) click to toggle source

Add a command object to this runner.

# File lib/simple_commander/runner.rb, line 233
def add_command(command)
  @commands[command.name] = command
end

alias?(name) click to toggle source

Check if command name is an alias.

# File lib/simple_commander/runner.rb, line 240
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/simple_commander/runner.rb, line 217
def alias_command(alias_name, name, *args)
  @commands[alias_name.to_s] = command name
  @aliases[alias_name.to_s] = args
end

always_trace!() click to toggle source

Enable tracing on all executions (bypasses –trace)

# File lib/simple_commander/runner.rb, line 119
def always_trace!
  @always_trace = true
  @never_trace = false
end

command(name, &block) 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/simple_commander/runner.rb, line 190
def command(name, &block)
                    SimpleCommander::Command.new(name).tap do |cmd|
                            add_command(cmd) if block
                            cmd.super_self = self
                            cmd.instance_eval &block if block
                    end
                    @commands[name.to_s]
end

command_exists?(name) click to toggle source

Check if a command name exists.

# File lib/simple_commander/runner.rb, line 247
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/simple_commander/runner.rb, line 226
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 SimpleCommander::Command#option This would be used for switches such as –version, –trace, etc.

# File lib/simple_commander/runner.rb, line 203
def global_option(*args, &block)
  switches, description = Runner.separate_switches_from_description(*args)
  @options << {
    args: args,
    proc: block,
    switches: switches,
    description: description,
  }
end

goto_child_command() click to toggle source

make the child command the active_command and remove the current command from the @args

# File lib/simple_commander/runner.rb, line 102
def goto_child_command 
        @args.shift
        @__active_command = nil
        @__command_name_from_args = nil
        have_action?
end

have_action?() click to toggle source

tests if the current active command have an action block

# File lib/simple_commander/runner.rb, line 93
def have_action?
        require_valid_command
        goto_child_command if active_command.has_no_action?
end

never_trace!() click to toggle source

Hide the trace option from the help menus and don't add it as a global option

# File lib/simple_commander/runner.rb, line 127
def never_trace!
  @never_trace = true
  @always_trace = false
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/simple_commander/runner.rb, line 160
def program(key, *args, &block)
  if key == :help && !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/simple_commander/runner.rb, line 50
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') do
    say version
    return
  end
  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
  if trace
    run_active_command
  else
    begin
                                    have_action?
      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
  end
end

version() click to toggle source

Return program version.

# File lib/simple_commander/runner.rb, line 112
def version
  format('%s %s', program(:name), program(:version))
end