couch_crumbs 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.0.1 2009-08-04
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,29 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/couch_crumbs.rb
+lib/core_ext/array.rb
+lib/couch_crumbs/server.rb
+lib/couch_crumbs/database.rb
+lib/couch_crumbs/query.rb
+lib/couch_crumbs/design.rb
+lib/couch_crumbs/document.rb
+lib/couch_crumbs/view.rb
+lib/couch_crumbs/json/all.json
+lib/couch_crumbs/json/children.json
+lib/couch_crumbs/json/design.json
+lib/couch_crumbs/json/simple.json
+script/console
+script/destroy
+script/generate
+spec/couch_crumbs_spec.rb
+spec/core_ext/array_spec.rb
+spec/couch_crumbs/database_spec.rb
+spec/couch_crumbs/design_spec.rb
+spec/couch_crumbs/document_spec.rb
+spec/couch_crumbs/server_spec.rb
+spec/couch_crumbs/view_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake

data/README.rdoc

@@ -0,0 +1,131 @@
+= couch_crumbs
+
+* http://github.com/lmlo/couch_crumbs
+
+== DESCRIPTION:
+
+A small library for basic CouchDB document-based apps.
+
+== FEATURES/PROBLEMS:
+
+- objects are JSON derived hashes 
+    (meaning properties support arrays, other hashes, dates, etc.)
+- named properties
+- timestamps (created_at/updated_at)
+- life-cycle callbacks
+- per-class database settings
+- simple "finder" views
+- advanced JavaScript views (in .json files)
+- document relationships
+
+== SYNOPSIS:
+
+  # Connect to a CouchDB server and set the default database
+  # :default_server is optional and defaults to http://couchdb.local/
+  # :default_database is also optional, and is used for classes
+  # that don't otherwise specify a database
+  CouchCrumbs::connect(:default_database => "example_database")
+  
+  @server = CouchCrumbs.default_server
+  
+  # Make sure we're running
+  @server.status
+  
+  # Create or retrieve a database
+  @database = Database.new(:name => "example_database")
+  
+  
+  # Create a class
+  class Person
+    
+    # Mixin document goodness
+    include CouchCrumbs::Document
+    
+    # Declare some properties
+    property :name
+    property :title
+    property :status
+
+    # Add :created_at and :updated_at properties
+    timestamps!
+    
+    child_document :address
+    
+  end
+  
+  class Address
+    
+    include CouchCrumbs::Document
+    
+    property :location
+    
+    timestamps!
+    
+    parent_document :person
+    
+  end
+  
+  # Instantiate a new Person document with properties
+  @person = Person.new(:name => "Steve")
+  # Manually set a property
+  @person.title = "CEO"
+  # Save the document (with #before_save and #after_save callbacks)
+  @person.save!
+  
+  
+  # Get a single document from the database
+  @steve = Person.get!(@person.id)
+
+
+  # Instantiate and save a new document in a single call (w/ callbacks)
+  @bill = Person.create!(:name => "Bill", :status => "Retired")
+  
+  # Destroy a document
+  @bill.destroy!
+
+
+  # Add an address to a person
+  @address = Address.create!(:location => "123 Main, Anytown USA")
+  
+  @steve.address = @address
+  
+  
+== LIMITATIONS:
+
+    - lacks support for attachments
+    - lacks support for show functions
+    - lacks support for many other aspects of CouchDB
+    - both sides of an association must be saved before being set
+    
+== REQUIREMENTS:
+
+    sudo gem install rest_client, json, english
+
+== INSTALL:
+
+    sudo gem install couch_crumbs
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 CouchCrumbs project.
+
+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/Rakefile

@@ -0,0 +1,37 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'couch_crumbs' do
+  self.developer 'Often Void, Inc.', 'admin@oftenvoid.com'
+  self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  self.rubyforge_name       = self.name # TODO this is default value
+  self.extra_deps         = [['english']]
+  self.version              = "0.0.1"
+end
+
+#require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]
+
+# Re-add the standard install task
+task :install => [:install_gem]
+
+# See: http://rspec.info/documentation/tools/rcov.html
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('coverage') do |t|
+  t.spec_opts = ['--format', 'specdoc', '-c']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', '/gems/,spec/']
+end

data/lib/core_ext/array.rb

@@ -0,0 +1,9 @@
+class Array
+
+  # Add a destroy all method to arrays
+  #
+  def destroy!
+    each { |o| o.destroy! }
+  end
+  
+end

data/lib/couch_crumbs/database.rb

@@ -0,0 +1,68 @@
+module CouchCrumbs
+  
+  # Direct representation of a CouchDB database (contains documents).
+  #
+  class Database
+    
+    include CouchCrumbs::Query
+    
+    DEFAULT_NAME = :couch_crumbs_database.freeze
+    
+    attr_accessor :server, :uri, :name, :status
+    
+    # Get or create a database
+    #
+    def initialize(opts = {})
+      self.server = opts[:server] || CouchCrumbs::default_server
+      self.name = (opts[:name] || DEFAULT_NAME).to_s
+      self.uri = File.join(server.uri, self.name)
+
+      begin
+        self.status = RestClient.get(uri)
+      rescue RestClient::ResourceNotFound
+        RestClient.put(uri, "{}")
+        retry
+      end      
+    end
+    
+    # Return an array of all documents
+    #
+    def documents(opts = {})
+      # Query the special built-in _all_docs view
+      query_docs(File.join(uri, "_all_docs"), opts).collect do |doc|
+        # Regular documents
+        if doc["crumb_type"]
+          # Eval the class (with basic filtering, i.e. trusting your database)
+          eval(doc["crumb_type"].gsub(/\W/i, '').capitalize!).get!(doc["_id"])
+          
+        elsif doc["_id"] =~ /^\_design\//
+          # Design docs
+          Design.get!(self, :id => doc["_id"])
+        else
+          # Ignore any other docs
+          warn "skipping unknown document: #{ doc }"
+          
+          nil
+        end
+      end
+    end
+          
+    # Return an array of only design documents
+    #
+    def design_documents
+      documents(:startkey => "_design/")
+    end
+    
+    # Delete database from the server
+    #
+    def destroy!
+      freeze
+      
+      result = JSON.parse(RestClient.delete(uri))
+            
+      result["ok"]
+    end
+
+  end
+  
+end

data/lib/couch_crumbs/design.rb

@@ -0,0 +1,129 @@
+module CouchCrumbs
+  
+  # Represents "special" design documents
+  #
+  class Design
+    
+    attr_accessor :raw, :uri
+
+    # Return a single design doc (from a specific database)
+    #
+    # ==== Parameters
+    # database<String>:: database instance
+    # opts => name<String>:: design doc name (i.e. "person")
+    # opts => id<String:: id of an existing design doc (i.e. "_design/person")
+    #
+    def self.get!(database, opts = {})
+      raise "opts must contain an :id or :name" unless (opts.has_key?(:id) || opts.has_key?(:name))
+      
+      # Munge the URI from an :id or :name
+      uri = File.join(database.uri, (opts[:id] || "_design/#{ opts[:name] }"))
+            
+      begin
+        # Try for an existing doc
+        result = RestClient.get(uri)
+        
+        design = Design.new(database, :json => result)
+      rescue RestClient::ResourceNotFound
+        # Or create a new one
+        design = Design.new(database, :name => File.basename(uri))
+        
+        design.save!
+      end
+      
+      design
+    end
+
+    # Instantiate a new design document
+    #
+    # ==== Parameters
+    # database<String>:: database instance
+    # opts => json<String>:: raw json to init from
+    # opts => name<String>:: design doc name (i.e. "person")
+    #
+    def initialize(database, opts = {})
+      if opts.has_key?(:json)
+        self.raw = JSON.parse(opts[:json])
+      elsif opts.has_key?(:name)        
+        # Read the design doc template
+        template = File.read(File.join(File.dirname(__FILE__), "json", "design.json"))
+
+        # Make our substitutions
+        template.gsub!(/\#design_id/, "_design/#{ opts[:name] }")
+      
+        # Init the raw hash
+        self.raw = JSON.parse(template)
+      else
+        raise "#new must have :json or a :name supplied"
+      end
+      
+      # Set out unique URI
+      self.uri = File.join(database.uri, id)
+    end
+    
+    # Return design doc id (typically "_design/resource")
+    #
+    def id
+      raw["_id"]
+    end
+  
+    # Return the revision
+    #
+    def rev
+      raw["_rev"]
+    end
+  
+    # Return the design name (id - prefix, i.e. "resource")
+    #
+    def name
+      raw["_id"].split("/").last
+    end
+    
+    # Save the design to the database
+    #
+    def save!
+      result = JSON.parse(RestClient.put(uri, raw.to_json))
+    
+      # update our stats
+      raw["_id"] = result["id"]
+      raw["_rev"] = result["rev"] 
+    
+      result["ok"]
+    end
+  
+    # Remove a design from the database
+    #
+    def destroy!
+      freeze
+            
+      result = JSON.parse(RestClient.delete(File.join(uri, "?rev=#{ rev }")))
+    
+      result["ok"]
+    end
+  
+    # Return all views of this design doc
+    # opts => supply a name to select a specific view
+    #
+    def views(opts = {})
+      if opts.has_key?(:name)
+        View.new(self, opts[:name].to_s, {:name => raw["views"][opts[:name].to_s]}.to_json)
+      else
+        raw["views"].collect do |key, value|
+          View.new(self, key.to_s, {key => value}.to_json)
+        end
+      end
+    end
+  
+    # Append a view to the view list
+    #
+    def add_view(view)
+      raise ArgumentError.new("view must be of kind View: #{ view }") unless view.kind_of?(View)
+      
+      raw["views"].merge!(view.raw)
+      
+      save!
+    end
+  
+  end
+  
+end