Class: Commander::Command

### Home Classes Methods

### In Files

- lib/commander/command.rb

### Parent

Object

### Namespace

- CLASS Commander::Command::Options

### Methods

- ::new
- #action
- #example
- #option
- #run
- #when_called

### 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::Command

### Attributes

description[RW]
examples[RW]
name[RW]
options[RW]
proxy_options[RW]
summary[RW]
syntax[RW]

### Public Class Methods

new(name) click to toggle source

Initialize new command with specified name.

    # File lib/commander/command.rb, line 40
    def initialize name
      @name, @examples, @when_called = name.to_s, [], []
      @options, @proxy_options = [], []
    end

### Public Instance Methods

action(*args, &block) click to toggle source
Alias for: when_called
example(description, command) click to toggle source

Add a usage example for this command.

Usage examples are later displayed in help documentation created by the help formatters.

### Examples

    command :something do |c|
      c.example "Should do something", "my_command something"
    end

    # File lib/commander/command.rb, line 58
    def example description, command
      @examples << [description, command]
    end

option(*args, &block) click to toggle source

Add an option.

Options are parsed via OptionParser so view it for additional usage documentation. A block may optionally be passed to handle the option, otherwise the options struct seen below contains the results of this option. This handles common formats such as:

    -h, --help          options.help           # => bool
    --[no-]feature      options.feature        # => bool
    --large-switch      options.large_switch   # => bool
    --file FILE         options.file           # => file passed
    --list WORDS        options.list           # => array
    --date [DATE]       options.date           # => date or nil when optional argument not set

### Examples

    command :something do |c|
      c.option '--recursive', 'Do something recursively'
      c.option '--file FILE', 'Specify a file'
      c.option('--info', 'Display info') { puts "handle with block" }
      c.option '--[no-]feature', 'With or without feature'
      c.option '--list FILES', Array, 'List the files specified'

      c.when_called do |args, options|
        do_something_recursively if options.recursive
        do_something_with_file options.file if options.file
      end
    end

### Help Formatters

This method also parses the arguments passed in order to determine which were switches, and which were descriptions for the option which can later be used within help formatters using option and option.

### Input Parsing

Since Commander utilizes OptionParser you can pre-parse and evaluate option arguments. Simply require 'optparse/time', or 'optparse/date', as these objects must respond to parse.

    c.option '--time TIME', Time
    c.option '--date [DATE]', Date

    # File lib/commander/command.rb, line 109
    def option *args, &block
      switches, description = Runner.separate_switches_from_description(*args)
      proc = block || option_proc(switches)
      @options << {
        :args => args,
        :proc => proc,
        :switches => switches,
        :description => description,
      }
    end

run(*args) click to toggle source

Run the command with args.

- parses options, call option blocks

- invokes when_called proc

    # File lib/commander/command.rb, line 154
    def run *args
      call parse_options_and_call_procs(*args)
    end

when_called(*args, &block) click to toggle source

Handle execution of command. The handler may be a class, object, or block (see examples below).

### Examples

    # Simple block handling
    c.when_called do |args, options|
       # do something
    end

    # Create inst of Something and pass args / options
    c.when_called MyLib::Command::Something

    # Create inst of Something and use arbitrary method
     c.when_called MyLib::Command::Something, :some_method

    # Pass an object to handle callback (requires method symbol)
    c.when_called SomeObject, :some_method

    # File lib/commander/command.rb, line 141
    def when_called *args, &block
      raise ArgumentError, 'must pass an object, class, or block.' if args.empty? and !block
      @when_called = block ? [block] : args
    end

Also aliased as: action

[Validate]

Generated with the Darkfish Rdoc Generator 2.