sudo_attributes 0.5.0 → 0.5.1

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

data/lib/sudo_attributes.rb

@@ -1,10 +1,27 @@
 module SudoAttributes
 
   module Base
+
+    # Protect attributes using ActiveRecord's built in <tt>attr_protected</tt> class macro.
+    # When invoked, it also adds other sudo_attributes class and instance methods to model such as +sudo_create+
+    #
+    # ==== Example
+    #   # Define attributes which are protected from mass assignment
+    #   class User < ActiveRecord::Base
+    #     sudo_attr_protected :admin
+    #   end
     def sudo_attr_protected(*attrs)
       Private::set_attributes(self, attrs, :protected)
     end
 
+    # Protect attributes using ActiveRecord's built in <tt>attr_accessible</tt> class macro.
+    # When invoked, it also adds other sudo_attributes class and instance methods to model such as +sudo_create+
+    #
+    # ==== Example
+    #   # Define attributes which are not protected from mass assignment
+    #   class User < ActiveRecord::Base
+    #     sudo_attr_accessible :admin
+    #   end
     def sudo_attr_accessible(*attrs)
       Private::set_attributes(self, attrs, :accessible)
     end
@@ -12,6 +29,7 @@ module SudoAttributes
 
   module Private
 
+    # Used internally to assign protected attributes and include additional sudo_attributes functionality
     def self.set_attributes(klass, attrs, type)
       unless attrs.empty?
         raise "Invalid argument passed to has_sudo_attributes" unless attrs.all? {|a| a.is_a? Symbol }
@@ -23,34 +41,74 @@ module SudoAttributes
       klass.send :include, SudoAttributes::InstanceMethods
     end
   end
-  
-  # Added to ActiveRecord model only if has_sudo_attributes is called
+
+  # Added to ActiveRecord model only if sudo_attr_(accessible|protected) is called
   module ClassMethods
+    # Creates an object with protected attributes and saves it to the database, if validations pass.
+    # The resulting object is returned whether the object was saved successfully to the database or not.
+    #
+    # Unlike ActiveRecord::Base.create, the <tt>attributes</tt> parameter can only be a Hash. This Hash describes the
+    # attributes on the objects that are to be created.
+    #
+    # ==== Example
+    #   # Create a single new object where admin is a protected attribute
+    #   User.sudo_create(:first_name => 'Pete', :admin => true)
     def sudo_create(attributes=nil)
       instance = sudo_new(attributes)
       instance.save
       instance
     end
 
+    # Creates an object just like sudo_create but calls save! instead of save so an exception is raised if the record is invalid
+    #
+    # ==== Example
+    #   # Create a single new object where admin is a protected attribute
+    #   User.sudo_create!(:first_name => 'Pete', :admin => true)
     def sudo_create!(attributes=nil)
       instance = sudo_new(attributes)
       instance.save!
       instance
     end
 
+    # Instantiates an object just like ActiveRecord::Base.new, but allowing mass assignment of protected attributes
+    #
+    # ==== Example
+    #   # Instantiate an object where admin is a protected attribute
+    #   User.sudo_new(:first_name => 'Pete', :admin => true)
     def sudo_new(attributes=nil)
       instance = new(nil)
       instance.send(:attributes=, attributes, false)
       instance
     end
+
+    # Alias of +sudo_new+
+    def sudo_build(attributes=nil)
+      sudo_new(attributes)
+    end
   end
- 
+
+  # Added to ActiveRecord model only if sudo_attr_(accessible|protected) is called
   module InstanceMethods
+
+    # Updates attributes of a model, including protected ones, from the passed-in hash and saves the
+    # record. If the object is invalid, the saving will fail and false will be returned.
+    #
+    # ==== Example
+    #   # Updated protected attributes on an instance of User
+    #   @user = User.find(params[:id])
+    #   @user.sudo_update_attributes(params[:user])
     def sudo_update_attributes(new_attributes)
       self.send(:attributes=, new_attributes, false)
       save
     end
 
+    # Updates its receiver just like +sudo_update_attributes+ but calls <tt>save!</tt> instead
+    # of +save+, so an exception is raised if the record is invalid.
+    #
+    # ==== Example
+    #   # Updated protected attributes on an instance of User
+    #   @user = User.find(params[:id])
+    #   @user.sudo_update_attributes!(params[:user])
     def sudo_update_attributes!(new_attributes)
       self.send(:attributes=, new_attributes, false)
       save!

data/spec/sudo_attributes_spec.rb

@@ -55,28 +55,32 @@ describe "Cat" do
         
         end
 
-        context "SudoAttributes sudo_new initializer" do
-          before(:each) { @cat = Cat.sudo_new @attributes}
-
-          it "should have a name" do
-            @cat.name.should == @attributes[:name]
-          end
-          
-          it "should set the name with sudo_update_attributes" do
-            @cat.sudo_update_attributes(:name => "Portia")
-            @cat.name.should == "Portia"
-          end
-
-          it "should have a color" do
-            @cat.color.should == @attributes[:color]
-          end
-
-          it "should not have an id" do
-            @cat.id.should be_nil
-          end
-          
-          it "should have an age" do
-            @cat.age.should == @attributes[:age]
+        # Tests for sudo_new and sudo_build, aliases of each other
+        [:sudo_new, :sudo_build].each do |sudo_method|
+
+          context "SudoAttributes #{sudo_method} initializer" do
+            before(:each) { @cat = Cat.send(sudo_method, @attributes)}
+
+            it "should have a name" do
+              @cat.name.should == @attributes[:name]
+            end
+            
+            it "should set the name with sudo_update_attributes" do
+              @cat.sudo_update_attributes(:name => "Portia")
+              @cat.name.should == "Portia"
+            end
+
+            it "should have a color" do
+              @cat.color.should == @attributes[:color]
+            end
+
+            it "should not have an id" do
+              @cat.id.should be_nil
+            end
+            
+            it "should have an age" do
+              @cat.age.should == @attributes[:age]
+            end
           end
         end
 

data/sudo_attributes.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sudo_attributes}
-  s.version = "0.5.0"
+  s.version = "0.5.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Peter Brown"]
-  s.date = %q{2011-01-12}
+  s.date = %q{2011-01-23}
   s.description = %q{Adds 'sudo' methods to update protected ActiveRecord attributes with mass assignment}
   s.email = %q{github@lette.us}
   s.extra_rdoc_files = [
@@ -35,7 +35,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/beerlington/sudo_attributes}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
+  s.rubygems_version = %q{1.4.2}
   s.summary = %q{Override ActiveRecord protected attributes with mass assignment}
   s.test_files = [
     "spec/spec_helper.rb",
@@ -43,7 +43,6 @@ Gem::Specification.new do |s|
   ]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sudo_attributes
 version: !ruby/object:Gem::Version 
-  hash: 11
-  prerelease: false
+  hash: 9
+  prerelease: 
   segments: 
   - 0
   - 5
-  - 0
-  version: 0.5.0
+  - 1
+  version: 0.5.1
 platform: ruby
 authors: 
 - Peter Brown
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-12 00:00:00 -05:00
+date: 2011-01-23 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -134,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.4.2
 signing_key: 
 specification_version: 3
 summary: Override ActiveRecord protected attributes with mass assignment