class RProgram::Task

Public Class Methods

arguments(options={},&block) click to toggle source

Creates a new Task object, then formats command-line arguments using the Task object.

@param [Hash{Symbol => Object}] options

Additional task options.

@yield [task]

If a block is given, it will be passed the newly created task.

@yieldparam [Task] task

The newly created Task object.

@return [Array]

The formatted arguments from a Task object.

@example

MyTask.arguments(:verbose => true, :count => 2)
# => [...]

@example

MyTask.arguments do |task|
  task.verbose = true
  task.file = 'output.txt'
end
# => [...]
# File lib/rprogram/task.rb, line 169
def self.arguments(options={},&block)
  self.new(options,&block).arguments
end
get_non_option(name) click to toggle source

Searches for the non-option with the matching name in the class and it's ancestors.

@param [Symbol, String] name

The name to search for.

@return [NonOption]

The non-option with the matching name.
# File lib/rprogram/task.rb, line 76
def self.get_non_option(name)
  name = name.to_sym

  ancestors.each do |base|
    if base < RProgram::Task
      if base.non_options.has_key?(name)
        return base.non_options[name]
      end
    end
  end

  return nil
end
get_option(name) click to toggle source

Searches for the option with the matching name in the class and it's ancestors.

@param [Symbol, String] name

The name to search for.

@return [Option]

The option with the matching name.
# File lib/rprogram/task.rb, line 130
def self.get_option(name)
  name = name.to_sym

  ancestors.each do |base|
    if base < RProgram::Task
      return base.options[name] if base.options.has_key?(name)
    end
  end

  return nil
end
has_non_option?(name) click to toggle source

Searches for the non-option with the matching name in the class and it's ancestors.

@param [Symbol, String] name

The name to search for.

@return [true, false]

Specifies whether the non-option with the matching name was
defined.
# File lib/rprogram/task.rb, line 54
def self.has_non_option?(name)
  name = name.to_sym

  ancestors.each do |base|
    if base < RProgram::Task
      return true if base.non_options.include?(name)
    end
  end

  return false
end
has_option?(name) click to toggle source

Searches for the option with the matching name in the class and it's ancestors.

@param [Symbol, String] name

The name to search for.

@return [true, false]

Specifies whether the option with the matching name was defined.
# File lib/rprogram/task.rb, line 108
def self.has_option?(name)
  name = name.to_sym

  ancestors.each do |base|
    if base < RProgram::Task
      return true if base.options.has_key?(name)
    end
  end

  return false
end
new(options={}) { |self| ... } click to toggle source

Creates a new Task object.

@param [Hash{Symbol => Object}] options

Additional task options.

@yield [task]

If a block is given, it will be passed the newly created task.

@yieldparam [Task] task

The newly created Task object.

@example

Task.new(:test => 'example', :count => 2, :verbose => true)

@example

Task.new(:help => true) do |task|
  # ...
end
# File lib/rprogram/task.rb, line 28
def initialize(options={})
  @subtasks = {}
  @options  = options

  yield self if block_given?
end
non_options() click to toggle source

@return [Hash]

All defined non-options of the class.
# File lib/rprogram/task.rb, line 39
def self.non_options
  @non_options ||= {}
end
options() click to toggle source

@return [Hash]

All defined options for the class.
# File lib/rprogram/task.rb, line 94
def self.options
  @options ||= {}
end

Protected Class Methods

define_option(options,&block) click to toggle source

Defines an option.

@param [Hash] options

Additional options.

@option options [Symbol, String] :name

The name of the option.

@option options [String] :flag

The flag to use for the option.

@option options [true, false] :multiple (false)

Specifies that the option may appear multiple times in the
arguments.

@option options [true, false] :sub_options (false)

Specifies that the option contains multiple sub-options.
# File lib/rprogram/task.rb, line 458
def self.define_option(options,&block)
  method_name = options[:name].to_sym

  self.options[method_name] = Option.new(options,&block)

  define_method(method_name) do
    if options[:sub_options]
      @options[method_name] ||= OptionList.new
    elsif options[:multiple]
      @options[method_name] ||= []
    else
      @options[method_name]
    end
  end

  define_method("#{method_name}=") do |value|
    if options[:sub_options]
      @options[method_name] = OptionList.new(value)
    else
      @options[method_name] = value
    end
  end
end
flag_namify(flag) click to toggle source

Converts a long-option flag to a Ruby method name.

@param [String] flag

The command-line flag to convert.

@return [String]

A method-name compatible version of the given flag.

@example

Task.flag_namify('--output-file')
# => "output_file"
# File lib/rprogram/task.rb, line 495
def self.flag_namify(flag)
  flag = flag.to_s.downcase

  # remove leading dashes
  method_name = if    flag.start_with?('--') then flag[2..-1]
                elsif flag.start_with?('-')  then flag[1..-1]
                else                              flag
                end

  # replace remaining dashes with underscores
  return method_name.gsub(/[-_\.\s]+/,'_')
end
long_option(options={},&block) click to toggle source

Defines a long-option.

@param [Hash] options

Additional options of the long-option.

@option options [String] :flag

The flag to use for the option.

@option options [Symbol] :name

The name of the option. Defaults to the flag_namify'ed form of
`options[:flag]`, if not given.

@option options [true, false] :multiply (false)

Specifies that the option may appear multiple times in the
arguments.

@option options [true, false] :sub_options (false)

Specifies that the option contains multiple sub-options.

@example

long_option :flag => '--output'

@example

long_option :flag => '-f', :name => :file
# File lib/rprogram/task.rb, line 405
def self.long_option(options={},&block)
  if (options[:name].nil? && options[:flag])
    options[:name] = Task.flag_namify(options[:flag])
  end

  return define_option(options,&block)
end
non_option(options={}) click to toggle source

Defines a non-option.

@param [Hash] options

Additional options for the non-option.

@option options [Symbol] :name

The name of the non-option.

@option options [true, false] :leading (true)

Implies the non-option is a leading non-option.

@option options [false, true] :tailing (false)

Implies the non-option is a tailing non-option.

@option options [false, true] :multiple (false)

Implies the non-option maybe given an Array of values.

@example

non_option :name => 'input_file', :tailing => true

@example

non_option :name => 'file', :tailing => true, :multiple => true
# File lib/rprogram/task.rb, line 361
def self.non_option(options={})
  name = options[:name].to_sym

  self.non_options[name] = NonOption.new(options)

  define_method(name) do
    if options[:multiple]
      @options[name] ||= []
    else
      @options[name]
    end
  end

  define_method("#{name}=") do |value|
    @options[name] = value
  end
end
short_option(options,&block) click to toggle source

Defines a short_option.

@param [Hash] options

Additional options for the short-option.

@option options [Symbol, String] :name

The name of the short-option.

@option options [String] :flag

The flag to use for the short-option.

@option options [true, false] :multiply (false)

Specifies that the option may appear multiple times in the
arguments.

@option options [true, false] :sub_options (false)

Specifies that the option contains multiple sub-options.

@example

short_option :flag => '-c', :name => :count
# File lib/rprogram/task.rb, line 435
def self.short_option(options,&block)
  define_option(options,&block)
end
subtask(name,task) click to toggle source

Defines a sub-task.

@param [String, Symbol] name

The name of the sub-task.

@param [Task] task

The task class of the sub-task.

@example

subtask :extra, ExtraTask
# File lib/rprogram/task.rb, line 317
def self.subtask(name,task)
  name = name.to_s
  file = __FILE__
  line = __LINE__ + 3

  class_eval %{
    def #{name}(options={},&block)
      if @subtasks[#{name.dump}]
        @subtasks[#{name.dump}].options.merge!(options)

        yield(@subtasks[#{name.dump}]) if block_given?
      else
        @subtasks[#{name.dump}] = #{task}.new(options,&block)
      end

      return @subtasks[#{name.dump}]
    end
  }, file, line
end

Public Instance Methods

arguments() click to toggle source

Generates the command-line arguments from the task.

@return [Array]

The command-line arguments compiled from the leading non-options,
options and tailing non-options of the task and it's sub-tasks.
# File lib/rprogram/task.rb, line 286
def arguments
  tailing_args = tailing_non_options

  if tailing_args.any? { |arg| arg[0,1] == '-' }
    tailing_args.unshift('--')
  end

  return leading_non_options + options + tailing_args
end
get_non_option(name) click to toggle source

@see get_non_option

# File lib/rprogram/task.rb, line 183
def get_non_option(name)
  self.class.get_non_option(name)
end
get_option(name) click to toggle source

@see get_option

# File lib/rprogram/task.rb, line 197
def get_option(name)
  self.class.get_option(name)
end
has_non_option?(name) click to toggle source

@see has_non_option?

# File lib/rprogram/task.rb, line 176
def has_non_option?(name)
  self.class.has_non_option?(name)
end
has_option?(name) click to toggle source

@see has_option?

# File lib/rprogram/task.rb, line 190
def has_option?(name)
  self.class.has_option?(name)
end
leading_non_options() click to toggle source

Generates the command-line arguments for all leading non-options.

@return [Array]

The command-line arguments generated from all the leading
non-options of the task and it's sub-tasks.
# File lib/rprogram/task.rb, line 208
def leading_non_options
  args = []

  # add the task leading non-options
  @options.each do |name,value|
    non_opt = get_non_option(name)

    if (non_opt && non_opt.leading?)
      args += non_opt.arguments(value)
    end
  end

  # add all leading subtask non-options
  @subtasks.each_value do |task|
    args += task.leading_non_options
  end

  return args
end
options() click to toggle source

Generates the command-line arguments from all options.

@return [Array]

The command-line arguments generated from all the options of the
task and it's sub-tasks.
# File lib/rprogram/task.rb, line 235
def options
  args = []

  # add all subtask options
  @subtasks.each_value do |task|
    args += task.arguments
  end

  # add the task options
  @options.each do |name,value|
    opt = get_option(name)
    args += opt.arguments(value) if opt
  end

  return args
end
tailing_non_options() click to toggle source

Generates the command-line arguments from all tailing non-options.

@return [Array]

The command-line arguments generated from all the tailing
non-options of the task and it's sub-tasks.
# File lib/rprogram/task.rb, line 259
def tailing_non_options
  args = []

  # add all tailing subtask non-options
  @subtasks.each_value do |task|
    args += task.tailing_non_options
  end

  # add the task tailing non-options
  @options.each do |name,value|
    non_opt = get_non_option(name)

    if (non_opt && non_opt.tailing?)
      args += non_opt.arguments(value)
    end
  end

  return args
end
to_a() click to toggle source

@see arguments

# File lib/rprogram/task.rb, line 299
def to_a
  arguments
end