couchrest_model 1.0.0.beta8 → 1.0.0

data/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+html/*
+pkg
+*.swp
+.rvmrc
+.bundle
+couchdb.std*
+*.*~
+

data/{spec/spec.opts → .rspec}

@@ -1,5 +1,4 @@
 --colour
 --format
 progress
---loadby
 mtime

data/Gemfile

@@ -0,0 +1,4 @@
+
+source :rubygems
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,77 @@
+PATH
+  remote: .
+  specs:
+    couchrest_model (1.0.0)
+      activemodel (~> 3.0.0)
+      couchrest (~> 1.0.1)
+      mime-types (~> 1.15)
+      railties (~> 3.0.0)
+      rspec (>= 2.0.0)
+      tzinfo (~> 0.3.22)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionpack (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.6)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activesupport (3.0.3)
+    builder (2.1.2)
+    couchrest (1.0.1)
+      json (>= 1.4.6)
+      mime-types (>= 1.15)
+      rest-client (>= 1.5.1)
+    diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    i18n (0.5.0)
+    json (1.4.6)
+    mime-types (1.16)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    railties (3.0.3)
+      actionpack (= 3.0.3)
+      activesupport (= 3.0.3)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
+    rake (0.8.7)
+    rest-client (1.6.1)
+      mime-types (>= 1.16)
+    rspec (2.2.0)
+      rspec-core (~> 2.2)
+      rspec-expectations (~> 2.2)
+      rspec-mocks (~> 2.2)
+    rspec-core (2.3.0)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    thor (0.14.6)
+    tzinfo (0.3.23)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel (~> 3.0.0)
+  couchrest (~> 1.0.1)
+  couchrest_model!
+  mime-types (~> 1.15)
+  rack-test (>= 0.5.7)
+  railties (~> 3.0.0)
+  rspec (>= 2.0.0)
+  tzinfo (~> 0.3.22)

data/README.md

@@ -9,16 +9,13 @@ for validations and callbacks.
 If your project is still running Rails 2.3, you'll have to continue using ExtendedDocument as 
 it is not possible to load ActiveModel into programs that do not use ActiveSupport 3.0.
 
-CouchRest Model only supports CouchDB 0.10.0 or newer.
+CouchRest Model is only tested on CouchDB 1.0.0 or newer.
 
 ## Install
 
-### From Gem
+### Gem
 
-CouchRest Model depends on Rails 3's ActiveModel which has not yet been released. You'll need to add
-`--pre` to the end of the gem install until the dependencies are stable:
-
-    $ sudo gem install couchrest_model --pre
+    $ sudo gem install couchrest_model
 
 ### Bundler
 
@@ -31,7 +28,33 @@ but no guarantees!
 
     gem 'couchrest_model', :git => 'git://github.com/couchrest/couchrest_model.git'
 
-   
+### Development
+
+CouchRest Model now comes with a Gemfile to help with development. If you want to make changes to the code, download a copy then run:
+
+    bundle install
+
+That should set everything up for `rake spec` to be run correctly. Update the couchrest_model.gemspec if your alterations
+use different gems.
+
+## Generators
+
+### Model
+
+		$ rails generate model person --orm=couchrest_model
+
+## Useful links and extensions
+
+Try some of these gems that add extra funcionality to couchrest_model:
+
+* [memories](http://github.com/moonmaster9000/memories) - object versioning using attachments (Matt Parker)
+* [couch_publish](http://github.com/moonmaster9000/couch_publish) - versioned state machine for draft and published documents (Matt Parker)
+* [couch_photo](http://github.com/moonmaster9000/couch_photo) - attach images to documents with variations (Matt Parker)
+* [copycouch](http://github.com/moonmaster9000/copycouch) - single document replication on documents (Matt Parker)
+* [recloner](https://github.com/moonmaster9000/recloner) - clone documents easily (Matt Parker)
+
+If you have an extension that you'd us to add to this list, please get in touch!
+			   
 ## General Usage 
 
     require 'couchrest_model'
@@ -66,16 +89,14 @@ but no guarantees!
 
 ## Properties
 
-Only attributes with a property definition will be stored be CouchRest Model (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.
+A property is the definition of an attribute, it describes what the attribute is called, how it should
+be type casted and other options such as the default value. These replace your typical 
+`add_column` methods found in relational database migrations.
 
+Attributes with a property definition will have setter and getter methods defined for them. Any other attibute
+can be set in the same way you'd update a Hash, this funcionality is inherited from CouchRest Documents.
 
-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:
+Here are a few examples of the way properties are used:
 
     class Cat < CouchRest::Model::Base
       property :name
@@ -100,8 +121,7 @@ Properties create getters and setters similar to the following:
       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:
+Properties can also have a type which will be used for casting data retrieved from CouchDB when the attribute is set:
 
     class Cat < CouchRest::Model::Base
       property :name, String
@@ -115,7 +135,7 @@ will be used for casting data retrieved from CouchDB when the attribute is set:
     @cat.last_fed_at < 20.minutes.ago   # True!
 
 
-Booleans or TrueClass will also create a getter with question mark at the end:
+Boolean or TrueClass types will create a getter with question mark at the end:
 
     class Cat < CouchRest::Model::Base
       property :awake, TrueClass, :default => true
@@ -125,9 +145,8 @@ Booleans or TrueClass will also create a getter with question mark at the end:
 
 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:
+A read-only property will only have a getter method, and its value is set when the document
+is read from the database. You can however update a read-only attribute using the `write_attribute` method:
 
     class Cat < CouchRest::Model::Base
       property :name, String
@@ -143,10 +162,23 @@ attribute using the `write_attribute` method:
     @cat.fall_off_balcony!
     @cat.lives    # Now 8!
 
+Mass assigning attributes is also possible in a similar fashion to ActiveRecord:
+
+    @cat.attributes = { :name => "Felix" }
+    @cat.save
+
+Is the same as:
+
+    @cat.update_attributes(:name => "Felix")
+
+By default, attributes without a property will not be updated via the `#attributes=` method. This provents useless data being passed to database, for example from an HTML form. However, if you would like truely
+dynamic attributes, the `mass_assign_any_attribute` configuration option when set to true will 
+store everything you put into the `Base#attributes=` method.
+
 
 ## Property Arrays
 
-An attribute may also contain an array of data. CouchRest Model handles this, along
+An attribute may contain an array of data. CouchRest Model handles this, along
 with casting, by defining the class of the child attributes inside an Array:
 
     class Cat < CouchRest::Model::Base
@@ -172,14 +204,14 @@ documents and retrieve them using the CastedModel module. Simply include the mod
 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
+    class CatToy < Hash
       include CouchRest::Model::CastedModel
 
       property :name, String
       property :purchased, Date
     end
 
-    class Cat << CouchRest::Model::Base
+    class Cat < CouchRest::Model::Base
       property :name, String
       property :toys, [CatToy]
     end
@@ -188,17 +220,16 @@ you'd like to use. For example:
     @cat.toys.first.class == CatToy
     @cat.toys.first.name == 'mouse'
 
-Additionally, any hashes sent to the property will automatically be converted:
+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 
+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 CouchRest Model (> 1.0.0) supports creating
-anonymous classes:
+you'd like to model, CouchRest Model supports creating anonymous classes:
 
-    class Cat << CouchRest::Model::Base
+    class Cat < CouchRest::Model::Base
       property :name, String
 
       property :toys do |toy|
@@ -211,7 +242,7 @@ anonymous classes:
     @cat.toys.last.rating == 5
     @cat.toys.last.name == 'catnip ball'
 
-Using this method of anonymous classes will *only* create arrays of objects.
+Anonymous classes will *only* create arrays of objects.
 
 
 ## Assocations
@@ -222,14 +253,67 @@ Two types at the moment:
 
     collection_of :tags
 
-TODO: Document properly!
+This is a somewhat controvesial feature of CouchRest Model that some document database purists may fringe at. CouchDB does not yet povide many features to support relationships between documents but the fact of that matter is that its a very useful paradigm for modelling data systems.
+
+In the near future we hope to add support for a `has_many` relationship that takes of the _Linked Documents_ feature that arrived in CouchDB 0.11.
+
+### Belongs To
+
+Creates a property in the document with `_id` added to the end of the name of the foreign model with getter and setter methods to access the model. 
+
+Example:
+
+    class Cat < CouchRest::Model::Base
+      belongs_to :mother
+      property :name
+    end
+
+    kitty = Cat.new(:name => "Felix")
+    kitty.mother = Mother.find_by_name('Sophie')
+
+Providing a object to the setter, `mother` in the example will automagically update the `mother_id` attribute. Retrieving the data later is just as expected:
+
+    kitty = Cat.find_by_name "Felix"
+    kitty.mother.name == 'Sophie'
+
+Belongs_to accepts a few options to add a bit more felxibility:
+
+* `:class_name` - the camel case string name of the class used to load the model.
+* `:foreign_key` - the name of the property to use instead of the attribute name with `_id` on the end.
+* `:proxy` - a string that when evaluated provides a proxy model that responds to `#get`.
+
+The last option, `:proxy` is a feature currently in testing that allows objects to be loaded from a proxy class, such as `ClassProxy`. For example:
+
+    class Invoice < CouchRest::Model::Base
+      attr_accessor :company
+      belongs_to :project, :proxy => 'self.company.projects'
+    end
+
+A project instance in this scenario would need to be loaded by calling `#get(project_id)` on `self.company.projects` in the scope of an instance of the Invoice. We hope to document and work on this powerful feature in the near future.
+
+
+### Collection Of
 
+A collection_of relationship is much like belongs_to except that rather than just one foreign key, an array of foreign keys can be stored. This is one of the great features of a document database. This relationship uses a proxy object to automatically update two arrays; one containing the objects being used, and a second with the foreign keys used to the find them.
+
+The best example of this in use is with Labels:
+
+    class Invoice < CouchRest::Model::Base
+      collection_of :labels
+    end
+
+    invoice = Invoice.new
+    invoice.labels << Label.get('xyz')
+    invoice.labels << Label.get('abc')
+
+    invoice.labels.map{|l| l.name} # produces ['xyz', 'abc']
+
+See the belongs_to relationship for the options that can be used. Note that this isn't especially efficient, a `get` is performed for each model in the array. As with a has_many relationship, we hope to be able to take advantage of the Linked Documents feature to avoid multiple requests.
 
 
 ## Validations
 
-CouchRest Model automatically includes the new ActiveModel validations, so they should work just as the traditional Rails
-validations. For more details, please see the ActiveModel::Validations documentation.
+CouchRest Model automatically includes the new ActiveModel validations, so they should work just as the traditional Rails validations. For more details, please see the ActiveModel::Validations documentation.
 
 CouchRest Model adds the possibility to check the uniqueness of attributes using the `validates_uniqueness_of` class method, for example:
 
@@ -246,9 +330,7 @@ you'd like to avoid the typical RestClient Conflict error:
     unique_id :code
     validates_uniqueness_of :code, :view => 'all'
 
-Given that the uniqueness check performs a request to the database, it is also possible
-to include a @:proxy@ parameter. This allows you to
-call a method on the document and provide an alternate proxy object.
+Given that the uniqueness check performs a request to the database, it is also possible to include a `:proxy` parameter. This allows you to call a method on the document and provide an alternate proxy object.
 
 Examples:
 
@@ -259,8 +341,7 @@ Examples:
     validates_uniqueness_of :title, :proxy => 'company.people'
 
 
-A really interesting use of +:proxy+ and +:view+ together could be where
-you'd like to ensure the ID is unique between several types of document. For example:
+A really interesting use of `:proxy` and `:view` together could be where you'd like to ensure the ID is unique between several types of document. For example:
 
     class Product < CouchRest::Model::Base
       property :code
@@ -285,40 +366,46 @@ you'd like to ensure the ID is unique between several types of document. For exa
 Pretty cool!
 
 
+## Configuration
 
-## Notable Issues
+CouchRest Model supports a few configuration options. These can be set either for the whole Model code
+base or for a specific model of your chosing. To configure globally, provide something similar to the 
+following in your projects loading code:
 
-CouchRest Model uses active_support for some of its internals. Ensure you have a stable active support gem installed 
-or at least 3.0.0.beta4.
+    CouchRest::Model::Base.configure do |config|
+      config.mass_assign_any_attribute = true
+      config.model_type_key = 'couchrest-type'
+    end
 
-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.
+To set for a specific model:
 
-## Ruby on Rails
+   class Cat < CouchRest::Model::Base
+     mass_assign_any_attribute true
+   end
 
-CouchRest Model is compatible with rails and provides some ActiveRecord-like methods.
+Options currently avilable are:
 
-The CouchRest companion rails project 
-[http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails) is great
-for provided default connection details for your database. At the time of writting however it 
-does not provide explicit support for CouchRest Model.
+ * `mass_assign_any_attribute` - false by default, when true any attribute may be updated via the update_attributes or attributes= methods.
+ * `model_type_key` - 'couchrest-type' by default, is the name of property that holds the class name of each CouchRest Model.
 
-CouchRest Model and the original CouchRest ExtendedDocument do not share the same namespace, 
-as such you should not have any problems using them both at the same time. This might
-help with migrations.
+
+## Notable Issues
+
+None at the moment...
 
 
-### Rails 3.0
+## Ruby on Rails
+
+CouchRest Model is compatible with rails and provides some ActiveRecord-like methods.
 
-In your Gemfile require the gem with a simple line:
+The CouchRest companion rails project [http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails) is great for providing default connection details for your database. At the time of writting however it does not provide explicit support for CouchRest Model.
 
-    gem "couchrest_model"
+CouchRest Model and the original CouchRest ExtendedDocument do not share the same namespace, as such you should not have any problems using them both at the same time. This might help with migrations.
 
 
 ## Testing
 
-The most complete documentation is the spec/ directory. To validate your
-CouchRest install, from the project root directory run `rake`, or `autotest`
-(requires RSpec and optionally ZenTest for autotest support).
+The most complete documentation is the spec/ directory. To validate your CouchRest install, from the project root directory run `rake`, or `autotest` (requires RSpec and optionally ZenTest for autotest support).
 
 ## Docs
 

data/Rakefile

@@ -1,54 +1,23 @@
+require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
 require 'rake'
 require "rake/rdoctask"
 
-$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
-require 'couchrest_model'
-
-begin
-  require 'spec/rake/spectask'
-rescue LoadError
-  puts <<-EOS
-To use rspec for testing you must install rspec gem:
-    gem install rspec
-EOS
-  exit(0)
-end
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "couchrest_model"
-    gemspec.summary = "Extends the CouchRest Document for advanced modelling."
-    gemspec.description = "CouchRest Model provides aditional features to the standard CouchRest Document class such as properties, view designs, associations, callbacks, typecasting and validations."
-    gemspec.email = "jchris@apache.org"
-    gemspec.homepage = "http://github.com/couchrest/couchrest_model"
-    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}/**/*"] - Dir["spec/tmp"]
-    gemspec.has_rdoc = true
-    gemspec.add_dependency("couchrest", "~> 1.0.0")
-    gemspec.add_dependency("mime-types", "~> 1.15")
-    gemspec.add_dependency("activesupport", "~> 2.3.5")
-    gemspec.add_dependency("activemodel", "~> 3.0.0.beta4")
-    gemspec.add_dependency("tzinfo", "~> 0.3.22")
-    gemspec.version = CouchRest::Model::VERSION
-    gemspec.date = Time.now.strftime("%Y-%m-%d")
-    gemspec.require_path = "lib"
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: gem install jeweler"
-end
+require 'rspec'
+require 'rspec/core/rake_task'
 
 desc "Run all specs"
-Spec::Rake::SpecTask.new('spec') do |t|
-	t.spec_opts = ["--color"]
-	t.spec_files = FileList['spec/**/*_spec.rb']
+Rspec::Core::RakeTask.new(:spec) do |spec|
+	spec.rspec_opts = ["--color"]
+	spec.pattern = 'spec/**/*_spec.rb'
 end
 
 desc "Print specdocs"
-Spec::Rake::SpecTask.new(:doc) do |t|
-	t.spec_opts = ["--format", "specdoc"]
-	t.spec_files = FileList['spec/*_spec.rb']
+Rspec::Core::RakeTask.new(:doc) do |spec|
+	spec.rspec_opts = ["--format", "specdoc"]
+	spec.pattern = 'spec/*_spec.rb'
 end
 
 desc "Generate the rdoc"

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/couchrest_model.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{couchrest_model}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1") if s.respond_to? :required_rubygems_version=
+  s.authors = ["J. Chris Anderson", "Matt Aimonetti", "Marcos Tapajos", "Will Leinweber", "Sam Lown"]
+  s.date = %q{2011-01-16}
+  s.description = %q{CouchRest Model provides aditional features to the standard CouchRest Document class such as properties, view designs, associations, callbacks, typecasting and validations.}
+  s.email = %q{jchris@apache.org}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md",
+    "THANKS.md"
+  ]
+  s.homepage = %q{http://github.com/couchrest/couchrest_model}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Extends the CouchRest Document for advanced modelling.}
+  
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_dependency(%q<couchrest>, "~> 1.0.1")
+  s.add_dependency(%q<mime-types>, "~> 1.15")
+  s.add_dependency(%q<activemodel>, "~> 3.0.0")
+  s.add_dependency(%q<tzinfo>, "~> 0.3.22")
+  s.add_dependency(%q<railties>, "~> 3.0.0")
+  s.add_dependency(%q<rspec>, ">= 2.0.0")
+  s.add_development_dependency(%q<rspec>, ">= 2.0.0")
+  s.add_development_dependency(%q<rack-test>, ">= 0.5.7")
+end
+

data/history.txt

@@ -1,10 +1,32 @@
-== Next Version
+== CouchRest Model 1.0.0
 
 * Major enhancements
+  * Support for configuration module and "model_type_key" option for overriding model's type key
+  * Added "mass_assign_any_attribute" configuration option to allow setting anything via the attribute= method.
+
+* Minor enhancements
+  * Fixing find("") issue (thanks epochwolf)
+  * Altered protected attributes so that hash provided to #attributes= is not modified
+  * Altering typecasting for floats to better handle commas and points
+  * Fixing the lame pagination bug where database url (and pass!!) were included in view requests (Thanks James Hayton)
+
+Notes:
+
+* 2010-10-22 @samlown:
+  * ActiveModel Attribute support was added but has now been removed due to major performance issues.
+  Until these have been resolved (if possible?!) they should not be included. See the
+  'active_model_attrs' if you'd like to test.
+
+== CouchRest Model 1.0.0.beta8
+
+* Major enhancements
+	* Added model generator
 
 * Minor enhancements
   * Raise error on adding objects to "collection_of" without an id
   * Allow mixing of protected and accessible properties. Any unspecified properties are now assumed to be protected by default
+  * Parsing times without zone
+  * Using latest rspec (2.0.0.beta.19)
 
 == CouchRest Model 1.0.0.beta7
 

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__),'lib', 'couchrest', 'model')

data/lib/couchrest/model/associations.rb

@@ -2,7 +2,7 @@ module CouchRest
   module Model
     module Associations
 
-      # Basic support for relationships between ExtendedDocuments
+      # Basic support for relationships between CouchRest::Model::Base
       
       def self.included(base)
         base.extend(ClassMethods)
@@ -171,24 +171,32 @@ module CouchRest
       (array ||= []).compact!
       casted_by[property.to_s] = [] # replace the original array!
       array.compact.each do |obj|
+        check_obj(obj)
         casted_by[property.to_s] << obj.id
       end
       super(array)
     end
+    
     def << obj
+      check_obj(obj)
       casted_by[property.to_s] << obj.id
       super(obj)
     end
+    
     def push(obj)
+      check_obj(obj)
       casted_by[property.to_s].push obj.id
       super(obj)
     end
+    
     def unshift(obj)
+      check_obj(obj)
       casted_by[property.to_s].unshift obj.id
       super(obj)
     end
 
     def []= index, obj
+      check_obj(obj)
       casted_by[property.to_s][index] = obj.id
       super(index, obj)
     end
@@ -197,10 +205,18 @@ module CouchRest
       casted_by[property.to_s].pop
       super
     end
+    
     def shift
       casted_by[property.to_s].shift
       super
     end
+
+    protected
+
+    def check_obj(obj)
+      raise "Object cannot be added to #{casted_by.class.to_s}##{property.to_s} collection unless saved" if obj.new?
+    end
+
   end