couch_potato-rails2 0.5.6

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+couch_potato_js_runner.js
+pkg
+.rvmrc
+*.swp

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.2
+  - 1.8.7
+  - ree
+env: "DATABASE='http://couchpotato.iriscouch.com/couch_potato_test' "

data/CHANGES.md

@@ -0,0 +1,148 @@
+## Changes
+
+### 0.5.6
+
+* remove the stale parameter from a view query if it's nil, as couchdb only allows stale to be ok or update\_after (langalex)
+
+### 0.5.5
+
+* support for split_design_documents_per_view (jweiss)
+* errors now returns a Hash instead of an Array (bterkuile)
+* support passing in list names as symbols in view specs (langalex)
+
+### 0.5.4
+* cast 'false' to false for boolean properties (langalex)
+
+### 0.5.3
+* added CouchPotato::Database.load! (langalex)
+
+### 0.5.2
+* added CouchPotato::Database#first and #first! methods (langalex)
+* added workaround for BigCouch/Cloudant to not add null reduce functions to views (langalex)
+* don't add _attachments if there are none (langalex)
+
+### 0.5.1
+* fixed issues with tzinfo gem (Bernd Ahlers)
+
+### 0.5.0
+* time zone support (Time properties are now converted to current Time.zone) (langalex)
+* lazy property initialization (performance!) (langalex)
+* active_model is now the default validation framework (langalex)
+
+### 0.4.0
+* ruby 1.9.2 compatibility (langalex)
+* couch potato objects now behave correctly when used as keys in Hashes (langalex)
+* use as\_json instead of to\_s(:json), which is the rails way
+* use ActiveModel dirty tracking (langalex) - this means no more "deep tracking", e.g. `user.tags << 'new_tag'; user.dirty? # false`
+
+### 0.3.2
+* support yielding to blocks on #initialize (martinrehfeld)
+* support for negative numbers in Fixnum/Float properties (langalex)
+
+### 0.3.1
+* ActiveModel callbacks (kazjote)
+* do not use Rails.env in initializer as it will free Rails.env for all times and in Rails 2.3.x apps it will be called too early thus always beeing development (jweiss)
+* ruby 1.9.2 compatibility (langalex)
+* can configure validation framework in couchdb.yml, process couchdb.yml with erb (langalex)
+
+### 0.3.0
+* support for lists (langalex)
+
+### 0.2.32
+* added persisted? and to_key for proper ActiveModel compliance (thilo)
+* id setter (jhohertz-work)
+* load document ids if include\_documents is false (jweiss)
+* persist given created\_at/updated\_at instead of Time.now (langalex)
+
+### 0.2.31
+* Removed requirement for validatable gem. Allows for using more uptodate versions of the library, or doesn't install it when you're using ActiveModel. (mattmatt)
+* fixed callbacks of super classes were not run (langalex)
+
+### 0.2.30
+* pass in multiple keys when querying a view (langalex)
+
+### 0.2.29
+* nicer inspect() for models (mattmatt)
+* fixed (re)reduce for property views wasn't working (langalex)
+
+### 0.2.28
+* fixed reloading nested classes (langalex)
+* fixed constant missing error when loading models with uninitialized classes via views (langalex)
+* added rspec helpers for stubbing out views (langalex)
+* fixed design document names for nested model classes (svenfuchs)
+
+### 0.2.27
+* workaround for Rails apps using bundler: database name was not initialized from couchdb.yml (langalex)
+
+### 0.2.26
+* added to_s(:json) to Date and Time to be able to get properly formatted dates/times for searching with dates/times (langalex)
+* all times are now stored as UTC (langalex)
+* added support for Float attributes (arbovm)
+
+
+### 0.2.25
+* automatic view updates: when you change the definition of a view couch potato will now update the design document in the database (langalex)
+* support for properties of type Date, better support for Time (langalex)
+* support for default reduce count methods in custom views (jweiss)
+
+### 0.2.24
+* persistent instances can now be marked as dirty with #is_dirty (langalex)
+
+### 0.2.23
+* Couch Potato models now conform to the ActiveModel interface when ActiveModel is installed, see http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ (langalex)
+* fixed error with dirty tracking and BigDecimals (thilo)
+* added the ability to use ActiveModel validations instead of validatable (martinrehfeld)
+
+### 0.2.22
+* fixed properties with default values returned default when a blank value like '' or [] was set (langalex)
+
+### 0.2.21
+* automatically set a database instance on results of CouchPotato::Database#view (langalex)
+* improved auto loading of unloaded constants - can now load constants that have never been loaded before (langalex)
+* raise exception on invalid parameters passed to a couchdb view query (langalex)
+* when querying a view: pass in ranges as key instead of startkey/endkey, pass in plain value instead of hash with key (langalex) 
+
+### 0.2.20
+* support for :boolean properties (jweiss)
+* return the total_rows when querying a view (langalex)
+
+### 0.2.19
+* added conditions to views (langalex)
+
+### 0.2.18
+* set Fixnum property to nil when given a blank string (langalex)
+
+### 0.2.17
+* fixed nil attributes were omitted in json (jweiss, mattmatt)
+* support for properties of type Fixnum (langalex)
+
+### 0.2.16
+* fixed problem with classes being not loaded in rails development mode (langalex)
+* fixed persist boolean false value (bernd)
+
+### 0.2.15
+* ability to change the name of the attribute that stores the ruby class in the documents by setting JSON.create_id (lennart)
+* fixed double loading issue with bundler (jweiss)
+* fixed an issue with setting attachments (endor)
+
+### 0.2.13
+
+* support adding errors in before_validation callbacks (mattmatt)
+* support for inheritance (mattmatt)
+* support for save without validations (mattmatt)
+* improved (de)serialization now supports deserializing nested objects (railsbros, specs by hagenburger)
+* RSpec matchers for testing map/reduce functions (langalex)
+
+### 0.2.10
+* fixed bug with hardcoded timezone
+
+### 0.2.9
+
+* allow to overwrite attribute accessor of properties and use super to call the original accessors
+* allow read access to attributes that are present in the Couchdb document but not defined as properties
+* support default values for properties via the :default parameter
+* support attachments via the _attachments property
+* support for namespaces models
+* removed belongs_to macro for now
+* removed CouchPotato::Config.database_server, just set CouchPotato::Config.database_name to the full url if you are not using localhost:5984
+* Ruby 1.9 was broken and is now working again

data/CREDITS

@@ -0,0 +1,6 @@
+Parts of this are taken or inspired by Geoffrey Grosenbach's travel_app which is part of his CouchDB screencast.
+
+Jan Lehnardt - got me started on doing this.
+Brian Candler - contributed performance patches
+
+see CHANGES.md for all the committers

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in couch_potato.gemspec
+gemspec

data/MIT-LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2007 Bryan Helmkamp, Seth Fitzsimmons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,450 @@
+## Couch Potato
+
+... is a persistence layer written in ruby for CouchDB.
+
+### Mission
+
+The goal of Couch Potato is to create a minimal framework in order to store and retrieve Ruby objects to/from CouchDB and create and query views.
+
+It follows the document/view/querying semantics established by CouchDB and won't try to mimic ActiveRecord behavior in any way as that IS BAD.
+
+Code that uses Couch Potato should be easy to test.
+
+Lastly Couch Potato aims to provide a seamless integration with Ruby on Rails, e.g. routing, form helpers etc.
+
+### Core Features
+
+* persisting objects by including the CouchPotato::Persistence module
+* declarative views with either custom or generated map/reduce functions
+* extensive spec suite
+
+### Supported Environments
+
+* Ruby 1.8.7, 1.9.2
+* CouchDB 1.1.0
+
+(Supported means I run the specs against those before releasing a new gem.)
+
+### Installation
+
+Couch Potato is hosted as a gem which you can install like this:
+
+    (sudo) gem install couch_potato
+
+#### Using with your ruby application:
+
+    require 'rubygems'
+    require 'couch_potato'
+
+After that you configure the name of the database:
+
+    CouchPotato::Config.database_name = 'name_of_the_db'
+
+The server URL will default to http://localhost:5984/ unless specified:
+
+    CouchPotato::Config.database_name = "http://example.com:5984/name_of_the_db"
+    
+Or with authentication
+  
+    CouchPotato::Config.database_name = "http://username:password@example.com:5984/name_of_the_db"
+  
+Optionally you can configure which framework you want to use for validations (either validatable or ActiveModel (default))
+
+    CouchPotato::Config.validation_framework = :validatable | :active_model
+    
+Another switch allows you to store each CouchDB view in its own design document. Otherwise views are grouped by model.
+
+    CouchPotato::Config.split_design_documents_per_view = true
+
+#### Using with Rails
+
+Create a config/couchdb.yml:
+
+    default: &default
+      validation_framework: :active_model # optional
+      split_design_documents_per_view: true # optional
+
+    development:
+      <<: *default
+      database: development_db_name
+    test:
+      <<: *default
+      database: test_db_name
+    production:
+      <<: *default
+      database: <%= ENV['DB_NAME'] %>
+
+#### Rails 2.x
+
+Add to your _config/environment.rb_:
+
+    config.gem 'couch_potato', :source => 'http://gemcutter.org'
+    config.frameworks -= [:active_record] # if you switch completely
+    
+#### Rails 3.x
+
+Add to your _Gemfile_:
+
+    # gem 'rails' # we don't want to load activerecord so we can't require rails
+    gem 'railties'
+    gem 'actionpack'
+    gem 'actionmailer'
+    gem 'activemodel'
+    gem "couch_potato"
+
+Note: please make sure that when you run `Date.today.as_json` in the Rails console it returns something like `2010/12/10` and not `2010-12-10` - if it does another gem has overwritten Couch Potato's Date patches - in this case move Couch Potato further down in your Gemfile or whereever you load it.
+
+### Introduction
+
+This is a basic tutorial on how to use Couch Potato. If you want to know all the details feel free to read the specs and the [rdocs](http://rdoc.info/projects/langalex/couch_potato).
+
+#### Save, load objects
+
+First you need a class.
+
+    class User
+    end
+
+To make instances of this class persistent include the persistence module:
+
+    class User
+      include CouchPotato::Persistence
+    end
+
+If you want to store any properties you have to declare them:
+
+    class User
+      include CouchPotato::Persistence
+
+      property :name
+    end
+
+Properties can be typed:
+
+    class User
+      include CouchPotato::Persistence
+
+      property :address, :type => Address
+    end
+    
+In this case Address also implements CouchPotato::Persistence which means its JSON representation will be added to the user document.  
+Couch Potato also has support for the basic types (right now Fixnum, Date, Time and :boolean are supported):
+
+    class User
+      include CouchPotato::Persistence
+
+      property :age, :type => Fixnum
+      property :receive_newsletter, :type => :boolean
+    end
+
+With this in place when you set the user's age as a String (e.g. using an hTML form) it will be converted into a Fixnum automatically.
+    
+
+Properties can have a default value:
+
+    class User
+      include CouchPotato::Persistence
+
+      property :active, :default => true
+    end
+
+Now you can save your objects. All database operations are encapsulated in the CouchPotato::Database class. This separates your domain logic from the database access logic which makes it easier to write tests and also keeps you models smaller and cleaner.
+
+    user = User.new :name => 'joe'
+    CouchPotato.database.save_document user # or save_document!
+
+You can of course also retrieve your instance:
+
+    CouchPotato.database.load_document "id_of_the_user_document" # => <#User 0x3075>
+
+
+#### Properties
+
+You can access the properties you declared above through normal attribute accessors.
+
+    user.name # => 'joe'
+    user.name = {:first => ['joe', 'joey'], :last => 'doe', :middle => 'J'} # you can set any ruby object that responds_to :to_json (includes all core objects)
+    user._id # => "02097f33a0046123f1ebc0ebb6937269"
+    user._rev # => "2769180384"
+    user.created_at # => Fri Oct 24 19:05:54 +0200 2008
+    user.updated_at # => Fri Oct 24 19:05:54 +0200 2008
+    user.new? # => false
+
+If you want to have properties that don't map to any JSON type, i.e. other than String, Number, Boolean, Hash or Array you have to define the type like this:
+
+    class User
+      property :date_of_birth, :type => Date
+    end
+
+The date_of_birth property is now automatically serialized to JSON and back when storing/retrieving objects.
+
+#### Dirty tracking
+
+CouchPotato tracks the dirty state of attributes in the same way ActiveRecord does:
+
+    user = User.create :name => 'joe'
+    user.name # => 'joe'
+    user.name_changed? # => false
+    user.name_was # => nil
+
+You can also force a dirty state:
+
+    user.name = 'jane'
+    user.name_changed? # => true
+    user.name_not_changed
+    user.name_changed? # => false
+    CouchPotato.database.save_document user # does nothing as no attributes are dirty
+
+
+#### Object validations
+
+Couch Potato by default uses ActiveModel for validation
+
+    class User
+      property :name
+      validates_presence_of :name
+    end
+
+    user = User.new
+    user.valid? # => false
+    user.errors[:name] # => ['can't be blank']
+  
+If you want you can use [Validatable](http://validatable.rubyforge.org/) by setting `CouchPotato::Config.validation(http://validatable.rubyforge.org/)\_framework = :validatable`
+
+#### Finding stuff / views / lists
+
+In order to find data in your CouchDB you have to create a [view](http://books.couchdb.org/relax/design-documents/views) first. Couch Potato offers you to create and manage those views for you. All you have to do is declare them in your classes:
+
+    class User
+      include CouchPotato::Persistence
+      property :name
+
+      view :all, :key => :created_at
+    end
+
+This will create a view called "all" in the "user" design document with a map function that emits "created_at" for every user document.
+
+    CouchPotato.database.view User.all
+
+This will load all user documents in your database sorted by created_at.
+
+    CouchPotato.database.view User.all(:key => (Time.now- 10)..(Time.now), :descending => true)
+
+Any options you pass in will be passed onto CouchDB.
+
+Composite keys are also possible:
+
+    class User
+      property :name
+
+      view :all, :key => [:created_at, :name]
+    end
+
+You can also pass conditions as a JavaScript string:
+
+    class User
+      property :name
+
+      view :completed, :key => :name, :conditions => 'doc.completed === true'
+    end
+
+The creation of views is based on view specification classes (see [CouchPotato::View::BaseViewSpec](http://rdoc.info/rdoc/langalex/couch_potato/blob/e8f0069e5529ad08a1bd1f02637ea8f1d6d0ab5b/CouchPotato/View/BaseViewSpec.html) and its descendants for more detailed documentation). The above code uses the ModelViewSpec class which is used to find models by their properties. For more sophisticated searches you can use other view specifications (either use the built-in or provide your own) by passing a type parameter:
+
+If you have larger structures and you only want to load some attributes you can use the PropertiesViewSpec (the full class name is automatically derived):
+
+    class User
+      property :name
+      property :bio
+
+      view :all, :key => :created_at, :properties => [:name], :type => :properties
+    end
+
+    CouchPotato.database.view(User.everyone).first.name # => "joe"
+    CouchPotato.database.view(User.everyone).first.bio # => nil
+  
+    CouchPotato.database.first(User.everyone).name # => "joe" # convenience function, returns nil if nothing found
+    CouchPotato.database.first!(User.everyone) # would raise CouchPotato::NotFound if nothing was found
+
+If you want Rails to automatically show a 404 page when `CouchPotato::NotFound` is raised add this to your `ApplicationController`:
+    
+    rescue_from CouchPotato::NotFound do
+      render(:file => 'public/404.html', :status => :not_found, :layout => false)
+    end
+
+You can also pass in custom map/reduce functions with the custom view spec:
+
+    class User
+      view :all, :map => "function(doc) { emit(doc.created_at, null)}", :include_docs => true, :type => :custom
+    end
+
+If you don't want the results to be converted into models the raw view is your friend:
+
+    class User
+      view :all, :map => "function(doc) { emit(doc.created_at, doc.name)}", :type => :raw
+    end
+
+When querying this view you will get the raw data returned by CouchDB which looks something like this: {'total_entries': 2, 'rows': [{'value': 'alex', 'key': '2009-01-03 00:02:34 +000', 'id': '75976rgi7546gi02a'}]}
+
+To process this raw data you can also pass in a results filter:
+
+    class User
+      view :all, :map => "function(doc) { emit(doc.created_at, doc.name)}", :type => :raw, :results_filter => lambda {|results| results['rows'].map{|row| row['value']}}
+    end
+
+In this case querying the view would only return the emitted value for each row.
+
+You can pass in your own view specifications by passing in :type => MyViewSpecClass. Take a look at the CouchPotato::View::*ViewSpec classes to get an idea of how this works.
+
+##### Lists
+
+CouchPotato also supports [CouchDB lists](http://books.couchdb.org/relax/design-documents/lists). With lists you can process the result of a view query with another JavaScript function. This can be useful for example if you want to filter your results, or add some data to each document.
+
+Defining a list works similarly to views:
+
+    class User
+      include CouchPotato::Persistence
+      
+      property :first_name
+      view :with_full_name, key: first_namne, list: :add_last_name
+      view :all, key: :first_name
+      
+      list :add_last_name, <<-JS
+        function(head, req) {
+          var row;
+          send('{"rows": [');
+          while(row = getRow()) {
+            row.doc.name = row.doc.first_name + ' doe';
+            send(JSON.stringify(row));
+          };
+          send(']}');
+        }
+      JS
+    end
+    
+    CouchPotato.database.save User.new(first_name: 'joe')
+    CouchPotato.database.view(User.with_full_name).first.name # => 'joe doe'
+    
+You can also pass in the list at query time:
+
+    CouchPotato.database.view(User.all(list: :add_last_name))
+
+#### Associations
+
+Not supported. Not sure if they ever will be. You can implement those yourself using views and custom methods on your models.
+
+#### Callbacks
+
+Couch Potato supports the usual lifecycle callbacks known from ActiveRecord:
+
+    class User
+      include CouchPotato::Persistence
+
+      before_create :do_something_before_create
+      before_update {|user| user.do_something_on_update}
+    end
+
+This will call the method do_something_before_create before creating an object and run the given lambda before updating one. Lambda callbacks get passed the model as their first argument. Method callbacks don't receive any arguments.
+
+Supported callbacks are: :before_validation, :before_validation_on_create, :before_validation_on_update, :before_validation_on_save, :before_create, :after_create, :before_update, :after_update, :before_save, :after_save, :before_destroy, :after_destroy.
+
+If you need access to the database in a callback: Couch Potato automatically assigns a database instance to the model before saving and when loading. It is available as _database_ accessor from within your model instance.
+
+#### Attachments
+
+There is basic attachment support: if you want to store any attachments set the _attachments attribute of a model before saving like this:
+
+    class User
+      include CouchPotato::Persistence
+    end
+    
+    data = File.read('some_file.text') # or from upload
+    user = User.new
+    user._attachments = {'photo' => {'data' => data, 'content_type' => 'image/png'}}
+    
+When saving this object an attachment with the name _photo_ will be uploaded into CouchDB. It will be available under the url of the user object + _/photo_. When loading the user at a later time you still have access to the _content_type_ and additionally to the _length_ of the attachment:
+
+    user_reloaded = CouchPotato.database.load user.id
+    user_reloaded._attachments['photo'] # => {'content_type' => 'image/png', 'length' => 37861}
+
+#### Testing
+
+To make testing easier and faster database logic has been put into its own class, which you can replace and stub out in whatever way you want:
+
+    class User
+      include CouchPotato::Persistence
+    end
+
+    # RSpec
+    describe 'save a user' do
+      it 'should save' do
+        couchrest_db = stub 'couchrest_db',
+        database = CouchPotato::Database.new couchrest_db
+        user = User.new
+        couchrest_db.should_receive(:save_doc).with(...)
+        database.save_document user
+      end
+    end
+
+By creating you own instances of CouchPotato::Database and passing them a fake CouchRest database instance you can completely disconnect your unit tests/spec from the database.
+
+For stubbing out the database couch potato offers some helpers:
+
+    class Comment
+      view :by_commenter_id, :key => :commenter_id
+    end
+    
+    # RSpec
+    require 'couch_potato/rspec'
+    
+    db = stub_db # stubs CouchPotato.database
+    db.stub_view(Comment, :by_commenter_id).with('23').and_return([:comment1, :comment2])
+    
+    CouchPotato.database.view(Comment.by_commenter_id('23)) # => [:comment1, :comment2]
+
+##### Testing map/reduce functions
+
+Couch Potato provides custom RSpec matchers for testing the map and reduce functions of your views. For example you can do this:
+
+    Class User
+      include CouchPotato::Persistence
+      
+      view :by_name, :key => :name
+      view :by_age, :key => :age
+    end
+    
+    #RSpec
+    require 'couch_potato/rspec'
+    
+    describe User, 'by_name' do
+      it "should map users to their name" do
+        User.by_name.should map(User.new(:name => 'bill', :age => 23)).to(['bill', null])
+      end
+      
+      it "should reduce the users to the sum of their age" do
+        User.by_age.should reduce([], [[23], [22]]).to(45)
+      end
+      
+      it "should rereduce" do
+        User.by_age.should rereduce([], [[23], [22]]).to(45)
+      end
+    end
+    
+This will actually run your map/reduce functions in a JavaScript interpreter, passing the arguments as JSON and converting the results back to Ruby. For more examples see the [spec](http://github.com/langalex/couch_potato/blob/master/spec/unit/rspec_matchers_spec.rb).
+
+In order for this to work you must have the `js` executable in your PATH. This is usually part of the _spidermonkey_ package/port. (On MacPorts that's _spidemonkey_, on Linux it could be one of _libjs_, _libmozjs_ or _libspidermonkey_). When you installed CouchDB via your packet manager Spidermonkey should already be there.
+
+### Helping out
+
+Please fix bugs, add more specs, implement new features by forking the github repo at http://github.com/langalex/couch_potato.
+
+Issues are tracked at github: http://github.com/langalex/couch_potato/issues
+
+There is a mailing list, just write to: couchpotato@librelist.com
+
+You can run all the specs by calling 'rake spec_unit' and 'rake spec_functional' in the root folder of Couch Potato. The specs require a running CouchDB instance at http://localhost:5984
+
+I will only accept patches that are covered by specs - sorry.
+
+### Contact
+
+If you have any questions/suggestions etc. please contact me at alex at upstream-berlin.com or @langalex on twitter.