flex_columns 1.0.0

data/lib/flex_columns/has_flex_columns.rb

@@ -0,0 +1,187 @@
+require 'active_record'
+require 'active_support/concern'
+require 'active_support/core_ext'
+require 'flex_columns/contents/flex_column_contents_base'
+
+module FlexColumns
+  # HasFlexColumns is the module that gets included in an ActiveRecord model class as soon as it declares a flex
+  # column (using FlexColumns::ActiveRecord::Base#flex_column). While most of the actual work of maintaining and working
+  # with a flex column is accomplished by the FlexColumns::Definition::FlexColumnContentsClass module and the
+  # FlexColumns::Contents::FlexColumnContentsBase class, there remains, nevertheless, some important work to do here.
+  module HasFlexColumns
+    extend ActiveSupport::Concern
+
+    # Register our hooks: we need to run before validation to make sure any validations defined directly on a flex
+    # column class are run (and transfer their errors over to the model object itself), and to run before save to make
+    # sure we serialize up any changes from a flex-column object.
+    included do
+      before_validation :_flex_columns_before_validation!
+      before_save :_flex_columns_before_save!
+    end
+
+    # Before we save this model, make sure each flex column has a chance to serialize itself up and assign itself
+    # properly to this model object. Note that we only need to call through to flex-column objects that have actually
+    # been instantiated, since, by definition, there's no way the contents of any other flex columns could possibly
+    # have been changed.
+    def _flex_columns_before_save!
+      self.class._all_flex_column_names.each do |flex_column_name|
+        klass = self.class._flex_column_class_for(flex_column_name)
+        if klass.requires_serialization_on_save?(self)
+          _flex_column_object_for(flex_column_name).before_save!
+        end
+      end
+    end
+
+    # Before we validate this model, make sure each flex column has a chance to run its validations and propagate any
+    # errors back to this model. Note that we need to call through to any flex-column object that has a validation
+    # defined, since we want to comply with Rails' validation strategy: validations run whenever you save an object,
+    # whether you've changed that particular attribute or not.
+    def _flex_columns_before_validation!
+      _all_present_flex_column_objects.each do |flex_column_object|
+        flex_column_object.before_validation! if flex_column_object.touched?
+      end
+    end
+
+    # Returns the correct flex-column object for the given column name. This simply creates an instance of the
+    # appropriate flex-column class, and saves it away so it will be returned again if someone requests the object for
+    # the same column later.
+    def _flex_column_object_for(column_name, create_if_needed = true)
+      # It's possible to end up with two copies of this method on a class, if that class both has a flex column of its
+      # own _and_ includes one via FlexColumns::Including::IncludeFlexColumns#include_flex_columns_from. If so, we want
+      # each method to defer to the other one, so that both will work.
+      begin
+        return super(column_name)
+      rescue NoMethodError
+        # ok
+      rescue FlexColumns::Errors::NoSuchColumnError
+        # ok
+      end
+
+      column_name = self.class._flex_column_normalize_name(column_name)
+
+      out = _flex_column_objects[column_name]
+      if (! out) && create_if_needed
+        out = _flex_column_objects[column_name] = self.class._flex_column_class_for(column_name).new(self)
+      end
+      out
+    end
+
+    # When you reload a model object, we should reload its flex-column objects, too.
+    def reload(*args)
+      super(*args)
+      @_flex_column_objects = { }
+    end
+
+    private
+    # Returns the Hash that we keep flex-column objects in, indexed by column name.
+    def _flex_column_objects
+      @_flex_column_objects ||= { }
+    end
+
+    # Returns all flex-column objects that have been instantiated -- that is, any flex-column object that anybody has
+    # asked for yet.
+    def _all_present_flex_column_objects
+      _flex_column_objects.values
+    end
+
+    module ClassMethods
+      # Does this class have any flex columns? If this module has been included into a class, then the answer is true.
+      def has_any_flex_columns?
+        true
+      end
+
+      # What are the names of all flex columns defined on this model?
+      def _all_flex_column_names
+        _flex_column_classes.map(&:column_name)
+      end
+
+      # Normalizes the name of a flex column, so we're consistent when using it for things like hash keys, no matter
+      # how the client specifies it to us.
+      def _flex_column_normalize_name(flex_column_name)
+        flex_column_name.to_s.strip.downcase.to_sym
+      end
+
+      # Given the name of a flex column, returns the flex-column class for that column. Raises
+      # FlexColumns::Errors::NoSuchColumnError if there is no column with the given name.
+      def _flex_column_class_for(flex_column_name)
+        flex_column_name = _flex_column_normalize_name(flex_column_name)
+        out = _flex_column_classes.detect { |fcc| fcc.column_name == flex_column_name }
+
+        unless out
+          raise FlexColumns::Errors::NoSuchColumnError, %{Model class #{self.name} has no flex column named #{flex_column_name.inspect};
+it has flex columns named: #{_all_flex_column_names.sort_by(&:to_s).inspect}.}
+        end
+
+        out
+      end
+
+      # Returns the DynamicMethodsModule that we add methods to that should be present on this model class.
+      def _flex_column_dynamic_methods_module
+        @_flex_column_dynamic_methods_module ||= FlexColumns::Util::DynamicMethodsModule.new(self, :FlexColumnsDynamicMethods)
+      end
+
+      # Declares a new flex column. +flex_column_name+ is its name; +options+ is passed through to
+      # FlexColumns::Definition::FlexColumnContentsClass#setup!, and so can contain any of the options that that method
+      # accepts. The block, if passed, will be evaluated in the context of the generated class.
+      def flex_column(flex_column_name, options = { }, &block)
+        flex_column_name = _flex_column_normalize_name(flex_column_name)
+
+        new_class = Class.new(FlexColumns::Contents::FlexColumnContentsBase)
+        new_class.setup!(self, flex_column_name, options, &block)
+
+        _flex_column_classes.delete_if { |fcc| fcc.column_name == flex_column_name }
+        _flex_column_classes << new_class
+
+        define_method(flex_column_name) do
+          _flex_column_object_for(flex_column_name)
+        end
+
+        _flex_column_dynamic_methods_module.remove_all_methods!
+        _flex_column_classes.each(&:sync_methods!)
+      end
+
+      # Exactly like #create_flex_objects_from, except that instead of taking an Array of raw strings and returning
+      # an Array of flex-column objects, takes a single raw string and returns a single flex-column object.
+      #
+      # #create_flex_objects_from is currently very slightly faster than simply calling this method in a loop; however,
+      # in the future, the difference in performance may increase. If you have more than one string to create a
+      # flex-column object from, you should definitely use #create_flex_objects_from instead of this method.
+      def create_flex_object_from(column_name, raw_string)
+        _flex_column_class_for(column_name).new(raw_string)
+      end
+
+      # Given the name of a column in +column_name+ and an Array of (possibly nil) JSON-formatted strings (which can
+      # also be compressed using the +flex_columns+ compression mechanism), returns an Array of new flex-column objects
+      # for that column that are not attached to any particular model instance. These objects will obey all
+      # field-definition rules for that column, be able to validate themselves (if you call #valid? on them),
+      # retrieve data, have any custom methods defined on them that you defined on that flex column, and so on.
+      #
+      # However, because they're detached from any model instance, they also won't save themselves to the database under
+      # any circumstances; you are responsible for calling #to_stored_data on them, and getting those strings into the
+      # database in the right places yourself, if you want to save them.
+      #
+      # The purpose of this method is to allow you to use +flex_columns+ in bulk-access situations, such as when you've
+      # selected many records from the database without using ActiveRecord, for performance reasons (_e.g._,
+      # <tt>User.connection.select_all("..."))</tt>.
+      def create_flex_objects_from(column_name, raw_strings)
+        column_class = _flex_column_class_for(column_name)
+        raw_strings.map do |rs|
+          column_class.new(rs)
+        end
+      end
+
+      private
+      # Returns the set of currently-active flex-column classes -- that is, classes that inherit from
+      # FlexColumns::Contents::FlexColumnContentsBase and represent our declared flex columns. We say "currently active"
+      # because declaring a new flex column with the same name as a previous one will replace its class in this list.
+      #
+      # This is an Array instead of a Hash because the order in which we sync methods to the dynamic-methods module
+      # matters: flex columns declared later should have any delegate methods they declare supersede any methods from
+      # flex columns declared previously. While Ruby >= 1.9 has ordered Hashes, which means we could use it here, we
+      # still support Ruby 1.8, and so need the ordering that an Array gives us.
+      def _flex_column_classes
+        @_flex_column_classes ||= [ ]
+      end
+    end
+  end
+end

data/lib/flex_columns/including/include_flex_columns.rb

@@ -0,0 +1,179 @@
+require 'active_support/concern'
+
+module FlexColumns
+  module Including
+    # IncludeFlexColumns defines the methods on ActiveRecord::Base that get triggered when you say
+    # 'include_flex_columns_from' on an ActiveRecord model. Note, however, that it is not simply directly included
+    # into ActiveRecord::Base; rather, it's included only when you actually make that declaration, and included
+    # into the specific model class itself. (This helps avoid pollution or conflict on any ActiveRecord models that
+    # have not used this functionality.)
+    #
+    # This module works in a pretty different way from FlexColumns::HasFlexColumns, which is the corresponding module
+    # that gets included when you declare a flex column with <tt>flex_column :foo do ... end</tt>. That module builds
+    # up an object representation of the flex column itself and of all its fields, and then holds onto these objects
+    # and uses them to do its work. This module, on the other hand, actively and aggressively defines the appropriate
+    # methods when you call #include_flex_columns_from, but does not create or hold onto any object representation of
+    # the included columns. This is for two reasons: first off, there's a lot more complexity in defining a flex
+    # column itself than in simply including one. Secondly, and more subtly, defining a flex column is a process with
+    # a decided start and end -- the contents of the block passed to +flex_column+. Including fields, however, is a
+    # component part of a class that's defined using the Ruby +class+ keyword, and which can get reopened and redefined
+    # at any given time. Thus, we really have no choice but to aggressively define methods when
+    # +include_flex_columns_from+ is called; holding onto an object representation would largely just ensure that that
+    # object representation grew incorrect over time in development mode, as columns get defined and redefined over
+    # time.
+    #
+    # (A corollary of this is that, in Rails development mode, depending on how classes get reloaded, it's possible that
+    # if you remove an +include_flex_columns_from+ declaration from a model, the defined methods won't actually
+    # disappear until you restart your server. There's really not much we can do about this, since there's no Ruby hook
+    # that says "someone is defining methods on class X" -- nor would one make any sense, since you can re-open classes
+    # at any time and as many times as you want in Ruby.)
+    #
+    # In comments below, we're working with the following example:
+    #
+    #    class UserDetail < ActiveRecord::Base
+    #      self.primary_key = :user_id
+    #      belongs_to :user
+    #
+    #      flex_column :details do
+    #        field :background_color
+    #        field :likes_peaches
+    #      end
+    #    end
+    #
+    #    class User < ActiveRecord::Base
+    #      has_one :detail
+    #
+    #      include_flex_columns_from :detail
+    #    end
+    module IncludeFlexColumns
+      # Make sure our ClassMethods module gets +extend+ed into any class that +include+s us.
+      extend ActiveSupport::Concern
+
+      # This is the method that gets called by generated delegated methods, and called in order to retrieve the
+      # correct flex-column object for a column. In other words, the generated method User#background_color looks
+      # something like:
+      #
+      #     def background_color
+      #       flex_column_object = _flex_column_object_for(:details)
+      #       flex_column_object.background_color
+      #     end
+      #
+      # (We do this partially so that the exact same method definition works for UserDetail and for User; _i.e._,
+      # whether you're running on a class that itself has a flex column, or on a class that simply is including another
+      # class's flex columns, #_flex_column_object_for will get you the right object.)
+      #
+      # There's only one nasty case to deal with here: what if User has its own flex column +detail+? In such a case, we
+      # want to return the flex-column object that's defined for the column the class has itself, not for the one it's
+      # including.
+      def _flex_column_object_for(column_name)
+        # This is the "nasty case", above.
+        begin
+          return super(column_name)
+        rescue NoMethodError
+          # ok
+        rescue FlexColumns::Errors::NoSuchColumnError
+          # ok
+        end
+
+        # Fetch the association that this column is included from.
+        association = self.class._flex_column_is_included_from(column_name)
+
+        if association
+          # Get the associated object. We automatically will build the associated object, if necessary; this is so that
+          # you don't have to either actively create associated objects ahead of time, just in case you need them later,
+          # or litter your code with checks to see if those objects exist already or not.
+          associated_object = send(association) || send("build_#{association}")
+          return associated_object.send(column_name)
+        else
+          raise FlexColumns::Errors::NoSuchColumnError.new(%{Class #{self.class.name} knows nothing of a flex column named #{column_name.inspect}.})
+        end
+      end
+
+      module ClassMethods
+        # The DynamicMethodsModule on which we define all methods generated by included flex columns.
+        def _flex_columns_include_flex_columns_dynamic_methods_module
+          @_flex_columns_include_flex_columns_dynamic_methods_module ||= FlexColumns::Util::DynamicMethodsModule.new(self, :FlexColumnsIncludedColumnsMethods)
+        end
+
+        # Returns the name of the association from which a flex column of the given name was included.
+        def _flex_column_is_included_from(flex_column_name)
+          @_included_flex_columns_map[flex_column_name]
+        end
+
+        # Includes methods from the given flex column or flex columns into this class.
+        #
+        # +args+ should be a list of association names from which you want to include columns. It can also end in an
+        # options Hash, which can contain:
+        #
+        # [:prefix] If set, included method names will be prefixed with the given string (followed by an underscore).
+        #           If not set, the prefix defined on each flex column, if any, will be used; you can override this by
+        #           explicitly passing +nil+ here.
+        # [:visibility] If set to +:private+, included methods will be marked +private+, meaning they can only be
+        #               accessed from inside this model. This can be used to ensure random code across your system
+        #               can't directly manipulate flex-column fields.
+        # [:delegate] If set to +false+ or +nil+, then only the method that accesses the flex column itself (above,
+        #             User#details) will be created; other methods (User#background_color, User#likes_peaches) will
+        #             not be automatically delegated.
+        def include_flex_columns_from(*args, &block)
+          # Grab our options, and validate them as necessary...
+          options = args.pop if args[-1] && args[-1].kind_of?(Hash)
+          options ||= { }
+
+          options.assert_valid_keys(:prefix, :visibility, :delegate)
+
+          case options[:prefix]
+          when nil, String, Symbol then nil
+          else raise ArgumentError, "Invalid value for :prefix: #{options[:prefix].inspect}"
+          end
+
+          unless [ :public, :private, nil ].include?(options[:visibility])
+            raise ArgumentError, "Invalid value for :visibility: #{options[:visibility].inspect}"
+          end
+
+          unless [ true, false, nil ].include?(options[:delegate])
+            raise ArgumentError, "Invalid value for :delegate: #{options[:delegate].inspect}"
+          end
+
+          association_names = args
+
+          @_included_flex_columns_map ||= { }
+
+          # Iterate through each association...
+          association_names.each do |association_name|
+            # Get the association and make sure it's of the right type...
+            association = reflect_on_association(association_name.to_sym)
+            unless association
+              raise ArgumentError, %{You asked #{self.name} to include flex columns from association #{association_name.inspect},
+  but this class doesn't seem to have such an association. Associations it has are:
+
+    #{reflect_on_all_associations.map(&:name).sort_by(&:to_s).join(", ")}}
+            end
+
+            unless [ :has_one, :belongs_to ].include?(association.macro)
+              raise ArgumentError, %{You asked #{self.name} to include flex columns from association #{association_name.inspect},
+  but that association is of type #{association.macro.inspect}, not :has_one or :belongs_to.
+
+  We can only include flex columns from an association of these types, because otherwise
+  there is no way to know which target object to include the data from.}
+            end
+
+            # Grab the target model class, and make sure it has one or more flex columns...
+            target_class = association.klass
+            if (! target_class.respond_to?(:has_any_flex_columns?)) || (! target_class.has_any_flex_columns?)
+              raise ArgumentError, %{You asked #{self.name} to include flex columns from association #{association_name.inspect},
+  but the target class of that association, #{association.klass.name}, has no flex columns defined.}
+            end
+
+            # Call through and tell those flex columns to create the appropriate methods.
+            target_class._all_flex_column_names.each do |flex_column_name|
+              @_included_flex_columns_map[flex_column_name] = association_name
+
+              flex_column_class = target_class._flex_column_class_for(flex_column_name)
+              flex_column_class.include_fields_into(_flex_columns_include_flex_columns_dynamic_methods_module, association_name, self, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flex_columns/util/dynamic_methods_module.rb

@@ -0,0 +1,86 @@
+module FlexColumns
+  module Util
+    # 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.
+    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
+
+        @target_class.const_set(@name, self)
+        @target_class.send(:include, self)
+
+        @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
+      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
+
+      # 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
+end