couch_crumbs 0.0.1

data/lib/couch_crumbs/document.rb

@@ -0,0 +1,471 @@
+require "facets/string"
+require "english/inflect"
+
+module CouchCrumbs
+  
+  # Document is an abstract base module that you mixin to your own classes
+  # to gain access to CouchDB document instances.
+  #
+  module Document
+    
+    module InstanceMethods
+      
+      include CouchCrumbs::Query
+      
+      # Return the class-based database
+      def database
+        self.class.database
+      end
+      
+      # Return document id (typically a UUID)
+      #
+      def id
+        raw["_id"]
+      end
+      
+      # Set the document id
+      def id=(new_id)
+        raise "only new documents may set an id" unless new_document?
+        
+        raw["_id"] = new_id
+      end
+      
+      # Return document revision
+      #
+      def rev
+        raw["_rev"]
+      end
+      
+      # Return the CouchCrumb document type
+      #
+      def crumb_type
+        raw["crumb_type"]
+      end
+      
+      # Save a document to a database
+      #
+      def save!
+        raise "unable to save frozen documents" if frozen?
+        
+        # Before Callback
+        before_save
+        
+        # Update timestamps
+        raw["updated_at"] = Time.now if self.class.properties.include?(:updated_at)
+        
+        # Save to the DB
+        result = JSON.parse(RestClient.put(uri, raw.to_json))
+        
+        # Update ID and Rev properties
+        raw["_id"] = result["id"]
+        raw["_rev"] = result["rev"]
+        
+        # After callback
+        after_save
+        
+        result["ok"]
+      end
+    
+      # Update and save the named properties
+      #
+      def update_attributes!(attributes = {})
+        attributes.each_pair do |key, value|
+          raw[key.to_s] = value
+        end
+        
+        save!
+      end
+      
+      # Return true prior to document being saved
+      #
+      def new_document?
+        raw["_rev"].eql?(nil)
+      end
+      
+      # Remove document from the database
+      #
+      def destroy!
+        before_destroy
+
+        freeze
+        
+        # destruction status
+        status = nil
+        
+        # Since new documents haven't been saved yet, and frozen documents
+        # *can't* be saved, simply return true here.
+        if new_document?
+          status = true
+        else
+          result = JSON.parse(RestClient.delete(File.join(uri, "?rev=#{ rev }")))
+  
+          status = result["ok"]
+        end
+        
+        after_destroy
+        
+        status
+      end
+      
+      # Hook called after a document has been initialized
+      #            
+      def after_initialize
+        nil
+      end
+      
+      # Hook called during #create! before a document is #saved!
+      #
+      def before_create
+        nil
+      end
+
+      # Hook called during #create! after a document has #saved!
+      #
+      def after_create
+        nil
+      end
+
+      # Hook called during #save! before a document has #saved!
+      #
+      def before_save
+        nil
+      end
+
+      # Hook called during #save! after a document has #saved!
+      #
+      def after_save
+        nil
+      end
+
+      # Hook called during #destroy! before a document has been destroyed
+      #
+      def before_destroy
+        nil
+      end
+
+      # Hook called during #destroy! after a document has been destroyed
+      #
+      def after_destroy
+        nil
+      end
+      
+    end
+    
+    module ClassMethods
+      
+      include CouchCrumbs::Query
+      
+      # Return the useful portion of module/class type
+      # @todo cache crumb_type on the including base class
+      #
+      def crumb_type
+        class_variable_get(:@@crumb_type)
+      end
+      
+      # Return the database to use for this class
+      #
+      def database
+        class_variable_get(:@@database)
+      end
+      
+      # Set the database that documents of this type will use (will create
+      # a new database if name does not exist)
+      #
+      def use_database(name)
+        class_variable_set(:@@database, Database.new(:name => name))
+      end
+      
+      # Return all named properties for this document type
+      #
+      def properties
+        class_variable_get(:@@properties)
+      end
+      
+      # Add a named property to a document type
+      #
+      def property(name, opts = {})
+        name = name.to_sym
+        properties << name
+                
+        class_eval do
+          # getter
+          define_method(name) do
+            raw[name.to_s]
+          end
+          # setter
+          define_method("#{ name }=".to_sym) do |new_value|
+            raw[name.to_s] = new_value
+          end
+        end
+      end
+      
+      # Append default timestamps as named properties
+      # @todo - add :created_at as a read-only property
+      #
+      def timestamps!
+        [:created_at, :updated_at].each do |name|
+          property(name)
+        end
+      end
+      
+      # Return the design doc for this class
+      #
+      def design_doc
+        Design.get!(database, :name => crumb_type)
+      end
+      
+      # Return an array of all views for this class
+      #
+      def views(opts = {})
+        design_doc.views(opts)
+      end
+            
+      # Create a default view on a given property, returning documents
+      #
+      def doc_view(*args)
+        # Get the design doc for this document type
+        design = design_doc
+        
+        # Create simple views for the named properties
+        args.each do |prop|
+          view = View.create!(design, prop.to_s, View.simple_json(crumb_type, prop))
+                    
+          self.class.instance_eval do
+            define_method("by_#{ prop }".to_sym) do |opts|
+              query_docs(view.uri, {:descending => false}.merge(opts||{})).collect do |doc|
+                if doc["crumb_type"]
+                  new(:hash => doc)
+                else
+                  warn "skipping unknown document: #{ document }"
+                end
+              end
+            end
+          end
+        end
+        
+        nil
+      end
+      
+      # Create an advanced view from a given :template
+      #
+      def custom_view(opts = {})
+        raise ArgumentError.new("opts must contain a :name key") unless opts.has_key?(:name)
+        raise ArgumentError.new("opts must contain a :template key") unless opts.has_key?(:template)
+                
+        view = View.create!(design_doc, opts[:name], View.advanced_json(opts[:template], opts))
+                
+        self.class.instance_eval do
+          define_method("#{ opts[:name] }".to_sym) do
+            if view.has_reduce?
+              query_values(view.uri)
+            else
+              query_docs(view.uri, :descending => false).collect do |doc|
+                if doc["crumb_type"]
+                  new(:hash => doc)
+                else
+                  warn "skipping unknown document: #{ doc }"
+                end
+              end
+            end
+          end
+        end
+      end
+      
+      # Create and save a new document
+      # @todo - add before_create and after_create callbacks
+      #
+      def create!(opts = {})
+        document = new(opts)
+        
+        yield document if block_given?
+        
+        document.before_create
+        
+        document.save!
+        
+        document.after_create
+        
+        document
+      end
+      
+      # Return a specific document given an exact id
+      #
+      def get!(id)
+        raise ArgumentError.new("id must not be blank") if id.empty? or id.nil?
+        
+        json = RestClient.get(File.join(database.uri, id))
+
+        result = JSON.parse(json)
+
+        document = new(
+          :json => json
+        )
+
+        document
+      end
+      
+      # Return an array of all documents of this type
+      #
+      def all(opts = {})
+        # Add the #all method
+        view = design_doc.views(:name => "all")
+      
+        query_docs("#{ view.uri }".downcase, opts).collect do |doc|          
+          if doc["crumb_type"]
+            get!(doc["_id"])
+          else
+            warn "skipping unknown document: #{ doc }"
+            
+            nil
+          end
+        end
+      end
+      
+      # Like parent_document :person
+      #
+      def parent_document(model, opts = {})
+        model = model.to_s.downcase
+        
+        property("#{ model }_parent_id")
+        
+        begin
+          parent_class = eval(model.modulize)
+        rescue
+          require "#{ model.methodize }.rb"
+          retry
+        end
+                
+        self.class_eval do
+          define_method(model.to_sym) do
+            parent_class.get!(raw["#{ model }_parent_id"])
+          end
+        
+          define_method("#{ model }=".to_sym) do |new_parent|
+            raise ArgumentError.new("parent documents must be saved before children") if new_parent.new_document?
+        
+            raw["#{ model }_parent_id"] = new_parent.id 
+          end
+        end
+        
+        nil
+      end
+          
+      # Like child_document :address
+      #
+      def child_document(model, opts = {})
+        model = model.to_s.downcase
+        
+        property("#{ model }_child_id")
+        
+        begin
+          child_class = eval(model.modulize)
+        rescue
+          require "#{ model.methodize }.rb"
+          retry
+        end
+        
+        self.class_eval do
+          define_method(model.to_sym) do
+            child_class.get!(raw["#{ model }_child_id"])
+          end
+        
+          define_method("#{ model }=".to_sym) do |new_child|
+            raise ArgumentError.new("parent documents must be saved before adding children") if new_document?
+            
+            raw["#{ model }_child_id"] = new_child.id 
+          end
+        end
+        
+        nil
+      end
+      
+      # Like has_many :projects
+      #
+      def child_documents(model, opts = {})
+        model = model.to_s.downcase
+        
+        begin
+          child_class = eval(model.modulize)
+        rescue
+          require "#{ model.methodize }.rb"
+          retry
+        end
+        
+        # Add a view to the child class
+        View.create!(child_class.design_doc, "#{ crumb_type }_parent_id", View.advanced_json(File.join(File.dirname(__FILE__), "json", "children.json"), :parent => self.crumb_type, :child => model))
+        
+        # Add a method to access the model's new view
+        self.class_eval do
+          define_method(English::Inflect.plural(model)) do
+            query_docs(eval(model.modulize).views(:name => "#{ self.class.crumb_type }_parent_id").uri).collect do |doc|
+              child_class.get!(doc["_id"])
+            end
+          end
+          
+          define_method("add_#{ model }") do |new_child|
+            new_child.send("#{ self.class.crumb_type }_parent_id=", self.id)
+            new_child.save!
+          end
+        end
+        
+        nil
+      end
+      
+    end
+    
+    # Mixin our document methods
+    #
+    def self.included(base)
+      base.send(:include, InstanceMethods)
+      base.extend(ClassMethods)
+      # Override #initialize
+      base.class_eval do
+        
+        # Set class variables
+        class_variable_set(:@@crumb_type, base.name.split('::').last.downcase)
+        class_variable_set(:@@database, CouchCrumbs::default_database)
+        class_variable_set(:@@properties, [])
+        
+        # Accessors
+        attr_accessor :uri, :raw
+        
+        # Override document #initialize
+        def initialize(opts = {})
+          raise ArgumentError.new("opts must be hash-like: #{ opts }") unless opts.respond_to?(:[])
+
+          # If :json is present, we just parse it as an existing document
+          if opts[:json]
+            self.raw = JSON.parse(opts[:json])
+          elsif opts[:hash]
+            self.raw = opts[:hash]
+          else
+            self.raw = {}
+            
+            # Init special values
+            raw["_id"] = opts[:id] || database.server.uuids
+            raw["_rev"] = opts[:rev] unless opts[:rev].eql?(nil)
+            raw["crumb_type"] = self.class.crumb_type
+            raw["created_at"] = Time.now if self.class.properties.include?(:created_at)
+            
+            # Init named properties
+            opts.each_pair do |name, value|
+              send("#{ name }=", value)
+            end
+          end
+          
+          # This specific CouchDB document URI
+          self.uri = File.join(database.uri, id)
+          
+          # Callback
+          after_initialize
+        end
+        
+      end
+      
+      # Create an advanced "all" view
+      View.create!(base.design_doc, "all", View.advanced_json(File.join(File.dirname(__FILE__), "json", "all.json"), :crumb_type => base.crumb_type))
+    end
+    
+  end
+  
+end

data/lib/couch_crumbs/json/all.json

@@ -0,0 +1,5 @@
+{ 
+  "all": {
+    "map": "function(doc) { if (doc.crumb_type == '#crumb_type') {emit(null, doc); } }"
+  }
+}

data/lib/couch_crumbs/json/children.json

@@ -0,0 +1,5 @@
+{ 
+    "#parent_parent_id": { 
+        "map": "function(doc) {  if(doc.crumb_type == '#child'){ emit(doc['#parent_parent_id'], doc); }}" 
+    }
+}

data/lib/couch_crumbs/json/design.json

@@ -0,0 +1,5 @@
+{
+   "_id": "#design_id",
+   "language": "javascript",
+   "views": {}
+}

data/lib/couch_crumbs/json/simple.json

@@ -0,0 +1,5 @@
+{ 
+  "#name": {
+    "map": "function(doc) { if (doc.crumb_type == '#crumb_type') { emit(doc['#property'], doc); } }"
+  } 
+}

data/lib/couch_crumbs/query.rb

@@ -0,0 +1,95 @@
+module CouchCrumbs
+  
+  # Mixin to query databases and views 
+  module Query
+    
+    # Query an URI with opts and return an array of ruby hashes 
+    # representing JSON docs.
+    #
+    # === Parameters (see: http://wiki.apache.org/couchdb/HTTP_view_API)
+    # key=keyvalue
+    # startkey=keyvalue
+    # startkey_docid=docid
+    # endkey=keyvalue
+    # endkey_docid=docid
+    # limit=max rows to return This used to be called "count" previous to Trunk SVN r731159
+    # stale=ok
+    # descending=true
+    # skip=number of rows to skip (very slow)
+    # group=true Version 0.8.0 and forward
+    # group_level=int
+    # reduce=false Trunk only (0.9)
+    # include_docs=true Trunk only (0.9)
+    #
+    def query_docs(uri, opts = {})
+      opts = {} unless opts
+      
+      # Build our view query string
+      query_params = "?"
+      
+      if opts.has_key?(:key)
+        query_params << %(key="#{ opts.delete(:key) }")
+      elsif opts.has_key?(:startkey)
+        query_params << %(startkey="#{ opts.delete(:startkey) }")
+        if opts.has_key?(:startkey_docid)
+          query_params << %(&startkey_docid="#{ opts.delete(:startkey_docid) }")
+        end
+        if opts.has_key?(:endkey)
+          query_params << %(&endkey="#{ opts.delete(:endkey) }")
+          if opts.has_key?(:endkey_docid)
+            query_params << %(&endkey_docid="#{ opts.delete(:endkey_docid) }")
+          end
+        end
+      end
+      
+      # Escape the quoted JSON query keys
+      query_params = URI::escape(query_params)
+      
+      # Default options
+      (@@default_options ||= {
+        :limit            => 25,    # limit => 0 will return metadata only
+        :stale            => false, 
+        :descending       => false,
+        :skip             => nil,   # The skip option should only be used with small values 
+        :group            => nil,
+        :group_level      => nil,
+        :include_docs     => true
+      }).merge(opts).each do |key, value|
+        query_params << %(&#{ key }=#{ value }) if value
+      end
+      
+      query_string = "#{ uri }#{ query_params }"
+      
+      # Query the server and return an array of documents (will include design docs)
+      JSON.parse(RestClient.get(query_string))["rows"].collect do |row|
+        row["doc"]
+      end
+    end
+    
+    # For querying views with a reduce function or other value-based views
+    # opts => :raw will return the raw view result, otherwise we try to
+    #   extract a value
+    #
+    def query_values(uri, opts = {})
+      query_params = "?"
+      
+      opts.each do |key, value|
+        query_params << %(&#{ key }=#{ value }) if value
+      end
+      
+      query_string = "#{ uri }#{ query_params }"
+      
+      result = JSON.parse(RestClient.get(query_string))
+      
+      # Extract "value" key/value
+      if opts[:raw]
+        result
+      else
+        result["rows"].first["value"]
+      end
+    end
+    
+
+  end
+  
+end

data/lib/couch_crumbs/server.rb

@@ -0,0 +1,45 @@
+require "rest_client"
+require "json"
+
+module CouchCrumbs
+  
+  # Represents an instance of a live running CouchDB server
+  #
+  class Server
+
+    DEFAULT_URI = "http://couchdb.local:5984".freeze
+    
+    attr_accessor :uri, :status
+
+    # Create a new instance of Server
+    #
+    def initialize(opts = {})
+      self.uri = opts[:uri] || DEFAULT_URI
+
+      self.status = JSON.parse(RestClient.get(self.uri))
+    end
+    
+    # Return an array of databases
+    # @todo - add a :refresh argument with a 10 second cache of the DBs
+    #
+    def databases
+      JSON.parse(RestClient.get(File.join(self.uri, "_all_dbs"))).collect do |database_name|
+        Database.new(:name => database_name)
+      end
+    end
+    
+    # Return a new random UUID for use in documents
+    #
+    def uuids(count = 1)
+      uuids = JSON.parse(RestClient.get(File.join(self.uri, "_uuids?count=#{ count }")))["uuids"]
+      
+      if count > 1
+        uuids
+      else
+        uuids.first
+      end
+    end
+    
+  end
+  
+end

data/lib/couch_crumbs/view.rb

@@ -0,0 +1,73 @@
+module CouchCrumbs
+  
+  # Based on the raw JSON that make up each view in a design doc.
+  #
+  class View
+    
+    include CouchCrumbs::Query
+    
+    attr_accessor :raw, :uri, :name
+  
+    # Return or create a new view object
+    #
+    def initialize(design, name, json)
+      self.name = name
+      self.uri = File.join(design.uri, "_view", name)
+      self.raw = JSON.parse(json)
+    end
+    
+    # Create a new view and save the containing design doc
+    def self.create!(design, name, json)
+      view = new(design, name, json)
+      
+      design.add_view(view)
+      
+      design.save!
+      
+      view
+    end
+    
+    # Return a view as a JSON hash
+    #
+    def self.simple_json(type, property)
+      # Read the 'simple' template (stripping newlines and tabs)
+      template = File.read(File.join(File.dirname(__FILE__), "json", "simple.json")).gsub!(/(\n|\r|\t)/, '')
+    
+      template.gsub!(/\#name/, property.to_s.downcase)
+      template.gsub!(/\#crumb_type/, type.to_s)
+      template.gsub!(/\#property/, property.to_s.downcase)
+      
+      template
+    end
+    
+    # Return an advanced view as a JSON hash 
+    # template => path to a .json template
+    # opts => options to gsub into the template
+    #
+    def self.advanced_json(template, opts = {})
+      # Read the given template (strip newlines to avoid JSON parser errors)
+      template = File.read(template).gsub(/(\n|\r|\t|\s{2,})/, '')
+      
+      # Sub in any opts
+      opts.each do |key, value|
+        template.gsub!(/\##{ key }/, value.to_s)
+      end
+      
+      template
+    end
+    
+    # Return a unique hash of the raw json
+    #
+    def hash
+      raw.hash
+    end
+    
+    # Return true if this view will reduce values
+    #
+    def has_reduce?      
+      raw[raw.keys.first].has_key?("reduce")
+    end
+    
+  end
+
+end