active_attr 0.2.2 → 0.3.0

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+# ActiveAttr 0.3.0 (November 26, 2011) #
+
+* Added BlockInitialization
+* Added DangerousAttributeError
+* Added Logger
+* Added MassAssignmentSecurity
+* Added QueryAttributes
+* Added UnknownAttributeError
+* Attributes now honors getters/setters when calling #read_attribute,
+  #write_attribute, #[], and #[]=
+* Attributes now raises DangerousAttributeError when defining an attribute
+  whose methods would conflict with an existing method
+* Attributes now raises UnknownAttributeError when getting/setting any
+  undefined attributes
+
 # ActiveAttr 0.2.2 (November 2, 2011) #
 
 * Fixed all instances of modules' #initialize not invoking its superclass

data/README.md

@@ -24,10 +24,10 @@ the attributes of your model.
       attribute :last_name
     end
 
-    p = Person.new
-    p.first_name = "Chris"
-    p.last_name = "Griego"
-    p.attributes #=> {"first_name"=>"Chris", "last_name"=>"Griego"}
+    person = Person.new
+    person.first_name = "Chris"
+    person.last_name = "Griego"
+    person.attributes #=> {"first_name"=>"Chris", "last_name"=>"Griego"}
 
 ### BasicModel ###
 
@@ -39,9 +39,48 @@ required for your model to meet the ActiveModel API requirements.
     end
 
     Person.model_name.plural #=> "people"
-    p = Person.new
-    p.valid? #=> true
-    p.errors.full_messages #=> []
+    person = Person.new
+    person.valid? #=> true
+    person.errors.full_messages #=> []
+
+### BlockInitialization ###
+
+Including the BlockInitialization module into your class will yield the model
+instance to a block passed to when creating a new instance.
+
+    class Person
+      include ActiveAttr::BlockInitialization
+      attr_accessor :first_name, :last_name
+    end
+
+    person = Person.new do |p|
+      p.first_name = "Chris"
+      p.last_name = "Griego"
+    end
+
+    person.first_name #=> "Chris"
+    person.last_name #=> "Griego"
+
+### Logger ###
+
+Including the Logger module into your class will give you access to a
+configurable logger in model classes and instances. Your preferred logger can
+be configured on an instance, subclass, class, parent class, and globally by
+setting ActiveAttr::Logger.logger. When using Rails, the Rails framework
+logger will be configured by default.
+
+    class Person
+      include ActiveAttr::Logger
+    end
+
+    Person.logger = Logger.new(STDOUT)
+    Person.logger? #=> true
+    Person.logger.info "Logging an informational message"
+
+    person = Person.new
+    person.logger? #=> true
+    person.logger = Logger.new(STDERR)
+    person.logger.warn "Logging a warning message"
 
 ### MassAssignment ###
 
@@ -56,10 +95,43 @@ attribute.
       attr_accessor :first_name, :last_name
     end
 
-    p = Person.new(:first_name => "Chris")
-    p.attributes = { :last_name => "Griego" }
-    p.first_name #=> "Chris"
-    p.last_name #=> "Griego"
+    person = Person.new(:first_name => "Chris")
+    person.attributes = { :last_name => "Griego" }
+    person.first_name #=> "Chris"
+    person.last_name #=> "Griego"
+
+### MassAssignmentSecurity ###
+
+Including the MassAssignmentSecurity module into your class extends the
+MassAssignment methods to honor any declared mass assignment permission
+blacklists or whitelists including support for mass assignment roles.
+
+    class Person
+      include ActiveAttr::MassAssignment
+      attr_accessor :first_name, :last_name
+      attr_protected :last_name
+    end
+
+    person = Person.new(:first_name => "Chris", :last_name => "Griego")
+    person.first_name #=> "Chris"
+    person.last_name #=> nil
+
+### QueryAttributes ###
+
+Including the QueryAttributes module into your class builds on Attributes by
+providing instance methods for querying your attributes
+
+    class Person
+      include ActiveAttr::QueryAttributes
+
+      attribute :first_name
+      attribute :last_name
+    end
+
+    person = Person.new
+    person.first_name = "Chris"
+    person.first_name? #=> true
+    person.last_name? #=> false
 
 ## RSpec Integration ##
 

data/active_attr.gemspec

@@ -21,7 +21,8 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency "activemodel",   "~> 3.1"
   s.add_runtime_dependency "activesupport", "~> 3.1"
 
-  s.add_development_dependency "bundler", "~> 1.0"
-  s.add_development_dependency "rake",    "~> 0.9.0"
-  s.add_development_dependency "rspec",   "~> 2.6"
+  s.add_development_dependency "bundler",      "~> 1.0"
+  s.add_development_dependency "factory_girl", "~> 2.2"
+  s.add_development_dependency "rake",         "~> 0.9.0"
+  s.add_development_dependency "rspec",        "~> 2.6"
 end

data/lib/active_attr.rb

@@ -1,3 +1,4 @@
+require "active_attr/railtie" if defined?(Rails)
 require "active_support/dependencies/autoload"
 
 # ActiveAttr is a set of modules to enhance Plain Old Ruby Objects (POROs)
@@ -13,8 +14,12 @@ module ActiveAttr
   autoload :BasicModel
   autoload :ChainableInitialization
   autoload :Error
+  autoload :Logger
   autoload :MassAssignment
+  autoload :MassAssignmentSecurity
+  autoload :QueryAttributes
   autoload :StrictMassAssignment
+  autoload :UnknownAttributeError
   autoload :UnknownAttributesError
   autoload :VERSION
 end

data/lib/active_attr/attributes.rb

@@ -1,5 +1,7 @@
 require "active_attr/attribute_definition"
 require "active_attr/chainable_initialization"
+require "active_attr/dangerous_attribute_error"
+require "active_attr/unknown_attribute_error"
 require "active_model"
 require "active_support/concern"
 
@@ -22,6 +24,10 @@ module ActiveAttr
     include ActiveAttr::ChainableInitialization
     include ActiveModel::AttributeMethods
 
+    # Methods deprecated on the Object class which can be safely overridden
+    # @since 0.3.0
+    DEPRECATED_OBJECT_METHODS = %w(id type)
+
     included do
       attribute_method_suffix ""
       attribute_method_suffix "="
@@ -42,7 +48,7 @@ module ActiveAttr
       attributes == other.attributes
     end
 
-    # Returns the raw attributes Hash
+    # Returns a Hash of all attributes
     #
     # @example Get attributes
     #   person.attributes # => {"name"=>"Ben Poweski"}
@@ -70,48 +76,79 @@ module ActiveAttr
     #
     # @since 0.2.0
     def inspect
-      attribute_descriptions = self.class.attributes.sort.map do |attribute|
-        "#{attribute.name.to_s}: #{read_attribute(attribute.name).inspect}"
-      end.join(", ")
-
-      attribute_descriptions = " " + attribute_descriptions unless attribute_descriptions.empty?
-
-      "#<#{self.class.name}#{attribute_descriptions}>"
+      attribute_descriptions = self.attributes.sort.map { |key, value| "#{key}: #{value.inspect}" }.join(", ")
+      separator = " " unless attribute_descriptions.empty?
+      "#<#{self.class.name}#{separator}#{attribute_descriptions}>"
     end
 
-    # Read a value from the model's attributes. If the value does not exist
-    # it will return nil.
+    # Read a value from the model's attributes.
     #
-    # @example Read an attribute.
+    # @example Read an attribute with read_attribute
     #   person.read_attribute(:name)
+    # @example Rean an attribute with bracket syntax
+    #   person[:name]
     #
-    # @param [String, Symbol] name The name of the attribute to get.
+    # @param [String, Symbol, #to_s] name The name of the attribute to get.
     #
     # @return [Object] The value of the attribute.
     #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    #
     # @since 0.2.0
     def read_attribute(name)
-      @attributes[name.to_s]
+      if respond_to? name
+        send name.to_s
+      else
+        raise UnknownAttributeError, "unknown attribute: #{name}"
+      end
     end
     alias_method :[], :read_attribute
-    alias_method :attribute, :read_attribute
-    private :attribute
 
     # Write a single attribute to the model's attribute hash.
     #
-    # @example Write the attribute.
+    # @example Write the attribute with write_attribute
     #   person.write_attribute(:name, "Benjamin")
+    # @example Write an attribute with bracket syntax
+    #   person[:name] = "Benjamin"
     #
-    # @param [String, Symbol] name The name of the attribute to update.
+    # @param [String, Symbol, #to_s] name The name of the attribute to update.
     # @param [Object] value The value to set for the attribute.
     #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    #
     # @since 0.2.0
     def write_attribute(name, value)
-      @attributes[name.to_s] = value
+      if respond_to? "#{name}="
+        send "#{name}=", value
+      else
+        raise UnknownAttributeError, "unknown attribute: #{name}"
+      end
     end
     alias_method :[]=, :write_attribute
-    alias_method :attribute=, :write_attribute
-    private :attribute=
+
+    protected
+
+    # Overrides ActiveModel::AttributeMethods
+    # @private
+    def attribute_method?(attr_name)
+      self.class.attributes.map { |definition| definition.name.to_s }.include? attr_name.to_s
+    end
+
+    private
+
+    # Read an attribute from the attributes hash
+    #
+    # @since 0.2.1
+    def attribute(name)
+      @attributes[name.to_s]
+    end
+
+    # Write an attribute to the attributes hash
+    #
+    # @since 0.2.1
+    def attribute=(name, value)
+      @attributes[name.to_s] = value
+    end
 
     module ClassMethods
       # Defines all the attributes that are to be returned from the attributes instance method.
@@ -124,11 +161,15 @@ module ActiveAttr
       #
       # @param (see AttributeDefinition#initialize)
       #
+      # @raise [DangerousAttributeError] if the attribute name conflicts with existing methods
+      #
       # @since 0.2.0
       def attribute(name, options={})
         AttributeDefinition.new(name, options).tap do |attribute_definition|
-          attributes << attribute_definition unless attributes.include? attribute_definition
-          define_attribute_method attribute_definition.name
+          unless attributes.include? attribute_definition
+            define_attribute_method attribute_definition.name
+            attributes << attribute_definition
+          end
         end
       end
 
@@ -169,12 +210,19 @@ module ActiveAttr
         @attributes = attributes
       end
 
+      # Overrides ActiveModel::AttributeMethods
+      # @private
+      def instance_method_already_implemented?(method_name)
+        deprecated_object_method = DEPRECATED_OBJECT_METHODS.include?(method_name.to_s)
+        already_implemented = !deprecated_object_method && self.allocate.respond_to?(method_name, true)
+        raise DangerousAttributeError, %{an attribute method named "#{method_name}" would conflict with an existing method} if already_implemented
+        false
+      end
+
       private
 
       # Ruby inherited hook to assign superclass attributes to subclasses
       #
-      # @param [Class] subclass
-      #
       # @since 0.2.2
       def inherited(subclass)
         super

data/lib/active_attr/block_initialization.rb

@@ -0,0 +1,37 @@
+require "active_attr/chainable_initialization"
+require "active_support/concern"
+
+module ActiveAttr
+  # BlockInitialization allows you to build an instance in a block
+  #
+  # Including the BlockInitialization module into your class will yield the
+  # model instance to a block passed to when creating a new instance.
+  #
+  # @example Usage
+  #   class Person
+  #     include ActiveAttr::BlockInitialization
+  #   end
+  #
+  # @since 0.3.0
+  module BlockInitialization
+    extend ActiveSupport::Concern
+    include ChainableInitialization
+
+    # Initialize a model and build via a block
+    #
+    # @example
+    #   person = Person.new do |p|
+    #     p.first_name = "Chris"
+    #     p.last_name = "Griego"
+    #   end
+    #
+    #   person.first_name #=> "Chris"
+    #   person.last_name #=> "Griego"
+    #
+    # @since 0.3.0
+    def initialize(*)
+      super
+      yield self if block_given?
+    end
+  end
+end

data/lib/active_attr/chainable_initialization.rb

@@ -20,18 +20,20 @@ module ActiveAttr
       # A collection of Ruby base objects
       #   [Object] on Ruby 1.8
       #   [Object, BasicObject] on Ruby 1.9
-      BASE_OBJECTS = begin
-        base_objects = []
+      #
+      # @private
+      BASE_OBJECTS = [].tap do |base_objects|
         superclass = Class.new
         base_objects << superclass while superclass = superclass.superclass
-        base_objects
       end
 
       # Only append the features of this module to the class that inherits
       # directly from one of the BASE_OBJECTS
+      #
+      # @private
       def append_features(base)
         if base.respond_to? :superclass
-          base = base.superclass while !BASE_OBJECTS.include?(base.superclass)
+          base = base.superclass while !BASE_OBJECTS.include? base.superclass
         end
 
         super

data/lib/active_attr/dangerous_attribute_error.rb

@@ -0,0 +1,11 @@
+require "active_attr/error"
+
+module ActiveAttr
+  # This exception is raised if attempting to define an attribute whose name
+  # conflicts with methods that are already defined
+  #
+  # @since 0.3.0
+  class DangerousAttributeError < ScriptError
+    include Error
+  end
+end

data/lib/active_attr/logger.rb

@@ -0,0 +1,46 @@
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module ActiveAttr
+  # Provides access to a configurable logger in model classes and instances
+  #
+  # @example Usage
+  #   class Person
+  #     include ActiveAttr::Logger
+  #   end
+  #
+  # @since 0.3.0
+  module Logger
+    extend ActiveSupport::Concern
+
+    # The global default logger
+    #
+    # @return [nil, Object] logger Configured global default logger
+    #
+    # @since 0.3.0
+    def self.logger
+      @logger
+    end
+
+    # Determin if a global default logger is configured
+    #
+    # @since 0.3.0
+    def self.logger?
+      !!logger
+    end
+
+    # Configure the global default logger
+    #
+    # @param [Logger, #debug] logger The new global default logger
+    #
+    # @since 0.3.0
+    def self.logger=(new_logger)
+      @logger = new_logger
+    end
+
+    included do
+      class_attribute :logger
+      self.logger = ActiveAttr::Logger.logger
+    end
+  end
+end