schema_monkey 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fcf24614a0b60131f52dc7bdd8dae426dac1d814
-  data.tar.gz: 8767b57fb97dc4b5f7ff17129b0dd6ddb0850f5f
+  metadata.gz: 2090c17d3f5bba79e1885f2f76a22a8c0bfcb389
+  data.tar.gz: d8fecf5bea771ace12cf1511583098408f9e2f38
 SHA512:
-  metadata.gz: 33210d7c9683c756deb46931f049b25bdd0efdd3aea15a5fd984e69fe8529f234e6c1a5ef61424628535c3414dcd3b79befe4a02c50c87e0ae695fb5d1a0f8e1
-  data.tar.gz: f573a50c27d09f31b0be37f86c278d6cc7b216370abfb06d015044c3c1b1ee210c33d71f052e1cf070edd4cd9690ad354b8920129400a2fa2859f0074a6cd074
+  metadata.gz: e2fdef632c27ed6619821a0b9fed86d1931a86eea897991ca0a98c88af7f7c3dfcb855243499f29af6c9d4f25397e6c3e42d2a630555eea14b820709c48cb808
+  data.tar.gz: ee53c8e8d0b1d7cb4dd824096cf208475ab16dc56cd2a9c5f2e84a844d00adcff40a60345809a30c98ed1e39bbd076c48417e642c01a1126836d1b060ebc5749

data/.gitignore

@@ -1,6 +1,7 @@
 /coverage
 /tmp
 /pkg
+Gemfile.local
 
 *.lock
 *.log

data/.travis.yml

@@ -5,7 +5,6 @@
 ---
 sudo: false
 rvm:
-- 1.9.3
 - 2.1.5
 gemfile:
 - gemfiles/activerecord-4.2/Gemfile.mysql2

data/Gemfile

@@ -1,3 +1,5 @@
 source "http://rubygems.org"
 
 gemspec
+
+File.exist?(gemfile_local = File.expand_path('../Gemfile.local', __FILE__)) and eval File.read(gemfile_local), binding, gemfile_local

data/README.md

@@ -5,37 +5,227 @@
 
 # SchemaMonkey
 
-SchemaMonkey is a behind-the-scenes gem to facilitate writing extensions to ActiveRecord (typically other gems, but could also be in an application).  It provides:
+SchemaMonkey is a behind-the-scenes gem to make it easy to write extensions to ActiveRecord.  It provides:
 
-* A "middleware"-style interface to key ActiveRecord internal functions.  For example, there's a middleware hook to let you insert a handler for migration column definition options, and there are several hooks to insert handlers for the various parts of a schema dump.
+* A simple convention-based mechanism to insert modules into ActiveRecord modules.
+* A simple convention-based mechanism to create and use [Modware](https://rubygems.org/gems/modware) middleware stacks.
 
-* A convention-based protocol for `include`'ing custom modules into ActiveRecord.  You just define your modules and SchemaMonkey will automatically include them in the right places.
+SchemaMonkey by itself doesn't add any behavior -- SchemaMonkey is intended to make it easy to add clients that define methods and stacks, that are then available to other clients or the app.  (In particular, most clients of SchemaMonkey will depend on [schema_plus_core](https://github.com/SchemaPlus/schema_plus_core), which is a SchemaMonkey client that provides an "internal extension API" to ActiveRecord.)
 
+## Installation
 
-The middleware interface has two benefits: it provides a clean API so that the gem or aplication code doesn't need to monkey-patch ActiveRecord (SchemaMonkey does all the monkey-patching for you), and it lets multiple client gems operate in parallel without concern about conflicting monkey-patches.
+As usual:
 
+```ruby
+gem "schema_monkey"                 # in a Gemfile
+gem.add_dependency "schema_monkey"  # in a .gemspec
+```
 
-## Installation
+To use with a rails app, also include
 
-As usual:
+```ruby
+gem "schema_monkey_rails"
+```
+
+which creates a Railtie to insert SchemaMonkey appropriately into the rails stack. To use with Padrino, see [schema_monkey_padrino](https://github.com/SchemaPlus/schema_monkey_padrino).
+
+## Usage
+
+SchemaMonkey works with the notion of a "client" -- which is a module containining definitions.  A typical SchemaMonkey client looks like
 
 ```ruby
-# In a gem's .gemspec:
-spec.add_dependency "schema_monkey", "~> <MAJOR>.<MINOR>", ">= <MAJOR>.<MINOR>.<PATCH>"
+require 'schema_monkey'
+require 'other-client1'   # if needed
+require 'other-client2'   # as needed
+
+module MyClient
+
+  module ActiveRecord
+    #
+    # active record extensions, if any
+    #
+  end
+
+  module Middleware
+    #
+    # middleware stack modules, if any
+    #
+  end
+  
+end
 
-# In an applications Gemfile:
-gem "schema_monkey", "~> <MAJOR>.<MINOR>", ">= <MAJOR>.<MINOR>.<PATCH>"
+SchemaMonkey.register MyClient     # <--- That's it!  No configuration needed
 ```
 
-SchemaMonkey follows semantic versioning; it's a good idea to explicitly use the `~>` and `>=` dependencies to make sure your gem's clients don't accidentally pull in a version of SchemaMonkey that your gem isn't compatible with.
+of course a typical client will be split into files corresponding to submodules; e.g. here's the top level of [schema_plus_indexes](https://github.com/SchemaPlus/schema_plus_indexes):
 
-To use with a rails app, also include
+```ruby
+require 'schema_plus/core'
+
+require_relative 'schema_plus_indexes/active_record/base'
+require_relative 'schema_plus_indexes/active_record/connection_adapters/abstract_adapter'
+require_relative 'schema_plus_indexes/active_record/connection_adapters/index_definition'
+
+require_relative 'schema_plus_indexes/middleware/dumper'
+require_relative 'schema_plus_indexes/middleware/migration'
+require_relative 'schema_plus_indexes/middleware/model'
+require_relative 'schema_plus_indexes/middleware/query'
+
+SchemaMonkey.register SchemaPlusIndexes
+```
+
+The details of ActiveRecord exentions and Middleware modules are described below.
+
+## ActiveRecord Extensions
+
+Here's a simple example of an extension to ActiveRecord:
 
 ```ruby
-gem "schema_monkey_rails"
+require 'schema_monkey'
+
+module PracticalJoker
+  module ActiveRecord
+    module Base
+       
+       def save(*args)
+         raise "April Fools!" if Time.now.yday == 31
+         super
+       end
+       
+       module ClassMethods
+         def columns
+           raise "Boo!" if Time.now.yday == 304
+           super
+         end
+       end
+       
+      end
+    end
+  end
+end
+
+SchemaMonkey.register PracticalJoker
+```
+
+SchemaMonkey inserts each submodule of `MyClient::ActiveRecord` into the corresponding module of ActiveRecord, with `ClassMethods` inserted as class methods.  
+
+This works for arbitrary submodule paths, such as `MyClient::ActiveRecord::ConnectionAdapters::TableDefinition`.  SchemaMonkey will raise an error if the client defines a module that does not have a corresponding ActiveRecord module.
+
+Notice that insertion is done using `:prepend`, so that client modules can override existing methods and use `super`.
+
+### DBMS-specific insertion
+
+If a client module's name includes one the dbms names `Mysql`, `PostgreSQL` or `SQLite3` (case insensitive), the insertion will only be performed if that's the dbms in use.  So, e.g. `MyClient::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter` will only be inserted if the app is using PostgreSQL.
+
+Additionally, for ActiveRecord modules that are not inherently dbms-specific, you can use one of the dbms names (case insensitive) as a component in the client module's path to do dbms-specific insertion.   E.g.
+
+```ruby
+module MyClient
+  module ActiveRecord
+    module ConnectionAdapters
+      module Sqlite3
+        module TableDefinition
+          #
+          # SQLite3-specific enhancements to 
+          # ActiveRecord::ConnectionAdapters::TableDefinition
+          #
+        end
+      end
+    end
+  end
+end
+```
+
+The dbms name component can be anywhere in the module path after `MyClient::ActiveRecord`
+
+### `insert` vs `prepend`
+
+
+* By default, SchemaMonkey inserts a client module using `prepend`, and a client ClassMethods module using `singleton_class.prepend`. This allows overriding existing methods and using `super`.  On insertion, Ruby will of course call the module's `self.prepended` method, if one is defined.
+
+* However, if the client module defines a module method `self.included` then SchemaMonkey will use `include` for a module and `singleton_class.include` for a ClassMethods module -- and Ruby will of course call that method.
+
+Note that in the case of a ClassMethods module, when Ruby calls `self.prepended` or `self.included`, it will pass the singleton class.  For convience SchemaMonkey will also call `self.extended` if defined passing it the ActiveRecord module itself, just as Ruby would if `extend` were used.         
+
+## Middleware Modlues
+
+SchemaMonkey provides a convention-based front end to using [Modware](https://github.com/ronen/modware) middleware stacks.
+
+SchemaMonkey uses Ruby modules to organize the stacks:  Each stack is contained in a submodule of `SchemaMonkey::Middleware`
+
+### Defining a stack
+
+Here's an example of defining a middleware stack:
+
+```ruby
+module MyClient
+  module Middleware
+    module Index
+      module Exists
+        Env = [:connection, :table_name, :column_name, :options, :result]
+      end
+    end
+  end
+end
+```
+
+This defines a stack available at `SchemaMonkey::Middleware::Index::Exists`.  You can use any module path you want for organizational convenience.  The const `Env` signals to SchemaMonkey to create a stack at that location; the environment object for the stack will have the listed fields. (Env actually can be an array of symbols or a Class, as per `Modware::Stack.new`.)
+
+SchemaMonkey will raise an error if a stack had already been defined there.
+
+The defined module has a module method `start` that delegates to `Modware::Stack.start`.  Here's an example of using the above stack as a wrapper around ActiveRecord's `index_exists?` method:
+
+```ruby
+module MyClient
+  module ActiveRecord
+    module ConnectionAdapters
+      module SchemaStatements
+        def index_exists?(table_name, column_name, options = {})
+          SchemaMonkey::Middleware::Index::Exists.start(connection: self, table_name: table_name, column_name: column_name, options: options) { |env|
+            env.result = super env.table_name, env.column_name, env.options
+          }.result
+        end
+      end
+    end
+  end
+end
 ```
 
-which creates a Railtie to insert SchemaMonkey appropriately into the rails stack.
+This is a fairly typical idiom for wrapping behavior in a stack:
+
+1. Pass `self` and the method arguments to the stack environment
+2. Call the base implementation, passing it argument values from the environment (giving clients a chance to modify them in `before` or `around` methods)
+3. Place the result in the environment (giving clients a chance to modify it in `after` or `around` methods
+4. `start` returns the environment object -- the method returns the result that's stored in the environment
+
+### Inserting Middleware in a stack
+
+If an earlier client defined a stack, a later client can insert middleware into the stack:
+
+```ruby
+require 'my_client' # earlier client defines the stack
+
+module UColumnImpliesUnique
+  module Middlware
+    module Index
+      module Exists
+        def before(env)
+          env.options.reverse_merge!(unique: env.column_name.start_with? 'u')
+        end
+      end
+    end
+  end
+end
+
+SchemaMonkey.register(UColumnImpliesUnique)
+```
+
+SchemaMonkey uses the module `MyLaterClient::Middleware::Index::Exists` as [Modware](https://github.com/ronen/modware) middleware for the corresponding stack.  The middleware module can define middleware methods `before`, `arround`, `after`, or `implementation` as per [Modware](https://github.com/ronen/modware)
+
+Note that the distinguishing feature between defining and using a stack is whether `Env` is defined.
+
+    
+
 
 ## Compatibility
 
@@ -43,16 +233,10 @@ SchemaMonkey is tested on:
 
 <!-- SCHEMA_DEV: MATRIX - begin -->
 <!-- These lines are auto-generated by schema_dev based on schema_dev.yml -->
-* ruby **1.9.3** with activerecord **4.2**, using **mysql2**, **sqlite3** or **postgresql**
 * ruby **2.1.5** with activerecord **4.2**, using **mysql2**, **sqlite3** or **postgresql**
 
 <!-- SCHEMA_DEV: MATRIX - end -->
 
-## Usage
-
-
-**Sorry -- no real documentation yet. See examples in [schema_plus_indexes](https://github/SchemaPlus/schema_plus_indexes) and [schema_plus_pg_indexes](https://github/SchemaPlus/schema_plus_pg_indexes)**
-
 
 
 ## Development & Testing
@@ -62,14 +246,6 @@ the standard protocol: fork, feature branch, develop, push, and issue pull reque
 
 Some things to know about to help you develop and test:
 
-* SchemaMonkey is a wrapper around two subparts:
-
-  * `SchemaMonkey::Tool` provides the convention-based mechanism for registering clients that extend ActiveRecord using `include`'s and middleware.
-  
-  * `SchemaMonkey::CoreExtensions` defines the ActiveRecord extension API. It is itself just the first client registered with `SchemaMonkey::Tool`.  **Ugh. Currently no specs for `SchemaMonkey::CoreExtensions`;  testing indirectly by testing the client gems that use it.  Working on it...**
-
-  One day might actually split these into separate gems to decouple their development and testing.  And actually the middleware mechanism of `SchemaMonkey::Tool` could be a split out separate gem.
-
 * **schema_dev**:  SchemaMonkey uses [schema_dev](https://github.com/SchemaPlus/schema_dev) to
   facilitate running rspec tests on the matrix of ruby, rails, and database
   versions that the gem supports, both locally and on

data/lib/schema_monkey.rb

@@ -1,5 +1,15 @@
-require_relative "schema_monkey/core_extensions"
-require_relative "schema_monkey/tool"
+require 'active_record'
+require 'active_support/core_ext/string'
+require 'its-it'
+require 'modware'
+
+require_relative "schema_monkey/active_record"
+require_relative "schema_monkey/client"
+require_relative "schema_monkey/errors"
+require_relative "schema_monkey/module"
+require_relative "schema_monkey/monkey"
+require_relative "schema_monkey/stack"
+require_relative 'schema_monkey/rake'
 
 # 
 # Middleware contents will be created dynamically
@@ -10,31 +20,34 @@ module SchemaMonkey
 end
 
 #
-# Wrap public API of SchemaMonkey::Tool
+# 
 #
 module SchemaMonkey
+
+  DBMS = [:PostgreSQL, :Mysql, :SQLite3]
+
   def self.register(mod)
-    Tool::register(mod)
+    monkey.register(mod)
   end
 
   def self.insert(opts={})
-    Tool::insert(opts)
+    monkey.insert(opts)
+  end
+
+  private
+
+  def self.monkey
+    @monkey ||= Monkey.new
   end
 
-  def self.include_once(*args)
-    Tool::Module.include_once(*args)
+  def self.reset_for_rspec
+    @monkey = nil
+    self.reset_middleware
   end
 
-  module Rake
-    def self.insert(*args)
-      Tool::Rake::insert(*args)
-    end
+  def self.reset_middleware
+    SchemaMonkey.send :remove_const, :Middleware
+    SchemaMonkey.send :const_set, :Middleware, ::Module.new
   end
 
-  MiddlewareError = Tool::MiddlewareError
 end
-
-#
-# Register CoreExtensions
-#
-SchemaMonkey::Tool.register(SchemaMonkey::CoreExtensions)

data/lib/schema_monkey/active_record.rb

@@ -0,0 +1,25 @@
+module SchemaMonkey
+  module ActiveRecord
+    module ConnectionAdapters
+      module AbstractAdapter
+        def initialize(*args)
+          super
+          dbm = case adapter_name
+                when /^MySQL/i                 then :Mysql
+                when 'PostgreSQL', 'PostGIS'   then :PostgreSQL
+                when 'SQLite'                  then :SQLite3
+                end
+          SchemaMonkey.insert(dbm: dbm)
+        end
+      end
+    end
+
+    def self.insert(relative_path, mod)
+      class_methods = relative_path.sub!(/::ClassMethods$/, '')
+      base = Module.const_lookup(::ActiveRecord, relative_path)
+      raise InsertionError, "No module ActiveRecord::#{relative_path} to insert #{mod}" unless base
+      Module.insert (class_methods ? base.singleton_class : base), mod
+      mod.extended base if class_methods and mod.respond_to? :extended
+    end
+  end
+end

data/lib/schema_monkey/client.rb

@@ -0,0 +1,65 @@
+module SchemaMonkey
+  class Client
+
+    def initialize(mod)
+      @root = mod
+      @inserted_middleware = {}
+    end
+
+    def insert(dbm: nil)
+      insert_active_record(dbm: dbm)
+      insert_middleware(dbm: dbm)
+    end
+
+    private
+
+    def insert_active_record(dbm: nil)
+      # Kernel.warn "--- inserting active_record for #{@root}, dbm=#{dbm.inspect}"
+      find_modules(:ActiveRecord, dbm: dbm).each do |mod|
+        next if mod.is_a? Class
+        relative_path = canonicalize_path(mod, :ActiveRecord, dbm)
+        ActiveRecord.insert(relative_path, mod)
+      end
+    end
+
+    def insert_middleware(dbm: nil)
+      find_modules(:Middleware, dbm: dbm).each do |mod|
+        next if @inserted_middleware[mod]
+        relative_path = canonicalize_path(mod, :Middleware, dbm)
+        Stack.insert(relative_path, mod) unless relative_path.empty?
+        @inserted_middleware[mod] = true
+      end
+    end
+
+    def canonicalize_path(mod, base, dbm)
+      path = mod.to_s.sub(/^#{@root}::#{base}::/, '')
+      if dbm
+        path = path.split('::')
+        if (i = path.find_index(&it =~ /\b#{dbm}\b/i)) # delete first occurence 
+          path.delete_at i
+        end
+        path = path.join('::').gsub(/#{dbm}/i, dbm.to_s) # canonicalize case for things like PostgreSQLAdapter
+      end
+      path
+    end
+
+    def find_modules(container, dbm: nil)
+      return [] unless (container = Module.const_lookup @root, container)
+
+      if dbm
+        accept = /#{dbm}/i
+        reject = nil
+      else
+        accept = nil
+        reject = /\b(#{DBMS.join('|')})/i
+      end
+
+      modules = []
+      modules += Module.descendants(container, can_load: accept)
+      modules.select!(&it.to_s =~ accept) if accept
+      modules.reject!(&it.to_s =~ reject) if reject
+      modules
+    end
+
+  end
+end