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

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Task

Returns a new instance of Task.



120
121
122
 
# File 'lib/ing/task.rb', line 120

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

Class Attribute Details

.inherited_options ⇒ Object

Returns the value of attribute inherited_options.



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

def inherited_options
  @inherited_options
end

Instance Attribute Details

#options ⇒ Object

Returns the value of attribute options.



119
120
121
 
# File 'lib/ing/task.rb', line 119

def options
  @options
end

#shell ⇒ Object

Returns the value of attribute shell.



119
120
121
 
# File 'lib/ing/task.rb', line 119

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.



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

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

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

Add a description line



52
53
54
 
# File 'lib/ing/task.rb', line 52

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

.desc_lines ⇒ Object

Description lines



96
97
98
 
# File 'lib/ing/task.rb', line 96

def desc_lines
  @desc_lines ||= []
end

.inherited(subclass) ⇒ Object 



16
17
18
 
# File 'lib/ing/task.rb', line 16

def inherited(subclass)
  subclass.inherited_options = self.options.dup
end

.inherited_option?(name) ⇒ Boolean

Returns:

  • (Boolean) 


20
21
22
 
# File 'lib/ing/task.rb', line 20

def inherited_option?(name)
  inherited_options.has_key?(name)
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



35
36
37
38
39
40
41
42
43
 
# File 'lib/ing/task.rb', line 35

def modify_option(name, specs)
  if inherited_option?(name)
    inherited_options[name].opts.merge!(specs)
  elsif option?(name)
    options[name].opts.merge!(specs)
  else
    opt(name, '', specs)
  end
end

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

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



63
64
65
 
# File 'lib/ing/task.rb', line 63

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

.option?(name) ⇒ Boolean

Returns:

  • (Boolean) 


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

def option?(name)
  options.has_key?(name)
end

.options ⇒ Object

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



107
108
109
 
# File 'lib/ing/task.rb', line 107

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`.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/ing/task.rb', line 71

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
  unless inherited_options.empty?
    parser.text "\nCommon Options:"
    inherited_options.each do |name, opt|
      parser.opt *opt.to_args
    end
  end
end

.usage(line = "") ⇒ Object

Add a usage line



58
59
60
 
# File 'lib/ing/task.rb', line 58

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

.usage_lines ⇒ Object

Usage lines



101
102
103
 
# File 'lib/ing/task.rb', line 101

def usage_lines
  @usage_lines ||= []
end

Instance Method Details

#ask_unless_given(*opts) ⇒ Object

Build a hash of options that weren’t given from command line via ask (i.e., $stdin.gets).

Note it currently does not cast options to appropriate types. Also note because the shell is not available until after initialization, this must be called from command method(s), e.g. #call



136
137
138
139
140
141
142
143
144
 
# File 'lib/ing/task.rb', line 136

def ask_unless_given(*opts)
  opts.inject({}) do |memo, opt|
    next memo if options[:"#{opt}_given"]
    msg = self.class.options[opt].desc + "?"
    df  = self.class.options[opt].default
    memo[opt] = shell.ask(msg, :default => df)
    memo
  end
end

#ask_unless_given!(*opts) ⇒ Object

Shortcut for:

options.merge! ask_unless_given :opt1, :opt2



150
151
152
 
# File 'lib/ing/task.rb', line 150

def ask_unless_given!(*opts)
  self.options.merge! ask_unless_given(*opts)
end

#initial_options(given) ⇒ Object

Override in subclass for adjusting given options on initialization



125
126
127
 
# File 'lib/ing/task.rb', line 125

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



162
163
164
165
 
# File 'lib/ing/task.rb', line 162

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.



174
175
176
177
178
179
 
# File 'lib/ing/task.rb', line 174

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