couch_potato 1.4.0 → 1.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 66ce129081c4c70157fc61c40f500d9460660900
-  data.tar.gz: 7be5df77cd9c672f71db5782440237702a7e1c8c
+  metadata.gz: 8581d86c34cc798e082cfd4e02bb53f042fa7751
+  data.tar.gz: b2f1a4996b05581a519706cb0efb10db43aa942f
 SHA512:
-  metadata.gz: 8f3e28aad6d21326a3497f995b242c055ec764c786d73571bbc72053ee84954277832a3f519e61b1667c0a323d1ed0f02a45eb6f1a343c3611f7cec6091cb624
-  data.tar.gz: 84f5e3b8ceb96051d8af95f0101b5620ac24b54736e4db36ccf8ad6ffe524c787140def2c242fd77d2f27fed8a2999a86803a94a6121ea7e8ea401ae956726cb
+  metadata.gz: aead6991131097d92510834befd4feb441c477a761472d43b72c3422cf0371eef35c7acfd52e2711483812c48f508ed706a72c8194875d00ebdd233fad774c38
+  data.tar.gz: f15626c508f062dbfd99d6672e0ed94b8364ec85d5030b77935656a42e3d27923b9bbc2e2bb8028f8f985de8c3967e55ff7754a410d97844f6836b410b8d05ba

data/.ruby-version

@@ -0,0 +1 @@
+2.2.2

data/.travis.yml

@@ -1,16 +1,20 @@
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1.2
-  - jruby-19mode
-  - rbx-2.2.10
+  - 2.2.2
+  - jruby-9.0.1.0
+  - rbx-2.5.8
+services:
+  - couchdb
 gemfile:
-  - active_support_3_2
-  - active_support_4_0
+  - gemfiles/active_support_4_0
+  - gemfiles/active_support_4_1
+  - gemfiles/active_support_4_2
+before_install:
+  gem install bundler --version 1.11.2
 before_script:
   - sudo sh -c 'echo "[native_query_servers]" >> /etc/couchdb/local.ini'
   - sudo sh -c 'echo "erlang = {couch_native_process, start_link, []}" >> /etc/couchdb/local.ini'
   - sudo /etc/init.d/couchdb restart
-matrix:
-  allow_failures:
-    - rvm: jruby-19mode
+  - bundle
+script: bundle exec rake

data/CHANGES.md

@@ -1,5 +1,9 @@
 ## Changes
 
+### 1.5.0
+
+* Moved RSpec matchers into couch_potato-rspec gem. This way, people not using RSpec don't need to install the helpers, plus we can release separate matchers for RSpec 2 and 3.
+
 ### 1.4.0
 
 * Added support for passing the model to blocks for computing the default value of a property (Alexander Lang)

data/Gemfile

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

data/README.md

@@ -27,9 +27,9 @@ Lastly Couch Potato aims to provide a seamless integration with Ruby on Rails, e
 
 ### Supported Environments
 
-* Ruby 1.9.3, 2.0, 2.1, Rubinius
-* CouchDB 1.2.0
-* ActiveSupport 3.2, 4.0
+* Ruby 2.0, 2.1, 2.2, Rubinius
+* CouchDB 1.6.0
+* ActiveSupport 4.0, 4.1, 4.2
 
 (Supported means I run the specs against those before releasing a new gem.)
 
@@ -37,69 +37,90 @@ Lastly Couch Potato aims to provide a seamless integration with Ruby on Rails, e
 
 Couch Potato is hosted as a gem which you can install like this:
 
-    gem install couch_potato
+```bash
+gem install couch_potato
+```
 
 #### Using with your ruby application:
 
-    require 'rubygems'
-    require 'couch_potato'
+```ruby
+require 'rubygems'
+require 'couch_potato'
+```
 
 After that you configure the name of the database:
 
-    CouchPotato::Config.database_name = 'name_of_the_db'
+```ruby
+CouchPotato::Config.database_name = 'name_of_the_db'
+```
 
-The server URL will default to http://localhost:5984/ unless specified:
+The server URL will default to `http://localhost:5984/` unless specified:
 
-    CouchPotato::Config.database_name = "http://example.com:5984/name_of_the_db"
+```ruby
+CouchPotato::Config.database_name = "http://example.com:5984/name_of_the_db"
+```
 
 But you can also specify the database host separately from the database name:
 
-    CouchPotato::Config.database_host = "http://example.com:5984"
-    CouchPotato::Config.database_name = "name_of_the_db"
+```ruby
+CouchPotato::Config.database_host = "http://example.com:5984"
+CouchPotato::Config.database_name = "name_of_the_db"
+```
 
 Or with authentication
 
-    CouchPotato::Config.database_name = "http://username:password@example.com:5984/name_of_the_db"
+```ruby
+CouchPotato::Config.database_name = "http://username:password@example.com:5984/name_of_the_db"
+```
 
-Optionally you can configure the default language for design documents (:javascript (default) or :erlang).
+Optionally you can configure the default language for design documents (`:javascript` (default) or `:erlang`).
 
-    CouchPotato::Config.default_language = :javascript | :erlang
+```ruby
+CouchPotato::Config.default_language = :javascript | :erlang
+```
 
 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
+```ruby
+CouchPotato::Config.split_design_documents_per_view = true
+```
 
 #### Using with Rails
 
-Create a config/couchdb.yml:
-
-    default: &default
-      split_design_documents_per_view: true # optional
-      default_language: :erlang # optional
-
-    development:
-      <<: *default
-      database: development_db_name
-    test:
-      <<: *default
-      database: test_db_name
-    production:
-      <<: *default
-      database: <%= ENV['DB_NAME'] %>
+Create a `config/couchdb.yml`:
+
+```yml
+default: &default
+  split_design_documents_per_view: true # optional, default is false
+  digest_view_names: true # optional, default is false
+  default_language: :erlang # optional, default is javascript
+
+development:
+  <<: *default
+  database: development_db_name
+test:
+  <<: *default
+  database: test_db_name
+production:
+  <<: *default
+  database: <%= ENV['DB_NAME'] %>
+```
 
 #### Rails 3.x
 
-Add to your _Gemfile_:
+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"
-    gem 'tzinfo'
+```ruby
+# 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"
+gem 'tzinfo'
+```
 
-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.
+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
 
@@ -109,69 +130,87 @@ This is a basic tutorial on how to use Couch Potato. If you want to know all the
 
 First you need a class.
 
-    class User
-    end
+```ruby
+class User
+end
+```
 
 To make instances of this class persistent include the persistence module:
 
-    class User
-      include CouchPotato::Persistence
-    end
+```ruby
+class User
+  include CouchPotato::Persistence
+end
+```
 
 If you want to store any properties you have to declare them:
 
-    class User
-      include CouchPotato::Persistence
+```ruby
+class User
+  include CouchPotato::Persistence
 
-      property :name
-    end
+  property :name
+end
+```
 
 Properties can be typed:
 
-    class User
-      include CouchPotato::Persistence
+```ruby
+class User
+  include CouchPotato::Persistence
 
-      property :address, :type => Address
-    end
+  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):
+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
+```ruby
+class User
+  include CouchPotato::Persistence
 
-      property :age, :type => Fixnum
-      property :receive_newsletter, :type => :boolean
-    end
+  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.
+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
+```ruby
+class User
+  include CouchPotato::Persistence
 
-      property :active, :default => true
-      property :signed_up, :default => Proc.new { Time.now }
-    end
+  property :active, :default => true
+  property :signed_up, :default => Proc.new { Time.now }
+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.
+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!
+```ruby
+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>
+```ruby
+CouchPotato.database.load_document "id_of_the_user_document" # => <#User 0x3075>
+```
 
 #### Handling conflicts
 
 CouchDB uses MVCC to detect write conflicts. If a conflict occurs when trying to update a document CouchDB returns an error. To handle conflicts easily you can save documents like this:
 
-    CouchPotato.database.save_document user do |user|
-      user.name = 'joe'
-    end
+```ruby
+CouchPotato.database.save_document user do |user|
+  user.name = 'joe'
+end
+```
 
 When a conflict occurs Couch Potato automatically reloads the document, runs the block and tries to save it again. Note that the block is also run before initally saving the document.
 
@@ -179,207 +218,261 @@ When a conflict occurs Couch Potato automatically reloads the document, runs the
 
 You can also load a bunch of documents with one request.
 
-    CouchPotato.database.load ['user1', 'user2', 'user3'] # => [<#User 0x3075>, <#User 0x3076>, <#User 0x3077>]
+```ruby
+CouchPotato.database.load ['user1', 'user2', 'user3'] # => [<#User 0x3075>, <#User 0x3076>, <#User 0x3077>]
+```
 
 #### 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
+```ruby
+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:
+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
+```ruby
+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.
+The `date_of_birth` property is now automatically serialized to JSON and back when storing/retrieving objects.
 
 If you want to store an Array of objects, just pass the definiton as an Array of Dates:
 
-    class User
-      property :birthdays, :type => [Date]
-    end
+```ruby
+class User
+  property :birthdays, :type => [Date]
+end
+```
 
 #### 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
+```ruby
+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
+```ruby
+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
+```
 
 #### Optional Deep Dirty Tracking
 
-In addition to standard dirty tracking, you can opt-in to more advanced dirty tracking for deeply structured documents by including the ```CouchPotato::DeepDirtyAttributes``` module in your models. This provides two benefits:
+In addition to standard dirty tracking, you can opt-in to more advanced dirty tracking for deeply structured documents by including the `CouchPotato::DeepDirtyAttributes` module in your models. This provides two benefits:
 
-1. Dirty checking for array and embedded document properties is more reliable, such that modifying elements in an array (by any means) or changing a property of an embedded document will make the root document be ```changed?```. With standard dirty checking, the ```#{property}=``` method must be called on the root document for it to be ```changed?```.
+1. Dirty checking for array and embedded document properties is more reliable, such that modifying elements in an array (by any means) or changing a property of an embedded document will make the root document be `changed?`. With standard dirty checking, the `#{property}=` method must be called on the root document for it to be `changed?`.
 2. It gives more useful and detailed change tracking for embedded documents, arrays of simple values, and arrays of embedded documents.
 
-The ```#{property}_changed?``` and ```#{property}_was``` methods work the same as basic dirty checking, and the ```_was``` values are always deep clones of the original/previous value. The ```#{property}_change``` and ```changes``` methods differ from basic dirty checking for embedded documents and arrays, giving richer details of the changes instead of just the previous and current values. This makes generating detailed, human friendly audit trails of documents easy.
+The `#{property}_changed?` and `#{property}_was` methods work the same as basic dirty checking, and the `_was` values are always deep clones of the original/previous value. The `#{property}_change` and `changes` methods differ from basic dirty checking for embedded documents and arrays, giving richer details of the changes instead of just the previous and current values. This makes generating detailed, human friendly audit trails of documents easy.
 
 Tracking changes in embedded documents gives easy access to the changes in that document:
 
-    book = Book.new(:cover => Cover.new(:color => "red"))
-    book.cover.color = "blue"
-    book.cover_changed? # => true
-    book.cover_was # => <deep clone of original state of book.cover>
-    book.cover_change # => [<deep clone of original state of book.cover>, {:color => ["red", "blue"]}]
+```ruby
+book = Book.new(:cover => Cover.new(:color => "red"))
+book.cover.color = "blue"
+book.cover_changed? # => true
+book.cover_was # => <deep clone of original state of book.cover>
+book.cover_change # => [<deep clone of original state of book.cover>, {:color => ["red", "blue"]}]
+```
 
 Tracking changes in arrays of simple properties gives easy access to added and removed items:
 
-    book = Book.new(:authors => ["Sarah", "Jane"])
-    book.authors.delete "Jane"
-    book.authors << "Sue"
-    book.authors_changed? # => true
-    book.authors_was # => ["Sarah", "Jane"]
-    book.authors_change # => [["Sarah", "Jane"], {:added => ["Sue"], :removed => ["Jane"]}]
+```ruby
+book = Book.new(:authors => ["Sarah", "Jane"])
+book.authors.delete "Jane"
+book.authors << "Sue"
+book.authors_changed? # => true
+book.authors_was # => ["Sarah", "Jane"]
+book.authors_change # => [["Sarah", "Jane"], {:added => ["Sue"], :removed => ["Jane"]}]
+```
 
 Tracking changes in an array of embedded documents also gives changed items:
 
-    book = Book.new(:pages => [Page.new(:number => 1), Page.new(:number => 2)]
-    book.pages[0].title = "New title"
-    book.pages.delete_at 1
-    book.pages << Page.new(:number => 3)
-    book.pages_changed? # => true
-    book.pages_was # => <deep clone of original pages array>
-    book.pages_change[0] # => <deep clone of original pages array>
-    book.pages_change[1] # => {:added => [<page 3>], :removed => [<page 2>], :changed => [[<deep clone of original page 1>, {:title => [nil, "New title"]}]]}
-
-For change tracking in nested documents and document arrays to work, the embedded documents **must** have unique ```_id``` values. This can be accomplished easily in your embedded CouchPotato models by overriding ```initialize```:
-
-    def initialize(*args)
-      self._id = SecureRandom.uuid
-      super
-    end
+```ruby
+book = Book.new(:pages => [Page.new(:number => 1), Page.new(:number => 2)]
+book.pages[0].title = "New title"
+book.pages.delete_at 1
+book.pages << Page.new(:number => 3)
+book.pages_changed? # => true
+book.pages_was # => <deep clone of original pages array>
+book.pages_change[0] # => <deep clone of original pages array>
+book.pages_change[1] # => {:added => [<page 3>], :removed => [<page 2>], :changed => [[<deep clone of original page 1>, {:title => [nil, "New title"]}]]}
+```
+
+For change tracking in nested documents and document arrays to work, the embedded documents **must** have unique `_id` values. This can be accomplished easily in your embedded CouchPotato models by overriding `initialize`:
+
+```ruby
+def initialize(*args)
+  self._id = SecureRandom.uuid
+  super
+end
+```
 
 #### Object validations
 
 Couch Potato by default uses ActiveModel for validation
 
-    class User
-      property :name
-      validates_presence_of :name
-    end
+```ruby
+class User
+  property :name
+  validates_presence_of :name
+end
 
-    user = User.new
-    user.valid? # => false
-    user.errors[:name] # => ['can't be blank']
+user = User.new
+user.valid? # => false
+user.errors[:name] # => ['can't be blank']
+```
 
 #### 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
+```ruby
+class User
+  include CouchPotato::Persistence
+  property :name
 
-      view :all, :key => :created_at
-    end
+  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
+```ruby
+CouchPotato.database.view User.all
+```
 
-This will load all user documents in your database sorted by created_at.
+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)
+```ruby
+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
+```ruby
+class User
+  property :name
 
-      view :all, :key => [:created_at, :name]
-    end
+  view :all, :key => [:created_at, :name]
+end
+```
 
 You can let Couch Potato generate these map/reduce functions in Erlang, which reslts in much faster view generation:
 
-    class User
-      property :name
+```ruby
+class User
+  property :name
 
-      view :all, :key => [:created_at, :name], :language => :erlang
-    end
+  view :all, :key => [:created_at, :name], :language => :erlang
+end
+```
 
 So far only very simple views like the above work with Erlang.
 
 You can also pass conditions as a JavaScript string:
 
-    class User
-      property :name
+```ruby
+class User
+  property :name
 
-      view :completed, :key => :name, :conditions => 'doc.completed === true'
-    end
+  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:
+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):
+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
+```ruby
+class User
+  property :name
+  property :bio
 
-      view :all, :key => :created_at, :properties => [:name], :type => :properties
-    end
+  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.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
+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
+```ruby
+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
+```ruby
+class User
+  view :all, :map => "function(doc) { emit(doc.created_at, null)}", :include_docs => true, :type => :custom
+end
+```
 
 commonJS modules can also be used in custom views:
 
-    class User
-      view :all, :map => "function(doc) { emit(null, require("views/lib/test").test)}", :lib => {:test => "exports.test = 'test'"}, :include_docs => true, :type => :custom
-    end
+```ruby
+class User
+  view :all, :map => "function(doc) { emit(null, require("views/lib/test").test)}", :lib => {:test => "exports.test = 'test'"}, :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
+```ruby
+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:
 
-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'}]}
+```json
+{'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
+```ruby
+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.
+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.
+
+##### Digest view names
+
+If turned on, Couch Potato will append an MD5 digest of the map function to each view name. This makes sure (together with split_design_documents_per_view) that no views/design documents are ever updated. Instead, new ones are created. Since reindexing can take a long time once your database is larger, you want to avoid blocking your app while CouchDB is busy. Instead, you create a new view, warm it up, and only then start using it. 
 
 ##### Lists
 
@@ -387,32 +480,43 @@ CouchPotato also supports [CouchDB lists](http://books.couchdb.org/relax/design-
 
 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'
+```ruby
+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))
+```ruby
+CouchPotato.database.view(User.all(list: :add_last_name))
+```
+
+And you can pass parameters to the list:
+
+```ruby
+CouchPotato.database.view(User.all(list: :add_last_name, list_params: {filter: '*'}))
+```
+
 
 #### Associations
 
@@ -422,124 +526,140 @@ Not supported. Not sure if they ever will be. You can implement those yourself u
 
 Couch Potato supports the usual lifecycle callbacks known from ActiveRecord:
 
-    class User
-      include CouchPotato::Persistence
+```ruby
+class User
+  include CouchPotato::Persistence
 
-      before_create :do_something_before_create
-      before_update {|user| user.do_something_on_update}
-    end
+  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.
+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:
+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
+```ruby
+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'}}
+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}
+```ruby
+user_reloaded = CouchPotato.database.load user.id
+user_reloaded._attachments['photo'] # => {'content_type' => 'image/png', 'length' => 37861}
+```
 
 #### Multi DB Support
 
 Couch Potato supports accessing multiple CouchDBs:
 
-    CouchPotato.with_database('couch_customer') do |couch|
-      couch.save @customer
-    end
+```ruby
+CouchPotato.with_database('couch_customer') do |couch|
+  couch.save @customer
+end
+```
 
-Unless configured otherwise this would save the customer model to _http://127.0.0.1:5984/couch_customer_.
+Unless configured otherwise this would save the customer model to `http://127.0.0.1:5984/couch_customer`.
 
 You can also first retrieve the database instance:
 
-    db = CouchPotato.use('couch_customer')
-    db.save @customer
+```ruby
+db = CouchPotato.use('couch_customer')
+db.save @customer
+```
 
 #### 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
+```ruby
+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
+# 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.
+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:
+For stubbing out the database couch potato offers some helpers via the `couch_potato-rspec` gem. Use version 2.x of the gem, you you are on RSpec 2, use 3.x for RSpec 3.
 
-    class Comment
-      view :by_commenter_id, :key => :commenter_id
-    end
+```ruby
+class Comment
+  view :by_commenter_id, :key => :commenter_id
+end
 
-    # RSpec
-    require 'couch_potato/rspec'
+# RSpec
+require 'couch_potato/rspec'
 
-    db = stub_db # stubs CouchPotato.database
-    db.stub_view(Comment, :by_commenter_id).with('23').and_return([:comment1, :comment2])
+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]
-    CouchPotato.database.first(Comment.by_commenter_id('23)) # => :comment1
+CouchPotato.database.view(Comment.by_commenter_id('23)) # => [:comment1, :comment2]
+CouchPotato.database.first(Comment.by_commenter_id('23)) # => :comment1
+```
 
 ##### 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
+```ruby
+class User
+  include CouchPotato::Persistence
 
-      property :name
-      property :age, :type => Fixnum
+  property :name
+  property :age, :type => Fixnum
 
-      view :by_name, :key => :name
-      view :by_age,  :key => :age
-      view :oldest_by_name,
-        :map => "function(doc) { emit(doc.name, doc.age); }",
-        :reduce => "function(keys, values, rereduce) { return Math.max.apply(this, values); }"
-    end
+  view :by_name, :key => :name
+  view :by_age,  :key => :age
+  view :oldest_by_name,
+    :map => "function(doc) { emit(doc.name, doc.age); }",
+    :reduce => "function(keys, values, rereduce) { return Math.max.apply(this, values); }"
+end
 
-    #RSpec
-    require 'couch_potato/rspec'
+#RSpec
+require 'couch_potato/rspec'
 
-    describe User, 'views' do
-      it "should map users to their name" do
-        User.by_name.should map(User.new(:name => 'bill', :age => 23)).to(['bill', 1])
-      end
+describe User, 'views' do
+  it "should map users to their name" do
+    User.by_name.should map(User.new(:name => 'bill', :age => 23)).to(['bill', 1])
+  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 reduce the users to the sum of their age" do
+    User.by_age.should reduce([], [23, 22]).to(45)
+  end
 
-      it "should map/reduce users to the oldest age by name" do
-        docs = [User.new(:name => "John", :age => 25), User.new(:name => "John", :age => 30), User.new(:name => "Jane", :age => 20)]
-        User.oldest_by_name.should map_reduce(docs).with_options(:group => true).to(
-          {"key" => "John", "value" => 30}, {"key" => "Jane", "value" => 20})
-      end
-    end
+  it "should map/reduce users to the oldest age by name" do
+    docs = [User.new(:name => "John", :age => 25), User.new(:name => "John", :age => 30), User.new(:name => "Jane", :age => 20)]
+    User.oldest_by_name.should map_reduce(docs).with_options(:group => true).to(
+      {"key" => "John", "value" => 30}, {"key" => "Jane", "value" => 20})
+  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. ```map_reduce``` specs map the input documents, reduce the emitted keys/values, and rereduce the results while also respecting the ```:group``` and ```:group_level``` couchdb options. For more examples see the [spec](http://github.com/langalex/couch_potato/blob/master/spec/unit/rspec_matchers_spec.rb).
+This will actually run your map/reduce functions in a JavaScript interpreter, passing the arguments as JSON and converting the results back to Ruby. `map_reduce` specs map the input documents, reduce the emitted keys/values, and rereduce the results while also respecting the `:group` and `:group_level` couchdb options. 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.
 
@@ -551,7 +671,7 @@ 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
+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.