db_mod 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4a3d4f97f88694b3cde2f3d7d76dfdb303b9a2b
-  data.tar.gz: 9bb085e3601b0bd356b5595402006cbdf09be6fa
+  metadata.gz: 7f28c5a3e9353c2ae963580ca872095598e926dd
+  data.tar.gz: 77b781ec8ba80b3d1adc89c6c515708f0ed5bda3
 SHA512:
-  metadata.gz: 644b2c6f41aa82dc5088ece70d6b962497308b5344c2237329df5ffc93754238ff42b5e85410eb793e8d414a23bf627a149df23f00c6a06af8f461664be6b964
-  data.tar.gz: 949071580278f7d612ceeefcc06b0b8260897cc5546ce558d207b0723943bff8a519ffd8d8fa7aeab59724774bc3dfe949df9a03665f39de74b0f4a88a9bd8ce
+  metadata.gz: f722a8ef3716308bf5232811298b4dc72cbebcb487299859b62d7acf4416f171fea909cbd282ada834d440a0fd06d718c8e7808bb4b6f28c00991694fd0c5df8
+  data.tar.gz: 4fe5b2cd8272462a7f902de07cf4210ac38aa681cbc6223418d24b7371f1da1484f5d4fa3963fe30c9fa750dd32466dd871b59d151876c80690de9e21ebfe1ca

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+0.0.6 (2015-10-21)
+==================
+
+* Procs now allowed for default parameter values - [@dslh](https://github.com/dslh).
+* Adds `returning` block to method configuration options - [@dslh](https://github.com/dslh).
+* Adds module-level `default_method_settings` for default prepared and statement method
+  configuration - [@dslh](https://github.com/dslh).
+* Fixes a bug with dynamic module method declarations - [@dslh](https://github.com/dslh).
+
 0.0.5 (2015-10-19)
 ==================
 

data/Gemfile

@@ -4,11 +4,9 @@ gemspec
 
 group :development, :test do
   gem 'byebug' unless RUBY_VERSION < '2.0.0'
-  gem 'rake'
-  gem 'redcarpet'
-  gem 'rubocop'
   gem 'guard'
   gem 'guard-bundler'
+  gem 'guard-inch'
   gem 'guard-rspec'
   gem 'guard-rubocop'
   gem 'guard-yard'

data/Guardfile

@@ -92,3 +92,7 @@ guard :bundler do
   # Assume files are symlinked from somewhere
   files.each { |file| watch(helper.real_path(file)) }
 end
+
+guard :inch, pedantic: true, private: true do
+  watch(/.+\.rb/)
+end

data/README.md

@@ -1,9 +1,12 @@
-## `db_mod`
+## DbMod
 
 Database enabled modules for ruby.
 
 [![GitHub version](https://badge.fury.io/gh/dslh%2Fdb_mod.svg)](https://github.com/dslh/db_mod)
 [![Travis CI](https://img.shields.io/travis/dslh/db_mod/master.svg)](https://travis-ci.org/dslh/db_mod)
+[![Code Climate](https://codeclimate.com/github/dslh/db_mod/badges/gpa.svg)](https://codeclimate.com/github/dslh/db_mod)
+[![Test Coverage](https://codeclimate.com/github/dslh/db_mod/badges/coverage.svg)](https://codeclimate.com/github/dslh/db_mod/coverage)
+[![Inline docs](http://inch-ci.org/github/dslh/db_mod.svg?branch=master)](http://inch-ci.org/github/dslh/db_mod)
 [![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)
@@ -20,6 +23,26 @@ guarantees will be made about backwards compatibility until v0.1.0.
 
 Issues, feature or pull requests, comments and feedback all welcomed.
 
+## Installation
+
+From the command line:
+
+```
+gem install db_mod
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem 'db_mod'
+```
+
+And then in your script:
+
+```ruby
+require 'db_mod'
+```
+
 ## Usage
 
 ### The database connection
@@ -204,6 +227,10 @@ Statement and prepared methods can be configured on declaration by using
 formatted as either a CSV document or an array of JSON objects, respectively.
 
 ```ruby
+# db_mod makes no attempt to load these
+require 'csv'
+require 'json'
+
 module Reports
   include DbMod
 
@@ -281,5 +308,149 @@ def_statement(:a, %(
 
 # ...
 
-a(1) # === a(1, 5, 6)
+a          # === a(4, 5, 6)
+a(1)       # === a(1, 5, 6)
+a(1, 2)    # === a(1, 2, 6)
+a(1, 2, 3) # === a(1, 2, 3)
+```
+
+A proc may be given as the default value for any parameter.
+The proc should accept one parameter, which will be the argument list/hash
+(depending on if the statement uses numbered or named arguments)
+and should return a single value to be used for this execution
+of the query.
+
+```ruby
+def_prepared(:default_min, %(
+  SELECT default_min
+    FROM defaults
+   WHERE foo_id = $1
+)) { single(:value) }
+
+def_prepared(:report, 'SELECT * FROM a WHERE b = $c AND d > $e') do
+  defaults min: ->(args) { default_min(args[:c]) }
+  as :json
+end
+```
+
+The above example shows how the proc will be executed using the instance
+of the `DbMod` module as scope, so statement, prepared, or other methods
+may be accessed.
+
+Note that the argument list will be partially constructed at the time it
+is received by the proc; other default values may or may not yet have been
+populated. Defaults will be populated in the order that they are declared
+using `defaults`.
+
+##### Custom method return values
+
+Besides the built-in result transformations provided by `as` and `single`,
+`db_mod` also allows arbitrary control over the return value of statement
+and prepared methods using a block provided via `returning`:
+
+```ruby
+def_prepared(:a, 'SELECT name, sound FROM animals') do
+  # Block parameter is the SQL result set
+  returning do |animals|
+    animals.map do |animal|
+      "the #{animal['name']} goes #{animal['sound']}"
+    end.join ' and '
+  end
+end
+
+def_prepared(:important_report!, 'SELECT address FROM email WHERE id = $1') do
+  # 'single' and 'as' will transform the result set
+  # before it is passed to the block
+  single(:value)
+
+  returning { |email| send_email(email, a) }
+end
+
+# Block has instance-level scope
+def send_email(address, body)
+  # ...
+end
+
+# ...
+
+important_report!(123)
+  # === send_email('ex@mp.le', 'the sheep goes baa and the cow goes moo')
+```
+
+##### Default configuration settings
+
+To save typing, modules may declare a `default_method_settings` block that will
+be applied to all following `def_statement` and `def_prepared` definitions. The
+dsl used is the same as for individual method configuration blocks.
+
+```ruby
+require 'csv'
+
+module CsvReports
+  include DbMod
+
+  default_method_settings do
+    as(:csv).returning { |csv| send_report(csv) }
+  end
+
+  def send_report(csv)
+    # ...
+  end
+
+  def_prepared(:report_a, 'SELECT * FROM report_a WHERE user_id = $1')
+  def_prepared(:report_b, 'SELECT * FROM report_b WHERE user_id = $1')
+  def_prepared(:report_c, 'SELECT * FROM report_c WHERE user_id = $1')
+end
+
+module ReportEmailer
+  include CsvReports
+
+  default_method_settings do
+    single(:column)
+    returning do |ids|
+      ids.each { |id| send_all_reports_for(id) }
+    end
+  end
+
+  def send_all_reports_for(user)
+    report_a(user)
+    report_b(user)
+    report_c(user)
+  end
+
+  def_statement(:send_all_reports, 'SELECT id FROM user')
+  def_statement(:send_priority_reports, 'SELECT id FROM user WHERE priority')
+
+  # individual settings may be overridden
+  def_statement(:send_all_a_reports, 'SELECT id FROM user') do
+    returning { |ids| ids.each { |id| report_a(id) } }
+  end
+  def_statement(:send_reports, 'SELECT id FROM user WHERE name = $name') do
+    single(:value).returning { |id| send_all_reports_for(id) }
+  end
+end
+```
+
+Defaults don't cascade automatically from one module to another module that
+has included it. However the following sorts of things work if you need more
+flexibility in reusing default settings:
+
+```ruby
+
+BASE_SETTINGS = ->() { single(:row).as(:json) }
+module A
+  include DbMod
+
+  # Use base settings with overrides in block
+  default_method_settings(BASE_SETTINGS) { as(:csv) }
+end
+
+A.default_method_settings # => { as: :csv, single: :row }
+
+module B
+  include A
+
+  # Inherit settings from A, overrides as named args
+  default_method_settings(A.default_method_settings, as: :csv)
+end
 ```

data/Rakefile

@@ -15,7 +15,7 @@ require 'rainbow/ext/string' unless String.respond_to?(:color)
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 
-task default: [:rubocop, :spec]
+task default: [:rubocop, :inch, :spec]
 
 require 'yard'
 DOC_FILES = ['lib/**/*.rb', 'README.md']
@@ -23,3 +23,9 @@ DOC_FILES = ['lib/**/*.rb', 'README.md']
 YARD::Rake::YardocTask.new(:doc) do |t|
   t.files = DOC_FILES
 end
+
+require 'inch/rake'
+Inch::Rake::Suggest.new do |inch|
+  inch.args << '--private'
+  inch.args << '--pedantic'
+end

data/db_mod.gemspec

@@ -16,11 +16,16 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'pg'
 
-  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'codeclimate-test-reporter'
+  s.add_development_dependency 'inch'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'redcarpet'
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rspec-mocks'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'simplecov'
   s.add_development_dependency 'yard'
-  s.add_development_dependency 'bundler'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- spec/*`.split("\n")

data/lib/db_mod.rb

@@ -11,15 +11,32 @@ require_relative 'db_mod/version'
 # will give your class or object the protected methods
 # {#db_connect} and {#conn=}, allowing the connection
 # to be set or created, as well as the methods {#conn},
-# {#query}, {#transaction}, and {#def_prepared}.
+# {#query}, {#transaction}, and +def_prepared+.
 module DbMod
   include Transaction
 
   # When a module includes {DbMod}, we define some
   # class-level functions specific to the module.
+  # This technique is required where it is not
+  # sufficient to simply define a module method
+  # on {DbMod} itself due to metaprogramming techniques
+  # requiring access to the module as +self+.
+  #
+  # See {DbMod::Create.setup}
+  # and {DbMod::Statements.setup}
+  #
+  # @param mod [Module] module which has had {DbMod} included
+  # @see http://ruby-doc.org/core-2.2.3/Module.html#method-i-included
+  #   Module#included
   def self.included(mod)
     DbMod::Create.setup(mod)
     DbMod::Statements.setup(mod)
+
+    # Ensure that these definitions cascade when
+    # submodules are included in subsequent submodules.
+    class << mod
+      define_method(:included) { |sub_mod| DbMod.included(sub_mod) }
+    end
   end
 
   protected
@@ -27,9 +44,23 @@ module DbMod
   # Database object to be used for all database
   # interactions in this module.
   # Use {#db_connect} to initialize the object.
-  attr_accessor :conn
+  #
+  # @return [PGconn] for now, only PostgreSQL is supported
+  attr_reader :conn
+
+  # A custom-built connection object
+  # may be supplied in place of calling {#db_connect}.
+  # Be aware in this case that certain responsibilities
+  # of {#db_connect} may need to be taken care of manually,
+  # in particular preparing SQL statements.
+  #
+  # @param value [PGconn] for now, only PostgreSQL is supported.
+  attr_writer :conn
 
   # Shorthand for +conn.query+
+  #
+  # @param sql [String] SQL query to execute
+  # @return [Object] SQL result set
   def query(sql)
     unless @conn
       fail DbMod::Exceptions::ConnectionNotSet, 'db_connect not called'
@@ -65,6 +96,7 @@ module DbMod
   # Load any missing options from defaults
   #
   # @param options [Hash] see {#db_connect}
+  # @see #db_connect
   def db_defaults!(options)
     fail ArgumentError, 'database name :db not supplied' unless options[:db]
     options[:port] ||= 5432
@@ -75,6 +107,7 @@ module DbMod
   # Create the database object itself.
   #
   # @param options [Hash] see {#db_connect}
+  # @return [PGconn] a new database connection
   def db_connect!(options)
     PGconn.connect(
       options[:host],

data/lib/db_mod/create.rb

@@ -16,9 +16,11 @@ module DbMod
     # for a module that has just had {DbMod}
     # included.
     #
-    # @param mod [Module]
+    # @param mod [Module] the module where {DbMod}
+    #   has been included
+    # @see DbMod.included
     def self.setup(mod)
-      mod.class.instance_eval do
+      class << mod
         define_method(:create) do |options = {}|
           @instantiable_class ||= Create.instantiable_class(self)
 
@@ -33,7 +35,8 @@ module DbMod
     # and can be instantiated with either a connection object
     # or some connection options.
     #
-    # @param mod [Module]
+    # @param mod [Module] the module to build a class for
+    # @return [Class] a singleton instantiable class that includes +mod+
     def self.instantiable_class(mod)
       Class.new do
         include mod

data/lib/db_mod/statements.rb

@@ -1,4 +1,5 @@
 require_relative 'statements/configuration'
+require_relative 'statements/default_method_settings'
 require_relative 'statements/statement'
 require_relative 'statements/prepared'
 
@@ -12,7 +13,14 @@ module DbMod
   module Statements
     # Called when a module includes {DbMod},
     # defines module-level +def_statement+ and +def_prepared+ dsl methods.
+    #
+    # @param mod [Module] module that has had {DbMod} included
+    # @see DbMod.included
+    # @see DefaultMethodSettings
+    # @see Prepared
+    # @see Statement
     def self.setup(mod)
+      DbMod::Statements::DefaultMethodSettings.setup(mod)
       DbMod::Statements::Prepared.setup(mod)
       DbMod::Statements::Statement.setup(mod)
     end

data/lib/db_mod/statements/configuration.rb

@@ -21,7 +21,14 @@ module DbMod
       # @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?
+        config =
+          if block_given?
+            MethodConfiguration.new(mod.default_method_settings, &block)
+          else
+            mod.default_method_settings
+          end
+
+        config &&= config.to_hash
 
         definition = attach_result_processors(definition, config) if config
         definition = attach_param_processor(definition, params, config)
@@ -45,6 +52,7 @@ module DbMod
 
           elsif params.is_a?(Fixnum) && params > 0
             define_fixed_args_method(definition, params)
+
           else
             ->() { instance_exec(&definition) }
           end
@@ -92,9 +100,11 @@ module DbMod
       # @param definition [Proc] base method definition
       # @param config [MethodConfiguration] configuration declared at
       #   method definition time
+      # @return [Proc] extended method definition
       def self.attach_result_processors(definition, config)
         definition = Single.extend(definition, config)
         definition = As.extend(definition, config)
+        definition = Returning.extend(definition, config)
 
         definition
       end
@@ -108,9 +118,16 @@ module DbMod
       # processing), perform some transform on it and return the result.
       #
       # @param definition [Proc] base method definition
-      # @param processor [#call] result processor
+      # @param processor [Proc,#call] result processor
+      # @return [Proc] wrapped method definition
       def self.attach_result_processor(definition, processor)
-        ->(*args) { processor.call instance_exec(*args, &definition) }
+        if processor.is_a? Proc
+          lambda do |*args|
+            instance_exec(instance_exec(*args, &definition), &processor)
+          end
+        else
+          ->(*args) { processor.call instance_exec(*args, &definition) }
+        end
       end
     end
   end