db_mod 0.0.5 → 0.0.6

data/lib/db_mod/statements/configuration/as.rb

@@ -24,10 +24,12 @@ module DbMod
         }
 
         # Extend the given method definition with additional
-        # result coercion.
+        # result coercion, if specified using {MethodConfiguration#as}.
         #
         # @param definition [Proc] base method definition
         # @param config [MethodConfiguration] method configuration
+        # @return [Proc] wrapped method definition, or the original
+        #   definition if no coercion has been specified
         def self.extend(definition, config)
           type = config[:as]
           return definition if type.nil?

data/lib/db_mod/statements/configuration/defaults.rb

@@ -14,6 +14,11 @@ module DbMod
       #    RETURNING p, q, r
       #  )) { defaults(5, 6).single(:row) }
       #
+      #  def_prepared(:c, 'SELECT a FROM b WHERE d = $e AND f > $g') do
+      #    # procs may be used
+      #    defaults g: ->(args) { args[:e] * 10 }
+      #  end
+      #
       #  # ...
       #
       #  a    # y => 10
@@ -21,6 +26,9 @@ module DbMod
       #
       #  # defaults filled in from the right
       #  b 1, 2 # => { 'p' => '1', 'q' => '2', 'r' => '6' }
+      #
+      #  # proc defaults executed when method is called
+      #  c e: 2 # === c e: 2, g: 20
       module Defaults
         # Extend a method definition by wrapping it with a proc that will
         # try to fill in any omitted arguments with given defaults.
@@ -32,7 +40,10 @@ module DbMod
         # @param defaults [Hash<Symbol,value,Array<value>]
         #   default values, in the same form as they would be provided
         #   to the original method definition except that some values
-        #   may be omitted
+        #   may be omitted. Defaults may either be constant values, or
+        #   a lambda proc may be given, which will be passed the
+        #   entirety of the argument list and should return a single
+        #   value to be used when none is given
         # @return [Proc] new method definition, or the same one
         #   if no default values have been appended
         def self.extend(definition, params, defaults)
@@ -57,14 +68,15 @@ module DbMod
         # @param definition [Proc] base method definition,
         #   with parameter validation already attached
         # @param defaults [Hash<Symbol,value>]
-        #   default parameter values
+        #   see {Defaults.extend}
+        # @return [Proc] wrapped method definition
         def self.extend_named_args_method(definition, defaults)
           unless defaults.is_a? Hash
             fail ArgumentError, 'hash expected for defaults'
           end
 
           lambda do |*args|
-            Defaults.use_named_defaults(args, defaults)
+            Defaults.use_named_defaults(self, args, defaults)
             instance_exec(*args, &definition)
           end
         end
@@ -72,11 +84,16 @@ module DbMod
         # Fill in any missing parameter arguments using default
         # values where available.
         #
+        # @param scope [Object] scope to be used for executing
+        #   default values that are lambda procedures. Should
+        #   be the instance object where the method has been
+        #   defined.
         # @param args [[Hash<Symbol,value>]] method arguments
         #   before processing and validation
         # @param defaults [Hash<Symbol,value>]
         #   default parameter values
-        def self.use_named_defaults(args, defaults)
+        # @see Defaults.extend_named_args_method
+        def self.use_named_defaults(scope, args, defaults)
           # Special case when no args given.
           args << {} if args.empty?
 
@@ -85,7 +102,30 @@ module DbMod
           return args unless args.last.is_a? Hash
 
           defaults.each do |arg, value|
-            args.last[arg] = value unless args.last.key? arg
+            next if args.last.key? arg
+
+            args.last[arg] = value! value, scope, args.last
+          end
+        end
+
+        # Execute the default 'value' if it is a +Proc+,
+        # or just return it.
+        #
+        # @param value [Proc,Object] default value as specified
+        #   by {MethodConfiguration#defaults}
+        # @param scope [Object] scope to be used for executing
+        #   default values that are lambda procedures. Should
+        #   be the instance object where the method has been
+        #   defined.
+        # @param args [Hash,Array] fixed or named argument
+        #   list, to be passed to the 'value' if it is a proc
+        # @return [Object] value to be passed to the parametered
+        #   database query
+        def self.value!(value, scope, args)
+          if value.is_a? Proc
+            scope.instance_exec(args, &value)
+          else
+            value
           end
         end
 
@@ -101,6 +141,7 @@ module DbMod
         #   by the base method definition
         # @param defaults [Array]
         #   default parameter values
+        # @return [Proc] wrapped method definition
         def self.extend_fixed_args_method(definition, arity, defaults)
           fail ArgumentError, 'too many defaults' if defaults.size > arity
 
@@ -112,7 +153,7 @@ module DbMod
           fail ArgumentError, 'too many defaults' if arity.min < 0
 
           lambda do |*args|
-            Defaults.use_fixed_defaults(args, defaults, arity)
+            Defaults.use_fixed_defaults(self, args, defaults, arity)
             instance_exec(*args, &definition)
           end
         end
@@ -120,18 +161,24 @@ module DbMod
         # Fill in any missing parameter arguments using default values
         # where available.
         #
+        # @param scope [Object] scope to be used for executing
+        #   default values that are lambda procedures. Should
+        #   be the instance object where the method has been
+        #   defined.
         # @param args [Array] method arguments
         #   before processing and validation
         # @param defaults [Array] default parameter values
         # @param arity [Range<Fixnum>] number of arguments
         #   expected by the base method definition
-        def self.use_fixed_defaults(args, defaults, arity)
+        # @raise [ArgumentError] if there are not enough or too many args
+        # @see Defaults.extend_fixed_args_method
+        def self.use_fixed_defaults(scope, args, defaults, arity)
           unless arity.include? args.count
             fail ArgumentError, "#{args.count} given, (#{arity}) expected"
           end
 
           defaults[args.size - arity.min...defaults.size].each do |arg|
-            args << arg
+            args << value!(arg, scope, args)
           end
         end
       end

data/lib/db_mod/statements/configuration/method_configuration.rb

@@ -1,5 +1,6 @@
 require_relative 'as'
 require_relative 'defaults'
+require_relative 'returning'
 require_relative 'single'
 
 module DbMod
@@ -14,10 +15,15 @@ module DbMod
         # Creates a new configuration object to be used as the scope for
         # blocks passed to +def_statement+ and +def_prepared+ declarations.
         #
+        # @param args [*] one or more +MethodConfiguration+ objects or hashes
+        #   from which existing settings will be merged
+        # @param block [proc] block containing method configuration declaration
         # @yield executes the block using +self+ as scope
-        def initialize(&block)
+        def initialize(*args, &block)
           @settings = {}
           instance_exec(&block) if block_given?
+
+          merge_settings(args)
         end
 
         # Extend the method by converting results into a given
@@ -25,6 +31,8 @@ module DbMod
         # under {DbMod::Statements::Configuration::As}.
         #
         # @param type [:csv,:json] output format for the method
+        #   may be set to +nil+ or +false+ to un-set any
+        #   inherited setting
         # @return [self]
         def as(type)
           one_of! type, Configuration::As::COERCERS
@@ -40,6 +48,8 @@ module DbMod
         # more details.
         #
         # @param type [Symbol] see {Configuration::Single::COERCERS}
+        #   may be set to +nil+ or +false+ to un-set any
+        #   inherited setting
         # @return [self]
         def single(type)
           one_of! type, Configuration::Single::COERCERS
@@ -57,8 +67,17 @@ module DbMod
         # 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.
+        #
         # @param defaults [Hash<Symbol,value>,Array<value>]
         #   default parameter values
+        # @return [self]
         def defaults(*defaults)
           if defaults.size == 1 && defaults.first.is_a?(Hash)
             defaults = defaults.first
@@ -71,6 +90,24 @@ module DbMod
           self
         end
 
+        # 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.
+        #
+        # @param block [Proc] block to be executed on the method's result set
+        # @return [self]
+        def returning(&block)
+          fail ArgumentError, 'block required' unless block_given?
+
+          set_once! :returning, block
+
+          self
+        end
+
         # Return all given settings in a hash.
         # @return [Hash]
         def to_hash
@@ -79,12 +116,47 @@ module DbMod
 
         private
 
+        # Merge settings from constructor arguments. Allowed arguments
+        # are hashes, other {MethodConfiguration} objects, or procs that
+        # will be executed with a {MethodConfiguration} object as the
+        # scope.
+        #
+        # @param args [Array] array of objects containing method
+        #   configuration settings
+        # @return [Hash] == `@settings`
+        # @raise [ArgumentError] if any args are invalid (see {#arg_to_hash})
+        def merge_settings(args)
+          inherited_settings = {}
+          args.each do |arg|
+            inherited_settings.merge! arg_to_hash arg
+          end
+
+          @settings = inherited_settings.merge @settings
+        end
+
+        # Convert a single constructor argument into a hash of settings
+        # that may be merged into this object's settings hash.
+        #
+        # @param arg [Object] see {#merge_settings}
+        # @return [Hash] a hash of settings derived from the object
+        # @raise [ArgumentError] if an unexpected argement is encountered
+        # @see #merge_settings
+        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
+
         # Guard method which asserts that a configuration method
         # may not be called more than once, or else raises
         # {DbMod::Exceptions::BadMethodConfiguration}.
         #
         # @param setting [Symbol] setting name
         # @param value [Object] setting value
+        # @raise [Exceptions::BadMethodConfiguration] if the settings has
+        #   already been set
         def set_once!(setting, value)
           if @settings.key? setting
             fail Exceptions::BadMethodConfiguration, "#{setting} already called"
@@ -98,6 +170,7 @@ module DbMod
         #
         # @param value [key] configuration setting
         # @param allowed [Hash] set of allowed configuration settings
+        # @raise [ArgumentError] if the value is not allowed
         def one_of!(value, allowed)
           return if allowed.key? value
 

data/lib/db_mod/statements/configuration/returning.rb

@@ -0,0 +1,31 @@
+module DbMod
+  module Statements
+    module Configuration
+      # Provides functionality backing the {MethodConfiguration#returning}
+      # setting. Allows a block to be declared that may perform additional
+      # processing on the SQL result set (the result of whatever other
+      # result transformations have been specified using
+      # {MethodConfiguration#as} or {MethodConfiguration#single}), and
+      # which may transform or replace entirely the method return value.
+      #
+      #  def_statement(:csv_email, 'SELECT * FROM foo') do
+      #    as(:csv)
+      #    returning { |csv| build_email(csv) }
+      #  end
+      module Returning
+        # Extend the given method definition with additional result
+        # coercion, if specified using {MethodConfiguration#returning}.
+        #
+        # @param definition [Proc] base method definition
+        # @param config [MethodConfiguration] method configuration
+        # @return [Proc] wrapped method definition, or the original
+        #   definition if no coercion has been specified
+        def self.extend(definition, config)
+          return definition unless config.key? :returning
+
+          Configuration.attach_result_processor definition, config[:returning]
+        end
+      end
+    end
+  end
+end

data/lib/db_mod/statements/configuration/single.rb

@@ -41,10 +41,12 @@ module DbMod
         }
 
         # Extend the given method definition with additional
-        # result coercion.
+        # result coercion, if specified using {MethodConfiguration#single.
         #
         # @param definition [Proc] base method definition
         # @param config [MethodConfiguration] method configuration
+        # @return [Proc] wrapped method definition, or the original
+        #   definition if no coercion has been specified
         def self.extend(definition, config)
           type = config[:single]
           return definition if type.nil?

data/lib/db_mod/statements/default_method_settings.rb

@@ -0,0 +1,81 @@
+require_relative 'configuration/method_configuration'
+
+module DbMod
+  module Statements
+    # Allows modules to declare a block of default settings that
+    # will be applied to all methods declared in the module using
+    # +def_prepared+ or +def_statement+. These default settings will
+    # be used for all methods in the module where no overriding
+    # settings are declared with the method definition.
+    #
+    #  module JsonAccessors
+    #    include DbMod
+    #
+    #    default_method_settings do
+    #      single(:row).as(:json).returning { |json| do_whatever(json) }
+    #    end
+    #
+    #    # Normal access to instance scope for `returning`
+    #    def do_whatever(thing)
+    #      # ...
+    #    end
+    #
+    #    def_prepared(:foo, 'SELECT * FROM foo WHERE id = $1')
+    #
+    #    def_prepared(:bar, 'SELECT * FROM bar WHERE id = $1')
+    #
+    #    # Overrides can be provided for any setting
+    #    def_prepared(:all_foos, 'SELECT * FROM foo') { single(false) }
+    #    def_prepared(:csv_foo, 'SELECT * FROM foo WHERE id = $1') do
+    #      as(:csv)
+    #    end
+    #  end
+    #
+    # Existing {Configuration::MethodConfiguration} objects may be
+    # passed directly to +default_method_settings+ instead of supplying
+    # a block. This allows configurations to be reused between modules.
+    #
+    #  SETTINGS = DbMod::Statements::Configuration::MethodConfiguration.new do
+    #    single(:row).as(:json)
+    #  end
+    #
+    #  module A
+    #    include DbMod
+    #
+    #    default_method_settings(SETTINGS)
+    #
+    #    # ...
+    #
+    #  end
+    #
+    #  module B
+    #    include A
+    #
+    #    # This also works
+    #    default_method_settings(A.default_method_settings)
+    #
+    #    # ...
+    #
+    #  end
+    module DefaultMethodSettings
+      # Defines a module-specific +default_method_settings+ function
+      # for a module that has just had {DbMod} included.
+      #
+      # @param mod [Module] module including {DbMod}
+      # @see DbMod.included
+      def self.setup(mod)
+        class << mod
+          define_method(:default_method_settings) do |*args, &block|
+            unless args.any? || block
+              return @default_method_settings ||=
+                Configuration::MethodConfiguration.new
+            end
+
+            @default_method_settings =
+              Configuration::MethodConfiguration.new(*args, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/db_mod/statements/parameters.rb

@@ -30,6 +30,7 @@ module DbMod
       #
       # @param count [Fixnum] arity of the method being called.
       # @param args [Array] list of arguments given.
+      # @raise [ArgumentError] if the wrong number of arguments is given
       def self.valid_fixed_args!(count, args)
         unless args.size == count
           fail ArgumentError, "#{args.size} args given, #{count} expected"
@@ -51,6 +52,8 @@ module DbMod
       # @param sql [String] statement to prepare
       # @return [Fixnum,Array<Symbol>] description of
       #   prepared statement's parameters
+      # @raise [ArgumentError] if there is any sort of problem
+      #   with the parameters declared in the sql statement
       def self.parse_params!(sql)
         Parameters.valid_sql_params! sql
         numbered = sql.scan NUMBERED_PARAM
@@ -81,6 +84,8 @@ module DbMod
       # Raises +ArgumentError+ otherwise.
       #
       # @param args [Array<Hash<Symbol>>] method arguments being validated
+      # @raise [ArgumentError] if the arguments passed to the method
+      #   do not pass validation
       def self.wrapped_hash!(args)
         unless args.size == 1
           fail ArgumentError, "unexpected arguments: #{args.inspect}"
@@ -99,6 +104,7 @@ module DbMod
       # @param expected [Array<Symbol>] the parameters expected to be present
       # @param args [Hash] given parameters
       # @return [Array] values to be passed to the prepared statement
+      # @raise [ArgumentError] if any arguments are missing
       def self.parameter_array(expected, args)
         expected.map do |arg|
           fail(ArgumentError, "missing arg #{arg}") unless args.key? arg
@@ -110,6 +116,11 @@ module DbMod
       # Fails if any parameters in an sql query aren't
       # in the expected format. They must either be
       # lower_case_a_to_z or digits only.
+      #
+      # @param sql [String] sql statement that may or may
+      #   not contain parameters
+      # @raise [ArgumentError] if there are any invalid
+      #   parameter declarations
       def self.valid_sql_params!(sql)
         sql.scan(/\$[A-Za-z0-9_]+/) do |param|
           unless param =~ NAMED_OR_NUMBERED
@@ -123,6 +134,8 @@ module DbMod
       #
       # @param params [Array<String>] '$1','$2', etc...
       # @return [Fixnum] parameter count
+      # @raise [ArgumentError] if there are any problems with the
+      #   given argument list
       def self.parse_numbered_params!(params)
         params.sort!
         params.uniq!