Module: Plumbum::Provider

Included in:
Plumbum::Providers::Plural, Plumbum::Providers::Singular
Defined in:
lib/plumbum/provider.rb

Overview

Abstract module defining the Provider interface.

A Plumbum::Provider is responsible for making one or more values available to a consumer object. How those values are stored or generated is up to the provider implementation.

Each provider implementation is responsible for defining the #get_value(key) and #has_value(key) methods:

  • #get_value(key) must accept a single non-empty String argument and return the provided value matching the key, or nil if there is no matching value.

  • #has_value?(key) must accept a single non-empty String argument and return true if the provider has a value matching the key, or false if there is no matching value.

See Also:

Instance Method Summary collapse

Instance Method Details

#get(key) ⇒ Object?

Retrieves the provided value for the given key.

Parameters:

  • key (String, Symbol) —

    the key for the requested value.

Returns:

  • (Object, nil) —

    the requested object, or nil if the provider does not have a value for the requested key.



35
36
37
38
39
 
# File 'lib/plumbum/provider.rb', line 35

def get(key)
  key
    .then { |obj| normalize_key(obj) }
    .then { |str| get_value(str) }
end

#has?(key, allow_undefined: false) ⇒ true, false

Checks if the provider has a value for the given key.

Parameters:

  • key (String, Symbol) —

    the key for the requested value.

  • allow_undefined (true, false) (defaults to: false) —

    if true, returns true even if the key exists but the value is undefined.

Returns:

  • (true, false) —

    true if the provider has a value for the requested key, otherwise false.



49
50
51
52
53
 
# File 'lib/plumbum/provider.rb', line 49

def has?(key, allow_undefined: false)
  key
    .then { |obj| normalize_key(obj) }
    .then { |str| has_value?(str, allow_undefined:) }
end

#options ⇒ Hash{Symbol => Object}

Returns the options used to configure the provider.

Returns:

  • (Hash{Symbol => Object}) —

    the options used to configure the provider.



78
79
80
 
# File 'lib/plumbum/provider.rb', line 78

def options
  @options ||= {}
end

#read_only? ⇒ true, false

Returns if true, indicates the provider is read only, and an exception will be raised when attempting to set or change its value(s).

Returns:

  • (true, false) —

    if true, indicates the provider is read only, and an exception will be raised when attempting to set or change its value(s).



84
85
86
 
# File 'lib/plumbum/provider.rb', line 84

def read_only?
  options.fetch(:read_only, true)
end

#set(key, value) ⇒ Object

Sets the value for the given key.

Parameters:

  • key (String, Symbol) —

    the key for the assigned value.

  • value (Object) —

    the value to assign.

Returns:

  • (Object) —

    the assigned value.

Raises:



64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/plumbum/provider.rb', line 64

def set(key, value)
  if frozen?
    raise FrozenError, "can't modify frozen #{self.class}: #{inspect}"
  end

  key
    .then { |obj| normalize_key(obj) }
    .tap  { |key| validate_key(key) }
    .tap  { |key| require_mutable(key) }
    .then { |key| set_value(key, value) }
end

#write_once? ⇒ true, false

Returns if true, indicates the provider permits overwriting undefined values, and an exception will be raised when attemption to set or change any other values.

Returns:

  • (true, false) —

    if true, indicates the provider permits overwriting undefined values, and an exception will be raised when attemption to set or change any other values.



91
92
93
 
# File 'lib/plumbum/provider.rb', line 91

def write_once?
  options.fetch(:write_once, false)
end