Class: DbMod::Statements::Configuration::MethodConfiguration

Inherits:
Object
  • Object
show all
Defined in:
lib/db_mod/statements/configuration/method_configuration.rb

Overview

Collects settings given at time of definition for statement and prepared methods. If a block is passed to def_statement or def_prepared it will be evaluated using an instance of this class, allowing methods such as #as or #single to be used to shape the behaviour of the defined method.

Instance Method Summary collapse

Constructor Details

#initialize(*args, &block) { ... } ⇒ MethodConfiguration

Creates a new configuration object to be used as the scope for blocks passed to def_statement and def_prepared declarations.

Parameters:

  • args (*) —

    one or more MethodConfiguration objects or hashes from which existing settings will be merged

  • block (proc) —

    block containing method configuration declaration

Yields:

  • executes the block using self as scope



22
23
24
25
26
27
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 22

def initialize(*args, &block)
  @settings = {}
  instance_exec(&block) if block_given?

  merge_settings(args)
end

Instance Method Details

#arg_to_hash(arg) ⇒ Hash (private)

Convert a single constructor argument into a hash of settings that may be merged into this object’s settings hash.

Parameters:

Returns:

  • (Hash) —

    a hash of settings derived from the object

Raises:

  • (ArgumentError) —

    if an unexpected argement is encountered

See Also:



144
145
146
147
148
149
150
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 144

def arg_to_hash(arg)
  return arg if arg.is_a? Hash
  return arg.to_hash if arg.is_a? MethodConfiguration
  return MethodConfiguration.new(&arg).to_hash if arg.is_a? Proc

  fail ArgumentError, "unknown method setting #{arg.inspect}"
end

#as(type) ⇒ self

Extend the method by converting results into a given format, using one of the coercion methods defined under As.

Parameters:

  • type (:csv, :json) —

    output format for the method may be set to nil or false to un-set any inherited setting

Returns:

  • (self) 


37
38
39
40
41
42
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 37

def as(type)
  one_of! type, Configuration::As::COERCERS
  set_once! :as, type

  self
end

#defaults(*defaults) ⇒ self

Declares default values for method parameters. For methods with named parameters, a hash of argument names and default values should be provided. For methods with indexed parameters, an array of 1..n default values should be provided, where n is the method’s arity. In this case default values will be applied to the right-hand side of the argument list, as with normal parameter default rules.

In place of a fixed default value, a lambda Proc may be supplied. In this case the proc will be executed, given the partially constructed argument list/hash and scoped against the instance variable where the prepared or statement method is defined. It should return a single value to be used for that particular execution of the method.

Parameters:

  • defaults (Hash<Symbol,value>, Array<value>) —

    default parameter values

Returns:

  • (self) 


81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 81

def defaults(*defaults)
  if defaults.size == 1 && defaults.first.is_a?(Hash)
    defaults = defaults.first
  elsif defaults.last.is_a? Hash
    fail ArgumentError, 'mixed default declaration not allowed'
  end

  set_once! :defaults, defaults

  self
end

#merge_settings(args) ⇒ Hash (private)

Merge settings from constructor arguments. Allowed arguments are hashes, other DbMod::Statements::Configuration::MethodConfiguration objects, or procs that will be executed with a DbMod::Statements::Configuration::MethodConfiguration object as the scope.

Parameters:

  • args (Array) —

    array of objects containing method configuration settings

Returns:

  • (Hash) —

    ‘@settings`

Raises:

  • (ArgumentError) —

    if any args are invalid (see #arg_to_hash)



128
129
130
131
132
133
134
135
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 128

def merge_settings(args)
  inherited_settings = {}
  args.each do |arg|
    inherited_settings.merge! arg_to_hash arg
  end

  @settings = inherited_settings.merge @settings
end

#one_of!(value, allowed) ⇒ Object (private)

Guard method which asserts that a configuration setting is one of the allowed values in the given hash.

Parameters:

  • value (key) —

    configuration setting

  • allowed (Hash) —

    set of allowed configuration settings

Raises:

  • (ArgumentError) —

    if the value is not allowed



174
175
176
177
178
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 174

def one_of!(value, allowed)
  return if allowed.key? value

  fail ArgumentError, "#{value} not in #{allowed.keys.join ', '}"
end

#returning(&block) ⇒ self

Declares a block that will be used to transform or replace the SQL result set before it is returned from the defined method. The block should accept a single parameter and can return pretty much whatever it wants.

The block will be applied after any transforms specified by #as or #single have already been applied.

Parameters:

  • block (Proc) —

    block to be executed on the method’s result set

Returns:

  • (self) 


103
104
105
106
107
108
109
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 103

def returning(&block)
  fail ArgumentError, 'block required' unless block_given?

  set_once! :returning, block

  self
end

#set_once!(setting, value) ⇒ Object (private)

Guard method which asserts that a configuration method may not be called more than once, or else raises Exceptions::BadMethodConfiguration.

Parameters:

  • setting (Symbol) —

    setting name

  • value (Object) —

    setting value

Raises:



160
161
162
163
164
165
166
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 160

def set_once!(setting, value)
  if @settings.key? setting
    fail Exceptions::BadMethodConfiguration, "#{setting} already called"
  end

  @settings[setting] = value
end

#single(type) ⇒ self

Extend the method by extracting a singular part of the result set, for queries expected to only return one row, one column, or one row with a single value. See Single for more details.

Parameters:

  • type (Symbol) —

    see Single::COERCERS may be set to nil or false to un-set any inherited setting

Returns:

  • (self) 


54
55
56
57
58
59
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 54

def single(type)
  one_of! type, Configuration::Single::COERCERS
  set_once! :single, type

  self
end

#to_hash ⇒ Hash

Return all given settings in a hash.

Returns:

  • (Hash) 


113
114
115
 
# File 'lib/db_mod/statements/configuration/method_configuration.rb', line 113

def to_hash
  @settings
end