couchobject 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2007-09-05
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Johan Sørensen
+
+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/Manifest.txt

@@ -0,0 +1,41 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+TODO
+config/hoe.rb
+config/requirements.rb
+lib/couch_object.rb
+lib/couch_object/database.rb
+lib/couch_object/document.rb
+lib/couch_object/model.rb
+lib/couch_object/persistable.rb
+lib/couch_object/response.rb
+lib/couch_object/server.rb
+lib/couch_object/utils.rb
+lib/couch_object/version.rb
+lib/couch_object/view.rb
+log/debug.log
+script/console
+script/destroy
+script/generate
+setup.rb
+spec/database_spec.rb
+spec/document_spec.rb
+spec/integration/database_integration_spec.rb
+spec/integration/document_integration_spec.rb
+spec/integration/integration_helper.rb
+spec/model_spec.rb
+spec/persistable_spec.rb
+spec/response_spec.rb
+spec/rspec_autotest.rb
+spec/server_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+spec/utils_spec.rb
+spec/view_spec.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake

data/README.txt

@@ -0,0 +1,119 @@
+= CouchObject
+
+CouchObject is a set of classes to help you talk to CouchDb (http://couchdbwiki.com/) with Ruby.
+
+* Author: Johan Sørensen
+* Contact: johan (at) johansorensen DOT com
+* Home: http://rubyforge.org/projects/couchobject/
+* Source (Git): http://repo.or.cz/w/couchobject.git
+ 
+== Creating, opening and deleting databases
+
+CouchObject::Database is the first interaction point to your CouchDb. Creating a CouchDb database:
+
+	>> CouchObject::Database.create!("http://localhost:8888", "mydb")
+	=> {"ok"=>true}
+	>> CouchObject::Database.all_databases("http://localhost:8888")
+	=> ["couchobject", "couchobject_test", "foo", "mydb"]
+	>> db = CouchObject::Database.open("http://localhost:8888/mydb")
+	=> #<CouchObject::Database:0x642fa8 @server=#<CouchObject::Server:0x642ef4 @connection=#<Net::HTTP localhost:8888 open=false>, @port=8888, @uri=#<URI::HTTP:0x321612 URL:http://localhost:8888>, @host="localhost">, @uri="http://localhost:8888", @dbname="mydb">
+	>> db.name
+	=> "mydb"
+	>> CouchObject::Database.delete!("http://localhost:8888", "mydb")
+	=> {"ok"=>true}
+	>> CouchObject::Database.all_databases("http://localhost:8888").include?("mydb")
+	=> false
+		
+=== Interacting with the database
+
+	>> db.get("_all_docs")
+	=> #<CouchObject::Response:0x14ed364 @response=#<Net::HTTPOK 200 OK readbody=true>, @parsed_body={"rows"=>[], "view"=>"_all_docs"}>
+		
+Issueing CouchObject::Database#get, CouchObject::Database#post, CouchObject::Database#put and CouchObject::Database#delete requests will return a CouchObject::Response object
+		
+	>> db.get("_all_docs").body
+	=> "{\"view\":\"_all_docs\", \"rows\":[\n\n]}"
+	>> db.get("_all_docs").parsed_body
+	=> {"rows"=>[], "view"=>"_all_docs"}
+	>> db.post("", JSON.unparse({"foo" => "bar"}))
+	=> #<CouchObject::Response:0x14d7780 @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F", "ok"=>true}>
+	>> db.get("_all_docs").parsed_body
+	=> {"rows"=>[{"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F"}], "view"=>"_all_docs"}
+	>> db.get("1206189E4496409DAD3818D241F5478F").parsed_body
+	=> {"_rev"=>-992681820, "_id"=>"1206189E4496409DAD3818D241F5478F", "foo"=>"bar"}
+	>> db.delete("1206189E4496409DAD3818D241F5478F").parsed_body
+	=> {"_rev"=>548318611, "ok"=>true}
+	>> db.get("_all_docs").parsed_body
+	=> {"rows"=>[], "view"=>"_all_docs"}
+		
+== The Document object
+
+CouchObject::Document wraps a few things in a nice api. In particular you can use it if you don't want to deal with hashes all the time (similar to ActiveRecord and so on):
+
+	>> doc = CouchObject::Document.new({ "foo" => [1,2], "bar" => true  })
+	=> #<CouchObject::Document:0x14a7224 @id=nil, @attributes={"foo"=>[1, 2], "bar"=>true}, @revision=nil>
+	>> doc["foo"]
+	=> [1, 2]
+	>> doc.foo
+	=> [1, 2]
+	>> doc.bar
+	=> true
+	>> doc.bar?
+	=> true
+		
+You can also save a document to the database:
+
+	>> doc.new?
+	=> true
+	>> doc.save(db)
+	=> #<CouchObject::Response:0x149f358 @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>2030456697, "_id"=>"CAEADDC895AC4D506542A3796CCA355D", "ok"=>true}>
+	>> doc.id
+	=> "CAEADDC895AC4D506542A3796CCA355D"
+		
+Since CouchObject::Database#get returns a CouchObject::Response object we can convert it into a Document instance easily with CouchObject::Database#to_document:
+
+	>> response = db.get(doc.id)
+	=> #<CouchObject::Response:0x1498b98 @response=#<Net::HTTPOK 200 OK readbody=true>, @parsed_body={"_rev"=>2030456697, "_id"=>"CAEADDC895AC4D506542A3796CCA355D", "foo"=>[1, 2], "bar"=>true}>
+	>> the_doc_we_just_saved = response.to_document
+	=> #<CouchObject::Document:0x148415c @id="CAEADDC895AC4D506542A3796CCA355D", @attributes={"foo"=>[1, 2], "bar"=>true}, @revision=2030456697>
+	>> the_doc_we_just_saved.foo
+	=> [1, 2]
+	>> doc.foo = "quux"
+	=> "quux"
+	>> doc.save(db)
+	=> #<CouchObject::Response:0x4b0adc @response=#<Net::HTTPCreated 201 Created readbody=true>, @parsed_body={"_rev"=>1670064786, "_id"=>"B4077269D2DF8433D145DC0702B9791C", "ok"=>true}>
+
+
+== CouchObject::Persistable
+
+It all started with this module, it maps ruby objects to CouchDb documents, using two mapping methods. It's highly experimental and may go away n future releases
+
+    gem "couchobject"
+    require "couch_object"
+    class Bike
+      include CouchObject::Persistable
+
+      def initialize(wheels)
+        @wheels = wheels
+      end
+      attr_accessor :wheels
+
+      def to_couch
+        {:wheels => @wheels}
+      end
+
+      def self.from_couch(attributes)
+        new(attributes["wheels"])
+      end
+    end
+
+By including the CouchObject::Persistable and defining two methods on our class we specify how we should serialize and deserialize our object to and from a CouchDb:
+
+    >> bike_4wd = Bike.new(4)
+    => #<Bike:0x6a0a68 @wheels=4>
+    >> bike_4wd.save("http://localhost:8888/couchobject")
+    => {"_rev"=>1745167971, "_id"=>"6FA2AFB623A93E0E77DEAAF59BB02565", "ok"=>true}
+    >> bike = Bike.get_by_id("http://localhost:8888/couchobject", bike_4wd.id)
+    => #<Bike:0x64846c @wheels=4>
+    
+

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/TODO

@@ -0,0 +1,8 @@
+- flat namespace for object attributes? (instead of the "attributes" key)
+- Query/View API
+- better handling of document id, including setting a custom ones
+- Database#filter for filtering documents with Ruby (with some ruby2js or RubyToRuby magic)
+- Expand on View class
+- A Document object
+
+- CouchObject::Model for more domain specific/clearer way to model Couch docs in ruby

data/config/hoe.rb

@@ -0,0 +1,73 @@
+require 'couch_object/version'
+
+AUTHOR = 'Johan Sørensen'  # can also be an array of Authors
+EMAIL = "johan@johansorensen.com"
+DESCRIPTION = "CouchObject is a library that maps ruby objects to CouchDb documents"
+GEM_NAME = 'couchobject' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'couchobject' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = CouchObject::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'couch_object documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["spec/**/spec_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\\n\\n")
+  # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  p.extra_deps = [ 
+    ["json", ">= 1.1.1"] 
+  ] 
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'couch_object'

data/lib/couch_object.rb

@@ -0,0 +1,27 @@
+$KCODE = 'u'
+require 'jcode'
+
+require "rubygems"
+gem "json"
+begin
+  require "json/ext"
+rescue LoadError
+  $stderr.puts "C version of json (fjson) could not be loaded, using pure ruby one"
+  require "json/pure"
+end
+require 'json/add/core'
+
+$:.unshift File.dirname(__FILE__)
+
+require "couch_object/utils"
+require "couch_object/document"
+require "couch_object/response"
+require "couch_object/server"
+require "couch_object/database"
+require "couch_object/view"
+require "couch_object/persistable"
+require "couch_object/model"
+
+module CouchObject
+  
+end

data/lib/couch_object/database.rb

@@ -0,0 +1,115 @@
+module CouchObject
+  # A CouchDb database object
+  class Database
+    # Create a new database at +uri+ with the name if +dbname+
+    def self.create!(uri, dbname)
+      server = Server.new(uri)
+      response = Response.new(server.put("/#{dbname}", "")).parse
+      response.parsed_body
+    end
+    
+    # Delete the database at +uri+ with the name if +dbname+
+    def self.delete!(uri, dbname)
+      server = Server.new(uri)
+      response = Response.new(server.delete("/#{dbname}")).parse
+      response.parsed_body
+    end
+    
+    # All databases at +uri+
+    def self.all_databases(uri)
+      # FIXME: Move to Server ?
+      server = Server.new(uri)
+      resp = server.get("/_all_dbs")
+      response = Response.new(resp).parse
+      response.parsed_body
+    end
+    
+    # Open a connection to the database at +uri+, where +uri+ is a full uri
+    # like: http://localhost:8888/foo
+    def self.open(uri)
+      uri = URI.parse(uri)
+      server_uri = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      new(server_uri, uri.path.tr("/", ""))
+    end
+    
+    def initialize(uri, dbname)
+      @uri = uri
+      @dbname = dbname
+      @server = Server.new(@uri)
+    end
+    attr_accessor :server
+    
+    # The full url of this database, eg http://localhost:8888/foo
+    def url
+      Utils.join_url(@uri, @dbname).to_s
+    end
+    
+    # Name of this database
+    def name
+      @dbname.dup
+    end
+    
+    # Send a GET request to the +path+ which is relative to the database path
+    # so calling with with "bar" as the path in the "foo_db" database will call
+    # http://host:port/foo_db/bar.
+    # Returns a Response object
+    def get(path)
+      Response.new(@server.get("/#{Utils.join_url(@dbname, path)}")).parse
+    end
+    
+    # Send a POST request to the +path+ which is relative to the database path
+    # so calling with with "bar" as the path in the "foo_db" database will call
+    # http://host:port/foo_db/bar. The post body is the +payload+
+    # Returns a Response object
+    def post(path, payload)
+      Response.new(@server.post("/#{Utils.join_url(@dbname, path)}", payload)).parse
+    end
+    
+    # Send a PUT request to the +path+ which is relative to the database path
+    # so calling with with "bar" as the path in the "foo_db" database will call
+    # http://host:port/foo_db/bar. The put body is the +payload+
+    # Returns a Response object
+    def put(path, payload="")
+      Response.new(@server.put("/#{Utils.join_url(@dbname, path)}", payload)).parse
+    end
+    
+    # Send a DELETE request to the +path+ which is relative to the database path
+    # so calling with with "bar" as the path in the "foo_db" database will call
+    # http://host:port/foo_db/bar.
+    # Returns a Response object
+    def delete(path)
+      Response.new(@server.delete("/#{Utils.join_url(@dbname, path)}")).parse
+    end
+    
+    # Get a document by id
+    def [](id)
+      get(id.to_s)
+    end
+    
+    # Get a document by +id+, optionally a specific +revision+ too
+    def document(id, revision=nil)
+      if revision
+        get("#{id}?rev=#{revision}")
+      else
+        get(id.to_s)
+      end
+    end
+    
+    # Returns an Array of all the documents in this db
+    def all_documents
+      resp = Response.new(get("_all_docs")).parse
+      resp.to_document.rows
+    end
+    
+    # Queries the database with the block (using a temp. view)
+    def filter(&blk)
+      
+    end
+    
+    def views(view_name)
+      view = View.new(self, view_name)
+      view.query
+    end
+    
+  end
+end

data/lib/couch_object/document.rb

@@ -0,0 +1,106 @@
+module CouchObject
+  # Represents a CouchDb document
+  class Document    
+    include Enumerable
+    
+    # initializes a new document object with +attributes+ as 
+    # the document values
+    def initialize(attributes={})
+      @attributes = attributes.dup
+      @id = @attributes.delete("_id")
+      @revision = @attributes.delete("_rev")
+    end
+    attr_accessor :attributes, :id, :revision
+    
+    # Sets the id to +new_id+
+    # (Only for internal use really, but public nevertheless)
+    def id=(new_id)
+      if new? 
+        attributes["_id"] = @id = new_id
+      else
+        nil
+      end
+    end
+    
+    # is this a new document? 
+    def new?
+      @id.nil? && @revision.nil?
+    end
+    
+    # yields each document attribute
+    def each(&blk)
+      @attributes.each(&blk)
+    end
+    
+    # Saves this document to the +database+
+    def save(database)
+      new? ? create(database) : update(database)
+    end
+    
+    # Look up an attribute by +key+
+    def [](key)
+      attributes[key]
+    end
+    
+    # Set an attributes by +key+ to +value+
+    def []=(key, value)
+      attributes[key] = value
+    end
+    
+    # is the attribute +key+ in this document?
+    def has_key?(key)
+      attributes.has_key?(key)
+    end
+
+    # is the attribute +key+ in this document?    
+    def respond_to?(meth)
+      method_name = meth.to_s
+      
+      if has_key?(method_name)
+        return true
+      elsif %w[ ? = ].include?(method_name[-1..-1]) && has_key?(method_name[0..-2])
+        return true
+      end
+      
+      super
+    end
+    
+    # Converts the Document to a JSON representation of its attributes
+    def to_json(extra={})
+      if id.nil?
+        opts = {}.merge(extra)
+      else
+        opts = {"_id" => id}.merge(extra)
+      end
+      attributes.merge(opts).to_json
+    end
+    
+    protected
+      def create(database)
+        response = database.post("", self.to_json)
+        # TODO error handling
+        @id = response.to_document.id
+        @revision = response.to_document.revision
+        response
+      end
+      
+      def update(database)
+        response = database.put(id, self.to_json("_rev" => revision))
+        # TODO error handling
+      end
+      
+    private
+      def method_missing(method_symbol, *arguments)
+        method_name = method_symbol.to_s
+      
+        case method_name[-1..-1]
+          when "="
+            self[method_name[0..-2]] = arguments.first
+          when "?"
+            self[method_name[0..-2]] == true
+          else
+            has_key?(method_name) ? self[method_name] : super
+        end
+      end
+  end
+end