Class: Puppet::Interface::Action Private

Inherits:
Object
  • Object
show all
Extended by:
DocGen
Includes:
FullDocs, Util::MethodHelper
Defined in:
lib/puppet/interface/action.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

This represents an action that is attached to a face. Actions should be constructed by calling Puppet::Interface::ActionManager#action, which is available on Puppet::Interface, and then calling methods of ActionBuilder in the supplied block.

Instance Attribute Summary collapse

Attributes included from FullDocs

#copyright_owner, #copyright_years

Instance Method Summary collapse

Methods included from DocGen

attr_doc, strip_whitespace

Methods included from FullDocs

#author, #author=, #authors, #copyright, #examples, #license, #munge_copyright_year, #notes, #short_description

Methods included from TinyDocs

#build_synopsis, #description, #summary

Methods included from Util::MethodHelper

#requiredopts, #set_options, #symbolize_options

Constructor Details

#initialize(face, name, attrs = {}) ⇒ Action

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Action.



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/puppet/interface/action.rb', line 15

def initialize(face, name, attrs = {})
  raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
  @face    = face
  @name    = name.to_sym

  # The few bits of documentation we actually demand.  The default license
  # is a favour to our end users; if you happen to get that in a core face
  # report it as a bug, please. --daniel 2011-04-26
  @authors = []
  @license  = 'All Rights Reserved'

  set_options(attrs)

  # @options collects the added options in the order they're declared.
  # @options_hash collects the options keyed by alias for quick lookups.
  @options        = []
  @display_global_options = []
  @options_hash   = {}
  @when_rendering = {}
end

Instance Attribute Details

#default ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Whether this is the default action for the face

Returns:

  • (Boolean) 


61
62
63
 
# File 'lib/puppet/interface/action.rb', line 61

def default
  @default
end

#face ⇒ Puppet::Interface (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The face this action is attached to

Returns:



56
57
58
 
# File 'lib/puppet/interface/action.rb', line 56

def face
  @face
end

#name ⇒ Symbol (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The name of this action

Returns:

  • (Symbol) 


52
53
54
 
# File 'lib/puppet/interface/action.rb', line 52

def name
  @name
end

#positional_arg_count ⇒ Integer (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The arity of the action

Returns:

  • (Integer) 


201
202
203
 
# File 'lib/puppet/interface/action.rb', line 201

def positional_arg_count
  @positional_arg_count
end

#render_as ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Symbol) 


137
138
139
 
# File 'lib/puppet/interface/action.rb', line 137

def render_as
  @render_as
end

#when_invoked ⇒ block

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The block that is executed when the action is invoked

Returns:

  • (block) 


205
206
207
 
# File 'lib/puppet/interface/action.rb', line 205

def when_invoked
  @when_invoked
end

Instance Method Details

#__dup_and_rebind_to(to) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.



42
43
44
45
46
 
# File 'lib/puppet/interface/action.rb', line 42

def __dup_and_rebind_to(to)
  bound_version = self.dup
  bound_version.instance_variable_set(:@face, to)
  return bound_version
end

#add_display_global_options(*args) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



285
286
287
288
289
290
291
292
293
 
# File 'lib/puppet/interface/action.rb', line 285

def add_display_global_options(*args)
  @display_global_options ||= []
  [args].flatten.each do |refopt|
    raise ArgumentError, "Global option #{refopt} does not exist in Puppet.settings" unless Puppet.settings.include? refopt
    @display_global_options << refopt
  end
  @display_global_options.uniq!
  @display_global_options
end

#add_option(option) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/puppet/interface/action.rb', line 259

def add_option(option)
  option.aliases.each do |name|
    if conflict = get_option(name) then
      raise ArgumentError, "Option #{option} conflicts with existing option #{conflict}"
    elsif conflict = @face.get_option(name) then
      raise ArgumentError, "Option #{option} conflicts with existing option #{conflict} on #{@face}"
    end
  end

  @options << option.name

  option.aliases.each do |name|
    @options_hash[name] = option
  end

  option
end

#default? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


62
63
64
 
# File 'lib/puppet/interface/action.rb', line 62

def default?
  !!@default
end

#display_global_options(*args) ⇒ Object Also known as: display_global_option

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



295
296
297
 
# File 'lib/puppet/interface/action.rb', line 295

def display_global_options(*args)
  args ? add_display_global_options(args) : @display_global_options + @face.display_global_options
end

#get_option(name, with_inherited_options = true) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



300
301
302
303
304
305
306
 
# File 'lib/puppet/interface/action.rb', line 300

def get_option(name, with_inherited_options = true)
  option = @options_hash[name.to_sym]
  if option.nil? and with_inherited_options
    option = @face.get_option(name)
  end
  option
end

#option?(name) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


277
278
279
 
# File 'lib/puppet/interface/action.rb', line 277

def option?(name)
  @options_hash.include? name.to_sym
end

#options ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



281
282
283
 
# File 'lib/puppet/interface/action.rb', line 281

def options
  @face.options + @options
end

#set_rendering_method_for(type, proc) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/puppet/interface/action.rb', line 95

def set_rendering_method_for(type, proc)
  unless proc.is_a? Proc
    msg = "The second argument to set_rendering_method_for must be a Proc"
    msg += ", not #{proc.class.name}" unless proc.nil?
    raise ArgumentError, msg
  end

  if proc.arity != 1 and proc.arity != (@positional_arg_count + 1)
    msg =  "the when_rendering method for the #{@face.name} face #{name} action "
    msg += "takes either just one argument, the result of when_invoked, "
    msg += "or the result plus the #{@positional_arg_count} arguments passed "
    msg += "to the when_invoked block, not "
    if proc.arity < 0 then
      msg += "a variable number"
    else
      msg += proc.arity.to_s
    end
    raise ArgumentError, msg
  end
  unless type.is_a? Symbol
    raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
  end
  if @when_rendering.has_key? type then
    raise ArgumentError, "You can't define a rendering method for #{type} twice"
  end
  # Now, the ugly bit.  We add the method to our interface object, and
  # retrieve it, to rotate through the dance of getting a suitable method
  # object out of the whole process. --daniel 2011-04-18
  @when_rendering[type] =
    @face.__send__( :__add_method, __render_method_name_for(type), proc)
end

#synopsis ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



70
71
72
 
# File 'lib/puppet/interface/action.rb', line 70

def synopsis
  build_synopsis(@face.name, default? ? nil : name, arguments)
end

#to_s ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



48
 
# File 'lib/puppet/interface/action.rb', line 48

def to_s() "#{@face}##{@name}" end

#validate_and_clean(original) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/puppet/interface/action.rb', line 308

def validate_and_clean(original)
  # The final set of arguments; effectively a hand-rolled shallow copy of
  # the original, which protects the caller from the surprises they might
  # get if they passed us a hash and we mutated it...
  result = {}

  # Check for multiple aliases for the same option, and canonicalize the
  # name of the argument while we are about it.
  overlap = Hash.new do |h, k| h[k] = [] end
  unknown = []
  original.keys.each do |name|
    if option = get_option(name) then
      canonical = option.name
      if result.has_key? canonical
        overlap[canonical] << name
      else
        result[canonical] = original[name]
      end
    elsif Puppet.settings.include? name
      result[name] = original[name]
    else
      unknown << name
    end
  end

  unless overlap.empty?
    msg = overlap.map {|k, v| "(#{k}, #{v.sort.join(', ')})" }.join(", ")
    raise ArgumentError, "Multiple aliases for the same option passed: #{msg}"
  end

  unless unknown.empty?
    msg = unknown.sort.join(", ")
    raise ArgumentError, "Unknown options passed: #{msg}"
  end

  # Inject default arguments and check for missing mandating options.
  missing = []
  options.map {|x| get_option(x) }.each do |option|
    name = option.name
    next if result.has_key? name

    if option.has_default?
      result[name] = option.default
    elsif option.required?
      missing << name
    end
  end

  unless missing.empty?
    msg = missing.sort.join(', ')
    raise ArgumentError, "The following options are required: #{msg}"
  end

  # All done.
  return result
end

#when_rendering(type) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/puppet/interface/action.rb', line 79

def when_rendering(type)
  unless type.is_a? Symbol
    raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
  end
  # Do we have a rendering hook for this name?
  return @when_rendering[type].bind(@face) if @when_rendering.has_key? type

  # How about by another name?
  alt = type.to_s.sub(/^to_/, '').to_sym
  return @when_rendering[alt].bind(@face) if @when_rendering.has_key? alt

  # Guess not, nothing to run.
  return nil
end