class Ordu

A little class for building command-line programs. Based on OptionParser.

You define a subclass of Ordu with the `option`, `command` and `action` directives. `option` looks a lot like `OptionParser#on`, but can also accept a Symbol or a String (allowing you to specify an instance method as the option handler). `command` takes a block which is used as the body of the command (or, again, a String/Symbol, or an Ordu class). `action` is another block (or Symbol/String) which is executed if no subcommands are run.

When the class is defined, these options, commands and action are simply remembered. Then when the class is initialized, the instance is created and the options applied.

When `parse!` is called, the command-line switches are parsed. The next leftover argument is checked to see if it is a command. If so, then that command is built into an Ordu, and `parse!`ed with the next arguments. Everything left is passed into the `action` method (which instance_execs the block specified in the class definition).

Public Class Methods

new(options: nil, commands: nil, action: nil) click to toggle source

Make a new Ordu instance. It will be set up with the options, commands and action specified in its class definition.

Calls superclass method

# File lib/ordu.rb, line 23
def initialize(options: nil, commands: nil, action: nil)
  super()
  options ||= self.class.options
  commands ||= self.class.commands
  action ||= self.class.action
  options.each { |o| option!(*o) }
  commands.each { |c| command!(*c) }
  on_tail(command_summary) if command_summary
  @action = action
end

parse!(args) click to toggle source

Parses a new instance. Note that this must be the top-level, since you can't supply a name. This is convenient for starting the parser from scripts.

# File lib/ordu.rb, line 56
def self.parse!(args)
  new.parse!(args)
end

Private Class Methods

action(&block) click to toggle source

Defines the action to be run once parsing is finished.

# File lib/ordu.rb, line 130
def self.action(&block)
  @action = block if block_given?
  @action ||= lambda { |*args| }
end

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

Defines a new command for instances of this Ordu class. The block will be pushed in as the last element of the command array.

# File lib/ordu.rb, line 119
def self.command(*args, &block)
  args.push(block) if block_given?
  commands.push(args)
end

commands() click to toggle source

An array of the commands available to instances of this Ordu class.

# File lib/ordu.rb, line 125
def self.commands
  @commands ||= []
end

desc(desc = nil) click to toggle source

# File lib/ordu.rb, line 75
def self.desc(desc = nil)
  @desc = desc if desc
  @desc if instance_variable_defined?(:@desc)
end

name(name = nil) click to toggle source

# File lib/ordu.rb, line 70
def self.name(name = nil)
  @name = name if name
  @name if instance_variable_defined?(:@name)
end

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

Defines a new option for instances of this Ordu class.

# File lib/ordu.rb, line 107
def self.option(*args, &block)
  args.push(block) if block_given?
  options.push(args)
end

options() click to toggle source

An array of the options to be applied

# File lib/ordu.rb, line 113
def self.options
  @options ||= []
end

Public Instance Methods

command_summary() click to toggle source

A string which summarizes the commands - shown in the help

# File lib/ordu.rb, line 45
def command_summary
  return if commands.empty?
  w = commands.keys.map(&:length).max
  lines = ['Available commands:']
  lines += commands.map { |k, v| "    %-#{w}s     %s" % [k, v.desc] }
  lines.join("\n")
end

parse!(args) click to toggle source

Parse options in order, and call commands for non-option arguments (if the command exists). This is how programs are exected.

# File lib/ordu.rb, line 36
def parse!(args)
  args = order!(args)
  unless args.empty?
    return commands[args.shift].parse!(args) if commands.key?(args.first)
  end
  run(*args)
end

Private Instance Methods

command!(name, desc, block) click to toggle source

Applies a new command (i.e., a new Ordu which may be run if the command is given). name and desc are set on the new class.

# File lib/ordu.rb, line 99
def command!(name, desc, block)
  command = Class.new(self.class, &block)
  command.name [program_name, name].join(' ')
  command.desc desc
  commands[name] = command
end

commands() click to toggle source

Gets the hash of subcommands

# File lib/ordu.rb, line 86
def commands
  @commands ||= {}
end

name() click to toggle source

# File lib/ordu.rb, line 66
def name
  @name ||= self.class.name
end

option!(*args) click to toggle source

Applies a new option (using OptionParser#on). The last argument must be a block, and will be instance_exec'ed in this instance.

# File lib/ordu.rb, line 92
def option!(*args)
  b = args.pop
  on(*args) { |*x| instance_exec(*x, &b) }
end

program_name() click to toggle source

Calls superclass method

# File lib/ordu.rb, line 62
def program_name
  name || super
end

run(*args) click to toggle source

Runs the action for this Ordu instance.

# File lib/ordu.rb, line 81
def run(*args)
  return instance_exec(*args, &@action) if @action
end