db_mod 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1fe4bb1c7e19c817bad5e788d2cd626ce909ba0d
-  data.tar.gz: 3bb72d90d2387e7f8e7373f41d390f779b0cc819
+  metadata.gz: 9f9ed4ad3824fbe0a2b09444c5aa9b4dde35ee94
+  data.tar.gz: 4a70f5c7416895da2fb5cc58608d5aaabeb610ce
 SHA512:
-  metadata.gz: b9318f1de5b1fe4c8189c7bc1d03cb42533316175411bb33440824e0051dd33da5c4c64595658e95d001b8995fca4fa4e4c67d24570e229e48418d4cfd346f5e
-  data.tar.gz: fe369f08a3c480d4c5d3322c35b575ecccb5cbada2b7db33f5b05a3fd692ad5d17cbc9580fabf2356e936b7886d28d1cc7d322e605ad3f6f3f2b04ad5523fa1e
+  metadata.gz: 22b0da036c7e04ee7f70d21c79a5dcb70db35895485ee8b1a9bae150a258be8a5c529023c0b71c1f6e74c80ddb911d8f0915d4ef341db88286c48bfaab8bf182
+  data.tar.gz: 23a8967663138b1b10d83d994b7b397dd00b8c536663d1a58b1227f6434a47334d7f1d77fcb58a86048d5bfcdbf30e8ab6800eb818d9f37116083cce35b2c0e1

data/.yardopts

@@ -0,0 +1 @@
+--private --protected lib/**/*.rb - *.md LICENSE

data/CHANGELOG.md

@@ -1,7 +1,13 @@
+0.0.4 (2015-10-15)
+==================
+
+* Adds `def_prepared/statement.single(:value/:row/:column)` - [@dslh](https://github.com/dslh).
+* Adds `.as(:json)` to go with `.as(:csv)` - [@dslh](https://github.com/dslh).
+
 0.0.3 (2015-10-13)
 ==================
 
-* Configurable method framework. Adds `def_prepared/statement.as(:csv)` - [@dslh](https://github.com/dslh)
+* Configurable method framework. Adds `def_prepared/statement.as(:csv)` - [@dslh](https://github.com/dslh).
 
 0.0.2 (2015-10-12)
 ==================

data/README.md

@@ -2,6 +2,13 @@
 
 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)
+
+[Rubydoc.info documentation](http://www.rubydoc.info/gems/db_mod)
+
 ## Description
 
 The `db_mod` gem is a simple framework that helps you organise your
@@ -187,19 +194,60 @@ 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 argument and result processing. For
-now only `.as(:csv)` is supported, which will cause the method to format
-the SQL result set as a CSV string.
+and prepared methods with additional result processing. A simple
+chained-method syntax is used
+
+##### 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
+formatted as either a CSV document or an array of JSON objects, respectively.
 
 ```ruby
-module CsvReports
+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)
 end
 
-include CsvReports
+include Reports
 db_connect db: 'testdb'
 
 foo(id: 1) # => "a,b\n1,2\n3,4\n..."
+bar(2) # => '[{"c":"5","d":"6"},...]'
+```
+
+##### Queries returning one row, column or value
+
+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.
+
+```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)
+end
+
+# ...
+
+user(1) # => { "id" => "1", "name" => "username" }
+name(1) # => "username"
+ids # => ['1', '2', '3', ...]
+```
+
+When no results are returned, `:column` returns `[]` while  `:row` and
+`:value` will return `nil`. To raise an exception instead of returning
+`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!)
+
+a # => nil
+b # => fail
 ```

data/lib/db_mod/exceptions/bad_method_configuration.rb

@@ -0,0 +1,11 @@
+require_relative 'base'
+
+module DbMod
+  module Exceptions
+    # Raised when an attempt is made to configure
+    # a dynamically defined statement or prepared method
+    # in an invalid way.
+    class BadMethodConfiguration < Base
+    end
+  end
+end

data/lib/db_mod/exceptions/no_results.rb

@@ -0,0 +1,12 @@
+require_relative 'base'
+
+module DbMod
+  module Exceptions
+    # Raised by a statement or prepared method that
+    # has been configured using {ConfigurableMethod#single},
+    # when a result set expected to contain at least one
+    # result does not.
+    class NoResults < Base
+    end
+  end
+end

data/lib/db_mod/exceptions/too_many_results.rb

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

data/lib/db_mod/exceptions.rb

@@ -1,6 +1,9 @@
-require_relative 'exceptions/connection_not_set'
 require_relative 'exceptions/already_in_transaction'
+require_relative 'exceptions/bad_method_configuration'
+require_relative 'exceptions/connection_not_set'
 require_relative 'exceptions/duplicate_statement_name'
+require_relative 'exceptions/no_results'
+require_relative 'exceptions/too_many_results'
 
 module DbMod
   # Non-standard errors raised by db_mod

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

@@ -0,0 +1,39 @@
+module DbMod
+  module Statements
+    module Configuration
+      module As
+        # Coercer which converts an SQL result set
+        # into a string formatted as a CSV document.
+        # 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 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
+          # from the result set.
+          #
+          # @param results [Object] SQL result set
+          # @return [String] a CSV formatted document
+          def self.call(results)
+            headers = nil
+            CSV.generate do |csv|
+              results.each do |row|
+                csv << (headers = row.keys) unless headers
+
+                csv << headers.map { |col| row[col] }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module DbMod
+  module Statements
+    module Configuration
+      module As
+        # Coercer which converts an SQL result set
+        # into a string formatted as a JSON array.
+        # 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 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.
+          #
+          # @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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+require_relative 'as/csv'
+require_relative 'as/json'
+
+module DbMod
+  module Statements
+    module Configuration
+      # Contains coercers and other functions that allow
+      # 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},
+      # 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}.
+        COERCERS = {
+          csv: As::Csv,
+          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.
+        #
+        # @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
+
+          Configuration.process_method_results(mod, name, COERCERS[type])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+require_relative 'as'
+require_relative 'single'
+
+module DbMod
+  module Statements
+    module Configuration
+      # Encapsulates a method that has just been defined
+      # via the dsl exposed in {DbMod::Statements} so that
+      # it can be extended with additional processing such
+      # as result coercion.
+      #
+      # The pattern here is something similar to rack's middleware.
+      # Calling any of the extension methods below will replace
+      # the original method defined by +def_prepared+ or +def_statement+
+      # with a wrapper function that may perform processing on given
+      # arguments, pass them to the original function, then perform
+      # additional processing on the result.
+      class ConfigurableMethod
+        # Encapsulate a method that has been newly defined
+        # by a {DbMod} dsl function, for additional configuration.
+        #
+        # @param mod [Module] the {DbMod} enabled module
+        #   where the method was defined
+        # @param name [Symbol] the method name
+        def initialize(mod, name)
+          @mod = mod
+          @name = name
+          @already_called = {}
+        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)
+          called! :as
+
+          Configuration::As.extend_method(@mod, @name, 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 {SINGLE_TYPES}
+        # @return [self]
+        def single(type)
+          called! :single
+
+          Configuration::Single.extend_method(@mod, @name, type)
+
+          self
+        end
+
+        private
+
+        # Guard method which asserts that a configuration method
+        # may not be called more than once, or else raises
+        # {DbMod::Exceptions::BadMethodConfiguration}.
+        #
+        # @param method [Symbol] method being called
+        def called!(method)
+          if @already_called[method]
+            fail Exceptions::BadMethodConfiguration, "#{method} already called"
+          end
+
+          @already_called[method] = true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module DbMod
+  module Statements
+    module Configuration
+      module Single
+        # Wrapper for a statement or prepared method that returns
+        # an array of the values from the first value of every row
+        # returned by the SQL statement.
+        #
+        #  def_statement(:a, 'SELECT a FROM b').single(:column)
+        #
+        #  def do_stuff
+        #    a # => ['a', 'b', 'c']
+        #  end
+        module Column
+          # Enables this module to be passed to
+          # {DbMod::Statements::Configuration.process_method_results} as the
+          # +wrapper+ function, where it will return an array of the first
+          # value from every row in the result set.
+          #
+          # @param results [Object] SQL result set
+          # @return [Array<String>] an array of values from the first column
+          def self.call(results)
+            results.map { |row| row[row.keys.first] }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module DbMod
+  module Statements
+    module Configuration
+      module Single
+        # Wrapper for a statement or prepared method that returns
+        # only the first row of the result set as a hash, to save
+        # manual unboxing. Raises an error unless exactly one row
+        # is returned.
+        #
+        #  def_statement(:a, 'SELECT a, b FROM foo').single(:row)
+        #
+        #  def do_stuff
+        #    a # => { 'a' => '1', 'b' => '2'
+        #  end
+        module RequiredRow
+          # Enables this module to be passed to
+          # {DbMod::Statements::Configuration.process_method_results} 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.
+          #
+          # @param results [Object] SQL result set
+          # @return [Hash<String,String>]
+          #   the first row of the SQL result set returned by the query
+          def self.call(results)
+            fail DbMod::Exceptions::NoResults unless results.any?
+            fail DbMod::Exceptions::TooManyResults if results.count > 1
+
+            results[0]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module DbMod
+  module Statements
+    module Configuration
+      module Single
+        # Wrapper for a statement or prepared method that returns
+        # the first column of the first returned row. Strictly enforces
+        # that exactly one row should be returned by the SQL result, and
+        # will fail if zero or more than one row is returned.
+        #
+        #  def_statement(:a, 'SELECT 1').single(:value!)
+        #
+        #  def do_stuff
+        #    a # => '1'
+        #  end
+        module RequiredValue
+          # Enables this module to be passed to
+          # {DbMod::Statements::Configuration.process_method_results} 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.
+          #
+          # @param results [Object] SQL result set
+          # @return [String] the first column of the first returned row
+          def self.call(results)
+            fail DbMod::Exceptions::NoResults unless results.any?
+            fail DbMod::Exceptions::TooManyResults if results.count > 1
+
+            row = results[0]
+            row[row.keys.first]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module DbMod
+  module Statements
+    module Configuration
+      module Single
+        # Wrapper for a statement or prepared method that returns
+        # only the first row of the result set as a hash, to save
+        # manual unboxing. Returns +nil+ if the query returns no
+        # results.
+        #
+        #  def_statement(:a, 'SELECT a, b FROM foo').single(:row)
+        #
+        #  def do_stuff
+        #    a # => { 'a' => '1', 'b' => '2'
+        #  end
+        module Row
+          # Enables this module to be passed to
+          # {DbMod::Statements::Configuration.process_method_results} as the
+          # +wrapper+ function, where it will return the first row of the
+          # result set, or +nil+ if the result set is empty.
+          #
+          # @param results [Object] SQL result set
+          # @return [Hash<String,String>,nil]
+          #   the first row of the SQL result set returned by the query
+          def self.call(results)
+            return nil unless results.any?
+
+            results[0]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+module DbMod
+  module Statements
+    module Configuration
+      module Single
+        # Wrapper for a statement or prepared method that
+        # returns the first column of the first returned row,
+        # or +nil+ if no rows are returned by the query.
+        #
+        #  def_statement(:a, 'SELECT 1').single(:value)
+        #
+        #  def do_stuff
+        #    a # => '1'
+        #  end
+        module Value
+          # Enables this module to be passed to
+          # {DbMod::Statements::Configuration.process_method_results} 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.
+          #
+          # @param results [Object] SQL result set
+          # @return [String,nil] the first column of the first returned row
+          def self.call(results)
+            return nil unless results.any?
+
+            row = results[0]
+            row[row.keys.first]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+require_relative 'single/value'
+require_relative 'single/required_value'
+require_relative 'single/row'
+require_relative 'single/required_row'
+require_relative 'single/column'
+
+module DbMod
+  module Statements
+    module Configuration
+      # 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
+      # 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 do_stuff
+      #    a # => "foo"
+      #    b # => ['1','2','3',...]
+      #    c # => Hash
+      #  end
+      #
+      # +.single(:row)+ and +.single(:value)+ will return the first
+      # row or the first value of the first row respectively, or +nil+
+      # if no results are found. To generate a
+      # {DbMod::Exceptions::NoResults} failure
+      # 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},
+        # and the methods used to process them.
+        COERCERS = {
+          value: Single::Value,
+          value!: Single::RequiredValue,
+          row: Single::Row,
+          row!: Single::RequiredRow,
+          column: Single::Column
+        }
+
+        # Extend a method so that only some singular part of
+        # the SQL result set is returned.
+        # See above for more details.
+        #
+        # @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
+
+          Configuration.process_method_results(mod, name, COERCERS[type])
+        end
+      end
+    end
+  end
+end

data/lib/db_mod/statements/configuration.rb

@@ -0,0 +1,48 @@
+module DbMod
+  module Statements
+    # Provides additional functionality to statement and
+    # prepared methods, allowing additional processing of
+    # arguments and results using the dsl extensions
+    # exposed via {ConfigurableMethod}.
+    module Configuration
+      # Used by submodules to when defining a method as declared by
+      # +def_statement+ or +def_prepared+. Wraps the defined method
+      # so that it may be extended with additional argument and
+      # result processing.
+      #
+      # @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)
+        mod.instance_eval { define_method(name, definition) }
+
+        ConfigurableMethod.new(mod, name)
+      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.
+      #
+      # @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)
+        end
+      end
+    end
+  end
+end
+
+require_relative 'configuration/configurable_method'

data/lib/db_mod/statements/parameters.rb

@@ -78,7 +78,7 @@ module DbMod
       # Assert that the given parameter list is an array
       # containing a single hash of named parameter values.
       #
-      # Raises {ArgumentError} otherwise.
+      # Raises +ArgumentError+ otherwise.
       #
       # @param args [Array<Hash<Symbol>>] method arguments being validated
       def self.wrapped_hash!(args)

data/lib/db_mod/statements/prepared.rb

@@ -10,23 +10,18 @@ module DbMod
     # For statements that are not prepared ahead of execution,
     # see +def_statement+ in {DbMod::Statements::Statement}.
     #
-    # def_prepared
-    # ------------
-    #
     # +def_prepared+ accepts two parameters:
-    # * `name` [Symbol]: The name that will be given to
+    # * *name* [Symbol]: The name that will be given to
     #   the prepared statement. A method will also be defined
     #   on the module with the same name which will call the
     #   statement and return the result.
-    # * `sql` [String]: The SQL statement to be prepared.
+    # * *sql* [String]: The SQL statement to be prepared.
     #   Parameters may be declared using the $ symbol followed
-    #   by a number ($1, $2, $3) or a name ($one, $two, $under_scores).
+    #   by a number +($1, $2, $3)+ or a name +($one, $two, $a_b)+.
     #   The two styles may not be mixed in the same statement.
     #   The defined function can then be passed parameters
     #   that will be used when the statement is executed.
     #
-    # ### example
-    #
     #  module MyModule
     #    include DbMod
     #
@@ -146,7 +141,7 @@ module DbMod
       #   and the prepared query to be called.
       def self.define_no_args_prepared_method(mod, name)
         method = ->() { conn.exec_prepared(name.to_s) }
-        Statements.configurable_method mod, name, method
+        Configuration.def_configurable mod, name, method
       end
 
       # Define a method with the given name that accepts the
@@ -164,7 +159,7 @@ module DbMod
           conn.exec_prepared(name.to_s, args)
         end
 
-        Statements.configurable_method mod, name, method
+        Configuration.def_configurable mod, name, method
       end
 
       # Define a method with the given name that accepts a fixed
@@ -185,7 +180,7 @@ module DbMod
           conn.exec_prepared(name.to_s, args)
         end
 
-        Statements.configurable_method(mod, name, method)
+        Configuration.def_configurable(mod, name, method)
       end
 
       # Adds +prepared_statements+ to a module. This list of named

data/lib/db_mod/statements/statement.rb

@@ -10,20 +10,38 @@ module DbMod
     # To declare prepared statements, see +def_prepared+
     # in {DbMod::Statements::Prepared}.
     #
-    # def_statement
-    # -------------
-    #
     # +def_statement+ accepts two parameters:
-    # * `name` [Symbol]: The name that will be given to the
+    # * *name* [Symbol]: The name that will be given to the
     #   method that can be used to execute the SQL statement
     #   and return the result.
-    # * `sql` [String]: The SQL statement that shoul be executed
+    # * *sql* [String]: The SQL statement that shoul be executed
     #   when the method is called. Parameters may be declared
-    #   using the $ symbol followed by a number ($1, $2, $3) or
-    #   a name ($one, $two, $under_scores). The two styles may
+    #   using the $ symbol followed by a number +($1, $2, $3)+ or
+    #   a name +($one, $two, $under_scores)+. The two styles may
     #   not be mixed in the same statement. The defined function
     #   can then be passed parameters that will be used to fill
     #   in the statement before execution.
+    #
+    #  module MyModule
+    #    include DbMod
+    #
+    #    def_prepared :my_prepared, <<-SQL
+    #      SELECT *
+    #        FROM stuff
+    #       WHERE a = $1 AND b = $2
+    #    SQL
+    #
+    #    def_prepared :my_named_prepared, <<-SQL
+    #      SELECT *
+    #        FROM stuff
+    #       WHERE a = $a AND b = $b
+    #    SQL
+    #  end
+    #
+    #  include MyModule
+    #  db_connect db: 'mydb'
+    #  my_prepared(1,2)
+    #  my_named_prepared(a: 1, b: 2)
     module Statement
       # Defines a module-specific +def_statement+ function
       # for a module that has just had {DbMod} included.
@@ -83,7 +101,7 @@ module DbMod
       # @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)
-        Statements.configurable_method mod, name, ->() { query(sql) }
+        Configuration.def_configurable mod, name, ->() { query(sql) }
       end
 
       # Define a method with the given name, that accepts the
@@ -99,7 +117,7 @@ module DbMod
           conn.exec_params(sql, args)
         end
 
-        Statements.configurable_method mod, name, method
+        Configuration.def_configurable mod, name, method
       end
 
       # Define a method with the given name that accepts a fixed number
@@ -117,7 +135,7 @@ module DbMod
           conn.exec_params(sql, args)
         end
 
-        Statements.configurable_method mod, name, method
+        Configuration.def_configurable mod, name, method
       end
     end
   end

data/lib/db_mod/statements.rb

@@ -1,4 +1,4 @@
-require_relative 'statements/configurable_method'
+require_relative 'statements/configuration'
 require_relative 'statements/statement'
 require_relative 'statements/prepared'
 
@@ -16,42 +16,5 @@ module DbMod
       DbMod::Statements::Prepared.setup(mod)
       DbMod::Statements::Statement.setup(mod)
     end
-
-    # Used by submodules to when defining a method as declared by
-    # +def_statement+ or +def_prepared+. Wraps the defined method
-    # so that it may be extended with additional argument and
-    # result processing.
-    #
-    # @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.configurable_method(mod, name, definition)
-      mod.instance_eval { define_method(name, definition) }
-
-      ConfigurableMethod.new(mod, name)
-    end
-
-    # Used by {ConfigurableMethod} (and associated code) to wrap a defined
-    # statement method or prepared method with additional parameter or result
-    # processing. A wrapper method definition should be provided, which will
-    # be called in place of the original method. It will be called with the
-    # original method proc as a first argument followed by the original
-    # method arguments (before +DbMod+ has made any attempt to validate them!).
-    # It is expected to yield to the original proc at some point, although it
-    # is allowed to do whatever it wants with the results before returning them.
-    #
-    # @param mod [Module] the module where the method has been defined
-    # @param name [Symbol] the method name
-    # @param wrapper [Proc] a function which will be used to wrap the
-    #   original method definition
-    def self.extend_method(mod, name, wrapper)
-      mod.instance_eval do
-        wrapped = instance_method(name)
-
-        define_method name, ->(*args) { wrapper.call wrapped.bind(self), *args }
-      end
-    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.3'
+  VERSION = '0.0.4'
 end

data/lib/db_mod.rb

@@ -1,8 +1,10 @@
 require 'pg'
-require_relative 'db_mod/exceptions'
-require_relative 'db_mod/transaction'
+
 require_relative 'db_mod/create'
+require_relative 'db_mod/exceptions'
 require_relative 'db_mod/statements'
+require_relative 'db_mod/transaction'
+require_relative 'db_mod/version'
 
 # This is the foundation module for enabling db_mod
 # support in an application. Including this module

data/spec/db_mod/{as → statements/configuration/as}/csv_spec.rb

@@ -1,14 +1,14 @@
 require 'spec_helper'
 require 'csv'
 
-describe DbMod::As::Csv do
+describe DbMod::Statements::Configuration::As::Csv do
   subject do
     Module.new do
       include DbMod
 
       def_statement(:statement, 'SELECT a, b FROM foo').as(:csv)
-      def_prepared(:prepared, 'SELECT c, d FROM bar').as(:csv)
-    end
+      def_prepared(:prepared, 'SELECT a, b FROM bar').as(:csv)
+    end.create(db: 'testdb')
   end
 
   before do
@@ -25,11 +25,12 @@ describe DbMod::As::Csv do
       it 'coerces results to csv' do
         expect(@conn).to receive(exec_type).and_return([
           { 'a' => '1', 'b' => '2' },
-          { 'a' => '3', 'b' => '4' }
+          { 'a' => '3', 'b' => '4' },
+          { 'a' => nil, 'b' => '5' }
         ])
 
-        csv = subject.create(db: 'testdb').send(method_type)
-        expect(csv).to eq("a,b\n1,2\n3,4\n")
+        csv = subject.send(method_type)
+        expect(csv).to eq("a,b\n1,2\n3,4\n,5\n")
       end
     end
   end

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

@@ -0,0 +1,38 @@
+require 'spec_helper'
+require 'json'
+
+describe DbMod::Statements::Configuration::As::Json do
+  subject 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)
+    end.create(db: 'testdb')
+  end
+
+  before do
+    @conn = instance_double 'PGconn'
+    allow(@conn).to receive(:prepare)
+    allow(PGconn).to receive(:connect).and_return @conn
+  end
+
+  {
+    statement: :query,
+    prepared: :exec_prepared
+  }.each do |method_type, exec_type|
+    context "#{method_type} methods" do
+      it 'coerces results to json' do
+        expect(@conn).to receive(exec_type).and_return([
+          { 'a' => '1', 'b' => 'foo' },
+          { 'a' => '2', 'b' => nil }
+        ])
+
+        json = subject.send(method_type)
+        expect(json).to eq(
+          '[{"a":"1","b":"foo"},{"a":"2","b":null}]'
+        )
+      end
+    end
+  end
+end

data/spec/db_mod/statements/configuration/as_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+# See submodules for more
+describe DbMod::Statements::Configuration::As do
+  it 'disallows unknown coercions' do
+    expect do
+      Module.new do
+        include DbMod
+
+        def_statement(:foo, 'SELECT 1').as(:lolwut)
+      end
+    end.to raise_exception ArgumentError
+  end
+
+  it 'disallows multiple coercions' do
+    expect do
+      Module.new do
+        include DbMod
+
+        def_statement(:foo, 'SELECT 1').as(:json).as(:csv)
+      end
+    end.to raise_exception DbMod::Exceptions::BadMethodConfiguration
+  end
+end

data/spec/db_mod/statements/configuration/single_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe DbMod::Statements::Configuration::Single do
+  subject do
+    Module.new do
+      include DbMod
+
+      def_statement(:v, 'SELECT a FROM foo').single(:value)
+      def_prepared(:v!, 'SELECT c FROM d WHERE e = $f').single(:value!)
+
+      def_prepared(:r, 'SELECT a, b FROM foo WHERE c = $1').single(:row)
+      def_statement(:r!, 'SELECT a, b FROM foo').single(:row!)
+
+      def_statement(:c, 'SELECT a FROM foo WHERE c > $min').single(:column)
+    end.create(db: 'testdb')
+  end
+
+  before do
+    @conn = instance_double 'PGconn'
+    allow(@conn).to receive(:prepare)
+    allow(PGconn).to receive(:connect).and_return(@conn)
+  end
+
+  context ':value, :value!' do
+    it 'extracts single values' do
+      expect(@conn).to receive(:query).and_return([{ 'a' => '1' }])
+      expect(subject.v).to eq('1')
+
+      expect(@conn).to receive(:exec_prepared).and_return([{ 'c' => '2' }])
+      expect(subject.v! f: 1).to eq('2')
+    end
+
+    it 'can assert a single result was returned' do
+      expect(@conn).to receive(:exec_prepared).and_return([])
+      expect { subject.v! f: 2 }.to raise_exception DbMod::Exceptions::NoResults
+
+      expect(@conn).to receive(:exec_prepared).and_return([
+        { 'c' => '3' },
+        { 'c' => '4' }
+      ])
+      expect { subject.v! f: 3 }.to raise_exception(
+        DbMod::Exceptions::TooManyResults
+      )
+    end
+  end
+
+  context ':row, :row!' do
+    it 'extracts single rows' do
+      result = [{ 'a' => '1', 'b' => '2' }]
+      expected = { 'a' => '1', 'b' => '2' }
+
+      expect(@conn).to receive(:exec_prepared).and_return(result)
+      expect(subject.r(1)).to eq(expected)
+
+      expect(@conn).to receive(:query).and_return(result)
+      expect(subject.r!).to eq(expected)
+    end
+
+    it 'can assert that a single result was returned' do
+      expect(@conn).to receive(:query).and_return([])
+      expect { subject.r! }.to raise_exception DbMod::Exceptions::NoResults
+
+      expect(@conn).to receive(:query).and_return([
+        { 'a' => '3', 'b' => '4' },
+        { 'a' => '5', 'b' => '6' }
+      ])
+      expect { subject.r! }.to raise_exception(
+        DbMod::Exceptions::TooManyResults
+      )
+    end
+  end
+
+  context ':column' do
+    it 'returns the column as an array' do
+      expect(@conn).to receive(:exec_params).and_return([
+        { 'a' => '1' },
+        { 'a' => '2' },
+        { 'a' => '3' }
+      ])
+      expect(subject.c min: 1).to eq(%w(1 2 3))
+
+      expect(@conn).to receive(:exec_params).and_return([])
+      expect(subject.c min: 2).to eq([])
+    end
+  end
+
+  it 'rejects unknown types' do
+    expect do
+      Module.new do
+        include DbMod
+
+        def_statement(:a, 'SELECT 1').single(:lolwut)
+      end
+    end.to raise_exception ArgumentError
+  end
+
+  it 'cannot be called twice' do
+    expect do
+      Module.new do
+        include DbMod
+
+        def_statement(:a, 'SELECT 1').single(:row).single(:value)
+      end
+    end.to raise_exception DbMod::Exceptions::BadMethodConfiguration
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: db_mod
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Doug Hammond
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-13 00:00:00.000000000 Z
+date: 2015-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -105,6 +105,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -114,24 +115,37 @@ files:
 - Rakefile
 - db_mod.gemspec
 - lib/db_mod.rb
-- lib/db_mod/as.rb
-- lib/db_mod/as/csv.rb
 - lib/db_mod/create.rb
 - lib/db_mod/exceptions.rb
 - lib/db_mod/exceptions/already_in_transaction.rb
+- lib/db_mod/exceptions/bad_method_configuration.rb
 - lib/db_mod/exceptions/base.rb
 - lib/db_mod/exceptions/connection_not_set.rb
 - lib/db_mod/exceptions/duplicate_statement_name.rb
+- lib/db_mod/exceptions/no_results.rb
+- lib/db_mod/exceptions/too_many_results.rb
 - lib/db_mod/statements.rb
-- lib/db_mod/statements/configurable_method.rb
+- lib/db_mod/statements/configuration.rb
+- lib/db_mod/statements/configuration/as.rb
+- lib/db_mod/statements/configuration/as/csv.rb
+- lib/db_mod/statements/configuration/as/json.rb
+- lib/db_mod/statements/configuration/configurable_method.rb
+- lib/db_mod/statements/configuration/single.rb
+- lib/db_mod/statements/configuration/single/column.rb
+- lib/db_mod/statements/configuration/single/required_row.rb
+- lib/db_mod/statements/configuration/single/required_value.rb
+- lib/db_mod/statements/configuration/single/row.rb
+- lib/db_mod/statements/configuration/single/value.rb
 - lib/db_mod/statements/parameters.rb
 - lib/db_mod/statements/prepared.rb
 - lib/db_mod/statements/statement.rb
 - lib/db_mod/transaction.rb
 - lib/db_mod/version.rb
-- spec/db_mod/as/csv_spec.rb
-- spec/db_mod/as_spec.rb
 - spec/db_mod/create_spec.rb
+- spec/db_mod/statements/configuration/as/csv_spec.rb
+- spec/db_mod/statements/configuration/as/json_spec.rb
+- spec/db_mod/statements/configuration/as_spec.rb
+- spec/db_mod/statements/configuration/single_spec.rb
 - spec/db_mod/statements/prepared_spec.rb
 - spec/db_mod/statements/statement_spec.rb
 - spec/db_mod/transaction_spec.rb
@@ -162,9 +176,11 @@ signing_key:
 specification_version: 4
 summary: Declarative, modular database library framework.
 test_files:
-- spec/db_mod/as/csv_spec.rb
-- spec/db_mod/as_spec.rb
 - spec/db_mod/create_spec.rb
+- spec/db_mod/statements/configuration/as/csv_spec.rb
+- spec/db_mod/statements/configuration/as/json_spec.rb
+- spec/db_mod/statements/configuration/as_spec.rb
+- spec/db_mod/statements/configuration/single_spec.rb
 - spec/db_mod/statements/prepared_spec.rb
 - spec/db_mod/statements/statement_spec.rb
 - spec/db_mod/transaction_spec.rb

data/lib/db_mod/as/csv.rb

@@ -1,37 +0,0 @@
-module DbMod
-  module As
-    # Coercer which converts an SQL result set
-    # into a string formatted as a CSV document.
-    # 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 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.extend_method}
-      # as the +wrapper+ function, in which case it will retrieve the results
-      # and format them as a CSV document using the column names from the
-      # result set.
-      #
-      # @param wrapped_method [Method] the method that has been wrapped
-      # @param args [*] arguments expected to be passed to the wrapped method
-      # @return [String] a CSV formatted document
-      def self.call(wrapped_method, *args)
-        results = wrapped_method.call(*args)
-
-        headers = nil
-        CSV.generate do |csv|
-          results.each do |row|
-            csv << (headers = row.keys) unless headers
-
-            csv << headers.map { |col| row[col] }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/db_mod/as.rb

@@ -1,38 +0,0 @@
-require_relative 'as/csv'
-
-module DbMod
-  # Contains coercers and other functions that allow
-  # 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 {DbMod::Statements::ConfigurableMethod#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
-    # List of available result coercion methods.
-    # Only keys defined here are allowed as arguments
-    # to {DbMod::Statements::ConfigurableMethod#as}.
-    COERCERS = {
-      csv: DbMod::As::Csv
-    }
-
-    # 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.
-    #
-    # @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
-
-      Statements.extend_method(mod, name, COERCERS[type])
-    end
-  end
-end

data/lib/db_mod/statements/configurable_method.rb

@@ -1,41 +0,0 @@
-require 'db_mod/as'
-
-module DbMod
-  module Statements
-    # Encapsulates a method that has just been defined
-    # via the dsl exposed in {DbMod::Statements} so that
-    # it can be extended with additional processing such
-    # as result coercion.
-    #
-    # The pattern here is something similar to rack's middleware.
-    # Calling any of the extension methods below will replace
-    # the original method defined by +def_prepared+ or +def_statement+
-    # with a wrapper function that may perform processing on given
-    # arguments, pass them to the original function, then perform
-    # additional processing on the result.
-    class ConfigurableMethod
-      # Encapsulate a method that has been newly defined
-      # by a {DbMod} dsl function, for additional configuration.
-      #
-      # @param mod [Module] the {DbMod} enabled module
-      #   where the method was defined
-      # @param name [Symbol] the method name
-      def initialize(mod, name)
-        @mod = mod
-        @name = name
-      end
-
-      # Extend the method by converting results into a given
-      # format, using one of the coercion methods defined
-      # under {DbMod::As}.
-      #
-      # @param type [Symbol] for now, only :csv is accepted
-      # @return [self]
-      def as(type)
-        DbMod::As.extend_method(@mod, @name, type)
-
-        self
-      end
-    end
-  end
-end

data/spec/db_mod/as_spec.rb

@@ -1,14 +0,0 @@
-require 'spec_helper'
-
-# See submodules for more
-describe DbMod::As do
-  it 'disallows unknown coercions' do
-    expect do
-      Module.new do
-        include DbMod
-
-        def_statement(:foo, 'SELECT 1').as(:lolwut)
-      end
-    end.to raise_exception ArgumentError
-  end
-end