has_metadata_column 1.0.0

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Tim Morgan
+
+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,106 @@
+Has Metadata Column -- Keep your tables narrow
+===================
+
+|             |                                 |
+|:------------|:--------------------------------|
+| **Author**  | Tim Morgan                      |
+| **Version** | 1.0 (Mar 1, 2012)               |
+| **License** | Released under the MIT License. |
+
+About
+-----
+
+So you're wondering why it is you need to make, test, schedule, and deploy a
+whole nother migration just to add one more freeform "Favorite Music"-type
+column to your users model?  Wish there were an easier way?
+
+There is! Combine all of those "about me," "favorite music," etc. type fields
+into _one_ JSON-serialized `TEXT` column, and now every model can have
+schemaless, migration-free data.
+
+If you're interested in moving your metadata out to another table (or database)
+entirely, consider using
+[HasMetadata](https://github.com/riscfuture/has_metadata).
+
+This gem does use some "metaprogramming magic" to make the metadata fields
+appear like first-class fields, for purposes of validation and easy access. If
+this is unsettling to you, I recommend using my gem
+[JsonSerialize](https://github.com/riscfuture/json_serialize) instead, as it
+does not get its little fingers all up in ActiveRecord's business.
+
+(Why yes, I _do_ have a gem for a every use case!)
+
+h2. Installation
+
+**Important Note:** This gem is only compatible with Ruby 1.9 and Rails 3.0.
+
+Merely add the gem to your Rails project's `Gemfile`:
+
+```` ruby
+gem 'has_metadata_column'
+````
+
+Usage
+-----
+
+The first thing to think about is what columns to keep. You will need to keep
+any indexed columns, or any columns you perform lookups or other SQL queries
+with. You should also keep any frequently accessed columns, especially if they
+are small (integers or booleans). Good candidates for the metadata column are
+the `TEXT`- and `VARCHAR`-type columns that you only need to render a page or
+two in your app.
+
+You'll need to add a `TEXT` column to your model to store the metadata. You can
+call it what you want; `metadata` is assumed by default.
+
+```` ruby
+t.text :metadata
+````
+
+Next, include the `HasMetadataColumn` module in your model, and call the
+`has_metadata_column` method to define the schema of your metadata. You can get
+more information in the {HasMetadataColumn::ClassMethods#has_metadata_column}
+documentation, but for starters, here's a basic example:
+
+```` ruby
+class User < ActiveRecord::Base
+  include HasMetadataColumn
+  has_metadata(
+    :my_metadata_column,
+    about_me:  { type: String, length: { maximum: 512 } },
+    birthdate: { type: Date, presence: true },
+    zipcode:   { type: Number, numericality: { greater_than: 9999, less_than: 10_000 } }
+  )
+end
+````
+
+As you can see, you pass field names mapped to a hash. The hash describes the
+validation that will be performed, and is in the same format as a call to
+`validates`. In addition to the `EachValidator` keys shown above, you can also
+pass a `type` key, to constrain the Ruby type that can be assigned to the field.
+You can only assign types that can be JSON-serialized: strings, numbers, arrays,
+hashes, dates/times, booleans, and `nil`.
+
+Each of these fields (in this case, `about_me`, `birthdate`, and `zipcode`) can
+be accessed and set as first_level methods on an instance of your model:
+
+```` ruby
+user.about_me #=> "I was born in 1982 in Aberdeen. My father was a carpenter from..."
+````
+
+... and thus, used as part of `form_for` fields:
+
+```` ruby
+form_for user do |f|
+  f.text_area :about_me, rows: 5, cols: 80
+end
+````
+
+... and validations.
+
+The only thing you _can't_ do is use these fields in a query, obviously. You
+can't do something like `User.where(zipcode: 90210)`, because that column
+doesn't exist on the `users` table.
+
+... Unless you use PostgreSQL 9.2, and define your metadata column as type
+`json`. Support for _that_ is coming...

data/has_metadata_column.gemspec

@@ -0,0 +1,61 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "has_metadata_column"
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Morgan"]
+  s.date = "2012-03-02"
+  s.description = "Reduce your table width and migration overhead by moving non-indexed columns to a separate metadata column."
+  s.email = "git@timothymorgan.info"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    "README.md",
+    "has_metadata_column.gemspec",
+    "lib/has_metadata_column.rb"
+  ]
+  s.homepage = "http://github.com/riscfuture/has_metadata_column"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new(">= 1.9")
+  s.rubygems_version = "1.8.17"
+  s.summary = "Schemaless metadata using JSON columns"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rails>, [">= 3.0"])
+      s.add_runtime_dependency(%q<boolean>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<redcarpet>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<rails>, [">= 3.0"])
+      s.add_dependency(%q<boolean>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<sqlite3>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<redcarpet>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rails>, [">= 3.0"])
+    s.add_dependency(%q<boolean>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<sqlite3>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<redcarpet>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+

data/lib/has_metadata_column.rb

@@ -0,0 +1,275 @@
+require 'boolean'
+
+# @private
+class Object
+
+  # Creates a deep copy of this object.
+  #
+  # @raise [TypeError] If the object cannot be deep-copied. All objects that can
+  #   be marshalled can be deep-copied.
+
+  def deep_clone
+    Marshal.load Marshal.dump(self)
+  end
+end
+
+# Provides the {ClassMethods#has_metadata_column} method to subclasses of
+# `ActiveRecord::Base`.
+
+module HasMetadataColumn
+  extend ActiveSupport::Concern
+
+  # Valid values for the `:type` option.
+  TYPES = [ String, Fixnum, Integer, Float, Hash, Array, TrueClass, FalseClass, Boolean, NilClass, Date, Time ]
+
+  # @private
+  def self.metadata_typecast(value, type=nil)
+    type ||= String
+    raise ArgumentError, "Can't convert objects of type #{type.to_s}" unless TYPES.include?(type)
+
+    if value.kind_of?(String) then
+      if type == Integer or type == Fixnum then
+        begin
+          return Integer(value.sub(/^0+/, '')) # so that it doesn't think it's in octal
+        rescue ArgumentError
+          return value
+        end
+      elsif type == Float then
+        begin
+          return Float(value)
+        rescue ArgumentError
+          return value
+        end
+      elsif type == Boolean then
+        return value.parse_bool
+      elsif type == Date then
+        return nil if value.nil?
+        begin
+          return Date.parse(value)
+        rescue ArgumentError
+          return value
+        end
+      elsif type == Time then
+        return nil if value.nil?
+        begin
+          return Time.parse(value)
+        rescue ArgumentError
+          return value
+        end
+      end
+    end
+    return value
+  end
+
+  # Class methods that are added to your model.
+
+  module ClassMethods
+
+    # Defines a set of fields whose values exist in the JSON metadata column.
+    # Each key in the `fields` hash is the name of a metadata field, and the
+    # value is a set of options to pass to the `validates` method. If you do not
+    # want to perform any validation on a field, simply pass `true` as its key
+    # value.
+    #
+    # In addition to the normal `validates` keys, you can also include a `:type`
+    # key to restrict values to certain classes, or a `:default` key to specify
+    # a value to return for the getter should none be set (normal default is
+    # `nil`). See {TYPES} for a list of valid values.
+    #
+    # @overload has_metadata_column(column, fields)
+    #   @param [Symbol] column (:metadata) The column containing the metadata
+    #     information.
+    #   @param [Hash<Symbol, Hash>] fields A mapping of field names to their
+    #     validation options (and/or the `:type` key).
+    # @raise [ArgumentError] If invalid arguments are given, or an invalid
+    #   class for the `:type` key.
+    # @raise [StandardError] If invalid field names are given (see source).
+    #
+    # @example Three metadata fields, one basic, one validated, and one type-checked.
+    #   has_metadata_column(optional: true, required: { presence: true }, number: { type: Fixnum })
+
+    def has_metadata_column(*args)
+      fields = args.extract_options!
+      column = args.shift
+
+      raise ArgumentError, "has_metadata_column takes a column name and a hash of fields" unless args.empty?
+      raise "Can't define Rails-magic timestamped columns as metadata" if Rails.version >= '3.2.0' && (fields.keys & [:created_at, :created_on, :updated_at, :updated_on]).any?
+      classes = fields.values.select { |o| o[:type] && !TYPES.include?(o[:type]) }
+      raise ArgumentError, "#{classes.to_sentence} cannot be serialized to JSON" if classes.any?
+
+      if !respond_to?(:metadata_column_fields) then
+        class_attribute :metadata_column_fields
+        self.metadata_column_fields = fields.deep_clone
+        class_attribute :metadata_column
+        self.metadata_column = column || :metadata
+
+        after_save :_reset_metadata
+
+        alias_method_chain :changed_attributes, :metadata_column
+        alias_method_chain :attribute_will_change!, :metadata_column
+        alias_method_chain :attribute_method?, :metadata
+        alias_method_chain :attribute, :metadata
+        alias_method_chain :attribute_before_type_cast, :metadata
+        alias_method_chain :_attribute, :metadata
+        alias_method_chain :attribute=, :metadata
+        alias_method_chain :query_attribute, :metadata
+        alias_method_chain :reload, :metadata
+      else
+        raise "Cannot redefine existing metadata column #{self.metadata_column}" if column && column != self.metadata_column
+        if metadata_column_fields.slice(*fields.keys) != fields
+          raise "Cannot redefine existing metadata fields: #{(fields.keys & self.metadata_column_fields.keys).to_sentence}" unless (fields.keys & self.metadata_column_fields.keys).empty?
+          self.metadata_column_fields = self.metadata_column_fields.merge(fields)
+        end
+      end
+
+      fields.each do |name, options|
+        if options.kind_of?(Hash) then
+          type          = options.delete(:type)
+          type_validate = !options.delete(:skip_type_validation)
+          options.delete :default
+
+          validate do |obj|
+            value = obj.send(name)
+            errors.add(name, :incorrect_type) if !HasMetadataColumn.metadata_typecast(value, type).kind_of?(type) &&
+              (!options[:allow_nil] || (options[:allow_nil] && !value.nil?)) &&
+              (!options[:allow_blank] || (options[:allow_blank] && !value.blank?))
+          end if type && type_validate
+          validates(name, options) unless options.empty? or (options.keys - [:allow_nil, :allow_blank]).empty?
+        end
+      end
+    end
+  end
+
+  # @private
+  def as_json(options={})
+    options           ||= Hash.new # the JSON encoder can sometimes give us nil options?
+    options[:except]  = Array.wrap(options[:except]) + [ self.class.metadata_column ]
+    options[:methods] = Array.wrap(options[:methods]) + self.class.metadata_column_fields.keys - options[:except].map(&:to_sym)
+    super options
+  end
+
+  # @private
+  def to_xml(options={})
+    options[:except]  = Array.wrap(options[:except]) + [ self.class.metadata_column ]
+    options[:methods] = Array.wrap(options[:methods]) + self.class.metadata_column_fields.keys - options[:except].map(&:to_sym)
+    super options
+  end
+
+  # @private
+  def assign_multiparameter_attributes(pairs)
+    fake_attributes = pairs.select { |(field, _)| self.class.metadata_column_fields.include? field[0, field.index('(')].to_sym }
+
+    fake_attributes.group_by { |(field, _)| field[0, field.index('(')] }.each do |field_name, parts|
+      options = self.class.metadata_column_fields[field_name.to_sym]
+      if options[:type] then
+        args = parts.each_with_object([]) do |(part_name, value), ary|
+          part_ann = part_name[part_name.index('(') + 1, part_name.length]
+          index    = part_ann.to_i - 1
+          raise "Out-of-bounds multiparameter argument index" unless index >= 0
+          ary[index] = if value.blank? then
+                         nil
+                       elsif part_ann.ends_with?('i)') then
+                         value.to_i
+                       elsif part_ann.ends_with?('f)') then
+                         value.to_f
+                       else
+                         value
+                       end
+        end
+        send :"#{field_name}=", options[:type].new(*args) unless args.empty?
+      else
+        raise "#{field_name} has no type and cannot be used for multiparameter assignment"
+      end
+    end
+
+    super(pairs - fake_attributes)
+  end
+
+  # @private
+  def inspect
+    "#<#{self.class.to_s} #{attributes.except(self.class.metadata_column.to_s).merge(_metadata_hash.try(:stringify_keys) || {}).map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+  end
+  
+  # @private
+  def reload_with_metadata
+    res = reload_without_metadata
+    @_metadata_hash = nil
+    @_changed_metadata = nil
+    res
+  end
+
+  private
+
+  def changed_attributes_with_metadata_column
+    changed_attributes_without_metadata_column.merge(_changed_metadata)
+  end
+
+  def attribute_will_change_with_metadata_column!(attr)
+    unless attribute_names.include?(attr)
+      send :"#{self.class.metadata_column}_will_change!"
+    end
+    attribute_will_change_without_metadata_column! attr
+  end
+
+  def _metadata_hash
+    @_metadata_hash ||= begin
+      send(self.class.metadata_column) ? JSON.parse(send(self.class.metadata_column)) : {}
+    end
+  end
+
+  def _changed_metadata
+    @_changed_metadata ||= {}
+  end
+
+  ## ATTRIBUTE MATCHER METHODS
+
+  def attribute_with_metadata(attr)
+    return attribute_without_metadata(attr) unless self.class.metadata_column_fields.include?(attr.to_sym)
+
+    options = self.class.metadata_column_fields[attr.to_sym] || {}
+    default = options.include?(:default) ? options[:default] : nil
+    _metadata_hash.include?(attr) ? HasMetadataColumn.metadata_typecast(_metadata_hash[attr], options[:type]) : default
+  end
+
+  def attribute_before_type_cast_with_metadata(attr)
+    return attribute_before_type_cast_without_metadata(attr) unless self.class.metadata_column_fields.include?(attr.to_sym)
+    options = self.class.metadata_column_fields[attr.to_sym] || {}
+    default = options.include?(:default) ? options[:default] : nil
+    _metadata_hash.include?(attr) ? _metadata_hash[attr] : default
+  end
+
+  def _attribute_with_metadata(attr)
+    return _attribute_without_metadata(attr) unless self.class.metadata_column_fields.include?(attr.to_sym)
+    attribute_with_metadata attr
+  end
+
+  def attribute_with_metadata=(attr, value)
+    return send(:attribute_without_metadata=, attr, value) unless self.class.metadata_column_fields.include?(attr.to_sym)
+
+    options = self.class.metadata_column_fields[attr.to_sym] || {}
+    attribute_will_change! attr
+    @_metadata_hash ||= {}
+    old = @_metadata_hash[attr.to_s]
+    send :"#{self.class.metadata_column}=", @_metadata_hash.merge(attr.to_s => value).to_json
+    @_metadata_hash = nil
+    @_changed_metadata[attr] = old
+    value
+  end
+
+  def query_attribute_with_metadata(attr)
+    return query_attribute_without_metadata(attr) unless self.class.metadata_column_fields.include?(attr.to_sym)
+    return false unless (value = send(attr))
+    options = self.class.metadata_column_fields[attr.to_sym] || {}
+    type = options[:type] || String
+    return !value.to_i.zero? if type.ancestors.include?(Numeric)
+    return !value.blank?
+  end
+
+  def attribute_method_with_metadata?(attr)
+    self.class.metadata_column_fields.include?(attr.to_sym) || attribute_method_without_metadata?(attr)
+  end
+
+  def _reset_metadata
+    @_changed_metadata = {}
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: has_metadata_column
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &70347550669760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70347550669760
+- !ruby/object:Gem::Dependency
+  name: boolean
+  requirement: &70347550669280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70347550669280
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70347550668800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70347550668800
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &70347550668320 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70347550668320
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70347550667840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70347550667840
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &70347550667360 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70347550667360
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &70347551403380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70347551403380
+description: Reduce your table width and migration overhead by moving non-indexed
+  columns to a separate metadata column.
+email: git@timothymorgan.info
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- README.md
+- has_metadata_column.gemspec
+- lib/has_metadata_column.rb
+- LICENSE.txt
+homepage: http://github.com/riscfuture/has_metadata_column
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '1.9'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Schemaless metadata using JSON columns
+test_files: []