active_attr 0.1.0 → 0.2.0

data/.document

@@ -0,0 +1 @@
+- CHANGELOG* *LICENSE*

data/.gitignore

@@ -1,5 +1,7 @@
 *.gem
 .bundle
+.yardoc
 coverage
+doc
 Gemfile.lock
 pkg/*

data/CHANGELOG.md

@@ -1,5 +1,17 @@
+# ActiveAttr 0.2.0 (October 3, 2011) #
+
+* ActiveAttr now autoloads nested classes and modules
+* Added AttributeDefinition
+* Added Attributes
+* Added BasicModel
+* Added Error
+* Added Matchers::HaveAttributeMatcher
+* Added StrictMassAssignment
+* Added UnknownAttributesError
+* Documented everything
+
 # ActiveAttr 0.1.0 (September 30, 2011) #
 
-* Added MassAssignment#initialize
-* Added MassAssignment#attributes=
 * Added MassAssignment#assign_attributes
+* Added MassAssignment#attributes=
+* Added MassAssignment#initialize

data/Gemfile

@@ -8,7 +8,10 @@ group :development do
   gem "guard-bundler"
   gem "guard-rspec"
   gem "rb-fsevent"
-  gem 'ruby-debug',    :platforms => :mri_18
+  gem "rdiscount"
+  gem "rdoc"
+  gem "ruby-debug",    :platforms => :mri_18
   gem "ruby-debug19",  :platforms => :mri_19 if RUBY_VERSION < "1.9.3"
   gem "spec_coverage", :platforms => :mri_19
+  gem "yard"
 end

data/Guardfile

@@ -1,10 +1,11 @@
-guard 'bundler' do
-  watch('Gemfile')
+guard "bundler" do
+  watch("Gemfile")
   watch(/^.+\.gemspec/)
 end
 
-guard 'rspec', :version => 2, :cli=> '--format nested --debugger' do
+guard "rspec", :version => 2, :cli=> "--format nested --debugger" do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb') { "spec" }
+  watch("spec/spec_helper.rb") { "spec" }
+  watch(%r{^spec/support/(.+)\.rb$}) { |m| "spec" }
 end

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2011 by Chris Griego
+Copyright (C) 2011 by Chris Griego, Ben Poweski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,7 +2,58 @@
 
 [![Build History][2]][1]
 
-ActiveAttr makes it easy to create plain old ruby models without reinventing the wheel.
+ActiveAttr makes it easy to create plain old ruby models without reinventing
+the wheel.
+
+[API Documentation](http://rubydoc.info/gems/active_attr)
 
 [1]: http://travis-ci.org/cgriego/active_attr
 [2]: https://secure.travis-ci.org/cgriego/active_attr.png?branch=master
+
+## Attributes ##
+
+Including the Attributes module into your class gives you a DSL for defining
+the attributes of your model.
+
+    class Person
+      include ActiveAttr::Attributes
+
+      attribute :first_name
+      attribute :last_name
+    end
+
+    p = Person.new
+    p.first_name = "Chris"
+    p.last_name = "Griego"
+    p.attributes #=> {"first_name"=>"Chris", "last_name"=>"Griego"}
+
+## BasicModel ##
+
+Including the BasicModel module into your class gives you the bare minimum
+required for your model to meet the ActiveModel API requirements.
+
+    class Person
+      include ActiveAttr::BasicModel
+    end
+
+    Person.model_name.plural #=> "people"
+    p = Person.new
+    p.valid? #=> true
+    p.errors.full_messages #=> []
+
+## MassAssignment ##
+
+Including the MassAssignment module into your class gives you methods for bulk
+initializing and updating the attributes of your model. Any unknown attributes
+are silently ignored unless you substitute the StrictMassAssignment module
+which will raise an exception if an attempt is made to assign an unknown
+attribute.
+
+    class Person
+      include ActiveAttr::MassAssignment
+    end
+
+    p = Person.new(:first_name => "Chris")
+    p.attributes = { :last_name => "Griego" }
+    p.first_name #=> "Chris"
+    p.last_name #=> "Griego"

data/active_attr.gemspec

@@ -5,8 +5,8 @@ require "active_attr/version"
 Gem::Specification.new do |s|
   s.name        = "active_attr"
   s.version     = ActiveAttr::VERSION
-  s.authors     = ["Chris Griego"]
-  s.email       = ["cgriego@gmail.com"]
+  s.authors     = ["Chris Griego", "Ben Poweski"]
+  s.email       = ["cgriego@gmail.com", "bpoweski@gmail.com"]
   s.homepage    = "https://github.com/cgriego/active_attr"
   s.summary     = %q{What ActiveModel left out}
   s.description = %q{Create plain old ruby models without reinventing the wheel.}

data/lib/active_attr.rb

@@ -1,4 +1,19 @@
-require "active_attr/version"
+require "active_support/dependencies/autoload"
 
+# ActiveAttr is a set of modules to enhance Plain Old Ruby Objects (POROs)
+#
+# These modules give your objects the type of features that are normally found
+# in popular Object Relation Mappers (ORMs) like ActiveRecord, DataMapper, and
+# Mongoid. The goal is to lower the bar for creating easy-to-use Ruby models.
 module ActiveAttr
+  extend ActiveSupport::Autoload
+
+  autoload :AttributeDefinition
+  autoload :Attributes
+  autoload :BasicModel
+  autoload :Error
+  autoload :MassAssignment
+  autoload :StrictMassAssignment
+  autoload :UnknownAttributesError
+  autoload :VERSION
 end

data/lib/active_attr/attribute_definition.rb

@@ -0,0 +1,52 @@
+module ActiveAttr
+  # Represents an attribute for reflection
+  #
+  # @example Usage
+  #   AttributeDefinition.new(:amount)
+  #
+  # @since 0.2.0
+  class AttributeDefinition
+    # The attribute name
+    # @since 0.2.0
+    attr_reader :name
+
+    # Performs equality checking of the attribute definition
+    #
+    # @example Compare for equality.
+    #   attribute_definition == other
+    #
+    # @param [AttributeDefinition, Object] other The other attribute definition to compare with.
+    #
+    # @return [true, false] True if attribute name is equal and other is instance of the same Class, false if not.
+    #
+    # @since 0.2.0
+    def ==(attribute)
+      return false unless attribute.instance_of? self.class
+      name == attribute.name
+    end
+
+    # Creates a new AttributeDefinition
+    #
+    # @example Create an attribute defintion
+    #   AttributeDefinition.new(:amount)
+    #
+    # @param [Symbol, String, #to_sym] attribute name
+    #
+    # @return [AttributeDefinition]
+    #
+    # @since 0.2.0
+    def initialize(name, options={})
+      raise TypeError, "can't convert #{name.class} into Symbol" unless name.respond_to? :to_sym
+      @name = name.to_sym
+    end
+
+    # Returns the attribute name
+    #
+    # @return [String] the attribute name
+    #
+    # @since 0.2.0
+    def to_s
+      name.to_s
+    end
+  end
+end

data/lib/active_attr/attributes.rb

@@ -0,0 +1,138 @@
+require "active_attr/attribute_definition"
+require "active_support/concern"
+
+module ActiveAttr
+  # Attributes provides a set of class methods for defining an attributes
+  # schema and instance methods for reading and writing attributes.
+  #
+  # @example Usage
+  #   class Person
+  #     include ActiveAttr::Attributes
+  #     attribute :name
+  #   end
+  #
+  #   person = Person.new
+  #   person.name = "Ben Poweski"
+  #
+  # @since 0.2.0
+  module Attributes
+    extend ActiveSupport::Concern
+
+    # Performs equality checking on the result of attributes and its type.
+    #
+    # @example Compare for equality.
+    #   model == other
+    #
+    # @param [Attributes, Object] other The other model to compare with.
+    #
+    # @return [true, false] True if attributes are equal and other is instance of the same Class, false if not.
+    #
+    # @since 0.2.0
+    def ==(other)
+      return false unless other.instance_of? self.class
+      attributes == other.attributes
+    end
+
+    # Returns the raw attributes Hash
+    #
+    # @example Get attributes
+    #   person.attributes # => {"name"=>"Ben Poweski"}
+    #
+    # @return [Hash] The Hash of attributes
+    #
+    # @since 0.2.0
+    def attributes
+      @attributes ||= {}
+    end
+
+    # Returns the class name plus its attributes
+    #
+    # @example Inspect the model.
+    #   person.inspect
+    #
+    # @return [String] A nice pretty string to look at.
+    #
+    # @since 0.2.0
+    def inspect
+      attribute_descriptions = self.class.attributes.map do |attribute|
+        "#{attribute.name.to_s}: #{read_attribute(attribute.name).inspect}"
+      end
+
+      "#<#{self.class.name} #{attribute_descriptions.join(", ")}>"
+    end
+
+    # Read a value from the model's attributes. If the value does not exist
+    # it will return nil.
+    #
+    # @example Read an attribute.
+    #   person.read_attribute(:name)
+    #
+    # @param [String, Symbol] name The name of the attribute to get.
+    #
+    # @return [Object] The value of the attribute.
+    #
+    # @since 0.2.0
+    def read_attribute(name)
+      attributes[name.to_s]
+    end
+
+    # Write a single attribute to the model's attribute hash.
+    #
+    # @example Write the attribute.
+    #   person.write_attribute(:name, "Benjamin")
+    #
+    # @param [String, Symbol] name The name of the attribute to update.
+    # @param [Object] value The value to set for the attribute.
+    #
+    # @since 0.2.0
+    def write_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.
+      # For each attribute that is defined, a getter and setter will be
+      # added as an instance method to the model. An AttributeDefinition instance will be
+      # added to result of the attributes class method.
+      #
+      # @example Define an attribute.
+      #   attribute :name
+      #
+      # @param [Symbol] name The name of the attribute.
+      #
+      # @since 0.2.0
+      def attribute(name, options={})
+        attribute_definition = AttributeDefinition.new(name, options)
+        attributes << attribute_definition
+        method_name = attribute_definition.name
+
+        define_method("#{method_name}=") { |value| write_attribute(name, value) }
+        define_method(method_name) { read_attribute(name) }
+      end
+
+      # Returns an Array of AttributeDefinition instances
+      #
+      # @example Get attribute definitions
+      #   Person.attributes
+      #
+      # @return [Array<AttributeDefinition>] The Array of AttributeDefinition instances
+      #
+      # @since 0.2.0
+      def attributes
+        @attributes ||= []
+      end
+
+      # Returns the class name plus its attribute definitions
+      #
+      # @example Inspect the model's definition.
+      #   Person.inspect
+      #
+      # @return [String] A nice pretty string to look at.
+      #
+      # @since 0.2.0
+      def inspect
+        "#{self.name}(#{attributes.map { |a| a.to_s }.join(", ")})"
+      end
+    end
+  end
+end

data/lib/active_attr/basic_model.rb

@@ -0,0 +1,25 @@
+require "active_model"
+require "active_support/concern"
+
+module ActiveAttr
+  # Provides the minimum functionality to pass the ActiveModel lint tests
+  #
+  # @example Usage
+  #   class Person
+  #     include ActiveAttr::BasicModel
+  #   end
+  #
+  # @since 0.2.0
+  module BasicModel
+    extend ActiveSupport::Concern
+    extend ActiveModel::Naming
+    include ActiveModel::Conversion
+    include ActiveModel::Validations
+
+    # @return [false]
+    # @since 0.2.0
+    def persisted?
+      false
+    end
+  end
+end

data/lib/active_attr/error.rb

@@ -0,0 +1,16 @@
+module ActiveAttr
+  # All exceptions defined by and raised directly by ActiveAttr include this
+  # module, if you want to rescue any of the exceptions raised by the
+  # ActiveAttr library, you can rescue {ActiveAttr::Error}
+  #
+  # @example Rescuing an ActiveAttr error
+  #   begin
+  #     Person.new(attributes)
+  #   rescue ActiveAttr::Error
+  #     Person.new
+  #   end
+  #
+  # @since 0.2.0
+  module Error
+  end
+end

data/lib/active_attr/mass_assignment.rb

@@ -1,18 +1,59 @@
 module ActiveAttr
+  # MassAssignment allows you to bulk set and update attributes
+  #
+  # Including MassAssignment into your model gives it a set of mass assignment
+  # methods, similar to those found in ActiveRecord.
+  #
+  # @example Usage
+  #   class Person
+  #     include ActiveAttr::MassAssignment
+  #   end
+  #
+  # @since 0.1.0
   module MassAssignment
-    def initialize(attributes=nil, options={})
-      assign_attributes attributes, options
+    # Mass update a model's attributes
+    #
+    # @example Assigning a hash
+    #   person.assign_attributes(:first_name => "Chris", :last_name => "Griego")
+    #   person.first_name #=> "Chris"
+    #   person.last_name #=> "Griego"
+    #
+    # @param [Hash, #each] attributes Attributes used to populate the model
+    #
+    # @since 0.1.0
+    def assign_attributes(new_attributes, options={})
+      new_attributes.each do |name, value|
+        writer = "#{name}="
+        send writer, value if respond_to? writer
+      end if new_attributes
     end
 
+    # Mass update a model's attributes
+    #
+    # @example Assigning a hash
+    #   person.attributes = { :first_name => "Chris", :last_name => "Griego" }
+    #   person.first_name #=> "Chris"
+    #   person.last_name #=> "Griego"
+    #
+    # @param (see #assign_attributes)
+    #
+    # @since 0.1.0
     def attributes=(new_attributes)
       assign_attributes new_attributes
     end
 
-    def assign_attributes(new_attributes, options={})
-      new_attributes.each do |name, value|
-        writer = "#{name}="
-        send writer, value if respond_to? writer
-      end if new_attributes
+    # Initialize a model with a set of attributes
+    #
+    # @example Initializing with a hash
+    #   person = Person.new(:first_name => "Chris", :last_name => "Griego")
+    #   person.first_name #=> "Chris"
+    #   person.last_name #=> "Griego"
+    #
+    # @param (see #assign_attributes)
+    #
+    # @since 0.1.0
+    def initialize(attributes=nil, options={})
+      assign_attributes attributes, options
     end
   end
 end