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.



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 16

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

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


221
222
223
 
# File 'lib/puppet/interface/action.rb', line 221

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) 


147
148
149
 
# File 'lib/puppet/interface/action.rb', line 147

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) 


225
226
227
 
# File 'lib/puppet/interface/action.rb', line 225

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 = dup
  bound_version.instance_variable_set(:@face, to)
  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. 



314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/puppet/interface/action.rb', line 314

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. 



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/puppet/interface/action.rb', line 282

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.

Returns:

  • (Boolean) 


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

def default?
  !!@default
end

#deprecate ⇒ 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.



155
156
157
 
# File 'lib/puppet/interface/action.rb', line 155

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.

Returns:

  • (Boolean) 


161
162
163
 
# File 'lib/puppet/interface/action.rb', line 161

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. 



328
329
330
 
# File 'lib/puppet/interface/action.rb', line 328

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. 



333
334
335
336
337
338
339
 
# File 'lib/puppet/interface/action.rb', line 333

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) 


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

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. 



310
311
312
 
# File 'lib/puppet/interface/action.rb', line 310

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
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/puppet/interface/action.rb', line 95

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

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



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

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. 



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
394
395
396
397
398
 
# File 'lib/puppet/interface/action.rb', line 341

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.
  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 %{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.
  nil
end