db_mod 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f9ed4ad3824fbe0a2b09444c5aa9b4dde35ee94
-  data.tar.gz: 4a70f5c7416895da2fb5cc58608d5aaabeb610ce
+  metadata.gz: e4a3d4f97f88694b3cde2f3d7d76dfdb303b9a2b
+  data.tar.gz: 9bb085e3601b0bd356b5595402006cbdf09be6fa
 SHA512:
-  metadata.gz: 22b0da036c7e04ee7f70d21c79a5dcb70db35895485ee8b1a9bae150a258be8a5c529023c0b71c1f6e74c80ddb911d8f0915d4ef341db88286c48bfaab8bf182
-  data.tar.gz: 23a8967663138b1b10d83d994b7b397dd00b8c536663d1a58b1227f6434a47334d7f1d77fcb58a86048d5bfcdbf30e8ab6800eb818d9f37116083cce35b2c0e1
+  metadata.gz: 644b2c6f41aa82dc5088ece70d6b962497308b5344c2237329df5ffc93754238ff42b5e85410eb793e8d414a23bf627a149df23f00c6a06af8f461664be6b964
+  data.tar.gz: 949071580278f7d612ceeefcc06b0b8260897cc5546ce558d207b0723943bff8a519ffd8d8fa7aeab59724774bc3dfe949df9a03665f39de74b0f4a88a9bd8ce

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+0.0.5 (2015-10-19)
+==================
+
+Breaking changes. Any statement or prepared methods with additional configuration
+should have such configuration declared in a block, rather than a method chain
+(although methods can be chained inside the method block). E.g.
+
+```ruby
+def_statement(:a, 'SELECT * FROM foo WHERE id = $1').single(:row).as(:json)
+
+# ... becomes ...
+
+def_statement(:a, 'SELECT * FROM foo WHERE id = $1') { single(:row).as(:json) }
+```
+
+* +def_statement+ and +def_prepared+ method configuration must now be supplied
+  as a block. This allows method configuration to be collected ahead of
+  method definition, and hence a bit more smarts during the method declaration
+  process - [@dslh](https://github.com/dslh).
+* `defaults` - default parameter values for statement and prepared methods - [@dslh](https://github.com/dslh).
+* `single(:row/:column).as(:json)` now works - [@dslh](https://github.com/dslh).
+
 0.0.4 (2015-10-15)
 ==================
 

data/README.md

@@ -3,9 +3,8 @@
 Database enabled modules for ruby.
 
 [![GitHub version](https://badge.fury.io/gh/dslh%2Fdb_mod.svg)](https://github.com/dslh/db_mod)
-[![Gem Version](https://badge.fury.io/rb/db_mod.svg)](https://rubygems.org/gems/db_mod)
 [![Travis CI](https://img.shields.io/travis/dslh/db_mod/master.svg)](https://travis-ci.org/dslh/db_mod)
-![Gem downloads](https://img.shields.io/gem/dt/db_mod.svg)
+[![Gem downloads](https://img.shields.io/gem/dt/db_mod.svg)](https://rubygems.org/gems/db_mod)
 
 [Rubydoc.info documentation](http://www.rubydoc.info/gems/db_mod)
 
@@ -19,7 +18,7 @@ For the moment `db_mod` only supports PostgreSQL databases via the
 `pg` gem. This gem is still in the early stages of development and no
 guarantees will be made about backwards compatibility until v0.1.0.
 
-Issues, pull requests, comments and feedback all welcomed.
+Issues, feature or pull requests, comments and feedback all welcomed.
 
 ## Usage
 
@@ -194,21 +193,22 @@ or twice during a program's execution.
 #### Configuring defined statements
 
 `db_mod` contains a simple framework for extending these statement methods
-and prepared methods with additional result processing. A simple
-chained-method syntax is used
+and prepared methods with additional result processing. A block can be
+passed to +def_prepared+ and +def_statement+ definitions, where a basic
+DSL is made available for additional method configuration.
 
 ##### JSON and CSV formatting
 
 Statement and prepared methods can be configured on declaration by using
-`.as(:csv)` and `.as(:json)`, which will convert the result set to a string
+`as(:csv)` and `as(:json)`, which will convert the result set to a string
 formatted as either a CSV document or an array of JSON objects, respectively.
 
 ```ruby
 module Reports
   include DbMod
 
-  def_prepared(:foo, 'SELECT a, b FROM foo WHERE bar_id = $id').as(:csv)
-  def_statement(:bar, 'SElECT c, d FROM bar WHERE foo_id = $1').as(:json)
+  def_prepared(:foo, 'SELECT a, b FROM foo WHERE bar_id = $id') { as(:csv) }
+  def_statement(:bar, 'SElECT c, d FROM bar WHERE foo_id = $1') { as(:json) }
 end
 
 include Reports
@@ -222,15 +222,15 @@ bar(2) # => '[{"c":"5","d":"6"},...]'
 
 To save a lot of repetetive unboxing of query results, methods that return
 only one row, or rows with only one column, or only one row with a single
-value, can be marked as such using the `.single` extension.
+value, can be marked as such using the `single` extension.
 
 ```ruby
 module Getters
   include DbMod
 
-  def_prepared(:user, 'SELECT * FROM user WHERE id = $1').single(:row)
-  def_prepared(:name, 'SELECT name FROM user WHERE id = $1').single(:value)
-  def_statement(:ids, 'SELECT id FROM user').single(:column)
+  def_prepared(:user, 'SELECT * FROM user WHERE id = $1') { single(:row) }
+  def_prepared(:name, 'SELECT name FROM user WHERE id = $1') { single(:value) }
+  def_statement(:ids, 'SELECT id FROM user') { single(:column) }
 end
 
 # ...
@@ -245,9 +245,41 @@ When no results are returned, `:column` returns `[]` while  `:row` and
 `nil`, use `:row!` and `:value!` instead.
 
 ```ruby
-def_statement(:a, 'SELECT 1 WHERE true = false').single(:value)
-def_statement(:b, 'SELECT 1 WHERE true = false').single(:value!)
+def_statement(:a, 'SELECT 1 WHERE true = false') { single(:value) }
+def_statement(:b, 'SELECT 1 WHERE true = false') { single(:value!) }
 
 a # => nil
 b # => fail
 ```
+
+##### Default parameter values
+
+Arbitrary default parameter values can be supplied using `defaults`.
+
+For methods with named parameters:
+
+```ruby
+def_statement(:a, 'SELECT * FROM foo WHERE id = $id AND y > $min') do
+  defaults min: 10
+end
+
+# ...
+
+a(id: 1) # === a(id: 1, min: 10)
+```
+
+For methods with fixed parameters:
+
+```ruby
+def_statement(:a, %(
+  SELECT *
+    FROM foo
+   WHERE x = $1
+     AND y < $2
+     AND z > $3
+)) { defaults 4, 5, 6 }
+
+# ...
+
+a(1) # === a(1, 5, 6)
+```

data/lib/db_mod/exceptions/no_results.rb

@@ -3,7 +3,8 @@ require_relative 'base'
 module DbMod
   module Exceptions
     # Raised by a statement or prepared method that
-    # has been configured using {ConfigurableMethod#single},
+    # has been configured using
+    # {Statements::Configuration::MethodConfiguration#single},
     # when a result set expected to contain at least one
     # result does not.
     class NoResults < Base

data/lib/db_mod/exceptions/too_many_results.rb

@@ -3,7 +3,8 @@ require_relative 'base'
 module DbMod
   module Exceptions
     # Raised by a statement or prepared method that
-    # has been configured using {ConfigurableMethod#single},
+    # has been configured using
+    # {Statements::Configuration::MethodConfiguration#single},
     # when a result set expected to contain not more than
     # one result, in fact, does.
     class TooManyResults < Base

data/lib/db_mod/statements/configuration.rb

@@ -3,7 +3,7 @@ module DbMod
     # Provides additional functionality to statement and
     # prepared methods, allowing additional processing of
     # arguments and results using the dsl extensions
-    # exposed via {ConfigurableMethod}.
+    # exposed via {MethodConfiguration}.
     module Configuration
       # Used by submodules to when defining a method as declared by
       # +def_statement+ or +def_prepared+. Wraps the defined method
@@ -12,37 +12,108 @@ module DbMod
       #
       # @param mod [Module] the module where the method has been declared
       # @param name [Symbol] the name of the module that has been defined
-      # @param definition [Proc] method definition
-      # @return [DbMod::Statements::ConfigurableMethod] dsl object for
-      #   further extending the method
-      def self.def_configurable(mod, name, definition)
+      # @param definition [Proc] method definition, the base function which
+      #   will perform database interaction and return an SQL result object
+      # @param params [Array<Symbol>,Fixnum] declares the parameters that
+      #   the method will accept. Can either be an array of named parameters
+      #   or a integer giving the arity of the function. +[]+ may also be
+      #   given to denote a no-argument method.
+      # @yield dsl block may be passed, which will be evaluated using a
+      #   {MethodConfiguration} object as scope
+      def self.def_configurable(mod, name, definition, params = 0, &block)
+        config = MethodConfiguration.new(&block).to_hash if block_given?
+
+        definition = attach_result_processors(definition, config) if config
+        definition = attach_param_processor(definition, params, config)
+
         mod.instance_eval { define_method(name, definition) }
+      end
+
+      private
+
+      # Attaches any required parameter processing and validation to
+      # the method definition by wrapping it in a further proc as required.
+      #
+      # @param definition [Proc] base method definition
+      # @param params see {Configuration.def_configurable}
+      # @param config [MethodConfiguration] for default values
+      # @return [Proc] a new wrapper for +definition+
+      def self.attach_param_processor(definition, params, config)
+        wrapped =
+          if params.is_a?(Array) && !params.empty?
+            define_named_args_method(definition, params)
+
+          elsif params.is_a?(Fixnum) && params > 0
+            define_fixed_args_method(definition, params)
+          else
+            ->() { instance_exec(&definition) }
+          end
+
+        return wrapped unless config
+        Defaults.extend(wrapped, params, config[:defaults])
+      end
 
-        ConfigurableMethod.new(mod, name)
+      # Wrap the given definition in a procedure that will validate any
+      # passed arguments, and transform them into an array that can be
+      # passed directly to +PGconn.exec_params+ or +PGconn.exec_prepared+.
+      #
+      # @param definition [Proc] base method definition
+      # @param params [Array<Symbol>] list of method parameter names
+      # @return [Proc] new method definition
+      def self.define_named_args_method(definition, params)
+        lambda do |*args|
+          args = Parameters.valid_named_args! params, args
+          instance_exec(*args, &definition)
+        end
       end
 
-      # Used by {ConfigurableMethod} (and associated code) to wrap a defined
-      # statement method or prepared method with additional result processing.
-      # A method should be provided, which accepts an SQL result set and
-      # returns some transformation of the results. The original method
-      # declaration will be replaced, so that the original method definition
-      # is called and the results are passed through this given method.
+      # Wrap the given definition in a procedure that will validate that
+      # the correct number of arguments has been passed, before passing them
+      # on to the original method definition.
       #
-      # @param mod [Module] the module where the method has been defined
-      # @param name [Symbol] the method name
-      # @param wrapper [#call]
-      #   a function that processes the SQL results in some way
-      def self.process_method_results(mod, name, wrapper)
-        mod.instance_eval do
-          wrapped = instance_method(name)
-
-          define_method(name, lambda do |*args|
-            wrapper.call wrapped.bind(self).call(*args)
-          end)
+      # @param definition [Proc] base method definition
+      # @param arity [Fixnum] expected number of arguments
+      # @return [Proc] new method definition
+      def self.define_fixed_args_method(definition, arity)
+        lambda do |*args|
+          Parameters.valid_fixed_args!(arity, args)
+          instance_exec(*args, &definition)
         end
       end
+
+      # Attaches any required result processing to the method definition,
+      # as may have been defined in a block passed to either of +def_statement+
+      # or +def_prepared+. This method is called before
+      # {Configuration.attach_param_processor}, so that the method definition
+      # can be wrapped by the parameter processor. In this way processors
+      # attached here are assured access to method parameters after any
+      # initial processing and validation has taken place.
+      #
+      # @param definition [Proc] base method definition
+      # @param config [MethodConfiguration] configuration declared at
+      #   method definition time
+      def self.attach_result_processors(definition, config)
+        definition = Single.extend(definition, config)
+        definition = As.extend(definition, config)
+
+        definition
+      end
+
+      # Attach a processor to the chain of result processors for a method.
+      # The pattern here is something similar to rack's middleware.
+      # A result processor is constructed with a method definition, and
+      # then acts as a replacement for the method, responding to +#call+.
+      # Subclasses must implement a +process+ method, which should accept
+      # an SQL result set (or possibly, the result of other upstream
+      # processing), perform some transform on it and return the result.
+      #
+      # @param definition [Proc] base method definition
+      # @param processor [#call] result processor
+      def self.attach_result_processor(definition, processor)
+        ->(*args) { processor.call instance_exec(*args, &definition) }
+      end
     end
   end
 end
 
-require_relative 'configuration/configurable_method'
+require_relative 'configuration/method_configuration'

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

@@ -8,16 +8,13 @@ module DbMod
       # module instance methods returning an SQL result set
       # to be extended with additional result coercion and
       # formatting. The normal way to access this functionality
-      # is via {ConfigurableMethod#as},
+      # is via {MethodConfiguration#as},
       # which is available when defining a statement method
       # or prepared method:
       #
       #  def_statement(:a, 'SELECT a, b, c FROM foo').as(:csv)
       #  def_prepared(:b, 'SELECT d, e, f FROM bar').as(:csv)
       module As
-        # For extend_method
-        Configuration = DbMod::Statements::Configuration
-
         # List of available result coercion methods.
         # Only keys defined here are allowed as arguments
         # to {DbMod::Statements::Configuration::ConfigurableMethod#as}.
@@ -26,20 +23,16 @@ module DbMod
           json: As::Json
         }
 
-        # Extend a method so that the SQL result set it
-        # returns will be coerced to the given type.
-        # See {COERCERS} for a list of defined coercion
-        # methods.
+        # 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] type to which result set should be coerced
-        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[:as]
+          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/as/csv.rb

@@ -7,17 +7,14 @@ module DbMod
         # May be enabled for a prepared method or
         # statement method using +.as(:csv)+:
         #
-        #  def_statement(:a, 'SELECT a, b FROM foo').as(:csv)
-        #  def_prepared(:b, 'SELECT b, c FROM bar').as(:csv)
+        #  def_statement(:a, 'SELECT a, b FROM foo') { as(:csv) }
+        #  def_prepared(:b, 'SELECT b, c FROM bar') { as(:csv) }
         #
         #  def do_stuff
         #    a # => "a,b\r\n1,2\r\n3,4\r\n..."
         #  end
-        module Csv
-          # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
-          # +wrapper+ function, in which case it will retrieve the results
-          # and format them as a CSV document using the column names
+        class Csv
+          # Formats the results as a CSV document using the column names
           # from the result set.
           #
           # @param results [Object] SQL result set

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

@@ -7,24 +7,22 @@ module DbMod
         # May be enabled for a prepared method or
         # statement method using +.as(:json)+:
         #
-        #  def_statement(:a, 'SELECT a, b FROM foo').as(:json)
-        #  def_prepared(:b, 'SELECT b, c FROM bar').as(:json)
+        #  def_statement(:a, 'SELECT a, b FROM foo') { as(:json) }
+        #  def_prepared(:b, 'SELECT b, c FROM bar') { as(:json) }
         #
         #  def do_stuff
         #   a # => '[{"a":"x","b":"y"},...]'
         #  end
-        module Json
-          # Enables this module to be passed to
-          # {DbMod::Statements::Configuration.process_method_results} as the
-          # +wrapper+ function, in which case it will retrieve the results
-          # and format them as a JSON string using the column names
-          # from the result set for the keys of each object.
+        class Json
+          # Formats the SQL results as a JSON object.
           #
           # @param results [Object] SQL result set
           # @return [String] a JSON formatted string
           def self.call(results)
-            # .map turns the result object into an array
-            results.map { |x| x }.to_json
+            # For compatibility with single(:row)
+            return results.to_json if results.is_a? Hash
+
+            results.to_a.to_json
           end
         end
       end

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

@@ -0,0 +1,140 @@
+module DbMod
+  module Statements
+    module Configuration
+      # Provides functionality backing the {MethodConfiguration#defaults}
+      # setting. Allows certain statement or prepared method parameters to
+      # be omitted, supplying default values where necessary:
+      #
+      #  def_statement(:a, 'SELECT id FROM a WHERE x > $y') { defaults y: 10 }
+      #  def_prepared(:b, %(
+      #    INSERT INTO b
+      #      (p, q, r)
+      #    VALUES
+      #      ($1, $2, $3)
+      #    RETURNING p, q, r
+      #  )) { defaults(5, 6).single(:row) }
+      #
+      #  # ...
+      #
+      #  a    # y => 10
+      #  a 11 # y => 11
+      #
+      #  # defaults filled in from the right
+      #  b 1, 2 # => { 'p' => '1', 'q' => '2', 'r' => '6' }
+      module Defaults
+        # Extend a method definition by wrapping it with a proc that will
+        # try to fill in any omitted arguments with given defaults.
+        #
+        # @param definition [Proc] base method definition,
+        #   with parameter validation already attached
+        # @param params [Hash<Symbol,value>,Array<value>]
+        #   see {Configuration.def_configurable}
+        # @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
+        # @return [Proc] new method definition, or the same one
+        #   if no default values have been appended
+        def self.extend(definition, params, defaults)
+          return definition if defaults.nil?
+
+          if [[], 0].include? params
+            fail ArgumentError, 'defaults not allowed for no-args methods'
+          end
+
+          if params.is_a? Array
+            extend_named_args_method(definition, defaults)
+          else
+            extend_fixed_args_method(definition, params, defaults)
+          end
+        end
+
+        private
+
+        # Extend a method with named parameters, providing default
+        # argument values for one or more parameters.
+        #
+        # @param definition [Proc] base method definition,
+        #   with parameter validation already attached
+        # @param defaults [Hash<Symbol,value>]
+        #   default parameter values
+        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)
+            instance_exec(*args, &definition)
+          end
+        end
+
+        # Fill in any missing parameter arguments using default
+        # values where available.
+        #
+        # @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)
+          # Special case when no args given.
+          args << {} if args.empty?
+
+          # If the args are weird, expect normal parameter validation
+          # to pick it up.
+          return args unless args.last.is_a? Hash
+
+          defaults.each do |arg, value|
+            args.last[arg] = value unless args.last.key? arg
+          end
+        end
+
+        # Extend a method with numbered parameters, providing
+        # default argument values for one or more parameters.
+        # Defaults will be applied, in the same left-to-right
+        # order, but at the right-hand side of the parameter
+        # list, as with normal method default arguments.
+        #
+        # @param definition [Proc] base method definition,
+        #   with parameter validation already attached
+        # @param arity [Fixnum] number of arguments expected
+        #   by the base method definition
+        # @param defaults [Array]
+        #   default parameter values
+        def self.extend_fixed_args_method(definition, arity, defaults)
+          fail ArgumentError, 'too many defaults' if defaults.size > arity
+
+          unless defaults.is_a? Array
+            fail ArgumentError, 'array expected for defaults'
+          end
+
+          arity = (arity - defaults.size)..arity
+          fail ArgumentError, 'too many defaults' if arity.min < 0
+
+          lambda do |*args|
+            Defaults.use_fixed_defaults(args, defaults, arity)
+            instance_exec(*args, &definition)
+          end
+        end
+
+        # Fill in any missing parameter arguments using default values
+        # where available.
+        #
+        # @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)
+          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
+          end
+        end
+      end
+    end
+  end
+end