Class: Commander::Runner

### Home Classes Methods

### In Files

- lib/commander/runner.rb

### Parent

Object

### Namespace

- CLASS Commander::Runner::CommandError
- CLASS Commander::Runner::InvalidCommandError

### Methods

- ::instance
- ::new
- #add_command
- #alias?
- #alias_command
- #command
- #command_exists?
- #default_command
- #global_option
- #program
- #run!
- #version

### Class/Module Index

Quicksearch

- Commander
- Commander::Command
- Commander::Command::Options
- Commander::Delegates
- Commander::HelpFormatter
- Commander::HelpFormatter::Base
- Commander::HelpFormatter::Terminal
- Commander::HelpFormatter::TerminalCompact
- Commander::Platform
- Commander::Runner
- Commander::Runner::CommandError
- Commander::Runner::InvalidCommandError
- Commander::UI
- Commander::UI::AskForClass
- Commander::UI::ProgressBar
- Array
- Blank
- Object

No matching classes.

# 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, &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/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 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 - ]-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

[Validate]

Generated with the Darkfish Rdoc Generator 2.