attr_encodable 0.1.0 → 0.1.1

data/README.md

@@ -1,142 +1,174 @@
-attr_encodable
-=
+# attr_encodable
 
 Never override `as_json` again! **attr_encodable** adds attribute black- or white-listing for ActiveRecord serialization, as well as default serialization options. This is especially useful for protecting private attributes when building a public API.
 
-Install
-==
+## Install
 
-Install using Rubygems:
+Bundler:
 
-	gem install attr_encodable
+	gem 'attr_encodable'
 
-Install using Bundler:
+Rubygems:
 
-	gem 'attr_encodable'
+	gem install attr_encodable
 
-Install in Rails 2.x (in your environment.rb file)
 
-	config.gem 'attr_encodable'
+## Usage
 
-Usage
-==
+### White-listing
 
-White-listing
-===
 
 You can whitelist or blacklist attributes for serialization using the `attr_encodable` and `attr_unencodable` class methods. Let's look at an example. For this example, we'll use the following classes:
 
-	class User < ActiveRecord::Base
-		has_many :permissions
-		validates_presence_of :email, :password
-		
-		def foobar
-			"baz"
-		end
-	end
-	
-	class Permission < ActiveRecord::Base
-		belongs_to :user
-		validates_presence_of :name, :user
-
-		def hello
-			"World!"
-		end
-	end
+```ruby
+class User < ActiveRecord::Base
+  has_many :permissions
+  validates_presence_of :email, :password
+
+  def foobar
+    "baz"
+  end
+end
+
+class Permission < ActiveRecord::Base
+  belongs_to :user
+  validates_presence_of :name, :user
+
+  def hello
+    "World!"
+  end
+end
+```
  
 ... with the following schema:
 
-	create_table :permissions, :force => true do |t|
-		t.belongs_to :user
-		t.string :name
-	end
-	
-	create_table :users, :force => true do |t|
-		t.string :login, :limit => 48
-		t.string :email, :limit => 128
-		t.string :name, :limit => 32
-		t.string :password, :limit => 60
-		t.boolean :admin, :default => false
-	end
+```ruby
+create_table :permissions, :force => true do |t|
+  t.belongs_to :user
+  t.string :name
+end
+
+create_table :users, :force => true do |t|
+  t.string :login, :limit => 48
+  t.string :email, :limit => 128
+  t.string :name, :limit => 32
+  t.string :password, :limit => 60
+  t.boolean :admin, :default => false
+end
+```
 
 Let's make a user and try encoding them:
 
-	@user = User.create(:name => "Flip", :email => "flip@x451.com", :password => "awesomesauce", :admin => true)
- 	=> #<User id: 1, login: nil, email: "flip@x451.com", name: "Flip", password: "awesomesauce", admin: true> 
-	@user.to_json
- 	=> {"name":"Flip","admin":true,"id":1,"password":"awesomesauce","login":null,"email":"flip@x451.com"}
-
+```ruby
+@user = User.create(:name => "Flip", :email => "flip@x451.com", :password => "awesomesauce", :admin => true)
+#=> #<User id: 1, login: nil, email: "flip@x451.com", name: "Flip", password: "awesomesauce", admin: true> 
+@user.to_json
+#=> {"name":"Flip","admin":true,"id":1,"password":"awesomesauce","login":null,"email":"flip@x451.com"}
+```
 Trouble is, we don't want their admin status OR their password coming through in our API. So why not protect their information a little bit?
 
-	User.attr_encodable :id, :name, :login, :email
-	@user.to_json
-	 => {"name":"Flip","id":1,"login":null,"email":"flip@x451.com"}
+```ruby
+User.attr_encodable :id, :name, :login, :email
+@user.to_json
+#=> {"name":"Flip","id":1,"login":null,"email":"flip@x451.com"}
+```
 
 Ah, that's so much better! Now whenever we encode a user instance we'll be showing only some default information.
 
 `attr_unencodable` is similar, except that it bans an attribute. Following along with the example above, if we then called `attr_unencodable`, we could
 restrict our user's information even more. Let's say I don't want my e-mail getting out:
 
-	User.attr_unencodable :email
-	@user.to_json
-	 => {"name":"Flip","id":1,"login":null}
+```ruby
+User.attr_unencodable :email
+@user.to_json
+#=> {"name":"Flip","id":1,"login":null}
+```
 
 Alright! Now you can't see my e-mail. Sucker.
 
-Default `:include` and `:method` options
-===
-
-`to_json` isn't just concerned with attributes. It also supports `:include`, which includes a relationship with `to_json` called on **it**, as well `:methods`, which adds the result of calling methods on the instance as well.
+### Default `:include` and `:method` options
 
-Let's try it out.
+`to_json` isn't just concerned with attributes. It also supports `:include`, which includes a relationship with `to_json` called on **it**, as well as `:methods`, which adds the result of calling one or more methods on the instance. `attr_encodable` supports both without specifying what you want to call; just include them in your list:
 
-	User.attr_encodable :foobar
-	@user.to_json
-	 => {"name":"Flip","foobar":"baz","id":1,"login":null}
+```ruby
+User.attr_encodable :foobar
+@user.to_json
+#=> {"name":"Flip","foobar":"baz","id":1,"login":null}
+```
 
 With includes, our example might look like this:
 
-	class User < ActiveRecord::Base
-		attr_encodable :id, :name, :login, :permissions
-		has_many :permissions
-	end
+```ruby
+class User < ActiveRecord::Base
+  attr_encodable :id, :name, :login, :permissions
+  has_many :permissions
+end
 	
-	@user.to_json
-	=> {"name":"Flip","foobar":"baz","id":1,"login":null,"permissions":[]}
+@user.to_json
+#=> {"name":"Flip","foobar":"baz","id":1,"login":null,"permissions":[]}
+```
 
-Neato! And of course, when `:permissions` is serialized, it will take into account any `attr_encodable` settings the Permissions class has!
+Neato! And of course, when `:permissions` is serialized, it will take into account any `attr_encodable` settings the `Permission` class has!
 
-Renaming Attributes
-===
+### Renaming Attributes
 
 Sometimes you don't want an attribute to come out in JSON named what it's named in the database. There are two options you can pursue here.
 
-Prefix it!
-====
+#### Prefix it!
 
 **attr_encodable** supports prefixing of attribute names. Just pass an options hash onto the end of the method with a :prefix key and you're good to go. Example:
 
-	class User < ActiveRecord::Base
-		attr_encodable :ed, :prefix => :i_will_hunt
-	end
+```ruby
+class User < ActiveRecord::Base
+  attr_encodable :ed, :prefix => :i_will_hunt
+end
 
-	@user.to_json
-	=> {"i_will_hunt_ed":true}
+@user.to_json
+=> {"i_will_hunt_ed":true}
+```
 
-Rename it completely!
-====
+#### Rename it completely!
 
 If you don't want to prefix, just rename the whole damn thing:
 
-	class User < ActiveRecord::Base
-		attr_encodable :admin => :superuser
-	end
-	
-	@user.to_json
-	#=> {"superuser":true}
+```ruby
+class User < ActiveRecord::Base
+  attr_encodable :admin => :superuser
+end
+
+@user.to_json
+#=> {"superuser":true}
+```
 
 Renaming and prefixing work for any `:include` and `:methods` arguments you pass in as well!
 
+### NEW! `attr_encodable` groups
+
+Soemtimes you may want to supply more information or less information, depending on the context. For example, if your API supports listing multiple records and viewing individual records, you may want to list multiple records with just enough information to get them to a URL where they can visit the individual record in detail. In that case, you can create a group using an `:as` option:
+
+```ruby
+User.attr_encodable :login, :name, :email
+User.attr_encodable :login, :as => :listing
+```
+
+This will create two groups: the default group, which is how your User will normally be serialized when you call `as_json` or `to_json` on it. Then, the `:listing` group, which can be used like so:
+
+```ruby
+@user.as_json #=> {"login": "flipsasser", "email": "support@getplinq.com", "name": "Flip Sasser"}
+@user.as_json(:listing) #=> {"login": "flipsasser"}
+```
+
+This comes in super handy when you want a quick way to limit or expand data in certain situations.
+
+To flip the example around, imagine you wanted to default to a very limited set of information, but expand it in a certain situation:
+
+```ruby
+User.attr_encodable :login
+User.attr_encodable :login, :admin, :email, :password, :as => :admin_api
+```
+
+Now you can call `@user.to_json(:admin_api)` somewhere, which will include a full users' details, but any other `as_json` call will keep that information private.
+
 Okay, that's all. Thanks for stopping by.
 
 Copyright &copy; 2011 Flip Sasser

data/lib/attr_encodable.rb

@@ -1,137 +1 @@
-require 'active_record'
-
-module Encodable
-  module ClassMethods
-    def attr_encodable(*attributes)
-      prefix = begin
-        if attributes.last.is_a?(Hash)
-          attributes.last.assert_valid_keys(:prefix)
-          prefix = attributes.extract_options![:prefix]
-        end
-      rescue ArgumentError
-      end
-      unless @encodable_whitelist_started
-        # Since we're white-listing, make sure we black-list every attribute to begin with
-        unencodable_attributes.push *column_names.map(&:to_sym)
-        @encodable_whitelist_started = true
-      end
-      stash_encodable_attribute = lambda {|method, value|
-        if prefix
-          value = "#{prefix}_#{value}"
-        end
-        method = method.to_sym
-        value = value.to_sym
-        renamed_encoded_attributes.merge!({method => value}) if method != value
-        # Un-black-list any attribute we white-listed
-        unencodable_attributes.delete method
-        default_attributes.push method
-      }
-      attributes.each do |attribute|
-        if attribute.is_a?(Hash)
-          attribute.each do |method, value|
-            stash_encodable_attribute.call(method, value)
-          end
-        else
-          stash_encodable_attribute.call(attribute, attribute)
-        end
-      end
-    end
-
-    def attr_unencodable(*attributes)
-      unencodable_attributes.push *attributes.map(&:to_sym)
-    end
-
-    def default_attributes
-      @default_attributes ||= begin
-        default_attributes = []
-        superk = superclass
-        while superk.respond_to?(:default_attributes)
-          default_attributes.push(*superk.default_attributes)
-          superk = superk.superclass
-        end
-        default_attributes
-      end
-    end
-
-    def renamed_encoded_attributes
-      @renamed_encoded_attributes ||= begin
-        renamed_encoded_attributes = {}
-        superk = superclass
-        while superk.respond_to?(:renamed_encoded_attributes)
-          renamed_encoded_attributes.merge!(superk.renamed_encoded_attributes)
-          superk = superk.superclass
-        end
-        renamed_encoded_attributes
-      end
-    end
-
-    def unencodable_attributes
-      @unencodable_attributes ||= begin
-        unencodable_attributes = []
-        superk = superclass
-        while superk.respond_to?(:unencodable_attributes)
-          unencodable_attributes.push(*superk.unencodable_attributes)
-          superk = superk.superclass
-        end
-        unencodable_attributes
-      end
-    end
-  end
-
-  module InstanceMethods
-    def serializable_hash(options = {})
-      options ||= {}
-      original_except = if options[:except]
-        options[:except] = Array(options[:except]).map(&:to_sym)
-      else
-        options[:except] = []
-      end
-
-      # Convert :only to :except
-      if options && options[:only]
-        options[:except].push *self.class.default_attributes - Array(options.delete(:only).map(&:to_sym))
-      end
-
-      # This is a little bit confusing. ActiveRecord's default behavior is to apply the :except arguments you pass
-      # in to any :include options UNLESS it's overridden on the :include option. In the event that we have some
-      # *default* excepts that come from Encodable, we want to ignore those and pass only whatever the original
-      # :except options from the user were on down to the :include guys.
-      inherited_except = original_except - self.class.default_attributes
-      case options[:include]
-      when Array, Symbol
-        # Convert includes arrays or singleton symbols into a hash with our original_except scope
-        includes = Array(options[:include])
-        options[:include] = Hash[*includes.map{|association| [association, {:except => inherited_except}]}.flatten]
-      else
-        options[:include] ||= {}
-      end
-      # Exclude the black-list
-      options[:except].push *self.class.unencodable_attributes
-      # Include any default :include or :methods arguments that were passed in earlier
-      self.class.default_attributes.each do |attribute, as|
-        unless options[:except].include?(attribute)
-          if association = self.class.reflect_on_association(attribute)
-            options[:include][attribute] = {:except => inherited_except}
-          elsif respond_to?(attribute) && !self.class.column_names.include?(attribute.to_s)
-            options[:methods] ||= Array(options[:methods]).compact
-            options[:methods].push attribute
-          end
-        end
-      end
-      as_json = super(options)
-      unless self.class.renamed_encoded_attributes.empty?
-        self.class.renamed_encoded_attributes.each do |attribute, as|
-          if as_json.has_key?(attribute) || as_json.has_key?(attribute.to_s)
-            as_json[as.to_s] = as_json.delete(attribute) || as_json.delete(attribute.to_s)
-          end
-        end
-      end
-      as_json
-    end
-  end
-end
-
-if defined? ActiveRecord::Base
-  ActiveRecord::Base.extend Encodable::ClassMethods
-  ActiveRecord::Base.send(:include, Encodable::InstanceMethods)
-end
+require 'encodable'

data/lib/encodable.rb

@@ -0,0 +1,10 @@
+module Encodable
+  autoload(:ActiveRecord, 'encodable/active_record')
+  autoload(:Array, 'encodable/array')
+end
+
+if defined? ActiveRecord::Base
+  ActiveRecord::Base.extend Encodable::ActiveRecord::ClassMethods
+  ActiveRecord::Base.send :include, Encodable::ActiveRecord::InstanceMethods
+  require 'encodable/array'
+end

data/lib/encodable/active_record.rb

@@ -0,0 +1,7 @@
+require 'encodable/active_record/class_methods'
+require 'encodable/active_record/instance_methods'
+
+module Encodable
+  module ActiveRecord
+  end
+end

data/lib/encodable/active_record/class_methods.rb

@@ -0,0 +1,100 @@
+module Encodable
+  module ActiveRecord
+    module ClassMethods
+      def attr_encodable(*attributes)
+        options = extract_encodable_options!(attributes)
+
+        unless @encodable_whitelist_started
+          # Since we're white-listing, make sure we black-list every attribute to begin with
+          unencodable_attributes(options[:as]).push *column_names.map(&:to_sym)
+          @encodable_whitelist_started = true
+        end
+
+        attributes.each do |attribute|
+          if attribute.is_a?(Hash)
+            attribute.each do |method, value|
+              add_encodable_attribute(method, value, options)
+            end
+          else
+            add_encodable_attribute(attribute, attribute, options)
+          end
+        end
+      end
+
+      def add_encodable_attribute(method, value, options = {})
+        value = "#{options[:prefix]}_#{value}" if options[:prefix]
+        method = method.to_sym
+        value = value.to_sym
+        renamed_encoded_attributes(options[:as]).merge!({method => value}) if method != value
+        # Un-black-list any attribute we white-listed
+        unencodable_attributes(options[:as]).delete method
+        default_attributes(options[:as]).push method
+      end
+
+      def attr_unencodable(*attributes)
+        options = extract_encodable_options!(attributes)
+        unencodable_attributes(options[:as]).push *attributes.map(&:to_sym)
+      end
+
+      def default_attributes(name = nil)
+        @default_attributes ||= merge_encodable_superclass_options(:default_attributes, [])
+        if name
+          @default_attributes[name] ||= []
+        else
+          @default_attributes
+        end
+      end
+
+      def encodable_sets
+        @encodable_sets
+      end
+
+      def renamed_encoded_attributes(name = nil)
+        @renamed_encoded_attributes ||= merge_encodable_superclass_options(:renamed_encoded_attributes, {})
+        if name
+          @renamed_encoded_attributes[name] ||= {}
+        else
+          @renamed_encoded_attributes
+        end
+      end
+
+      def unencodable_attributes(name = nil)
+        @unencodable_attributes ||= merge_encodable_superclass_options(:unencodable_attributes, [])
+        if name
+          @unencodable_attributes[name] ||= []
+        else
+          @unencodable_attributes
+        end
+      end
+
+      private
+      def extract_encodable_options!(attributes)
+        begin
+          attributes.last.assert_valid_keys(:prefix, :as)
+          options = attributes.extract_options!
+        rescue ArgumentError
+        end if attributes.last.is_a?(Hash)
+
+        options ||= {}
+        options[:as] ||= :default
+        options
+      end
+
+      def merge_encodable_superclass_options(method, default)
+        value = {}
+        superk = superclass
+        while superk.respond_to?(method)
+          supervalue = superk.send(method)
+          case default
+          when Array
+            supervalue.each {|name, default| (value[name] ||= []).push *default }
+          when Hash
+            supervalue.each {|name, default| (value[name] ||= {}).merge! default }
+          end
+          superk = superk.superclass
+        end
+        value
+      end
+    end
+  end
+end

data/lib/encodable/active_record/instance_methods.rb

@@ -0,0 +1,65 @@
+module Encodable
+  module ActiveRecord
+    module InstanceMethods
+      def as_json(name = nil, options = nil)
+        case name
+        when Hash, NilClass
+          options = name
+        when String, Symbol
+          (options ||= {}).merge! :as => name
+        end
+        super options
+      end
+
+      def serializable_hash(options = {})
+        options ||= {}
+        options[:as] ||= :default
+
+        original_except = if options[:except]
+          options[:except] = Array(options[:except]).map(&:to_sym)
+        else
+          options[:except] = []
+        end
+
+        # Convert :only to :except
+        if options && options[:only]
+          options[:except].push *self.class.default_attributes(options[:as]) - Array(options.delete(:only).map(&:to_sym))
+        end
+
+        # This is a little bit confusing. ActiveRecord's default behavior is to apply the :except arguments you pass
+        # in to any :include options UNLESS it's overridden on the :include option. In the event that we have some
+        # *default* excepts that come from Encodable, we want to ignore those and pass only whatever the original
+        # :except options from the user were on down to the :include guys.
+        inherited_except = original_except - self.class.default_attributes(options[:as])
+        case options[:include]
+        when Array, Symbol
+          # Convert includes arrays or singleton symbols into a hash with our original_except scope
+          includes = Array(options[:include])
+          options[:include] = Hash[*includes.map{|association| [association, {:except => inherited_except}]}.flatten]
+        else
+          options[:include] ||= {}
+        end
+        # Exclude the black-list
+        options[:except].push *self.class.unencodable_attributes(options[:as])
+        # Include any default :include or :methods arguments that were passed in earlier
+        self.class.default_attributes(options[:as]).each do |attribute, as|
+          unless options[:except].include?(attribute)
+            if association = self.class.reflect_on_association(attribute)
+              options[:include][attribute] = {:except => inherited_except}
+            elsif respond_to?(attribute) && !self.class.column_names.include?(attribute.to_s)
+              options[:methods] ||= Array(options[:methods]).compact
+              options[:methods].push attribute
+            end
+          end
+        end
+        as_json = super(options)
+        self.class.renamed_encoded_attributes(options[:as]).each do |attribute, as|
+          if as_json.has_key?(attribute) || as_json.has_key?(attribute.to_s)
+            as_json[as.to_s] = as_json.delete(attribute) || as_json.delete(attribute.to_s)
+          end
+        end
+        as_json
+      end
+    end
+  end
+end

data/lib/encodable/array.rb

@@ -0,0 +1,12 @@
+Array.class_eval do
+  def as_json_with_encodable(name = nil, options = nil)
+    case name
+    when Hash, NilClass
+      options = name
+    when String, Symbol
+      (options ||= {}).merge! :as => name
+    end
+    as_json_without_encodable options
+  end
+  alias_method_chain :as_json, :encodable
+end

data/spec/attr_encodable_spec.rb

@@ -1,5 +1,6 @@
-require File.join(File.dirname(__FILE__), '..', 'lib', 'attr_encodable')#{}"../lib/attr_encodable"
+require 'active_record'
 require 'active_support'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'attr_encodable')
 
 describe Encodable do
   it "should automatically extend ActiveRecord::Base" do
@@ -61,11 +62,11 @@ describe Encodable do
   end
 
   it "should favor whitelisting to blacklisting" do
-    User.unencodable_attributes.should == []
+    User.unencodable_attributes(:default).should == []
     User.attr_unencodable 'foo', 'bar', 'baz'
-    User.unencodable_attributes.should == [:foo, :bar, :baz]
+    User.unencodable_attributes(:default).should == [:foo, :bar, :baz]
     User.attr_encodable :id, :first_name
-    User.unencodable_attributes.map(&:to_s).should == ['foo', 'bar', 'baz'] + User.column_names - ['id', 'first_name']
+    User.unencodable_attributes(:default).map(&:to_s).should == ['foo', 'bar', 'baz'] + User.column_names - ['id', 'first_name']
   end
 
   describe "at the parent model level" do
@@ -202,4 +203,19 @@ describe Encodable do
     class SubUser < User; end
     SubUser.unencodable_attributes.should == User.unencodable_attributes
   end
+
+  describe "named groups" do
+    it "should be supported on a class-basis with a :name option" do
+      User.attr_unencodable :id
+      User.all.as_json.should == [@user.attributes.except('id')]
+      User.attr_encodable :id, :first_name, :last_name, :as => :short
+      User.all.as_json(:short).should == [{'id' => 1, 'first_name' => 'flip', 'last_name' => 'sasser'}]
+    end
+
+    it "should be supported on an instance-basis with a :name option" do
+      User.attr_encodable :id, :first_name, :last_name, :as => :short
+      @user.as_json.should == @user.attributes
+      @user.as_json(:short).should == {'id' => 1, 'first_name' => 'flip', 'last_name' => 'sasser'}
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attr_encodable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -40,6 +40,11 @@ files:
 - LICENSE
 - README.md
 - lib/attr_encodable.rb
+- lib/encodable.rb
+- lib/encodable/active_record.rb
+- lib/encodable/active_record/class_methods.rb
+- lib/encodable/active_record/instance_methods.rb
+- lib/encodable/array.rb
 - spec/attr_encodable_spec.rb
 homepage: http://github.com/Plinq/attr_encodable
 licenses: []