Class: Puppet::Interface::Action Private

Inherits:
Object
  • Object
show all
Extended by:
DocGen
Includes:
FullDocs
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

Constructor Details

#initialize(face, name) ⇒ 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


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

def initialize(face, name)
  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'

  # @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

#defaultBoolean

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


58
59
60
# File 'lib/puppet/interface/action.rb', line 58

def default
  @default
end

#facePuppet::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


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

def face
  @face
end

#nameSymbol (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


49
50
51
# File 'lib/puppet/interface/action.rb', line 49

def name
  @name
end

#positional_arg_countInteger (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


219
220
221
# File 'lib/puppet/interface/action.rb', line 219

def positional_arg_count
  @positional_arg_count
end

#render_asSymbol

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.


144
145
146
# File 'lib/puppet/interface/action.rb', line 144

def render_as
  @render_as
end

#when_invokedblock

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


223
224
225
# File 'lib/puppet/interface/action.rb', line 223

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.


39
40
41
42
43
# File 'lib/puppet/interface/action.rb', line 39

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.


310
311
312
313
314
315
316
317
318
319
320
321
# File 'lib/puppet/interface/action.rb', line 310

def add_display_global_options(*args)
  @display_global_options ||= []
  [args].flatten.each do |refopt|
    unless Puppet.settings.include? refopt
      #TRANSLATORS 'Puppet.settings' should not be translated
      raise ArgumentError, _("Global option %{option} does not exist in Puppet.settings") % { option: refopt }
    end
    @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.


278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
# File 'lib/puppet/interface/action.rb', line 278

def add_option(option)
  option.aliases.each do |name|
    conflict = get_option(name)
    if conflict
      raise ArgumentError, _("Option %{option} conflicts with existing option %{conflict}") %
          { option: option, conflict: conflict }
    else
      conflict = @face.get_option(name)
      if conflict
        raise ArgumentError, _("Option %{option} conflicts with existing option %{conflict} on %{face}") %
            { option: option, conflict: conflict, face: @face }
      end
    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.


59
60
61
# File 'lib/puppet/interface/action.rb', line 59

def default?
  !!@default
end

#deprecatevoid

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.


151
152
153
# File 'lib/puppet/interface/action.rb', line 151

def deprecate
  @deprecated = true
end

#deprecated?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.


157
158
159
# File 'lib/puppet/interface/action.rb', line 157

def deprecated?
  @deprecated
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.


323
324
325
# File 'lib/puppet/interface/action.rb', line 323

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.


328
329
330
331
332
333
334
# File 'lib/puppet/interface/action.rb', line 328

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.


302
303
304
# File 'lib/puppet/interface/action.rb', line 302

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

#optionsObject

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.


306
307
308
# File 'lib/puppet/interface/action.rb', line 306

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.


92
93
94
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
126
127
128
129
130
131
132
# File 'lib/puppet/interface/action.rb', line 92

def set_rendering_method_for(type, proc)
  unless proc.is_a? Proc
    msg = if proc.nil?
            #TRANSLATORS 'set_rendering_method_for' and 'Proc' should not be translated
            _("The second argument to set_rendering_method_for must be a Proc")
          else
            #TRANSLATORS 'set_rendering_method_for' and 'Proc' should not be translated
            _("The second argument to set_rendering_method_for must be a Proc, not %{class_name}") %
                { class_name: proc.class.name }
          end
    raise ArgumentError, msg
  end

  if proc.arity != 1 and proc.arity != (@positional_arg_count + 1)
    msg = if proc.arity < 0 then
            #TRANSLATORS 'when_rendering', 'when_invoked' are method names and should not be translated
            _("The when_rendering method for the %{face} face %{name} action takes either just one argument,"\
                " the result of when_invoked, or the result plus the %{arg_count} arguments passed to the"\
                " when_invoked block, not a variable number") %
                { face: @face.name, name: name, arg_count: @positional_arg_count }
          else
            #TRANSLATORS 'when_rendering', 'when_invoked' are method names and should not be translated
            _("The when_rendering method for the %{face} face %{name} action takes either just one argument,"\
                " the result of when_invoked, or the result plus the %{arg_count} arguments passed to the"\
                " when_invoked block, not %{string}") %
                { face: @face.name, name: name, arg_count: @positional_arg_count, string: proc.arity.to_s }
          end
    raise ArgumentError, msg
  end
  unless type.is_a? Symbol
    raise ArgumentError, _("The rendering format must be a symbol, not %{class_name}") % { class_name: type.class.name }
  end
  if @when_rendering.has_key? type then
    raise ArgumentError, _("You can't define a rendering method for %{type} twice") % { type: type }
  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

#synopsisObject

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.


67
68
69
# File 'lib/puppet/interface/action.rb', line 67

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

#to_sObject

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.


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

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.


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
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
# File 'lib/puppet/interface/action.rb', line 336

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|
    option = get_option(name)
    if option
      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?
    overlap_list = overlap.map {|k, v| "(#{k}, #{v.sort.join(', ')})" }.join(", ")
    raise ArgumentError, _("Multiple aliases for the same option passed: %{overlap_list}") %
        { overlap_list: overlap_list }
  end

  unless unknown.empty?
    unknown_list = unknown.sort.join(", ")
    raise ArgumentError, _("Unknown options passed: %{unknown_list}") % { unknown_list: unknown_list }
  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?
    missing_list = missing.sort.join(', ')
    raise ArgumentError, _("The following options are required: %{missing_list}") % { missing_list: missing_list }
  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.


76
77
78
79
80
81
82
83
84
85
86
87
88
89
# File 'lib/puppet/interface/action.rb', line 76

def when_rendering(type)
  unless type.is_a? Symbol
    raise ArgumentError, _("The rendering format must be a symbol, not %{class_name}") % { class_name: 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