couchrest_extended_document 1.0.0.beta6 → 1.0.0

data/README.md

@@ -28,6 +28,177 @@ Note: CouchRest::ExtendedDocument only supports CouchDB 0.10.0 or newer.
 
     end
 
+    @cat = Cat.new(:name => 'Felix', :nicknames => ['so cute', 'sweet kitty'])
+
+    @cat.new?   # true
+    @cat.save
+
+    @cat['name']   # "Felix"
+
+    @cat.nicknames << 'getoffdamntable'
+
+    @cat = Cat.new
+    @cat.update_attributes(:name => 'Felix', :random_text => 'feline')
+    @cat.new? # false
+    @cat.random_text  # Raises error!
+
+
+### Properties
+
+Only attributes with a property definition will be stored be ExtendedDocument (as opposed
+to a normal CouchRest Document which will store everything). To help prevent confusion, 
+a property should be considered as the definition of an attribute. An attribute must be associated
+with a property, but a property may not have any attributes associated if none have been set.
+
+
+In its simplest form, a property
+will only create a getter and setter passing all attribute data directly to the database. Assuming the attribute
+provided responds to +to_json+, there will not be any problems saving it, but when loading the 
+data back it will either be a string, number, array, or hash:
+
+    class Cat < CouchRest::ExtendedDocument
+      property :name
+      property :birthday
+    end
+
+    @cat = Cat.new(:name => 'Felix', :birthday => 2.years.ago)
+    @cat.name        # 'Felix'
+    @cat.birthday.is_a?(Time)  # True!
+    @cat.save
+    @cat = Cat.find(@cat.id)
+    @cat.name        # 'Felix'
+    @cat.birthday.is_a?(Time)  # False!
+
+Properties create getters and setters similar to the following:
+
+    def name
+      read_attribute('name')
+    end
+
+    def name=(value)
+      write_attribute('name', value)
+    end
+
+Properties can also have a type which 
+will be used for casting data retrieved from CouchDB when the attribute is set:
+
+    class Cat < CouchRest::ExtendedDocument
+      property :name, String
+      property :last_fed_at, Time
+    end
+
+    @cat = Cat.new(:name => 'Felix', :last_fed_at => 10.minutes.ago)
+    @cat.last_fed_at.is_a?(Time)   # True!
+    @cat.save
+    @cat = Cat.find(@cat.id)
+    @cat.last_fed_at < 20.minutes.ago   # True!
+
+
+Booleans or TrueClass will also create a getter with question mark at the end:
+
+    class Cat < CouchRest::ExtendedDocument
+      property :awake, TrueClass, :default => true
+    end
+
+    @cat.awake?   # true
+
+Adding the +:default+ option will ensure the attribute always has a value.
+
+Defining a property as read-only will mean that its value is set only when read from the
+database and that it will not have a setter method. You can however update a read-only
+attribute using the +write_attribute+ method:
+
+    class Cat < CouchRest::ExtendedDocument
+      property :name, String
+      property :lives, Integer, :default => 9, :readonly => true  
+
+      def fall_off_balcony!
+        write_attribute(:lives, lives - 1)
+        save
+      end
+    end
+
+    @cat = Cat.new(:name => "Felix")
+    @cat.fall_off_balcony!
+    @cat.lives    # Now 8!
+
+
+### Property Arrays
+
+An attribute may also contain an array of data. ExtendedDocument handles this, along
+with casting, by defining the class of the child attributes inside an Array:
+
+    class Cat < CouchRest::ExtendedDocument
+      property :name, String
+      property :nicknames, [String]
+    end
+
+By default, the array will be ready to use from the moment the object as been instantiated:
+
+    @cat = Cat.new(:name => 'Fluffy')
+    @cat.nicknames << 'Buffy'
+
+    @cat.nicknames == ['Buffy']
+
+When anything other than a string is set as the class of a property, the array will be converted
+into special wrapper called a CastedArray. If the child objects respond to the 'casted_by' method
+(such as those created with CastedModel, below) it will contain a reference to the parent.
+
+### Casted Models
+
+ExtendedDocument allows you to take full advantage of CouchDB's ability to store complex 
+documents and retrieve them using the CastedModel module. Simply include the module in
+a Hash (or other model that responds to the [] and []= methods) and set any properties
+you'd like to use. For example:
+
+    class CatToy << Hash
+      include CouchRest::CastedModel
+
+      property :name, String
+      property :purchased, Date
+    end
+
+    class Cat << CouchRest::ExtendedDocument
+      property :name, String
+      property :toys, [CatToy]
+    end
+
+    @cat = Cat.new(:name => 'Felix', :toys => [{:name => 'mouse', :purchases => 1.month.ago}])
+    @cat.toys.first.class == CatToy
+    @cat.toys.first.name == 'mouse'
+
+Additionally, any hashes sent to the property will automatically be converted:
+
+    @cat.toys << {:name => 'catnip ball'}
+    @cat.toys.last.is_a?(CatToy) # True!
+
+Of course, to use your own classes they *must* be defined before the parent uses them otherwise 
+Ruby will bring up a missing constant error. To avoid this, or if you have a really simple array of data
+you'd like to model, the latest version of ExtendedDocument (> 1.0.0) supports creating
+anonymous classes:
+
+    class Cat << CouchRest::ExtendedDocument
+      property :name, String
+
+      property :toys do |toy|
+        toy.property :name, String
+        toy.property :rating, Integer
+      end
+    end
+
+    @cat = Cat.new(:name => 'Felix', :toys => [{:name => 'mouse', :rating => 3}, {:name => 'catnip ball', :rating => 5}])
+    @cat.toys.last.rating == 5
+    @cat.toys.last.name == 'catnip ball'
+
+Using this method of anonymous classes will *only* create arrays of objects.
+
+### Notable Issues
+
+ExtendedDocument uses active_support for some of its internals. Ensure you have a stable active support gem installed 
+or at least 3.0.0.beta4.
+
+JSON gem versions 1.4.X are kown to cause problems with stack overflows and general badness. Version 1.2.4 appears to work fine.
+
 ### Ruby on Rails
 
 CouchRest::ExtendedDocument is compatible with rails and provides some ActiveRecord-like methods.
@@ -54,13 +225,13 @@ CouchRest install, from the project root directory run `rake`, or `autotest`
 
 API: [http://rdoc.info/projects/couchrest/couchrest_extended_document](http://rdoc.info/projects/couchrest/couchrest_extended_document)
 
-Check the wiki for documentation and examples [http://wiki.github.com/couchrest/couchrest](http://wiki.github.com/couchrest/couchrest)
+Check the wiki for documentation and examples [http://wiki.github.com/couchrest/couchrest_extended_document](http://wiki.github.com/couchrest/couchrest_extended_document)
 
 
 
 ## Contact
 
-Please post bugs, suggestions and patches to the bug tracker at [http://github.com/couchrest/couchrest/issues](http://github.com/couchrest/couchrest/issues).
+Please post bugs, suggestions and patches to the bug tracker at [http://github.com/couchrest/couchrest_extended_document/issues](http://github.com/couchrest/couchrest_extended_document/issues).
 
 Follow us on Twitter: [http://twitter.com/couchrest](http://twitter.com/couchrest)
 

data/Rakefile

@@ -20,16 +20,16 @@ begin
     gemspec.description = "CouchRest::ExtendedDocument provides aditional features to the standard CouchRest::Document class such as properties, view designs, callbacks, typecasting and validations."
     gemspec.email = "jchris@apache.org"
     gemspec.homepage = "http://github.com/couchrest/couchrest_extended_document"
-    gemspec.authors = ["J. Chris Anderson", "Matt Aimonetti", "Marcos Tapajos", "Will Leinweber"]
+    gemspec.authors = ["J. Chris Anderson", "Matt Aimonetti", "Marcos Tapajos", "Will Leinweber", "Sam Lown"]
     gemspec.extra_rdoc_files = %w( README.md LICENSE THANKS.md )
     gemspec.files = %w( LICENSE README.md Rakefile THANKS.md history.txt couchrest.gemspec) + Dir["{examples,lib,spec,utils}/**/*"] - Dir["spec/tmp"]
     gemspec.has_rdoc = true
-    gemspec.add_dependency("couchrest", ">= 1.0.0.beta")
+    gemspec.add_dependency("couchrest", ">= 1.0.0")
     gemspec.add_dependency("mime-types", ">= 1.15")
     gemspec.add_dependency("activesupport", ">= 2.3.0")
     gemspec.add_dependency("builder", ">=2.1.2")
     gemspec.version = CouchRest::ExtendedDocument::VERSION
-    gemspec.date = "2010-07-01"
+    gemspec.date = Time.now.strftime("%Y-%m-%d")
     gemspec.require_path = "lib"
   end
 rescue LoadError

data/THANKS.md

@@ -13,7 +13,10 @@ changes. A list of these people is included below.
  * [Matt Lyon](http://mattly.tumblr.com/)
  * Simon Rozet (simon /at/ rozet /dot/ name)
  * [Marcos Tapajós](http://tapajos.me)
+ * [Sam Lown](http://github.com/samlown)
+ * [Will Leinweber](http://github.com/will)
+
  
-Patches are welcome. The primary source for this software project is [on Github](http://github.com/couchrest/couchrest)
+Patches are welcome. The primary source for this software project is [on Github](http://github.com/couchrest/couchrest_extended_document)
 
 A lot of people have active forks - thank you all - even the patches I don't end up using are helpful.

data/history.txt

@@ -8,7 +8,13 @@
 
 * Minor enhancements
   * Added 'find_by_*' alias for finding first item in view with matching key.
-  * Fixed issue with active_support in Rails3.
+  * Fixed issue with active_support in Rails3 and text in README for JSON.
+  * Refactoring of properties, added read_attribute and write_attribute methods.
+  * Now possible to send anything to update_attribtues method. Invalid or readonly attributes will be ignored.
+  * Updating to use couchrest_inheritable_attributes to avoid possible Rails conflicts 
+
+* Major enhancements
+  * Added support for anonymous CastedModels defined in Documents
 
 == 1.0.0.beta5
 

data/lib/couchrest/casted_array.rb

@@ -6,20 +6,34 @@
 module CouchRest
   class CastedArray < Array
     attr_accessor :casted_by
+    attr_accessor :property
+
+    def initialize(array, property)
+      self.property = property
+      super(array)
+    end
     
     def << obj
-      obj.casted_by = self.casted_by if obj.respond_to?(:casted_by)
-      super(obj)
+      super(instantiate_and_cast(obj))
     end
     
     def push(obj)
-      obj.casted_by = self.casted_by if obj.respond_to?(:casted_by)
-      super(obj)
+      super(instantiate_and_cast(obj))
     end
     
     def []= index, obj
-      obj.casted_by = self.casted_by if obj.respond_to?(:casted_by)
-      super(index, obj)
+      super(index, instantiate_and_cast(obj))
+    end
+
+    protected
+
+    def instantiate_and_cast(obj)
+      if self.casted_by && self.property && obj.class != self.property.type_class
+        self.property.cast_value(self.casted_by, obj)
+      else
+        obj.casted_by = self.casted_by if obj.respond_to?(:casted_by)
+        obj
+      end
     end
   end
 end

data/lib/couchrest/casted_model.rb

@@ -5,17 +5,15 @@ module CouchRest
       base.send(:include, ::CouchRest::Mixins::Callbacks)
       base.send(:include, ::CouchRest::Mixins::Properties)
       base.send(:attr_accessor, :casted_by)
-      base.send(:attr_accessor, :document_saved)
     end
     
     def initialize(keys={})
       raise StandardError unless self.is_a? Hash
-      apply_defaults # defined in CouchRest::Mixins::Properties
+      apply_all_property_defaults # defined in CouchRest::Mixins::Properties
       super()
       keys.each do |k,v|
-        self[k.to_s] = v
+        write_attribute(k.to_s, v)
       end if keys
-      cast_keys      # defined in CouchRest::Mixins::Properties
     end
     
     def []= key, value
@@ -36,7 +34,7 @@ module CouchRest
     # False if the casted model has already
     # been saved in the containing document
     def new?
-      !@document_saved
+      @casted_by.nil? ? true : @casted_by.new?
     end
     alias :new_record? :new?
     

data/lib/couchrest/extended_document.rb

@@ -8,7 +8,7 @@ module CouchRest
   # Same as CouchRest::Document but with properties and validations
   class ExtendedDocument < Document
 
-    VERSION = "1.0.0.beta6"
+    VERSION = "1.0.0"
 
     include CouchRest::Mixins::Callbacks
     include CouchRest::Mixins::DocumentQueries    
@@ -18,6 +18,7 @@ module CouchRest
     include CouchRest::Mixins::ClassProxy
     include CouchRest::Mixins::Collection
     include CouchRest::Mixins::AttributeProtection
+    include CouchRest::Mixins::Attributes
 
     # Including validation here does not work due to the way inheritance is handled.
     #include CouchRest::Validation
@@ -57,12 +58,17 @@ module CouchRest
       base.new(doc, :directly_set_attributes => true)      
     end
     
+
+    # Instantiate a new ExtendedDocument by preparing all properties
+    # using the provided document hash.
+    #
+    # Options supported:
+    # 
+    # * :directly_set_attributes: true when data comes directly from database
+    #
     def initialize(doc = {}, options = {})
-      apply_defaults # defined in CouchRest::Mixins::Properties
-      remove_protected_attributes(doc) unless options[:directly_set_attributes]
-      directly_set_attributes(doc) unless doc.nil?
+      prepare_all_attributes(doc, options) # defined in CouchRest::Mixins::Attributes
       super(doc)
-      cast_keys      # defined in CouchRest::Mixins::Properties
       unless self['_id'] && self['_rev']
         self['couchrest-type'] = self.class.to_s
       end
@@ -94,12 +100,12 @@ module CouchRest
     # decent time format by default. See Time#to_json
     def self.timestamps!
       class_eval <<-EOS, __FILE__, __LINE__
-        property(:updated_at, :read_only => true, :type => 'Time', :auto_validation => false)
-        property(:created_at, :read_only => true, :type => 'Time', :auto_validation => false)
+        property(:updated_at, Time, :read_only => true, :protected => true, :auto_validation => false)
+        property(:created_at, Time, :read_only => true, :protected => true, :auto_validation => false)
         
         set_callback :save, :before do |object|
-          object['updated_at'] = Time.now
-          object['created_at'] = object['updated_at'] if object.new?
+          write_attribute('updated_at', Time.now)
+          write_attribute('created_at', Time.now) if object.new?
         end
       EOS
     end
@@ -142,14 +148,6 @@ module CouchRest
     
     ### instance methods
     
-    # Returns the Class properties
-    #
-    # ==== Returns
-    # Array:: the list of properties for the instance
-    def properties
-      self.class.properties
-    end
-    
     # Gets a reference to the actual document in the DB
     # Calls up to the next document if there is one,
     # Otherwise we're at the top and we return self
@@ -163,28 +161,6 @@ module CouchRest
       !@casted_by
     end
     
-    # Takes a hash as argument, and applies the values by using writer methods
-    # for each key. It doesn't save the document at the end. Raises a NoMethodError if the corresponding methods are
-    # missing. In case of error, no attributes are changed.    
-    def update_attributes_without_saving(hash)
-      # remove attributes that cannot be updated, silently ignoring them
-      # which matches Rails behavior when, for instance, setting created_at.
-      # make a copy, we don't want to change arguments
-      attrs = hash.dup
-      %w[_id _rev created_at updated_at].each {|attr| attrs.delete(attr)}
-      check_properties_exist(attrs)
-			set_attributes(attrs)
-    end
-    alias :attributes= :update_attributes_without_saving
-
-    # Takes a hash as argument, and applies the values by using writer methods
-    # for each key. Raises a NoMethodError if the corresponding methods are
-    # missing. In case of error, no attributes are changed.
-    def update_attributes(hash)
-      update_attributes_without_saving hash
-      save
-    end
-
     # for compatibility with old-school frameworks
     alias :new_record? :new?
     alias :new_document? :new?
@@ -255,7 +231,6 @@ module CouchRest
       raise ArgumentError, "a document requires a database to be saved to (The document or the #{self.class} default database were not set)" unless database
       set_unique_id if new? && self.respond_to?(:set_unique_id)
       result = database.save_doc(self, bulk)
-      mark_as_saved 
       result["ok"] == true
     end
     
@@ -281,43 +256,6 @@ module CouchRest
         end
       end
     end
-    
-    protected
-    
-    # Set document_saved flag on all casted models to true
-    def mark_as_saved
-      self.each do |key, prop|
-        if prop.is_a?(Array)
-          prop.each do |item|
-            if item.respond_to?(:document_saved)
-              item.send(:document_saved=, true)
-            end
-          end
-        elsif prop.respond_to?(:document_saved)
-          prop.send(:document_saved=, true)
-        end
-      end
-    end
-
-		private
-
-		def check_properties_exist(attrs)
-      attrs.each do |attribute_name, attribute_value|
-        raise NoMethodError, "#{attribute_name}= method not available, use property :#{attribute_name}" unless self.respond_to?("#{attribute_name}=")
-      end      
-		end
-    
-    def directly_set_attributes(hash)
-      hash.each do |attribute_name, attribute_value|
-        if self.respond_to?("#{attribute_name}=")
-          self.send("#{attribute_name}=", hash.delete(attribute_name))
-        end
-      end
-    end
-    
-		def set_attributes(hash)
-			attrs = remove_protected_attributes(hash)
-			directly_set_attributes(attrs)
-		end
+  
   end
 end