Class: Ing::Task

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

Overview

A base class to simplify typical task use-cases. Adds some class methods and state to allow inherited options/flexibly- ordered option specification. Note that options are inherited to subclasses, but description and usage lines are not.

Direct Known Subclasses

Generator

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Task

Returns a new instance of Task.



99
100
101
 
# File 'lib/ing/task.rb', line 99

def initialize(options)
  self.options = initial_options(options)
end

Instance Attribute Details

#options ⇒ Object

Returns the value of attribute options.



98
99
100
 
# File 'lib/ing/task.rb', line 98

def options
  @options
end

#shell ⇒ Object

Returns the value of attribute shell.



98
99
100
 
# File 'lib/ing/task.rb', line 98

def shell
  @shell
end

Class Method Details

.default(name, val) ⇒ Object

Modify the default for option name to val. Option will be created if it doesn’t exist.



32
33
34
 
# File 'lib/ing/task.rb', line 32

def default(name, val)
  modify_option name, {:default => val}
end

.desc(line = "") ⇒ Object Also known as: description

Add a description line



37
38
39
 
# File 'lib/ing/task.rb', line 37

def desc(line="")
  desc_lines << line
end

.desc_lines ⇒ Object

Description lines



75
76
77
 
# File 'lib/ing/task.rb', line 75

def desc_lines
  @desc_lines ||= []
end

.inherited(subclass) ⇒ Object 



14
15
16
 
# File 'lib/ing/task.rb', line 14

def inherited(subclass)
  subclass.set_options self.options.dup
end

.modify_option(name, specs) ⇒ Object

Modify the option named name according to specs (Hash). Option will be created if it doesn’t exist.

Example:

modify_option :file, :required => true



25
26
27
28
 
# File 'lib/ing/task.rb', line 25

def modify_option(name, specs)
  opt(name) unless options[name]
  options[name].opts.merge!(specs)
end

.opt(name, desc = "", settings = {}) ⇒ Object Also known as: option

Add an option. Note the syntax is identical to Trollop::Parser#opt



48
49
50
 
# File 'lib/ing/task.rb', line 48

def opt(name, desc="", settings={})
  options[name] = Option.new(name, desc, settings)
end

.options ⇒ Object

Options hash. Note that in a subclass, options are copied down from superclass.



86
87
88
 
# File 'lib/ing/task.rb', line 86

def options
  @options ||= {}
end

.specify_options(parser) ⇒ Object

Build option parser based on desc, usage, and options (including inherited options). This method is called by ‘Ing::Dispatcher`.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/ing/task.rb', line 56

def specify_options(parser)
  desc_lines.each do |line|
    parser.text line
  end
  unless usage_lines.empty?
    parser.text "\nUsage:"
    usage_lines.each do |line|
      parser.text line
    end
  end
  unless options.empty?
    parser.text "\nOptions:"
    options.each do |name, opt|
      parser.opt *opt.to_args
    end
  end
end

.usage(line = "") ⇒ Object

Add a usage line



43
44
45
 
# File 'lib/ing/task.rb', line 43

def usage(line="")
  usage_lines << line
end

.usage_lines ⇒ Object

Usage lines



80
81
82
 
# File 'lib/ing/task.rb', line 80

def usage_lines
  @usage_lines ||= []
end

Instance Method Details

#initial_options(given) ⇒ Object

Override in subclass for adjusting given options on initialization



104
105
106
 
# File 'lib/ing/task.rb', line 104

def initial_options(given)
  given
end

#validate_option(opt, desc = opt, msg = nil) ⇒ Object

Use in initialization for option validation (post-parsing).

Example:

validate_option(:color, "Color must be :black or :white") do |actual|
  [:black, :white].include?(actual)
end



116
117
118
119
 
# File 'lib/ing/task.rb', line 116

def validate_option(opt, desc=opt, msg=nil)
  msg ||= "Error in option #{desc} for `#{self.class}`."
  !!yield(self.options[opt]) or raise ArgumentError, msg
end

#validate_option_exists(opt, desc = opt) ⇒ Object

Validate that the option was passed or otherwise defaulted to something truthy. Note that in most cases, instead you should set :required => true on the option and let Trollop catch the error – rather than catching it post-parsing.

Note validate_option_exists will raise an error if the option is passed but false or nil, unlike the Trollop parser.



128
129
130
131
132
133
 
# File 'lib/ing/task.rb', line 128

def validate_option_exists(opt, desc=opt)
  msg = "No #{desc} specified for #{self.class}. You must either " +
        "specify a `--#{opt}` option or set a default in #{self.class} or " +
        "in its superclass(es)."
  validate_option(opt, desc, msg) {|val| val }
end