Class: Puppet::Pops::Binder::Injector

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/pops/binder/injector.rb

Overview

The injector is the “lookup service” class

Initialization

The injector is initialized with a configured Binder. The Binder instance contains a resolved set of ‘key => “binding information”` that is used to setup the injector.

Lookup

It is possible to lookup either the value, or a producer of the value. The #lookup method looks up a value, and the #lookup_producer looks up a producer. Both of these methods can be called with three different signatures; ‘lookup(key)`, `lookup(type, name)`, and `lookup(name)`, with the corresponding calls to obtain a producer; `lookup_producer(key)`, `lookup_producer(type, name)`, and `lookup_producer(name)`.

It is possible to pass a block to #lookup and #lookup_producer, the block is passed the result of the lookup and the result of the block is returned as the value of the lookup. This is useful in order to provide a default value.

Singleton or Not

The lookup of a value is always based on the lookup of a producer. For *singleton producers* this means that the value is determined by the first value lookup. Subsequent lookups via lookup or lookup_producer will produce the same instance.

*Non singleton producers* will produce a new instance on each request for a value. For constant value producers this means that a new deep-clone is produced for mutable objects (but not for immutable objects as this is not needed). Custom producers should have non singleton behavior, or if this is not possible ensure that the produced result is immutable. (The behavior if a custom producer hands out a mutable value and this is mutated is undefined).

Custom bound producers capable of producing a series of objects when bound as a singleton means that the producer is a singleton, not the value it produces. If such a producer is bound as non singleton, each lookup will get a new producer (hence, typically, restarting the series). However, the producer returned from lookup_producer will not recreate the producer on each call to produce; i.e. each lookup_producer returns a producer capable of returning a series of objects.

Assisted Inject

The injector supports lookup of instances of classes *even if the requested class is not explicitly bound*. This is possible for classes that have a zero argument initialize method, or that has a class method called inject that takes two arguments; injector, and scope. This is useful in ruby logic as a class can then use the given injector to inject details. An inject class method wins over a zero argument initialize in all cases.

Access to key factory and type calculator

It is important to use the same key factory, and type calculator as the binder. It is therefor possible to obtaint these with the methods #key_factory, and #type_calculator.

Special support for producers

There is one method specially designed for producers. The #get_contributions method returns an array of all contributions to a given *contributions key*. This key is obtained from the #key_factory for a given multibinding. The returned set of contributed bindings is sorted in descending precedence order. Any conflicts, merges, etc. is performed by the multibinding producer configured for a multibinding.

Examples:

Lookup with default value

injector.lookup('favourite_food') {|x| x.nil? ? 'bacon' : x }

Using assisted inject

# Class with assisted inject support
class Duck
  attr_reader :name, :year_of_birth

  def self.inject(injector, scope, binding, *args)
    # lookup default name and year of birth, and use defaults if not present
    name = injector.lookup(scope,'default-duck-name') {|x| x ? x : 'Donald Duck' }
    year_of_birth = injector.lookup(scope,'default-duck-year_of_birth') {|x| x ? x : 1934 }
    self.new(name, year_of_birth)
  end

  def initialize(name, year_of_birth)
    @name = name
    @year_of_birth = year_of_birth
  end
end

injector.lookup(scope, Duck)
# Produces a Duck named 'Donald Duck' or named after the binding 'default-duck-name' (and with similar treatment of
# year_of_birth).

See Also:

Defined Under Namespace

Modules: Private

Constant Summary collapse

Producers = 
Puppet::Pops::Binder::Producers

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(configured_binder) ⇒ Injector

An Injector is initialized with a configured Binder.

Parameters:

  • configured_binder (Puppet::Pops::Binder::Binder, nil) —

    The configured binder containing effective bindings. A given value of nil creates an injector that returns or yields nil on all lookup requests.

Raises:

  • ArgumentError if the given binder is not fully configured



97
98
99
100
101
102
103
 
# File 'lib/puppet/pops/binder/injector.rb', line 97

def initialize(configured_binder)
  if configured_binder.nil?
    @impl = Private::NullInjectorImpl.new()
  else
    @impl = Private::InjectorImpl.new(configured_binder)
  end
end

Class Method Details

.null_injector ⇒ Object

Returns an Injector that returns (or yields) nil on all lookups, and produces an empty structure for contributions This method is intended for testing purposes.



270
271
272
 
# File 'lib/puppet/pops/binder/injector.rb', line 270

def self.null_injector
  self.new(nil)
end

Instance Method Details

#get_contributions(scope, contributions_key) ⇒ Array<Puppet::Pops::Binder::InjectorEntry>

Returns the contributions to a multibind given its contribution key (as produced by the KeyFactory). This method is typically used by multibind value producers, but may be used for introspection of the injector’s state.

Parameters:

  • scope (Puppet::Parser::Scope) —

    the scope to use

  • contributions_key (Object) —

    Opaque key as produced by KeyFactory as the contributions key for a multibinding

Returns:



263
264
265
 
# File 'lib/puppet/pops/binder/injector.rb', line 263

def get_contributions(scope, contributions_key)
  @impl.get_contributions(scope, contributions_key)
end

#key_factory ⇒ Puppet::Pops::Binder::KeyFactory

The KeyFactory used to produce keys in this injector. The factory is shared with the Binder to ensure consistent translation to keys. A compatible type calculator can also be obtained from the key factory.

Returns:



112
113
114
 
# File 'lib/puppet/pops/binder/injector.rb', line 112

def key_factory()
  @impl.key_factory
end

#lookup(scope, key) ⇒ Object #lookup(scope, type, name = '') ⇒ Object #lookup(scope, name) ⇒ Object

Lookup (a.k.a “inject”) of a value given a key. The lookup may be called with different parameters. This method is a convenience method that dispatches to one of #lookup_key or #lookup_type depending on the arguments. It also provides the ability to use an optional block that is called with the looked up value, or scope and value if the block takes two parameters. This is useful to provide a default value or other transformations, calculations based on the result of the lookup.

Overloads:

Yields:

  • (value) —

    passes the looked up value to an optional block and returns what this block returns

  • (scope, value) —

    passes scope and value to the block and returns what this block returns

Yield Parameters:

Raises:

  • (ArgumentError) —

    if the block has an arity that is not 1 or 2



159
160
161
 
# File 'lib/puppet/pops/binder/injector.rb', line 159

def lookup(scope, *args, &block)
  @impl.lookup(scope, *args, &block)
end

#lookup_key(scope, key) ⇒ Object?

Looks up the key and returns the entry, or nil if no entry is found. Produced type is checked for type conformance with its binding, but not with the lookup key. (This since all subtypes of PDataType are looked up using a key based on PDataType). Use the Puppet::Pops::Types::TypeCalculator#instance? method to check for conformance of the result if this is wanted, or use #lookup_type.

Parameters:

  • key (Object) —

    lookup of key as produced by the key factory

Returns:

  • (Object, nil) —

    produced value of type that conforms with bound type (type conformance with key not guaranteed).

Raises:

  • (ArgumentError) —

    if the produced value does not conform with the bound type



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

def lookup_key(scope, key)
  @impl.lookup_key(scope, key)
end

#lookup_producer(scope, key) ⇒ Puppet::Pops::Binder::Producers::Producer, ... #lookup_producer(scope, type, name = '') ⇒ Puppet::Pops::Binder::Producers::Producer, ... #lookup_producer(scope, name) ⇒ Puppet::Pops::Binder::Producers::Producer, ...

Lookup (a.k.a “inject”) producer of a value given a key. The producer lookup may be called with different parameters. This method is a convenience method that dispatches to one of #lookup_producer_key or #lookup_producer_type depending on the arguments. It also provides the ability to use an optional block that is called with the looked up producer, or scope and producer if the block takes two parameters. This is useful to provide a default value, call a custom producer method, or other transformations, calculations based on the result of the lookup.

Overloads:

Yields:

  • (producer) —

    passes the looked up producer to an optional block and returns what this block returns

  • (scope, producer) —

    passes scope and producer to the block and returns what this block returns

Yield Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if the block has an arity that is not 1 or 2



231
232
233
 
# File 'lib/puppet/pops/binder/injector.rb', line 231

def lookup_producer(scope, *args, &block)
  @impl.lookup_producer(scope, *args, &block)
end

#lookup_producer_key(scope, key) ⇒ Puppet::Pops::Binder::Producers::Producer?

Looks up a Producer given an opaque binder key.

Returns:



240
241
242
 
# File 'lib/puppet/pops/binder/injector.rb', line 240

def lookup_producer_key(scope, key)
  @impl.lookup_producer_key(scope, key)
end

#lookup_producer_type(scope, type, name = '') ⇒ Puppet::Pops::Binder::Producers::Producer?

Note:

The result is not type checked (it cannot be until the producer has produced an instance).

Looks up a Producer given a type/name key.

Returns:



250
251
252
 
# File 'lib/puppet/pops/binder/injector.rb', line 250

def lookup_producer_type(scope, type, name='')
  @impl.lookup_producer_type(scope, type, name)
end

#lookup_type(scope, type, name = '') ⇒ Object?

Looks up a (typesafe) value based on a type/name combination. Creates a key for the type/name combination using a KeyFactory. Specialization of the Data type are transformed to a Data key, and the result is type checked to conform with the given key.

Parameters:

  • type (Puppet::Pops::Types::PObjectType) —

    the type to lookup as defined by Puppet::Pops::Types::TypeFactory

  • name (String) (defaults to: '') —

    the (optional for non Data types) name of the entry to lookup. The name may be an empty String (the default), but not nil. The name is required for lookup for subtypes of Data.

Returns:

  • (Object, nil) —

    the looked up bound object, or nil if not found (type conformance with given type is guaranteed)

Raises:

  • (ArgumentError) —

    if the produced value does not conform with the given type



176
177
178
 
# File 'lib/puppet/pops/binder/injector.rb', line 176

def lookup_type(scope, type, name='')
  @impl.lookup_type(scope, type, name)
end

#type_calculator ⇒ Puppet::Pops::Types::TypeCalculator

Returns the TypeCalculator in use for keys. The same calculator (as used for keys) should be used if there is a need to check type conformance, or infer the type of Ruby objects.

Returns:



122
123
124
 
# File 'lib/puppet/pops/binder/injector.rb', line 122

def type_calculator()
  @impl.type_calculator()
end