andrewtimberlake-couch_potato 0.2.8.1

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,279 @@
+## 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
+
+### Installation
+
+Couch Potato is hosted as a gem on github which you can install like this:
+
+    sudo gem source --add http://gems.github.com # if you haven't already
+    sudo gem install langalex-couch_potato
+
+#### Using with your ruby application:
+
+    require 'rubygems'
+    gem 'langalex-couch_potato'
+    require 'couch_potato'
+
+Alternatively you can download or clone the source repository and then require lib/couch_potato.rb.
+
+You MUST specificy the name of the database:
+
+    CouchPotato::Config.database_name = 'name of the db'
+
+The server URL will default to http://localhost:5984/ unless specified with:
+
+    CouchPotato::Config.database_server = "http://example.com:5984/"
+
+#### Using with Rails
+
+Add to your config/environment.rb:
+
+    config.gem 'langalex-couch_potato', :lib => 'couch_potato', :source => 'http://gems.github.com'
+
+Then create a config/couchdb.yml:
+
+    development: development_db_name
+    test: test_db_name
+    production: http://db.server/production_db_name
+
+Alternatively you can also install Couch Potato directly as a plugin.
+
+### 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.
+
+#### 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 of any type:
+
+    class User
+      include CouchPotato::Persistence
+
+      property :address, :type => Address
+    end
+
+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 uses the validatable library for vaidation (http://validatable.rubyforge.org/)\
+
+    class User
+      property :name
+      validates_presence_of :name
+    end
+
+    user = User.new
+    user.valid? # => false
+    user.errors.on(:name) # => [:name, 'can't be blank']
+
+#### Finding stuff
+
+In order to find data in your CouchDB you have to create a view 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
+
+The creation of views is based on view specification classes (see the CouchPotato::View module). 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
+
+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.
+
+#### 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.
+
+#### 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.
+
+### Helping out
+
+Please fix bugs, add more specs, implement new features by forking the github repo at http://github.com/langalex/couch_potato.
+
+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.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 2
+:patch: 8
+:major: 0

data/init.rb

@@ -0,0 +1,3 @@
+# this is for rails only
+
+require File.dirname(__FILE__) + '/rails/init'

data/lib/core_ext/date.rb

@@ -0,0 +1,10 @@
+class Date
+  def to_json(*a)
+    %("#{strftime("%Y/%m/%d")}")
+  end
+  
+  def self.json_create string
+    return nil if string.nil?
+    Date.parse(string)
+  end
+end

data/lib/core_ext/object.rb

@@ -0,0 +1,5 @@
+Object.class_eval do
+  def try(method, *args)
+    self.send method, *args if self.respond_to?(method)
+  end
+end

data/lib/core_ext/string.rb

@@ -0,0 +1,19 @@
+module ActiveSupportMethods
+  def camelize
+    sub(/^([a-z])/) {$1.upcase}.gsub(/_([a-z])/) do
+      $1.upcase
+    end
+  end
+  
+  # Source
+  # http://github.com/rails/rails/blob/b600bf2cd728c90d50cc34456c944b2dfefe8c8d/activesupport/lib/active_support/inflector.rb
+  def underscore
+    gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+end
+
+String.send :include, ActiveSupportMethods unless String.new.respond_to?(:underscore)

data/lib/core_ext/symbol.rb

@@ -0,0 +1,15 @@
+# taken from ActiveSupport 2.3.2
+unless :to_proc.respond_to?(:to_proc)
+  class Symbol
+    # Turns the symbol into a simple proc, which is especially useful for enumerations. Examples:
+    #
+    #   # The same as people.collect { |p| p.name }
+    #   people.collect(&:name)
+    #
+    #   # The same as people.select { |p| p.manager? }.collect { |p| p.salary }
+    #   people.select(&:manager?).collect(&:salary)
+    def to_proc
+      Proc.new { |*args| args.shift.__send__(self, *args) }
+    end
+  end
+end

data/lib/core_ext/time.rb

@@ -0,0 +1,11 @@
+class Time
+  def to_json(*a)
+    %("#{strftime("%Y/%m/%d %H:%M:%S +0000")}")
+  end
+  
+  def self.json_create string
+    return nil if string.nil?
+    d = DateTime.parse(string).new_offset
+    self.utc(d.year, d.month, d.day, d.hour, d.min, d.sec)
+  end
+end

data/lib/couch_potato.rb

@@ -0,0 +1,40 @@
+require 'couchrest'
+require 'json'
+require 'json/add/core'
+require 'json/add/rails'
+
+require 'ostruct'
+
+
+module CouchPotato
+  Config = OpenStruct.new
+
+  # Returns a database instance which you can then use to create objects and query views. You have to set the CouchPotato::Config.database_name before this works.
+  def self.database
+    @@__database ||= Database.new(self.couchrest_database)
+  end
+
+  # Returns the underlying CouchRest database object if you want low level access to your CouchDB. You have to set the CouchPotato::Config.database_name before this works.
+  def self.couchrest_database
+    @@__couchrest_database ||= CouchRest.database(full_url_to_database)
+  end
+
+  private
+
+  def self.full_url_to_database
+    raise('No Database configured. Set CouchPotato::Config.database_name') unless CouchPotato::Config.database_name
+    if CouchPotato::Config.database_server
+      return "#{CouchPotato::Config.database_server}#{CouchPotato::Config.database_name}"
+    else
+      return "http://127.0.0.1:5984/#{CouchPotato::Config.database_name}"
+    end
+  end
+end
+
+require File.dirname(__FILE__) + '/core_ext/object'
+require File.dirname(__FILE__) + '/core_ext/time'
+require File.dirname(__FILE__) + '/core_ext/date'
+require File.dirname(__FILE__) + '/core_ext/string'
+require File.dirname(__FILE__) + '/core_ext/symbol'
+require File.dirname(__FILE__) + '/couch_potato/persistence'
+

data/lib/couch_potato/database.rb

@@ -0,0 +1,105 @@
+module CouchPotato
+  class Database
+    
+    class ValidationsFailedError < ::StandardError; end
+  
+    def initialize(couchrest_database)
+      @database = couchrest_database
+      begin
+        couchrest_database.info 
+      rescue RestClient::ResourceNotFound
+        raise "Database '#{couchrest_database.name}' does not exist."
+      end
+    end
+    
+    def view(spec)
+      results = CouchPotato::View::ViewQuery.new(database,
+        spec.design_document, spec.view_name, spec.map_function,
+        spec.reduce_function).query_view!(spec.view_parameters)
+      spec.process_results results
+    end
+  
+    def save_document(document)
+      return true unless document.dirty?
+      if document.new?
+        create_document document
+      else
+        update_document document
+      end
+    end
+    alias_method :save, :save_document
+  
+    def save_document!(document)
+      save_document(document) || raise(ValidationsFailedError.new(document.errors.full_messages))
+    end
+    alias_method :save!, :save_document!
+  
+    def destroy_document(document)
+      document.run_callbacks :before_destroy
+      document._deleted = true
+      database.delete_doc document.to_hash
+      document.run_callbacks :after_destroy
+      document._id = nil
+      document._rev = nil
+    end
+    alias_method :destroy, :destroy_document
+  
+    def load_document(id)
+      raise "Can't load a document without an id (got nil)" if id.nil?
+      begin
+        json = database.get(id)
+        instance = Class.const_get(json['ruby_class']).json_create json
+        instance.database = self
+        instance
+      rescue(RestClient::ResourceNotFound)
+        nil
+      end
+    end
+    alias_method :load, :load_document
+  
+    def inspect
+      "#<CouchPotato::Database>"
+    end
+  
+    private
+
+    def clean_hash(hash)
+      hash.each do |k,v|
+        hash.delete k unless v
+      end
+    end
+  
+    def create_document(document)
+      document.database = self
+      document.run_callbacks :before_validation_on_save
+      document.run_callbacks :before_validation_on_create
+      return unless document.valid?
+      document.run_callbacks :before_save
+      document.run_callbacks :before_create
+      res = database.save_doc clean_hash(document.to_hash)
+      document._rev = res['rev']
+      document._id = res['id']
+      document.run_callbacks :after_save
+      document.run_callbacks :after_create
+      true
+    end
+  
+    def update_document(document)
+      document.run_callbacks :before_validation_on_save
+      document.run_callbacks :before_validation_on_update
+      return unless document.valid?
+      document.run_callbacks :before_save
+      document.run_callbacks :before_update
+      res = database.save_doc clean_hash(document.to_hash)
+      document._rev = res['rev']
+      document.run_callbacks :after_save
+      document.run_callbacks :after_update
+      true
+    end
+  
+    def database
+      @database
+    end
+  
+  end
+end