has_easy 0.9.0

data/CHANGELOG

@@ -0,0 +1,16 @@
+06/23/2008
+* added :postprocess option
+* only the "underscore accessors" are affected by :preprocess and :postprocess
+
+06/20/2008
+* added :default_dynamic option
+
+06/19/2008
+* added validation via naming a method with a Symbol
+* added support for custom validation error messages
+
+06/18/2008
+* added :alias and :aliases options to has_easy
+
+03/28/2012
+* converted to a gem, version 0.9.0 (Jeff Wigal)

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+  gem "sqlite3"
+end
+
+gem "rails", ">= 3.0"

data/Gemfile.lock

@@ -0,0 +1,100 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.1.3)
+      actionpack (= 3.1.3)
+      mail (~> 2.3.0)
+    actionpack (3.1.3)
+      activemodel (= 3.1.3)
+      activesupport (= 3.1.3)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      i18n (~> 0.6)
+      rack (~> 1.3.5)
+      rack-cache (~> 1.1)
+      rack-mount (~> 0.8.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.0.3)
+    activemodel (3.1.3)
+      activesupport (= 3.1.3)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activerecord (3.1.3)
+      activemodel (= 3.1.3)
+      activesupport (= 3.1.3)
+      arel (~> 2.2.1)
+      tzinfo (~> 0.3.29)
+    activeresource (3.1.3)
+      activemodel (= 3.1.3)
+      activesupport (= 3.1.3)
+    activesupport (3.1.3)
+      multi_json (~> 1.0)
+    arel (2.2.3)
+    builder (3.0.0)
+    erubis (2.7.0)
+    git (1.2.5)
+    hike (1.2.1)
+    i18n (0.6.0)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    json (1.6.5)
+    mail (2.3.2)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.17.2)
+    multi_json (1.1.0)
+    polyglot (0.3.3)
+    rack (1.3.6)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-mount (0.8.3)
+      rack (>= 1.0.0)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rails (3.1.3)
+      actionmailer (= 3.1.3)
+      actionpack (= 3.1.3)
+      activerecord (= 3.1.3)
+      activeresource (= 3.1.3)
+      activesupport (= 3.1.3)
+      bundler (~> 1.0)
+      railties (= 3.1.3)
+    railties (3.1.3)
+      actionpack (= 3.1.3)
+      activesupport (= 3.1.3)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (0.9.2.2)
+    rcov (1.0.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    shoulda (2.11.3)
+    sprockets (2.0.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.5)
+    thor (0.14.6)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.32)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.4)
+  rails (>= 3.0)
+  rcov
+  shoulda
+  sqlite3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+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

@@ -0,0 +1,306 @@
+Easy access and creation of "has many" relationships.
+
+What's the difference between flags, preferences and options?  Nothing really, they are just "has many" relationships.  So why should I install a separate plugin for each one?  This plugin can be used to add preferences, flags, options, etc to any model.
+
+==Installation
+In your Gemfile:
+
+ gem "has_easy"
+
+At the command prompt:
+ rails g has_easy_migration
+ rake db:migrate
+ 
+==Example
+
+ class User < ActiveRecord::Base
+   has_easy :preferences do |p|
+     p.define :color
+     p.define :theme
+   end
+   has_easy :flags do |f|
+     f.define :is_admin
+     f.define :is_spammer
+   end
+ end
+
+ user = User.new
+ 
+ # hash like access
+ user.preferences[:color] = 'red'
+ user.preferences[:color] # => 'red'
+ 
+ # object like access
+ user.preferences.theme? # => false, shorthand for !!user.preferences.theme
+ user.preferences.theme = "savage thunder"
+ user.preferences.theme # => "savage thunder"
+ user.preferences.theme? # => true
+ 
+ # easy access for form inputs
+ user.flags_is_admin? # => false, shorthand for !!user.flags_is_admin
+ user.flags_is_admin = true
+ user.flags_is_admin # => true
+ user.flags_is_admin? # => true
+
+ # save user's preferences
+ user.preferences.save # will trickle down validation errors to user
+ user.errors.empty? # hopefully true
+ 
+ # save user's flags
+ user.flags.save! # will raise exception on validation errors
+
+
+==Advanced Usage
+There are a lot of options that you can use with has_easy:
+* aliasing
+* default values
+* inheriting default values from parent associations
+* calculated default values
+* type checking values
+* validating values
+* preprocessing values
+In this section, we'll go over how to use each option and explain why it's useful.
+
+===:alias and :aliases
+These options go on the has_easy method call and specify alternate ways of invoking the association.
+  class User < ActiveRecord::Base
+    has_easy :preferences, :aliases => [:prefs, :options] do |p|
+      p.define :likes_cheese
+    end
+    has_easy :flags, :alias => :status do |p|
+      p.define :is_admin
+    end
+  end
+
+  user.preferences.likes_cheese = 'yes'
+  user.prefs.likes_cheese => 'yes'
+  user.options_likes_cheese => 'yes'
+  user.prefs[:likes_cheese] => 'yes'
+  user.options.likes_cheese? => true
+  ...etc...
+
+===:default
+Very simple.  It does what you think it does.
+ class User < ActiveRecord::Base
+   has_easy :options do |p|
+     p.define :gender, :default => 'female'
+   end
+ end
+ 
+ User.new.options.gender # => 'female'
+
+===:default_through
+Allows the model to inherit it's default value from an association.
+ class Client < ActiveRecord::Base
+   has_many :users
+   has_easy :options do |p|
+     p.define :gender, :default => 'male'
+   end
+ end
+ class User < ActiveRecord::Base
+   belongs_to :client
+   has_easy :options do |p|
+     p.define :gender, :default_through => :client, :default => 'female'
+   end
+ end
+ 
+ client = Client.create
+ user = client.users.create
+ user.options.gender # => 'male'
+ 
+ client.options.gender = 'asexual'
+ client.options.save
+ user.client(true) # reload association
+ user.options.gender # => 'asexual'
+ 
+ User.new.options.gender => 'female'
+ 
+
+===:default_dynamic
+Allows for calculated default values.
+  class User < ActiveRecord::Base
+    has_easy 'prefs' do |t|
+      t.define :likes_cheese, :default_dynamic => :defaults_to_like_cheese
+      t.define :is_dumb, :default_dynamic => Proc.new{ |user| user.dumb_post_count > 10 }
+    end
+  
+    def defaults_to_like_cheese
+      cheesy_post_count > 10
+    end
+  end
+
+  user = User.new :cheesy_post_count => 5
+  user.prefs.likes_cheese? => false
+  
+  user = User.new :cheesy_post_count => 11
+  user.prefs.likes_cheese? => true
+  
+  user = User.new :dumb_post_count => 5
+  user.prefs.is_dumb? => false
+  
+  user = User.new :dumb_post_count => 11
+  user.prefs.is_dumb? => true
+
+
+===:type_check
+Allows type checking of values (for people who are into that).
+  class User < ActiveRecord::Base
+    has_easy :prefs do |p|
+      p.define :theme, :type_check => String
+      p.define :dollars, :type_check => [Fixnum, Bignum]
+    end
+  end
+
+  user.prefs.theme = 123
+  user.prefs.save! # ActiveRecord::InvalidRecord exception raised with message like:
+                   # 'theme' for has_easy('prefs') failed type check
+
+  user.prefs.dollars = "hello world"
+  user.prefs.save
+  user.errors.empty? # => false
+  user.errors.on(:prefs) # => 'dollars' for has_easy('prefs') failed type check
+
+
+===:validate
+Make sure that values fit some kind of criteria.  If you use a Proc or name a method with a Symbol to do validation, there are three ways to specify failure:
+1. return false
+2. raise a HasEasy::ValidationError
+3. return an array of custom validation error messages
+  class User < ActiveRecord::Base
+    has_easy :prefs do |p|
+      p.define :foreground, :validate => ['red', 'blue', 'green']
+      p.define :background, :validate => Proc.new{ |value| %w[black white grey].include?(value) }
+      p.define :midground,  :validate => :midground_validator
+    end
+    def midground_validator(value)
+      return ["msg1", msg2] unless %w[yellow brown purple].include?(value)
+    end
+  end
+
+  user.prefs.foreground = 'yellow'
+  user.prefs.save! # ActiveRecord::InvalidRecord exception raised with message like:
+                   # 'theme' for has_easy('prefs') failed validation
+
+  user.prefs.background = "pink"
+  user.prefs.save
+  user.errors.empty? => false
+  user.errors.on(:prefs) => 'background' for has_easy('prefs') failed validation
+  
+  user.prefs.midground = "black"
+  user.prefs.save
+  user.errors.on(:prefs)[0] => "msg1"
+  user.errors.on(:prefs)[1] => "msg2"
+
+
+===:preprocess
+Alter the value before it goes through type checking and/or validation.  This is useful when working with forms and boolean values.  CAREFUL!!  This option only applies to the underscore accessors, i.e. <tt>prefs_likes_cheese=</tt>, not <tt>prefs.likes_cheese=</tt> or <tt>prefs[:likes_cheese]=</tt>.
+  class User < ActiveRecord::Base
+    has_easy :prefs do |p|
+      p.define :likes_cheese, :validate => [true, false],
+                              :preprocess => Proc.new{ |value| ['true', 'yes'].include?(value) ? true : false }
+    end
+  end
+
+  user.prefs.likes_cheese = 'yes' # :preprocess NOT invoked; it only applies to underscore accessors!!
+  user.prefs.likes_cheese
+  => 'yes'
+  user.prefs.save! # exception, validation failed
+  
+  user.prefs_likes_cheese = 'yes' # :preprocess invoked
+  user.prefs.likes_cheese
+  => true
+  user.prefs.save! # no exception
+
+
+===:postprocess
+Alter the value when it is read.  This is useful when working with forms and boolean values.  CAREFUL!!  This option only applies to the underscore accessors, i.e. <tt>prefs_likes_cheese</tt>, not <tt>prefs.likes_cheese</tt> or <tt>prefs[:likes_cheese]</tt>.
+  class User < ActiveRecord::Base
+    has_easy :prefs do |p|
+      p.define :likes_cheese, :validate => [true, false],
+                              :postprocess => Proc.new{ |value| value ? 'yes' : 'no' }
+    end
+  end
+
+  user.prefs.likes_cheese = true
+  user.prefs.likes_cheese # :postprocess NOT invoked, it only applies to underscore accessors
+  => true
+  user.prefs_likes_cheese # :postprocess invoked
+  => 'yes'
+
+==Using with Forms
+Suppose you have a <tt>has_easy</tt> field defined as a boolean and you want to use it with a checkbox in <tt>form_for</tt>.
+
+  (model)
+
+  class User < ActiveRecord::Base
+    has_easy :prefs do |p|
+      p.define :likes_cheese, :type_check => [TrueClass, FalseClass],
+                              :preprocess => Proc.new{ |value| value == 'yes' },
+                              :postprocess => Proc.new{ |value| value ? 'yes' : 'no' }
+    end
+  end
+  
+  (view)
+  
+  <% form_for(@user) do |f| %>
+    <%= f.check_box 'user', 'prefs_likes_cheese', {}, 'yes', 'no' %> # invokes @user.prefs_likes_cheese which does the :postprocess
+  <% end %>
+  
+  (controller)
+  
+  @user.update_attributes(params[:user]) # invokes @user.prefs_likes_cheese= which does the :preprocess
+  @user.prefs.save
+  @user.prefs.likes_cheese
+  => true or false
+  @user.prefs_likes_cheese # remember, only underscore accessors invoke the :preprocess and :postprocess options
+  => 'yes' or 'no'
+  
+The general idea is that we make the form use <tt>prefs_likes_cheese=</tt> and <tt>prefs_likes_cheese</tt> accessors which in turn use the :preprocess and :postprocess options.  Then in our normal code, we use <tt>prefs.likes_cheese</tt> or <tt>prefs[:likes_cheese]</tt> accessors to get our expected boolean values.
+
+==Missing Features
+
+===Autovivification
+For when we want to use fields without having to define them first.
+  class User < ActiveRecord::Base
+    has_easy :prefs, :autovivify => true do |p|
+      p.define :likes_cheese, :default => 'yes'
+    end
+  end
+
+  user.prefs.likes_cheese => 'yes'
+  user.prefs.likes_pizza => nil
+  user.prefs.likes_pizza = true
+  user.prefs.likes_pizza => true
+
+
+===Scoping to other models
+Ehh, can't think of a way to describe this other than example.  Also, the syntax is completely up in the air, there are so many different ways to do it, I have no idea which way to go with.  Please tell me your ideas.
+  class User < ActiveRecord::Base
+    has_easy :prefs do |p|
+      p.define :subscribed, :scoped => Post
+      p.define :color, :scoped => [Car, Motorcycle] # polymorphic but must be Car or Motorcycle
+      p.define :hair_color, :scoped => true # polymorphic no restrictions
+      p.define :likes_cheese, :scoped => [Food, NilClass] # scoped and not scoped at the same time
+    end
+  end
+  
+  post = Post.find :first, :conditions => {:topic => 'rails'}
+  me.prefs.subscribed? :to => post
+  => true
+  
+  vette = Car.find :first, :conditions => {:model => 'corvette'}
+  me.prefs.color :for => vette
+  => 'black'
+  
+  gf = Girl.find :first, :conditions => {:name => 'aimee'}
+  me.prefs.hair_color :on => gf
+  => 'brown'
+  
+  watermelon = Food.find :first, :conditions => {:kind => 'watermelon'}
+  my.prefs.likes_cheese? # not scoped; do I like cheese in general?
+  => true
+  my.prefs.likes_cheese? :on => watermelon # scoped; do I like cheese on watermelon?
+  => false
+
+
+Copyright (c) 2008 Christopher J. Bottaro <cjbottaro@alumni.cs.utexas.edu>, released under the MIT license