Class: RProgram::Task

Inherits:
Object
  • Object
show all
Defined in:
lib/rprogram/task.rb

Direct Known Subclasses

SudoTask

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|task| ... } ⇒ Task

Creates a new Task object.

Examples:

Task.new(:test => 'example', :count => 2, :verbose => true)
Task.new(:help => true) do |task|
  # ...
end

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {}) —

    Additional task options.

Yields:

  • (task) —

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

Yield Parameters:

  • task (Task) —

    The newly created Task object.



28
29
30
31
32
33
 
# File 'lib/rprogram/task.rb', line 28

def initialize(options={},&block)
  @subtasks = {}
  @options = options

  block.call(self) if block
end

Class Method Details

.arguments(options = {}) {|task| ... } ⇒ Array

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

Examples:

MyTask.arguments(:verbose => true, :count => 2)
# => [...]
MyTask.arguments do |task|
  task.verbose = true
  task.file = 'output.txt'
end
# => [...]

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {}) —

    Additional task options.

Yields:

  • (task) —

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

Yield Parameters:

  • task (Task) —

    The newly created Task object.

Returns:

  • (Array) —

    The formatted arguments from a Task object.



169
170
171
 
# File 'lib/rprogram/task.rb', line 169

def self.arguments(options={},&block)
  self.new(options,&block).arguments
end

.define_option(options, &block) ⇒ Object (protected)

Defines an option.

Parameters:

  • options (Hash) —

    Additional options.

Options Hash (options):

  • :name (Symbol, String) —

    The name of the option.

  • :flag (String) —

    The flag to use for the option.

  • :multiple (true, false) — default: false —

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

  • :sub_options (true, false) — default: false —

    Specifies that the option contains multiple sub-options.



453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
 
# File 'lib/rprogram/task.rb', line 453

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) ⇒ String (protected)

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

Examples:

Task.flag_namify('--output-file')
# => "output_file"

Parameters:

  • flag (String) —

    The command-line flag to convert.

Returns:

  • (String) —

    A method-name compatible version of the given flag.



490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
 
# File 'lib/rprogram/task.rb', line 490

def Task.flag_namify(flag)
  flag = flag.to_s.downcase

  # remove leading dashes
  if flag[0..1] == '--'
    method_name = flag[2..-1]
  elsif flag[0..0] == '-'
    method_name = flag[1..-1]
  else
    method_name = flag
  end

  # replace remaining dashes with underscores
  return method_name.gsub(/[-_\.\s]+/,'_')
end

.get_non_option(name) ⇒ NonOption

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

Parameters:

  • name (Symbol, String) —

    The name to search for.

Returns:

  • (NonOption) —

    The non-option with the matching name.



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# 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) ⇒ Option

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

Parameters:

  • name (Symbol, String) —

    The name to search for.

Returns:

  • (Option) —

    The option with the matching name.



130
131
132
133
134
135
136
137
138
139
140
 
# 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) ⇒ true, false

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

Parameters:

  • name (Symbol, String) —

    The name to search for.

Returns:

  • (true, false) —

    Specifies whether the non-option with the matching name was defined.



54
55
56
57
58
59
60
61
62
63
64
 
# 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) ⇒ true, false

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

Parameters:

  • name (Symbol, String) —

    The name to search for.

Returns:

  • (true, false) —

    Specifies whether the option with the matching name was defined.



108
109
110
111
112
113
114
115
116
117
118
 
# 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

.long_option(options = {}, &block) ⇒ Object (protected)

Defines a long-option.

Examples:

long_option :flag => '--output'
long_option :flag => '-f', :name => :file

Parameters:

  • options (Hash) (defaults to: {}) —

    Additional options of the long-option.

Options Hash (options):

  • :flag (String) —

    The flag to use for the option.

  • :name (Symbol) —

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

  • :multiply (true, false) — default: false —

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

  • :sub_options (true, false) — default: false —

    Specifies that the option contains multiple sub-options.



400
401
402
403
404
405
406
 
# File 'lib/rprogram/task.rb', line 400

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 = {}) ⇒ Object (protected)

Defines a non-option.

Examples:

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

Parameters:

  • options (Hash) (defaults to: {}) —

    Additional options for the non-option.

Options Hash (options):

  • :name (Symbol) —

    The name of the non-option.

  • :leading (true, false) — default: true —

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

  • :tailing (false, true) — default: false —

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

  • :multiple (false, true) — default: false —

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



356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/rprogram/task.rb', line 356

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

.non_options ⇒ Hash

Returns All defined non-options of the class.

Returns:

  • (Hash) —

    All defined non-options of the class.



39
40
41
 
# File 'lib/rprogram/task.rb', line 39

def self.non_options
  @non_options ||= {}
end

.options ⇒ Hash

Returns All defined options for the class.

Returns:

  • (Hash) —

    All defined options for the class.



94
95
96
 
# File 'lib/rprogram/task.rb', line 94

def self.options
  @options ||= {}
end

.short_option(options, &block) ⇒ Object (protected)

Defines a short_option.

Examples:

short_option :flag => '-c', :name => :count

Parameters:

  • options (Hash) —

    Additional options for the short-option.

Options Hash (options):

  • :name (Symbol, String) —

    The name of the short-option.

  • :flag (String) —

    The flag to use for the short-option.

  • :multiply (true, false) — default: false —

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

  • :sub_options (true, false) — default: false —

    Specifies that the option contains multiple sub-options.



430
431
432
 
# File 'lib/rprogram/task.rb', line 430

def self.short_option(options,&block)
  define_option(options,&block)
end

.subtask(name, task) ⇒ Object (protected)

Defines a sub-task.

Examples:

subtask :extra, ExtraTask

Parameters:

  • name (String, Symbol) —

    The name of the sub-task.

  • task (Task) —

    The task class of the sub-task.



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/rprogram/task.rb', line 312

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

Instance Method Details

#arguments ⇒ Array Also known as: to_a

Generates the command-line arguments from the task.

Returns:

  • (Array) —

    The command-line arguments compiled from the leading non-options, options and tailing non-options of the task and it's sub-tasks.



286
287
288
289
290
291
292
293
294
 
# 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) ⇒ Object

See Also:



183
184
185
 
# File 'lib/rprogram/task.rb', line 183

def get_non_option(name)
  self.class.get_non_option(name)
end

#get_option(name) ⇒ Object

See Also:



197
198
199
 
# File 'lib/rprogram/task.rb', line 197

def get_option(name)
  self.class.get_option(name)
end

#has_non_option?(name) ⇒ Boolean

Returns:

  • (Boolean)

See Also:



176
177
178
 
# File 'lib/rprogram/task.rb', line 176

def has_non_option?(name)
  self.class.has_non_option?(name)
end

#has_option?(name) ⇒ Boolean

Returns:

  • (Boolean)

See Also:



190
191
192
 
# File 'lib/rprogram/task.rb', line 190

def has_option?(name)
  self.class.has_option?(name)
end

#leading_non_options ⇒ Array

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

Returns:

  • (Array) —

    The command-line arguments generated from all the leading non-options of the task and it's sub-tasks.



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# 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 ⇒ Array

Generates the command-line arguments from all options.

Returns:

  • (Array) —

    The command-line arguments generated from all the options of the task and it's sub-tasks.



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# 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 ⇒ Array

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

Returns:

  • (Array) —

    The command-line arguments generated from all the tailing non-options of the task and it's sub-tasks.



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# 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