mattly-exegesis 0.2.0 → 0.2.1

data/README.rdoc

@@ -9,15 +9,9 @@ A CouchDB ODM (Object/Document Mapper) in Ruby.
 
 == Features:
 
-Encourages per-"Account" databases. Actually, does not even currently provide a way to do a 
-"singleton" or global database, however this is planned. Since a given class (say, "Article") 
-cannot know what database it is supposed to get/search from you cannot do classical class-based 
-finders such as "Article.find('value')".
+Encourages per-"Account" databases. Actually, does not even currently provide a way to do a "singleton" or global database, however this is planned. Since a given class (say, "Article") cannot know what database it is supposed to get/search from you cannot do classical class-based finders such as "Article.find('value')". While it might be possible to pass in a database to use for some class-wide view, Exegesis takes the opinion that this is bad design for couchdb for the reasons that views may return multiple document types other than the desired class, and that views should be scoped to objects that mixin the database accessors.
 
-CouchDB is table-less, and Exegesis's design reflects this. In CouchDB, Documents are retrieved 
-by their unique id, or can be queried from a view function in a design document. Exegesis provides
-tools to aid this. Additionally, since view functions can be used for map/reduce computations against
-your documents, Exegesis helps you get non-document data out of your views.
+CouchDB is table-less, and Exegesis's design reflects this. In CouchDB, Documents are retrieved by their unique id, or can be queried from a view function in a design document. Exegesis provides tools to aid this. Additionally, since view functions can be used for map/reduce computations against your documents, Exegesis helps you get non-document data out of your views.
 
 == Examples:
 
@@ -64,4 +58,6 @@ For running the tests:
 * Test::Unit (you got it)
 * Context (http://github.com/jeremymcanally/context, can install from github gems)
 * Matchy (http://github.com/jeremymcanally/matchy, github gem version out of date; clone, build & install for now)
-* Zebra (http://github.com/giraffesoft/zerba, depends on jeremymcanally-matchy, which is out of date; clone, build & install for now)
+* Zebra (http://github.com/giraffesoft/zerba, depends on jeremymcanally-matchy, which is out of date; clone, build & install for now)
+
+The test suite creates and destroys a database for each test that requires access to the database. This is slow, and the test suite may take some time to run. However, I would rather the test suite be slow and accurate than quick and full of mocking.

data/Rakefile

@@ -0,0 +1,32 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "exegesis"
+    s.summary = "TODO"
+    s.email = "matt@flowerpowered.com"
+    s.homepage = "http://github.com/mattly/exegesis"
+    s.description = "A Document <> Object Mapper for CouchDB Documents"
+    s.authors = ["Matt Lyon"]
+    s.add_dependency('rest-client', '>= 0.12.6')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'test-gem'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

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

data/lib/exegesis/database.rb

@@ -19,24 +19,35 @@ module Exegesis
         end
       end
       
-      # A hash mapping design names to class names.
-      def designs
-        @designs ||= {}
-      end
-      
       # declare a design document for this database. Creates a new class and yields a given block to the class to
       # configure the design document and declare views; See Class methods for Exegesis::Design
       def design design_name, opts={}, &block
         klass_name = "#{design_name.to_s.capitalize}Design"
         klass = const_set(klass_name, Class.new(Exegesis::Design))
-        designs[design_name] = klass
         klass.design_directory = opts[:directory] || self.designs_directory + design_name.to_s
         klass.design_name = opts[:name] || design_name.to_s
         klass.compose_canonical
         klass.class_eval &block
         define_method design_name do
-          @designs ||= {}
-          @designs[design_name] ||= klass.new(self)
+          @exegesis_designs ||= {}
+          @exegesis_designs[design_name] ||= klass.new(self)
+        end
+      end
+      
+      def named_document document_name, opts={}, &block
+        klass_name = document_name.to_s.capitalize.gsub(/_(\w)/) { $1.capitalize }
+        klass = const_set(klass_name, Class.new(Exegesis::GenericDocument))
+        klass.unique_id { document_name.to_s }
+        klass.class_eval &block if block
+        define_method document_name do
+          @exegesis_named_documents ||= {}
+          @exegesis_named_documents[document_name] ||= begin
+            get(document_name.to_s)
+          rescue RestClient::ResourceNotFound
+            doc = klass.new({}, self)
+            doc.save
+            doc
+          end
         end
       end
     end
@@ -62,11 +73,18 @@ module Exegesis
         @server.get @uri # raise RestClient::ResourceNotFound if the database does not exist
       end
       
+      def to_s
+        "#<#{self.class.name}(Exegesis::Database):#{self.object_id} uri=#{uri}>"
+      end
+      alias :inspect :to_s
+      
+      # performs a raw GET request against the database
       def raw_get id, options={}
         keys = options.delete(:keys)
+        id = Exegesis::Http.escape_id id
         url = Exegesis::Http.format_url "#{@uri}/#{id}", options
         if id.match(%r{^_design/.*/_view/.*$}) && keys
-          Exegesis::Http.post url, {:keys => keys}
+          Exegesis::Http.post url, {:keys => keys}.to_json
         else
           Exegesis::Http.get url
         end
@@ -74,7 +92,13 @@ module Exegesis
       
       # GETs a document with the given id from the database
       def get id, opts={}
-        Exegesis.instantiate raw_get(id), self
+        if id.kind_of?(Array)
+          collection = opts.delete(:collection) # nil or true for yes, false for no
+          r = post '_all_docs?include_docs=true', {"keys"=>id}
+          r['rows'].map {|d| Exegesis.instantiate d['doc'], self }
+        else
+          Exegesis.instantiate raw_get(id), self
+        end
       end
       
       # saves a document or collection thereof
@@ -92,17 +116,17 @@ module Exegesis
       end
       
       # PUTs the body to the given id in the database
-      def put id, body
-        Exegesis::Http.put "#{@uri}/#{id}", body
+      def put id, body, headers={}
+        Exegesis::Http.put "#{@uri}/#{id}", (body || '').to_json, headers
       end
       
       # POSTs the body to the database
-      def post url, body={}
+      def post url, body={}, headers={}
         if body.is_a?(Hash) && body.empty?
           body = url
           url = ''
         end
-        Exegesis::Http.post "#{@uri}/#{url}", body
+        Exegesis::Http.post "#{@uri}/#{url}", (body || '').to_json, headers
       end
     end
   end

data/lib/exegesis/design.rb

@@ -1,6 +1,7 @@
 require 'pathname'
 module Exegesis
   class Design
+    
     include Exegesis::Document
     
     def self.design_directory= dir
@@ -36,46 +37,67 @@ module Exegesis
       }
     end
     
+    def self.views
+      @views ||= canonical_design['views'].keys
+    end
+    
+    def self.reduceable? view_name
+      view_name = view_name.to_s
+      views.include?(view_name) && canonical_design['views'][view_name].has_key?('reduce')
+    end
+    
     def self.view name, default_options={}
-      define_method name do |key, *opts|
-        view name, key, opts.first, default_options
+      define_method name do |*opts|
+        options = parse_opts opts.shift, opts.first, default_options
+        Exegesis::DocumentCollection.new(call_view(name, options), database)
       end
     end
     
     def self.docs name, default_options={}
-      default_options = {:include_docs => true, :reduce => false}.merge(default_options)
+      view_name = default_options.delete(:view) || name
+      raise ArgumentError, "missing view #{view_name}" unless views.include?(view_name.to_s)
+      if [:reduce, :group, :group_level].any? {|key| default_options.has_key?(key)}
+        raise ArgumentError, "cannot reduce (:group, :group_level, :reduce) on a docs view"
+      end
+      
+      default_options = {:include_docs => true}.merge(default_options)
+      default_options.update({:reduce => false}) if reduceable?(view_name)
+
       define_method name do |*opts|
         key = opts.shift
         options = parse_opts key, opts.first, default_options
-        response = call_view name, options
-        ids = []
-        response.inject([]) do |memo, doc|
-          unless ids.include?(doc['id'])
-            ids << doc['id']
-            memo << Exegesis.instantiate(doc['doc'], database)
-          end
-          memo
-        end
+        Exegesis::DocumentCollection.new(call_view(view_name, options), database)
       end
     end
     
     def self.hash name, default_options={}
-      default_options = {:group => true}.merge(default_options)
       view_name = default_options.delete(:view) || name
+      raise ArgumentError, "missing view #{view_name}" unless views.include?(view_name.to_s)
+      raise NameError, "Cannot return a hash for views without a reduce function" unless reduceable?(view_name)
+      if default_options.has_key?(:group) && default_options[:group] == false
+        raise ArgumentError, "cannot turn off grouping for a hash view" 
+      end
+      
+      default_options = {:group => true}.merge(default_options)
+      
       define_method name do |*opts|
-        key = opts.shift
-        options = parse_opts key, opts.first, default_options
-        options.delete(:group) if options[:key]
+        options = parse_opts opts.shift, opts.first, default_options
+
+        if options.has_key?(:group) && options[:group] == false
+          raise ArgumentError, "cannot turn off grouping for a hash view"
+        end
+
+        if options[:key]
+          options.delete(:group)
+          options.delete(:group_level)
+        end
         
         response = call_view view_name, options
         if response.size == 1 && response.first['key'].nil?
           response.first['value']
         else
           response.inject({}) do |memo, row|
-            if ! memo.has_key?(row['key'])
-              memo[row['key']] = row['value']
-            end
-            memo
+            memo.update(row['key'] => row['value'])
           end
         end
       end
@@ -84,7 +106,8 @@ module Exegesis
     
     def initialize db
       begin
-        super db.get("_design/#{design_name}"), db
+        super db.raw_get("_design/#{design_name}")
+        self.database = db
       rescue RestClient::ResourceNotFound
         db.put("_design/#{design_name}", self.class.canonical_design)
         retry
@@ -113,6 +136,7 @@ module Exegesis
       parse_key opts
       parse_keys opts
       parse_range opts
+      parse_reduce opts
       opts
     end
     
@@ -151,5 +175,17 @@ module Exegesis
       end
     end
     
+    def parse_reduce opts
+      if opts.has_key?(:group)
+        opts[:group_level] = opts.delete(:group) if opts[:group].is_a?(Numeric)
+      end
+      if opts.keys.any? {|key| [:group, :group_level].include?(key) }
+        raise ArgumentError, "cannot include_docs when reducing" if opts[:include_docs]
+        if opts.has_key?(:reduce) && opts[:reduce] == false
+          raise ArgumentError, "cannot reduce=false when either group or group_level is present"
+        end
+      end
+    end
+    
   end
 end

data/lib/exegesis/document/attachment.rb

@@ -0,0 +1,44 @@
+module Exegesis
+  module Document
+    class Attachment
+      
+      attr_reader :name, :metadata, :document
+      
+      def initialize(name, thing, doc)
+        @document = doc
+        @metadata = thing
+        @name = name
+      end
+      
+      def to_s
+        "#<Exegesis::Document::Attachment document=#{@document.uri} #{@metadata.inspect}>"
+      end
+      alias :inspect :to_s
+      
+      def content_type
+        @metadata['content_type']
+      end
+      
+      def length
+        @metadata['length'] || -1
+      end
+      
+      def stub?
+        @metadata['stub'] || false
+      end
+      
+      def file
+        RestClient.get("#{document.database.uri}/#{document.id}/#{name}")
+      end
+      
+      def to_json
+        if @metadata['data']
+          {'content_type' => @metadata['content_type'], 'data' => @metadata['data']}.to_json
+        else
+          @metadata.to_json
+        end
+      end
+      
+    end
+  end
+end

data/lib/exegesis/document/attachments.rb

@@ -0,0 +1,53 @@
+require 'base64'
+module Exegesis
+  module Document
+    class Attachments < Hash
+      
+      attr_accessor :document
+      
+      def initialize doc
+        @document = doc
+        if @document['_attachments']
+          @document['_attachments'].each do |name,meta| 
+            update(name => Exegesis::Document::Attachment.new(name, meta, document))
+          end
+        end
+      end
+      
+      def to_s
+        "#<Exegesis::Document::Attachments document=#{@document.uri} attachments=#{keys.join(', ')}>"
+      end
+      alias :inspect :to_s
+      
+      def dirty?
+        @dirty || false
+      end
+      
+      def clean!
+        each do |name, attachment|
+          next if attachment.stub?
+          attachment.metadata['stub'] = true
+          attachment.metadata.delete('data')
+        end
+        @dirty = false
+      end
+      
+      # saves the attachment to the database NOW. does not keep the attachment in memory once this is done.
+      def put(name, contents, type)
+        r = Exegesis::Http.put("#{document.uri}/#{name}?rev=#{document.rev}", contents, {:content_type => type})
+        if r['ok']
+          document['_rev'] = r['rev']
+          update(name => Exegesis::Document::Attachment.new(name, {'content_type' => type, 'stub' => true, 'length' => contents.length}, document))
+        end
+      end
+
+      def []= name, contents_and_type
+        @dirty = true
+        content = contents_and_type.shift
+        meta = {'data' => Base64.encode64(content).gsub(/\s/,''), 'content_type' => contents_and_type.first, 'length' => content.length}
+        update(name => Exegesis::Document::Attachment.new(name, meta, document))
+      end
+    end
+    
+  end
+end

data/lib/exegesis/document/collection.rb

@@ -0,0 +1,78 @@
+module Exegesis
+  class DocumentCollection
+    include Enumerable
+    
+    attr_reader :rows, :parent, :index
+    
+    def initialize docs=[], master=nil, index=0
+      @rows = docs
+      if master.is_a?(Exegesis::DocumentCollection)
+        @parent = master
+      else
+        @database = master
+      end
+      @index = index
+    end
+    
+    def to_s
+      "#<Exegesis::DocumentCollection:#{object_id} database=#{database.uri} rows=#{size} depth=#{index}>"
+    end
+    alias :inspect :to_s
+    
+    def database
+      @database || @parent.database
+    end
+    
+    def size
+      @rows.length
+    end
+    
+    def keys
+      @keys ||= rows.map {|r| r['key'] }.uniq
+    end
+    
+    def values
+      @values ||= rows.map {|r| r['value'] }
+    end
+    
+    def documents
+      @documents ||= load_documents
+    end
+    
+    def [] key
+      @keymaps ||= {}
+      filtered_rows = rows.select do |row|
+        if row['key'].is_a?(Array)
+          row['key'][index] == key
+        else
+          row['key'] == key
+        end
+      end
+      new_index = index + 1
+      @keymaps[key] ||= self.class.new(filtered_rows, self, new_index)
+    end
+    
+    def each &block
+      rows.each do |row|
+        yield row['key'], row['value'], documents[row['id']]
+      end
+    end
+    
+    private
+    def load_documents
+      docmap = {}
+      if parent.nil?
+        non_doc_rows = rows.select {|r| ! r.has_key?('doc') }
+        if non_doc_rows.empty?
+          rows.map {|r| docmap[r['id']] = Exegesis.instantiate(r['doc'], database) }
+        else
+          database.get(non_doc_rows.map{|r| r['id']}.uniq, :include_docs=>true).each {|doc| docmap[doc.id] = doc}
+        end
+      else
+        rows.map {|r| docmap[r['id']] = parent.documents[r['id']] }
+      end
+      docmap
+    end
+    
+  end
+end

data/lib/exegesis/document/generic_document.rb

@@ -0,0 +1,5 @@
+module Exegesis
+  class GenericDocument
+    include Exegesis::Document
+  end
+end

data/lib/exegesis/document.rb

@@ -1,5 +1,10 @@
 module Exegesis
   module Document
+    autoload :Attachments,  'exegesis/document/attachments'
+    autoload :Attachment,   'exegesis/document/attachment'
+    
+    class MissingDatabaseError < StandardError; end
+    class NewDocumentError < StandardError; end
     
     def self.included base
       base.send :include, Exegesis::Model
@@ -35,6 +40,20 @@ module Exegesis
         @database = db
       end
       
+      def uri
+        raise MissingDatabaseError if database.nil?
+        raise NewDocumentError if rev.nil? || id.nil?
+        "#{database.uri}/#{id}"
+      end
+      
+      def reload
+        raise NewDocumentError if rev.nil? || id.nil?
+        raise MissingDatabaseError if database.nil?
+        @attachments = nil
+        @references = nil
+        @attributes = database.raw_get(id)
+      end
+      
       def == other
         self.id == other.id
       end
@@ -54,19 +73,28 @@ module Exegesis
         else
           save_document
         end
+        @attachments.clean! if @attachments && @attachments.dirty?
       end
       
       def update_attributes attrs={}
-        raise ArgumentError, 'must include a matching _rev attribute' unless rev == attrs.delete('_rev')
+        raise ArgumentError, 'must include a matching _rev attribute' unless (rev || '') == (attrs.delete('_rev') || '')
         super attrs
         save
       end
       
+      def attachments
+        @attachments ||= Exegesis::Document::Attachments.new(self)
+      end
+      
+      def to_json
+        @attributes.merge({'_attachments' => @attachments}).to_json
+      end
+      
       private
       
       def save_document
         raise ArgumentError, "canont save without a database" unless database
-        database.save self.attributes
+        database.save self
       end
       
       def save_with_custom_unique_id

data/lib/exegesis/model.rb

@@ -4,13 +4,13 @@ module Exegesis
     def self.included base
       base.extend ClassMethods
       base.send :include, InstanceMethods
-      Exegesis.model_classes[base.name] = base
       base.send :attr_accessor, :attributes, :references, :parent
     end
     
     module ClassMethods
       def expose *attrs
         opts = attrs.last.is_a?(Hash) ? attrs.pop : {}
+        raise ArgumentError, "casted keys cannot have defined writers" if opts[:as] && opts[:writer]
         [attrs].flatten.each do |attrib|
           attrib = attrib.to_s
           if opts[:writer]
@@ -20,6 +20,7 @@ module Exegesis
           end
           if opts[:as] == :reference
             define_reference attrib
+            define_reference_writer attrib unless opts[:writer] == false
           elsif opts[:as]
             define_caster attrib, opts[:as]
           else
@@ -53,6 +54,22 @@ module Exegesis
         end
       end
       
+      def define_reference_writer attrib
+        define_writer(attrib) do |val|
+          if val.is_a?(String)
+            @attributes[attrib] = val
+          elsif val.is_a?(Exegesis::Document)
+            if val.rev && val.id
+              @attributes[attrib] = val.id
+            else
+              raise ArgumentError, "cannot reference unsaved documents"
+            end
+          else
+            raise ArgumentError, "was not a document or document id"
+          end
+        end
+      end
+      
       def define_caster attrib, as
         define_method(attrib) do
           @attributes[attrib] = if @attributes[attrib].is_a?(Array)
@@ -109,8 +126,9 @@ module Exegesis
       
       def cast as, value
         return nil if value.nil?
+        return value unless [String, Hash, Fixnum, Float].include?(value.class)
         klass = if as == :given && value.is_a?(Hash)
-          Exegesis.model_classes[value['class']]
+          Exegesis.constantize(value['class'])
         elsif as.is_a?(Class)
           as
         else

data/lib/exegesis/server.rb

@@ -22,7 +22,7 @@ module Exegesis
     end
     
     def inspect
-      "#<Exegesis::Server #{@uri}>"
+      "#<Exegesis::Server:#{object_id} uri=#{@uri}>"
     end
   end
 end

data/lib/exegesis/utils/http.rb

@@ -15,23 +15,29 @@ module Exegesis
     end
     
     def escape_id id
-      /^_design\/(.*)/ =~ id ? "_design/#{CGI.escape($1)}" : CGI.escape(id) 
+      if %r{^_design/(.*)/_view/(.*)} =~ id
+        "_design/#{CGI.escape($1)}/_view/#{CGI.escape($2)}"
+      elsif /^_design\/(.*)/ =~ id
+        "_design/#{CGI.escape($1)}"
+      else 
+        CGI.escape(id)
+      end
     end
     
-    def get url
-      JSON.parse(RestClient.get(url), :max_nesting => false)
+    def get url, headers={}
+      JSON.parse(RestClient.get(url, headers), :max_nesting => false)
     end
     
-    def post url, body=''
-      JSON.parse(RestClient.post(url, (body || '').to_json))
+    def post url, body='', headers={}
+      JSON.parse(RestClient.post(url, body, headers))
     end
     
-    def put url, body=''
-      JSON.parse(RestClient.put(url, (body || '').to_json))
+    def put url, body='', headers={}
+      JSON.parse(RestClient.put(url, body, headers))
     end
     
-    def delete url
-      JSON.parse(RestClient.delete(url))
+    def delete url, headers={}
+      JSON.parse(RestClient.delete(url, headers))
     end
     
   end