Class: Puppet::Pops::Adaptable::Adapter Private

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/pops/adaptable.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.

Base class for an Adapter.

A typical adapter just defines some accessors.

A more advanced adapter may need to setup the adapter based on the object it is adapting.

Examples:

Making Duck adaptable

class Duck
  include Puppet::Pops::Adaptable
end

Giving a Duck a nick name

class NickNameAdapter < Puppet::Pops::Adaptable::Adapter
  attr_accessor :nick_name
end
d = Duck.new
NickNameAdapter.adapt(d).nick_name = "Daffy"
NickNameAdapter.get(d).nick_name # => "Daffy"

Giving a Duck a more elaborate nick name

class NickNameAdapter < Puppet::Pops::Adaptable::Adapter
  attr_accessor :nick_name, :object
  def initialize o
    @object = o
    @nick_name = "Yo"
  end
  def nick_name
    "#{@nick_name}, the #{o.class.name}"
  end
  def NickNameAdapter.create_adapter(o)
    x = new o
    x
  end
end
d = Duck.new
n = NickNameAdapter.adapt(d)
n.nick_name # => "Yo, the Duck"
n.nick_name = "Daffy"
n.nick_name # => "Daffy, the Duck"

Using a block to set values

NickNameAdapter.adapt(o) { |a| a.nick_name = "Buddy!" }
NickNameAdapter.adapt(o) { |a, o| a.nick_name = "You're the best #{o.class.name} I met."}

Class Method Summary collapse

Class Method Details

.adapt(o) ⇒ Adapter<self> .adapt(o, {|adapter| block}) ⇒ Adapter<self> .adapt(o, {|adapter, o| block}) ⇒ Adapter<self>

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 an existing adapter for the given object, or creates a new adapter if the object has not been adapted, or the adapter has been cleared.

Examples:

Using a block to set values

NickNameAdapter.adapt(o) { |a| a.nick_name = "Buddy!" }
NickNameAdapter.adapt(o) { |a, o| a.nick_name = "Your the best #{o.class.name} I met."}

Parameters:

  • o (Adaptable)

    object to add adapter to

  • block (Proc)

    optional, evaluated in the context of the adapter (existing or new)

Yield Parameters:

  • adapter (Adapter<self>)

    the created adapter

  • o (Adaptable)

    optional, the given adaptable

Returns:

  • (Adapter<self>)

    an adapter of the same class as the receiver of the call

Raises:

  • (ArgumentError)

    if the given object o is not adaptable



92
93
94
95
96
97
98
99
100
101
102
103
104
# File 'lib/puppet/pops/adaptable.rb', line 92

def self.adapt(o, &block)
  attr_name = self_attr_name
  value = o.instance_variable_get(attr_name)
  adapter = value || associate_adapter(create_adapter(o), o)
  if block_given?
    if block.arity == 1
      block.call(adapter)
    else
      block.call(adapter, o)
    end
  end
  adapter
end

.adapt_new(o) ⇒ Adapter<self> .adapt_new(o, {|adapter| block}) ⇒ Adapter<self> .adapt_new(o, {|adapter, o| block}) ⇒ Adapter<self>

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.

Creates a new adapter, associates it with the given object and returns the adapter.

This is used when a fresh adapter is wanted instead of possible returning an existing adapter as in the case of adapt.

Examples:

Using a block to set values

NickNameAdapter.adapt_new(o) { |a| a.nick_name = "Buddy!" }
NickNameAdapter.adapt_new(o) { |a, o| a.nick_name = "Your the best #{o.class.name} I met."}

Parameters:

  • o (Adaptable)

    object to add adapter to

  • block (Proc)

    optional, evaluated in the context of the new adapter

Yield Parameters:

  • adapter (Adapter<self>)

    the created adapter

  • o (Adaptable)

    optional, the given adaptable

Returns:

  • (Adapter<self>)

    an adapter of the same class as the receiver of the call

Raises:

  • (ArgumentError)

    if the given object o is not adaptable



123
124
125
126
127
128
129
130
131
132
133
# File 'lib/puppet/pops/adaptable.rb', line 123

def self.adapt_new(o, &block)
  adapter = associate_adapter(create_adapter(o), o)
  if block_given?
    if block.arity == 1
      block.call(adapter)
    else
      block.call(adapter, o)
    end
  end
  adapter
end

.associate_adapter(adapter, o) ⇒ adapter

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.

Associates the given adapter with the given target object

Parameters:

  • adapter (Adapter)

    the adapter to associate with the given object o

  • o (Adaptable)

    the object to adapt

Returns:

  • (adapter)

    the given adapter



165
166
167
168
# File 'lib/puppet/pops/adaptable.rb', line 165

def self.associate_adapter(adapter, o)
  o.instance_variable_set(self_attr_name, adapter)
  adapter
end

.clear(o) ⇒ Adapter?

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.

Clears the adapter set in the given object o. Returns any set adapter or nil.

Parameters:

  • o (Adaptable)

    the object where the adapter should be cleared

Returns:

  • (Adapter)

    if an adapter was set

  • (nil)

    if the adapter has not been set



140
141
142
143
144
145
146
147
# File 'lib/puppet/pops/adaptable.rb', line 140

def self.clear(o)
  attr_name = self_attr_name
  if o.instance_variable_defined?(attr_name)
    o.send(:remove_instance_variable, attr_name)
  else
    nil
  end
end

.create_adapter(o) ⇒ Adapter<self>

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 base version creates an instance of the class (i.e. an instance of the concrete subclass of Adapter). A Specialization may want to create an adapter instance specialized for the given target object.

Parameters:

  • o (Adaptable)

    The object to adapt. This implementation ignores this variable, but a specialization may want to initialize itself differently depending on the object it is adapting.

Returns:

  • (Adapter<self>)

    instance of the subclass of Adapter receiving the call



156
157
158
# File 'lib/puppet/pops/adaptable.rb', line 156

def self.create_adapter(o)
  new
end

.get(o) ⇒ Adapter<self>?

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 an existing adapter for the given object, or nil, if the object is not adapted.

Parameters:

  • o (Adaptable)

    object to get adapter from

Returns:

  • (Adapter<self>)

    an adapter of the same class as the receiver of #get

  • (nil)

    if the given object o has not been adapted by the receiving adapter

Raises:

  • (ArgumentError)

    if the object is not adaptable



71
72
73
74
# File 'lib/puppet/pops/adaptable.rb', line 71

def self.get(o)
  attr_name = self_attr_name
  o.instance_variable_get(attr_name)
end

.instance_var_name(name) ⇒ String

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 suitable instance variable name given a class name. The returned string is the fully qualified name of a class with ‘::’ replaced by ‘_’ since ‘::’ is not allowed in an instance variable name.

Parameters:

  • name (String)

    the fully qualified name of a class

Returns:

  • (String)

    the name with all ‘::’ replaced by ‘_’



177
178
179
# File 'lib/puppet/pops/adaptable.rb', line 177

def self.instance_var_name(name)
  name.split(DOUBLE_COLON).join(USCORE)
end

.self_attr_nameString

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 suitable instance variable name for the name of this instance. The name is created by calling Adapter#instance_var_name and then cached.

Returns:

  • (String)

    the instance variable name for name



192
193
194
# File 'lib/puppet/pops/adaptable.rb', line 192

def self.self_attr_name
  @attr_name_sym ||= :"@#{instance_var_name(type_name)}"
end

.type_nameString

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 the name of the class, or the name of the type if the class represents an Object type

Returns:

  • (String)

    the name of the class or type



183
184
185
# File 'lib/puppet/pops/adaptable.rb', line 183

def self.type_name
  self.name
end