objectid_columns 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA512: 
+  metadata.gz: 8752dd26c637b7ba079438edd6abedce5c7df3fe44965c176f3aa3b3c137b1fbd504d5193e69e6d6ac200d445fe1e2808b04d494395c304b92c0b6878838f43e
+  data.tar.gz: aecea712ee39f11a59e245bce3d89136415b3429317500f4b8087c8e3b90b53ca6df937b904ca7f0abfc328f6961016105422ca94a6b4bfd99ad98644758e472
+SHA1: 
+  metadata.gz: a55261b9a4c1cdf209e6b14c9d04a5a8aa0ff38d
+  data.tar.gz: fc27e32b0629998e0aa28180ba01cbb71ae1fc29

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+/spec_database_config.rb*

data/.travis.yml

@@ -0,0 +1,35 @@
+rvm:
+    - "1.8.7"
+    - "1.9.3"
+    - "2.0.0"
+    - "2.1.0"
+    - "jruby-1.7.9"
+env:
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.0.20 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=mysql
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.0.20 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=postgres
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.0.20 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.1.12 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=mysql
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.1.12 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=postgres
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.1.12 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.2.16 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=mysql
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.2.16 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=postgres
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=3.2.16 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=4.0.2 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=mysql
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=4.0.2 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=postgres
+    - OBJECTID_COLUMNS_AR_TEST_VERSION=4.0.2 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite
+before_script:
+    - mysql -e 'create database myapp_test;'
+    - psql -c 'create database myapp_test;' -U postgres
+matrix:
+    exclude:
+        # ActiveRecord 4.x doesn't support Ruby 1.8.7
+        -   rvm: 1.8.7
+            env: OBJECTID_COLUMNS_AR_TEST_VERSION=4.0.2 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=mysql
+        -   rvm: 1.8.7
+            env: OBJECTID_COLUMNS_AR_TEST_VERSION=4.0.2 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=postgres
+        -   rvm: 1.8.7
+            env: OBJECTID_COLUMNS_AR_TEST_VERSION=4.0.2 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite
+    allow_failures:
+        -   env: OBJECTID_COLUMNS_AR_TEST_VERSION=3.1.12 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite
+        -   rvm: 1.8.7
+            env: OBJECTID_COLUMNS_AR_TEST_VERSION=3.2.16 OBJECTID_COLUMNS_TRAVIS_CI_DATABASE_TYPE=sqlite

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in objectid_columns.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Swiftype, Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,224 @@
+# ObjectidColumns
+
+Transparely store MongoDB [ObjectId](http://docs.mongodb.org/manual/reference/object-id/) values (the primary key of
+all MongoDB tables) in ActiveRecord objects in a relational database. You can store values as:
+
+* A binary column (`BINARY`, `VARBINARY`, `BLOB`, _etc._) of length at least 12; the ObjectId value will be stored as
+  pure binary data — the most efficient format. (Most databases, including MySQL and PostgreSQL, can index this
+  column and work with it just like a String; it just takes half as much space (!).)
+* A String column (`CHAR`, `VARCHAR`, _etc._) of length at least 24; the ObjectId value will be stored as a hexadecimal
+  string.
+
+(Note that it is not possible to store binary data transparently in a String column, because not all byte sequences
+are valid binary data in all possible character sets.)
+
+Once declared, an ObjectId column will return instances of either `BSON::ObjectId` or `Moped::BSON::ObjectId`
+(depending on which one you have loaded) when you access an attribute of a model that you've declared as an ObjectId
+column. It will accept a String (in either hex or binary formats) or an instance of either of those classes when
+assigning to the column.
+
+`ObjectidColumns` also allows you to use ObjectId values as primary keys; it will assign them to new records by
+default, and make sure `find(id)` accepts them.
+
+This gem requires either the `moped` gem (which defines `Moped::BSON::ObjectId`) or the `bson` gem (which defines
+`BSON::ObjectId`) for the actual ObjectId classes it uses. It declares an official dependency on neither, because we
+want to allow you to use either one. It will accept either one when assigning ObjectIds; it will return ObjectIds as
+whichever one you have loaded, (currently) preferring `BSON::ObjectId` if you have both.
+
+ObjectidColumns supports Ruby 1.8.7, 1.9.3, 2.0.0, and 2.1.0, plus JRuby 1.7.9; it supports ActiveRecord 3.0.20,
+3.1.12, 3.2.16, and 4.0.2. It supports SQLite 3.x, MySQL 5.x, and PostgreSQL 8.x. (These are just the versions it's
+tested against; while it will not work with ActiveRecord 2.x, it is otherwise highly unlikely to be sensitive to
+exact ActiveRecord or Ruby versions, or type of RDBMS, and generally should work with most combinations.)
+
+*Note*: If you use SQLite3 with ActiveRecord 3.1.x on MRI (_i.e._, not JRuby), or SQLite3 with ActiveRecord 3.2.x on
+MRI 1.8.7, there is a bug in the SQLite3-ActiveRecord integration that causes ObjectId primary keys to not work. (They
+are inserted properly, but searching by primary key fails.) Needless to say, these are very rare combinations of
+software to be running in production, but it's worth noting. (ActiveRecord 3.0.x or 3.2.x work fine with SQLite3 on
+MRI; SQLite3 with ActiveRecord 3.2.x works fine on MRI >= 1.9.3; and MySQL and PostgreSQL work perfectly everywhere.)
+
+Current build status: ![Current Build Status](https://api.travis-ci.org/swiftype/objectid_columns.png?branch=master)
+
+Brought to you by the folks at [Swiftype](https://www.swiftype.com). First version written by [Andrew Geweke](https://www.github.com/ageweke).
+
+## Installation
+
+First, make sure you have either `BSON::ObjectId` or `Moped::BSON::ObjectId` defined in your Rails environment;
+these are the two ObjectId classes that `ObjectidColumns` can work with. If you don't have either defined, add one
+of these lines to your `Gemfile` (loading both is fine, but unnecessary):
+
+       gem 'bson'
+    OR gem 'moped'
+
+Now, add this line to your application's Gemfile:
+
+    gem 'objectid_columns'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install objectid_columns
+
+## Usage
+
+If you name your object-ID columns with `_oid` at the end, simply do this:
+
+    class MyModel < ActiveRecord::Base
+      has_objectid_columns
+    end
+
+This will automatically find any columns that end in `_oid` and make them ObjectId columns. When reading them, you will
+get back an instance of an ObjectId class (from `moped` or `bson`, depending on which one you have loaded; see the
+introduction for more). When writing them, you can assign a String in hex or binary formats, or an instance of either
+of the supported ObjectId classes.
+
+If you didn't name your columns this way, or _don't_ want to pick up columns ending in `_oid`, just name them
+explicitly:
+
+    class MyModel < ActiveRecord::Base
+      has_objectid_columns :some_oid, :foo
+    end
+
+This will not only define `some_oid` and `foo` as being ObjectId columns, but it will also skip the automatic detection
+of columns ending in `_oid`.
+
+ObjectidColumns will never automatically make a primary-key column an ObjectId, even if it ends with `_oid`; if you
+want a primary key to be an ObjectId, you must do that explicitly, using `has_objectid_primary_key`, below.
+
+Note that trying to declare a column as an ObjectId column if it isn't of a supported type (a type that ActiveRecord
+considers to be `:string` or `:binary`), or if it isn't long enough to support an ObjectId (twelve characters for
+binary columns, 24 for string columns); this will happen from the `has_objectid_columns` call (so at load time for the
+model class).
+
+Once you have declared such a column:
+
+    my_model = MyModel.find(...)
+
+    my_model.my_oid                    # => BSON::ObjectId('52eab2cf78161f1314000001')
+    my_model.my_oid.to_s               # => "52eab2cf78161f1314000001" (built-in behavior from BSON::ObjectId)
+    my_model.my_oid.to_binary          # => "R\xEA\xB2\xCFx\x16\x1F\x13\x14\x00\x00\x01"
+    my_model.my_oid.to_binary.encoding # => #<Encoding:ASCII-8BIT>
+
+    my_model.my_oid = BSON::ObjectId.new         # OK
+    my_model.my_oid = "52eab32878161f1314000002" # OK
+    my_model.my_oid = "R\xEA\xB2\xCFx\x16\x1F\x13\x14\x00\x00\x01" # OK
+
+    MyModel.where(:my_oid => some_oid).first # => my_model -- i.e., where(...) works with a hash.
+
+Note that to assign a binary-format string, it must have an encoding of `Encoding::BINARY` (which is an alias for
+`Encoding::ASCII-8BIT`). (If your string has a different encoding, it may be coming from a source that does not
+actually support full binary data transparently, which _will_ cause big problems.)
+
+### Gotchas
+
+If you query on an ObjectId column and use the hash syntax &mdash; _i.e._, `MyModel.where(:some_oid => ...)` &mdash;
+then everything will work perfectly; `ObjectidColumns` looks for this syntax and properly translates the value from
+an ObjectId object, binary String, or hex String to the proper database value. On the other hand, if you specify a
+SQL statement or fragment of SQL yourself, you must do the translation, or you'll either get a database error or just
+no rows found:
+
+    MyModel.where("some_oid = ?", my_oid.to_bson_id.to_binary) # if some_oid is binary
+    MyModel.where("some_oid = ?", my_oid.to_bson_id.to_s)      # if some_oid is a String
+
+(Without actively parsing SQL, which is kind of an insane thing to do, there is no easy way around this. Even if we
+detected ObjectId objects in the set of values passed in, we'd have no way of figuring out which ObjectId column they
+were constraining on, and thus whether to turn them into binary or hexadecimal ObjectId values.)
+
+### Using an ObjectId for a Primary Key
+
+You can use ObjectId values as primary keys:
+
+    class MyModel < ActiveRecord::Base
+      has_objectid_primary_key
+    end
+
+Perhaps obviously, your primary-key column must either be `:binary` of length >= 12 or `:string` of length >= 24.
+
+If your primary-key column is not called `:id`, you must do one of two things:
+
+* Set the primary key on the class _before_ you call `has_objectid_primary_key`, by just using the normal ActiveRecord
+  `self.primary_key = :foo` syntax.
+* Pass the primary key as an argument to `has_objectid_primary_key`: `has_objectid_primary_key :foo`.
+
+(The two are exactly equivalent.)
+
+When you do this, `ObjectidColumns` adds a `before_create` hook to your model, assigning a new ObjectId immediately
+before the first time a row is saved in the database. This will not replace an existing ID, so, if you always (or
+sometimes) assign a new ID yourself, `ObjectidColumns` will not overwrite your ID.
+
+Perhaps obviously, this means that new IDs are generated and stored client-side; you almost certainly should declare
+your primary-key column as `NOT NULL`, but you don't need to give it a default (and probably shouldn't, unless you're
+using a database function that is capable of generating correctly-formatted ObjectId values using the correct
+algorithm).
+
+
+### Setting the Preferred Class
+
+If you have both the `bson` and `moped` gems defined, then, by default, ObjectId columns will be returned as instances
+of `bson`'s `BSON::ObjectId` class. If you want to use `moped`'s instead, do this:
+
+    ObjectidColumns.preferred_bson_class = Moped::BSON::ObjectId
+
+### Extensions
+
+This gem extends String with a single method, `#to_bson_id`; it simply returns an instance of the preferred BSON class
+from that String if it's in either the valid hex or the valid binary format, or raises `ArgumentError` otherwise.
+
+This gem also extends whatever BSON ObjectId classes are loaded with methods `to_bson_id` (which just returns `self`),
+and the method `to_binary`, which returns a binary String of length 12 for that object ID.
+
+### Running Specs
+
+`objectid_columns` has thorough system-level (_i.e._, integration) tests, written in RSpec. Because nearly all of its
+functionality is centered around interfacing with ActiveRecord (as opposed to having significant, complex code within
+its codebase directly), there are no unit tests &mdash; they would simply be setting complex expectations around calls
+to ActiveRecord, making the tests fragile and not particularly useful.
+
+In order to run these specs, you must have access to a database you can use. It's best if the database is dedicated
+to running these specs. The tests create and destroy their own tables, and make every effort to clean up anything they
+created at the end &mdash; so it should be possible to piggyback on top of an existing database you also use for other
+things. However, it's _always_ much safer to use a dedicated database. (Note that this is intentional use of the word
+"database", as opposed to "database server"; you don't need, for example, an entirely separate instance of `mysqld`
+&mdash; just a separate database that you can switch to using `USE ....`.)
+
+Once you have this set up, simply create a file at the root level of the Gem (_i.e._, inside the root
+`objectid_columns` directory) called `spec_database_config.rb`, and define a constant
+`OBJECTID_COLUMNS_SPEC_DATABASE_CONFIG` as so:
+
+    OBJECTID_COLUMNS_SPEC_DATABASE_CONFIG = {
+      :database_gem_name => 'mysql2',
+      :require => 'mysql2',
+      :config => {
+        :adapter => 'mysql2',
+        :database => 'objectid_columns_specs_db',
+        :username => 'root'
+      }
+    }
+
+The keys are as follows:
+
+* `:database_gem_name` is the name of the RubyGem that provides access to the database &mdash; exactly as you'd put
+  it in a `Gemfile`;
+* `:require` is whatever should be passed to Ruby's built-in `require` statement to require the Gem &mdash;
+   typically this is the same as `:database_gem_name`, but not always (this is the same as a Gemfile's `:require => ..
+   ` syntax);
+* `:config` is exactly what gets passed to `ActiveRecord::Base.establish_connection`, and so you can pass any
+  options that it accepts (which are the same as what goes in Rails' `database.yml`).
+
+Once you've done this, you can run the system specs using `bundle exec rspec spec/objectid_columns/system`. (Or run
+them along with the unit specs with a simple `bundle exec rspec spec`.)
+
+Note that there's also support deep in the code (in
+`objectid_columns/spec/objectid_columns/helpers/database_helper.rb`)
+for defining connections to [Travis CI](https://travis-ci.org/)'s database options, so that Travis can run the tests
+automatically. Generally, you don't need to worry about this, but it's worth noting.
+
+## Contributing
+
+1. Fork it ( http://github.com/swiftype/objectid_columns/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/objectid_columns/active_record/base.rb

@@ -0,0 +1,33 @@
+require 'objectid_columns'
+require 'active_support'
+require 'objectid_columns/has_objectid_columns'
+
+module ObjectidColumns
+  module ActiveRecord
+    # This module gets included into ActiveRecord::Base when ObjectidColumns loads. It is just a "trampoline" -- the
+    # first time you call one of its methods, it includes ObjectidColumns::HasObjectidColumns into your model, and
+    # then re-calls the method. (This looks like infinite recursion, but isn't, because once we include the module,
+    # its implementation takes precedence over ours -- because we will always be a module earlier on the inheritance
+    # chain, since we by definition were included before ObjectidColumns::HasObjectidColumns.)
+    module Base
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Do we have any ObjectId columns? This is always false -- once we include ObjectidColumns::HasObjectidColumns,
+        # its implementation (which just returns 'true') takes precedence.
+        def has_objectid_columns?
+          false
+        end
+
+        # These are our "trampoline" methods -- the methods that you should be able to call on an ActiveRecord class
+        # that has never had any ObjectidColumns-related methods called on it before, that bootstrap the process.
+        [ :has_objectid_columns, :has_objectid_column, :has_objectid_primary_key ].each do |method_name|
+          define_method(method_name) do |*args|
+            include ::ObjectidColumns::HasObjectidColumns
+            send(method_name, *args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/objectid_columns/active_record/relation.rb

@@ -0,0 +1,40 @@
+require 'objectid_columns'
+
+module ObjectidColumns
+  module ActiveRecord
+    # This module gets included into ActiveRecord::Relation; it is responsible for modifying the behavior of +where+.
+    # Note that when you call +where+ directly on an ActiveRecord class, it (through various AR magic) ends up calling
+    # ActiveRecord::Relation#where, so this takes care of that, too.
+    module Relation
+      extend ActiveSupport::Concern
+
+      # There is really only one case where we can transparently modify queries -- where you're using hash syntax:
+      #
+      #     model.where(:foo_oid => <objectID>)
+      #
+      # If you're using SQL string syntax:
+      #
+      #     model.where("foo_oid = ?", <objectID>)
+      #
+      # ...then there's no way to reliably determine what should be converted as an ObjectId (and, critically, to what
+      # format -- hex or binary -- we should convert it). As such, we leave the responsibility for that case up to
+      # the user.
+      def where(*args)
+        # Bail out if we don't have any ObjectId columns
+        return super(*args) unless respond_to?(:has_objectid_columns?) && has_objectid_columns?
+        # Bail out if we're not using the Hash form
+        return super(*args) unless args.length == 1 && args[0].kind_of?(Hash)
+
+        query = { }
+        args[0].each do |key, value|
+          # #translate_objectid_query_pair is a method defined on the ObjectidColumns::ObjectidColumnsManager, and is
+          # called via the delegation defined in ObjectidColumns::HasObjectidColumns.
+          (key, value) = translate_objectid_query_pair(key, value)
+          query[key] = value
+        end
+
+        super(query)
+      end
+    end
+  end
+end

data/lib/objectid_columns/dynamic_methods_module.rb

@@ -0,0 +1,104 @@
+module ObjectidColumns
+  # A DynamicMethodsModule is used to add dynamically-generated methods to an existing class.
+  #
+  # Why do we need a module to do that? Why can't we simply call #define_method on the class itself?
+  #
+  # We could. However, if you do that, a few problems crop up:
+  #
+  # * There is no precendence that you can control. If you define a method +:foo+ on class Bar, then that method is
+  #   always run when an instance of that class is sent the message +:foo+. The only way to change the behavior of
+  #   that class is to completely redefine that method, which brings us to the second problem...
+  # * Overriding and +super+ doesn't work. That is, you can't override such a method and call the original method
+  #   using +super+. You're reduced to using +alias_method_chain+, which is a mess.
+  # * There's no namespacing at all -- at runtime, it's not even remotely clear where these methods are coming from.
+  # * Finally, if you're living in a dynamic environment -- like Rails' development mode, where classes get reloaded
+  #   very frequently -- once you define a method, it is likely to be forever defined. You have to write code to keep
+  #   track of what you've defined, and remove it when it's no longer present.
+  #
+  # A DynamicMethodsModule fixes these problems. It's little more than a Module that lets you define methods (and
+  # helpfully makes #define_method +public+ to help), but it also will include itself into a target class and bind
+  # itself to a constant in that class (which magically gives the module a name, too). Further, it also keeps track
+  # of which methods you've defined, and can remove them all with #remove_all_methods!. This allows you to construct
+  # a much more reliable paradigm: instead of trying to figure out what methods you should remove and add when things
+  # change, you can just call #remove_all_methods! and then redefine whatever methods _currently_ should exist.
+  #
+  # A DynamicMethodsModule also supports class methods; if you define a method with #define_class_method, it will be
+  # added to a module that the target class has called +extend+ on (rather than +include+), and hence will show up as
+  # a class method on that class. This is useful for the exact same reasons as the base DynamicMethodsModule; it allows
+  # for precedence control, use of +super+, namespacing, and dynamism.
+  class DynamicMethodsModule < ::Module
+    # Creates a new instance. +target_class+ is the Class into which this module should include itself; +name+ is the
+    # name to which it should bind itself. (This will be bound as a constant inside that class, not at top-level on
+    # Object; so, for example, if +target_class+ is +User+ and +name+ is +Foo+, then this module will end up named
+    # +User::Foo+, not simply +Foo+.)
+    #
+    # If passed a block, the block will be evaluated in the context of this module, just like Module#new. Note that
+    # you <em>should not</em> use this to define methods that you want #remove_all_methods!, below, to remove; it
+    # won't work. Any methods you add in this block using normal +def+ will persist, even through #remove_all_methods!.
+    def initialize(target_class, name, &block)
+      raise ArgumentError, "Target class must be a Class, not: #{target_class.inspect}" unless target_class.kind_of?(Class)
+      raise ArgumentError, "Name must be a Symbol or String, not: #{name.inspect}" unless name.kind_of?(Symbol) || name.kind_of?(String)
+
+      @target_class = target_class
+      @name = name.to_sym
+
+      # Unfortunately, there appears to be no way to "un-include" a Module in Ruby -- so we have no way of replacing
+      # an existing DynamicMethodsModule on the target class, which is what we'd really like to do in this situation.
+      if @target_class.const_defined?(@name)
+        existing = @target_class.const_get(@name)
+
+        if existing && existing != self
+          raise NameError, %{You tried to define a #{self.class.name} named #{name.inspect} on class #{target_class.name},
+but that class already has a constant named #{name.inspect}: #{existing.inspect}}
+        end
+      end
+
+      @class_methods_module = Module.new
+      (class << @class_methods_module; self; end).send(:public, :private)
+      @target_class.const_set("#{@name}ClassMethods", @class_methods_module)
+      @target_class.send(:extend, @class_methods_module)
+
+      @target_class.const_set(@name, self)
+      @target_class.send(:include, self)
+
+      @methods_defined = { }
+      @class_methods_defined = { }
+
+      super(&block)
+    end
+
+    # Removes all methods that have been defined on this module using #define_method, below. (If you use some other
+    # mechanism to define a method on this DynamicMethodsModule, then it will not be removed when this method is
+    # called.)
+    def remove_all_methods!
+      instance_methods.each do |method_name|
+        # Important -- we use Class#remove_method, not Class#undef_method, which does something that's different in
+        # some important ways.
+        remove_method(method_name) if @methods_defined[method_name.to_sym]
+      end
+
+      @class_methods_module.instance_methods.each do |method_name|
+        @class_methods_module.send(:remove_method, method_name) if @class_methods_defined[method_name]
+      end
+    end
+
+    # Defines a method. Works identically to Module#define_method, except that it's +public+ and #remove_all_methods!
+    # will remove the method.
+    def define_method(name, &block)
+      name = name.to_sym
+      super(name, &block)
+      @methods_defined[name] = true
+    end
+
+    # Defines a class method.
+    def define_class_method(name, &block)
+      @class_methods_module.send(:define_method, name, &block)
+    end
+
+    # Makes it so you can say, for example:
+    #
+    #     my_dynamic_methods_module.define_method(:foo) { ... }
+    #     my_dynamic_methods_module.private(:foo)
+    public :private # teehee
+  end
+end