db_mod 0.0.4 → 0.0.5

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

@@ -0,0 +1,109 @@
+require_relative 'as'
+require_relative 'defaults'
+require_relative 'single'
+
+module DbMod
+  module Statements
+    module Configuration
+      # 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.
+      class MethodConfiguration
+        # Creates a new configuration object to be used as the scope for
+        # blocks passed to +def_statement+ and +def_prepared+ declarations.
+        #
+        # @yield executes the block using +self+ as scope
+        def initialize(&block)
+          @settings = {}
+          instance_exec(&block) if block_given?
+        end
+
+        # Extend the method by converting results into a given
+        # format, using one of the coercion methods defined
+        # under {DbMod::Statements::Configuration::As}.
+        #
+        # @param type [:csv,:json] output format for the method
+        # @return [self]
+        def as(type)
+          one_of! type, Configuration::As::COERCERS
+          set_once! :as, type
+
+          self
+        end
+
+        # 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 {DbMod::Statements::Configuration::Single} for
+        # more details.
+        #
+        # @param type [Symbol] see {Configuration::Single::COERCERS}
+        # @return [self]
+        def single(type)
+          one_of! type, Configuration::Single::COERCERS
+          set_once! :single, type
+
+          self
+        end
+
+        # 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.
+        #
+        # @param defaults [Hash<Symbol,value>,Array<value>]
+        #   default parameter values
+        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
+
+        # Return all given settings in a hash.
+        # @return [Hash]
+        def to_hash
+          @settings
+        end
+
+        private
+
+        # 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
+        def set_once!(setting, value)
+          if @settings.key? setting
+            fail Exceptions::BadMethodConfiguration, "#{setting} already called"
+          end
+
+          @settings[setting] = value
+        end
+
+        # Guard method which asserts that a configuration setting
+        # is one of the allowed values in the given hash.
+        #
+        # @param value [key] configuration setting
+        # @param allowed [Hash] set of allowed configuration settings
+        def one_of!(value, allowed)
+          return if allowed.key? value
+
+          fail ArgumentError, "#{value} not in #{allowed.keys.join ', '}"
+        end
+      end
+    end
+  end
+end

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

@@ -10,17 +10,17 @@ module DbMod
       # Provides convenience extensions for statement and
       # prepared methods that return only a single result,
       # row, or column. The normal way to access this functionality
-      # is via {ConfigurableMethod#single}, which is available
+      # is via {MethodConfiguration#single}, which is available
       # when defining a statement method or prepared method:
       #
-      #  def_statement(:a, 'SELECT name FROM a WHERE id=$1').single(:value)
-      #  def_prepared(:b, 'SELECT id FROM b WHERE value > $min').single(:column)
-      #  def_prepared(:c, 'SELECT * FROM c WHERE id = $id').single(:row)
+      #  def_statement(:a, 'SELECT name FROM a WHERE id=$1') { single(:value) }
+      #  def_prepared(:b, 'SELECT id FROM b WHERE x > $y') { single(:column) }
+      #  def_prepared(:c, 'SELECT * FROM c WHERE id = $id') { single(:row) }
       #
       #  def do_stuff
-      #    a # => "foo"
-      #    b # => ['1','2','3',...]
-      #    c # => Hash
+      #    a(1)    # => "foo"
+      #    b(y: 2) # => ['1','2','3',...]
+      #    c id: 3 # => Hash
       #  end
       #
       # +.single(:row)+ and +.single(:value)+ will return the first
@@ -30,10 +30,7 @@ module DbMod
       # instead of returning +nil+, use +.single(:row!)+ or
       # +.single(:value!)+.
       module Single
-        # For process_method_results
-        Configuration = DbMod::Statements::Configuration
-
-        # List of allowed parameters for {#single},
+        # List of allowed parameters for {MethodConfiguration#single},
         # and the methods used to process them.
         COERCERS = {
           value: Single::Value,
@@ -43,19 +40,16 @@ module DbMod
           column: Single::Column
         }
 
-        # Extend a method so that only some singular part of
-        # the SQL result set is returned.
-        # See above for more details.
+        # Extend the given method definition with additional
+        # result coercion.
         #
-        # @param mod [Module] module where the method has been defined
-        # @param name [Symbol] method name
-        # @param type [Symbol] one of {SINGLE_TYPES}
-        def self.extend_method(mod, name, type)
-          unless COERCERS.key? type
-            fail ArgumentError, "#{type} not in #{COERCERS.keys.join ', '}"
-          end
+        # @param definition [Proc] base method definition
+        # @param config [MethodConfiguration] method configuration
+        def self.extend(definition, config)
+          type = config[:single]
+          return definition if type.nil?
 
-          Configuration.process_method_results(mod, name, COERCERS[type])
+          Configuration.attach_result_processor definition, COERCERS[type]
         end
       end
     end

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

@@ -13,7 +13,7 @@ module DbMod
         #  end
         module Column
           # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
+          # {DbMod::Statements::Configuration.attach_result_processor} as the
           # +wrapper+ function, where it will return an array of the first
           # value from every row in the result set.
           #

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

@@ -14,7 +14,7 @@ module DbMod
         #  end
         module RequiredRow
           # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
+          # {DbMod::Statements::Configuration.attach_result_processor} as the
           # +wrapper+ function, where it will return the first row of the
           # result set, or raise an exception if exactly one row is not
           # returned.

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

@@ -14,7 +14,7 @@ module DbMod
         #  end
         module RequiredValue
           # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
+          # {DbMod::Statements::Configuration.attach_result_processor} as the
           # +wrapper+ function, where it will return the first column of the
           # first row of the result set, or fail if anything other than
           # exactly one row is returned.

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

@@ -14,7 +14,7 @@ module DbMod
         #  end
         module Row
           # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
+          # {DbMod::Statements::Configuration.attach_result_processor} as the
           # +wrapper+ function, where it will return the first row of the
           # result set, or +nil+ if the result set is empty.
           #

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

@@ -13,7 +13,7 @@ module DbMod
         #  end
         module Value
           # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
+          # {DbMod::Statements::Configuration.attach_result_processor} as the
           # +wrapper+ function, where it will return the first column of the
           # first row of the result set, or +nil+ if no results are returned.
           #

data/lib/db_mod/statements/parameters.rb

@@ -101,7 +101,9 @@ module DbMod
       # @return [Array] values to be passed to the prepared statement
       def self.parameter_array(expected, args)
         expected.map do |arg|
-          args[arg] || fail(ArgumentError, "missing arg #{arg}")
+          fail(ArgumentError, "missing arg #{arg}") unless args.key? arg
+
+          args[arg]
         end
       end
 

data/lib/db_mod/statements/prepared.rb

@@ -65,13 +65,13 @@ module DbMod
       # @param mod [Module] a module with {DbMod} included
       def self.define_def_prepared(mod)
         mod.class.instance_eval do
-          define_method(:def_prepared) do |name, sql|
+          define_method(:def_prepared) do |name, sql, &block|
             sql = sql.dup
             name = name.to_sym
 
             params = Parameters.parse_params! sql
             prepared_statements[name] = sql
-            Prepared.define_prepared_method(mod, name, params)
+            Prepared.define_prepared_method(mod, name, params, &block)
           end
         end
       end
@@ -119,15 +119,13 @@ module DbMod
       # @param params [Fixnum,Array<Symbol>]
       #   expected parameter count, or a list of argument names.
       #   An empty array produces a no-argument method.
-      def self.define_prepared_method(mod, name, params)
-        if params.is_a?(Array)
-          if params.empty?
-            define_no_args_prepared_method(mod, name)
-          else
-            define_named_args_prepared_method(mod, name, params)
-          end
+      # @yield dsl block may be passed, which will be evaluated using a
+      #   {Configuration::MethodConfiguration} object as scope
+      def self.define_prepared_method(mod, name, params, &block)
+        if params == []
+          define_no_args_prepared_method(mod, name, &block)
         else
-          define_fixed_args_prepared_method(mod, name, params)
+          define_prepared_method_with_args(mod, name, params, &block)
         end
       end
 
@@ -139,48 +137,22 @@ module DbMod
       #   where the method will be defined
       # @param name [Symbol] name of the method to be defined
       #   and the prepared query to be called.
-      def self.define_no_args_prepared_method(mod, name)
-        method = ->() { conn.exec_prepared(name.to_s) }
-        Configuration.def_configurable mod, name, method
-      end
-
-      # Define a method with the given name that accepts the
-      # given set of named parameters, that will call the prepared
-      # statement with the same name.
-      #
-      # @param mod [Module] {DbMod} enabled module
-      #   where the method will be defined
-      # @param name [Symbol] name of the method to be defined
-      #   and the prepared query to be called.
-      # @param params [Array<Symbol>] list of parameter names
-      def self.define_named_args_prepared_method(mod, name, params)
-        method = lambda do |*args|
-          args = Parameters.valid_named_args! params, args
-          conn.exec_prepared(name.to_s, args)
-        end
-
-        Configuration.def_configurable mod, name, method
+      # @yield dsl method configuration object may be passed
+      def self.define_no_args_prepared_method(mod, name, &block)
+        method = ->(*) { conn.exec_prepared(name.to_s) }
+        Configuration.def_configurable mod, name, method, &block
       end
 
-      # Define a method with the given name that accepts a fixed
-      # number of arguments, that will call the prepared statement
-      # with the same name.
-      #
       # @param mod [Module] {DbMod} enabled module
       #   where the method will be defined
       # @param name [Symbol] name of the method to be defined
       #   and the prepared query to be called.
-      # @param count [Fixnum] arity of the defined method,
-      #   the number of parameters that the prepared statement
-      #   requires
-      def self.define_fixed_args_prepared_method(mod, name, count)
-        method = lambda do |*args|
-          Parameters.valid_fixed_args!(count, args)
-
-          conn.exec_prepared(name.to_s, args)
-        end
-
-        Configuration.def_configurable(mod, name, method)
+      # @param params [Fixnum,Array<Symbol>]
+      #   expected parameter count, or a list of argument names.
+      #   An empty array produces a no-argument method.
+      def self.define_prepared_method_with_args(mod, name, params, &block)
+        method = ->(*args) { conn.exec_prepared(name.to_s, args) }
+        Configuration.def_configurable(mod, name, method, params, &block)
       end
 
       # Adds +prepared_statements+ to a module. This list of named

data/lib/db_mod/statements/statement.rb

@@ -61,12 +61,12 @@ module DbMod
       # @param mod [Module] a module with {DbMod} included
       def self.define_def_statement(mod)
         mod.class.instance_eval do
-          define_method(:def_statement) do |name, sql|
+          define_method(:def_statement) do |name, sql, &block|
             sql = sql.dup
             name = name.to_sym
 
             params = Parameters.parse_params! sql
-            Statement.define_statement_method(mod, name, params, sql)
+            Statement.define_statement_method(mod, name, params, sql, &block)
           end
         end
       end
@@ -80,62 +80,15 @@ module DbMod
       # @param params [Fixnum,Array<Symbol>]
       #   expected parameter count, or a list of argument names.
       #   An empty array produces a no-argument method.
-      def self.define_statement_method(mod, name, params, sql)
-        if params.is_a?(Array)
-          if params.empty?
-            define_no_args_statement_method(mod, name, sql)
-          else
-            define_named_args_statement_method(mod, name, params, sql)
-          end
+      # @yield dsl block may be passed, which will be evaluated using a
+      #   {Configuration::MethodConfiguration} object as scope
+      def self.define_statement_method(mod, name, params, sql, &block)
+        if params == []
+          Configuration.def_configurable(mod, name, ->(*) { query sql }, &block)
         else
-          define_fixed_args_statement_method(mod, name, params, sql)
-        end
-      end
-
-      # Define a no-argument method with the given name
-      # that will execute the given sql statement and return
-      # the result.
-      #
-      # @param mod [Module] {DbMod} enabled module
-      #   where the method will be defined
-      # @param name [Symbol] name of the method to be defined
-      # @param sql [String] parameterless SQL statement to execute
-      def self.define_no_args_statement_method(mod, name, sql)
-        Configuration.def_configurable mod, name, ->() { query(sql) }
-      end
-
-      # Define a method with the given name, that accepts the
-      # given set of named parameters that will be used to execute
-      # the given SQL query.
-      #
-      # @param mod [Module] {DbMod} enabled module
-      # @param name [Symbol] name of the method to be defined
-      # @param params [Array<Symbol>] parameter names and order
-      def self.define_named_args_statement_method(mod, name, params, sql)
-        method = lambda do |*args|
-          args = Parameters.valid_named_args! params, args
-          conn.exec_params(sql, args)
+          method = ->(*args) { conn.exec_params(sql, args) }
+          Configuration.def_configurable(mod, name, method, params, &block)
         end
-
-        Configuration.def_configurable mod, name, method
-      end
-
-      # Define a method with the given name that accepts a fixed number
-      # of arguments, that will be used to execute the given SQL query.
-      #
-      # @param mod [Module] {DbMod} enabled module where the method
-      #   will be defined
-      # @param name [Symbol] name of the method to be defined
-      # @param count [Fixnum] arity of the defined method,
-      #   the number of parameters that the SQL statement requires
-      def self.define_fixed_args_statement_method(mod, name, count, sql)
-        method = lambda do |*args|
-          Parameters.valid_fixed_args!(count, args)
-
-          conn.exec_params(sql, args)
-        end
-
-        Configuration.def_configurable mod, name, method
       end
     end
   end

data/lib/db_mod/version.rb

@@ -1,5 +1,5 @@
 # Version information
 module DbMod
   # The current version of db_mod.
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

data/spec/db_mod/statements/configuration/as/csv_spec.rb

@@ -6,8 +6,8 @@ describe DbMod::Statements::Configuration::As::Csv do
     Module.new do
       include DbMod
 
-      def_statement(:statement, 'SELECT a, b FROM foo').as(:csv)
-      def_prepared(:prepared, 'SELECT a, b FROM bar').as(:csv)
+      def_statement(:statement, 'SELECT a, b FROM foo') { as(:csv) }
+      def_prepared(:prepared, 'SELECT a, b FROM bar') { as(:csv) }
     end.create(db: 'testdb')
   end
 

data/spec/db_mod/statements/configuration/as/json_spec.rb

@@ -6,8 +6,20 @@ describe DbMod::Statements::Configuration::As::Json do
     Module.new do
       include DbMod
 
-      def_statement(:statement, 'SELECT a, b FROM foo').as(:json)
-      def_prepared(:prepared, 'SELECT a, b FROM bar').as(:json)
+      def_statement(:statement, 'SELECT a, b FROM foo') { as(:json) }
+      def_prepared(:prepared, 'SELECT a, b FROM bar') { as(:json) }
+
+      def_statement(
+        :single,
+        'SELECT * FROM foo WHERE a = $1'
+      ) { single(:row).as(:json) }
+
+      def_statement(
+        :single!,
+        'SELECT * FROM foo WHERE a = $1'
+      ) { single(:row!).as(:json) }
+
+      def_statement(:col, 'SELECT a FROM foo') { single(:column).as(:json) }
     end.create(db: 'testdb')
   end
 
@@ -35,4 +47,19 @@ describe DbMod::Statements::Configuration::As::Json do
       end
     end
   end
+
+  it 'can be chained with single(:row)' do
+    result = [{ 'a' => '1', 'b' => '2' }]
+    expected = '{"a":"1","b":"2"}'
+
+    expect(@conn).to receive(:exec_params).exactly(2).times.and_return(result)
+    expect(subject.single(1)).to eq(expected)
+    expect(subject.single!(2)).to eq(expected)
+  end
+
+  it 'can be chained with single(:column)' do
+    result = [{ 'a' => '1' }, { 'a' => '2' }, { 'a' => '3' }]
+    expect(@conn).to receive(:query).and_return(result)
+    expect(subject.col).to eq('["1","2","3"]')
+  end
 end