boombera 0.2.1 → 0.2.2

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/boombera.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{boombera}
-  s.version = "0.2.1"
+  s.version = "0.2.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["John Wilger"]
-  s.date = %q{2011-05-30}
+  s.date = %q{2011-05-31}
   s.description = %q{CouchDB-backed content repository for multi-tenant, multi-stage applications}
   s.email = %q{johnwilger@gmail.com}
   s.extra_rdoc_files = [
@@ -32,6 +32,7 @@ Gem::Specification.new do |s|
     "lib/boombera/content_item.rb",
     "lib/boombera/information.rb",
     "spec/integration/boombera_spec.rb",
+    "spec/lib/boombera/content_item_map_resolver_spec.rb",
     "spec/lib/boombera/content_item_spec.rb",
     "spec/lib/boombera_spec.rb",
     "spec/spec_helper.rb"

data/lib/boombera.rb

@@ -1,40 +1,147 @@
 $:.unshift(File.expand_path(File.dirname(__FILE__)))
 require 'couchrest'
 
+# This is the main interface to the Boombera content repository.
+#
+# Usage examples:
+#
+#   # install/update the CouchDB design document
+#   Boombera.install_design_doc!('my_database')
+#
+#   # connect to the database
+#   boombera = Boombera.new('my_database')
+#   
+#   # put and get some content
+#   boombera.put('/hello', 'Hello, world!')
+#   #=> true
+#
+#   content = boombera.get('/hello')
+#   content.body
+#   #=> 'Hello, world!'
+#
+#   # update the content via the ContentItem
+#   content.body = 'Hello, friends!'
+#   content.save
+#   #=> true
+#
+#   # update the content without an object
+#   boombera.put('/hello', 'Hello, everyone!')
+#   content = boombera.get('/hello')
+#   content.body
+#   #=> 'Hello, everyone!'
+#
+#   # map an alias to the content
+#   boombera.map('/hi', '/hello')
+#   content = boombera.get('/hi')
+#   content.path
+#   #=> '/hello'
+#
+#   content.body
+#   #=> 'Hello, everyone!'
+#
+#   # override the map with some different content
+#   boombera.put('/hi', "G'day, mate!")
+#   content = boombera.get('/hi')
+#   content.path
+#   #=> '/hi'
+#
+#   content.body
+#   #=> "G'day, mate!"
+#
+#   content = boombera.get('/hello')
+#   content.path
+#   #=> '/hello'
+#
+#   content.body
+#   #=> 'Hello, everyone!'
 class Boombera
   require 'boombera/content_item'
   require 'boombera/information'
 
+  # Exception is raised when connecting to a Boombera CouchDB database that
+  # expects a different version of the Boombera library than the one currently
+  # being used.
   VersionMismatch = Class.new(StandardError)
+
+  # Exception is raised when attempting to create a content mapping and the
+  # source document doesn't exist.
   InvalidMapping = Class.new(RuntimeError)
 
   extend Boombera::Information
 
+  # The CouchRest::Database instance
   attr_reader :db
 
+  # Connects to the CouchDB server and verifies the database version.
+  # 
+  # +database_name+:: can be either a full url to a CouchDB server and database
+  # (\http://example.com:5984/my_database) or it can be just the database name
+  # itself (my_database). The latter will connect to the database at
+  # \http://127.0.0.1:5984.
+  #
+  # raises:: VersionMismatch
   def initialize(database_name)
     @db = CouchRest.database!(database_name)
     check_database_version!
   end
 
+  # Installs the CouchDB design document for this version of the library in the
+  # specified database!
+  #
+  # *WARNING*:: This will overwrite the current design document and prevent
+  # applications that are using a different version of the Boombera library from
+  # accessing the database. This change will be replicated along with everything
+  # else in your database.
+  # 
+  # +database_name+:: can be either a full url to a CouchDB server and database
+  # (\http://example.com:5984/my_database) or it can be just the database name
+  # itself (my_database). The latter will connect to the database at
+  # \http://127.0.0.1:5984.
+  def self.install_design_doc!(database)
+    db = CouchRest.database!(database)
+    existing = current_design_doc(db)
+    design = design_doc
+    design['_rev'] = existing['_rev'] unless existing.nil?
+    db.save_doc(design)
+  end
+
+  # Creates or updates the content stored at +path+ with +body+.
+  #
+  # +body+:: can be # any object that can convert to JSON.
+  # +path+:: should be a String with /-separated tokens (i.e. "/foo/bar/baz").
   def put(path, body)
-    content_item = get(path, :resolve_map => false) and content_item.body = body
+    content_item = get_pointer(path) and content_item.body = body
     content_item ||= ContentItem.new(path, body, db)
     content_item.save
   end
 
-  def get(path, options = {})
-    ContentItem.get(path, db, options)
+  # Returns the ContentItem associated with the specified path or +nil+ if none
+  # is found. If +path+ is mapped to another ContentItem, the resolved
+  # ContentItem will be returned.
+  def get(path)
+    ContentItem::MapResolver.new(path, db).resolve
   end
 
+  # Creates a content mapping so that two paths can reference the same content
+  # without needing to store that content twice.
+  #
+  # +path+:: the new alias path for the ContentItem
+  # +source_path+:: the path of the ContentItem that should be returned for
+  # requests to +path+. This path *must* point to an existing ContentItem.
+  # 
+  # raises:: InvalidMapping
   def map(path, source_path)
-    content_map = get(path, :resolve_map => false) || ContentItem.new(path, nil, db)
+    content_map = get_pointer(path) || ContentItem.new(path, nil, db)
     content_map.map_to source_path
     content_map.save
   end
 
   private
 
+  def get_pointer(path)
+    ContentItem::MapResolver.new(path, db, :resolve_map => false).resolve
+  end
+
   def check_database_version!
     database_version = Boombera.database_version(db)
     unless Boombera.version == database_version

data/lib/boombera/content_item.rb

@@ -1,5 +1,8 @@
+# ContentItem is a specialization of CouchRest::Document that adds
+# content-mapping semantics and method-based access to the attributes that
+# Boombera knows about.
 class Boombera::ContentItem < CouchRest::Document
-  class MapResolver
+  class MapResolver #:nodoc: all
     def initialize(path, database, options = {})
       @path = path
       @database = database
@@ -27,16 +30,15 @@ class Boombera::ContentItem < CouchRest::Document
     end
   end
 
-  class << self
-    def get(path, database, options = {})
-      MapResolver.new(path, database, options).resolve
-    end
-  end
-
+  # The actual content that is being stored
   attr_accessor :body
-  attr_reader :path, :maps_to
 
-  def initialize(doc_or_path, body = nil, database = nil)
+  # The path used to access the ContentItem
+  attr_reader :path
+
+  attr_reader :maps_to #:nodoc:
+
+  def initialize(doc_or_path, body = nil, database = nil) #:nodoc:
     case doc_or_path
     when CouchRest::Document
       @database = doc_or_path.database
@@ -49,7 +51,7 @@ class Boombera::ContentItem < CouchRest::Document
     end
   end
 
-  def map_to(source_path)
+  def map_to(source_path) #:nodoc:
     rows = @database.view('boombera/content_map', :key => source_path)['rows']
     if rows.empty?
       raise Boombera::InvalidMapping,
@@ -60,29 +62,26 @@ class Boombera::ContentItem < CouchRest::Document
     end
   end
 
+  # Returns the paths that are aliased to this ContentItem
   def referenced_by
     rows = @database.view('boombera/map_references', :key => path)['rows']
     rows.map{ |row| row['value'] }.sort
   end
 
-  # :nodoc:
-  def path
+  def path #:nodoc:
     self[:path]
   end
 
-  # :nodoc:
-  def body
+  def body #:nodoc:
     self[:body]
   end
 
-  # :nodoc:
-  def body=(new_body)
+  def body=(new_body) #:nodoc:
     self[:body] = new_body
     self[:maps_to] = path unless new_body.nil?
   end
 
-  # :nodoc:
-  def maps_to
+  def maps_to #:nodoc:
     self[:maps_to]
   end
 end

data/lib/boombera/information.rb

@@ -1,4 +1,4 @@
-module Boombera::Information
+module Boombera::Information #:nodoc: all
   def version
     File.read(File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'VERSION')))
   end
@@ -8,14 +8,6 @@ module Boombera::Information
     doc && doc['gem_version']
   end
 
-  def install_design_doc!(database)
-    db = CouchRest.database!(database)
-    existing = current_design_doc(db)
-    design = design_doc
-    design['_rev'] = existing['_rev'] unless existing.nil?
-    db.save_doc(design)
-  end
-
   def design_doc
     {
       '_id' => '_design/boombera',

data/spec/lib/boombera/content_item_map_resolver_spec.rb

@@ -0,0 +1,66 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'spec_helper'))
+
+describe Boombera::ContentItem::MapResolver do
+  describe '#resolve' do
+    context 'with an existing content item' do
+      it 'returns a ContentItem instance for the found document' do
+        view_result = {'rows' => [{'id' => '123', 'value' => '/foo'}]}
+        db = mock(CouchRest::Database)
+        db.should_receive(:view) \
+          .with('boombera/content_map', :key => '/foo') \
+          .and_return(view_result)
+        db.should_receive(:get) \
+          .with('123') \
+          .and_return(CouchRest::Document.new('path' => '/foo', 'body' => 'bar'))
+        result = Boombera::ContentItem::MapResolver.new('/foo', db).resolve
+        result.path.should == '/foo'
+        result.body.should == 'bar'
+      end
+    end
+
+    context 'with a non-existant content item' do
+      it 'returns nil' do
+        view_result = {'rows' => []}
+        db = mock(CouchRest::Database)
+        db.should_receive(:view) \
+          .with('boombera/content_map', :key => '/foo') \
+          .and_return(view_result)
+        Boombera::ContentItem::MapResolver.new('/foo', db).resolve.should == nil
+      end
+    end
+
+    context 'with a path that maps to another content item' do
+      it 'returns the mapped content item' do
+        map_view_result = {'rows' => [{'id' => '123', 'value' => '/bar'}]}
+        content_view_result = {'rows' => [{'id' => '456', 'value' => '/bar'}]}
+        db = mock(CouchRest::Database)
+        db.should_receive(:view) \
+          .with('boombera/content_map', :key => '/foo') \
+          .and_return(map_view_result)
+        db.should_receive(:view) \
+          .with('boombera/content_map', :key => '/bar') \
+          .and_return(content_view_result)
+        db.should_receive(:get) \
+          .with('456') \
+          .and_return(CouchRest::Document.new('path' => '/bar', 'body' => 'bar'))
+        result = Boombera::ContentItem::MapResolver.new('/foo', db).resolve
+        result.path.should == '/bar'
+        result.body.should == 'bar'
+      end
+
+      it 'returns the pointer content item when passed the :resolve_map option as false' do
+        map_view_result = {'rows' => [{'id' => '123', 'value' => '/bar'}]}
+        db = mock(CouchRest::Database)
+        db.should_receive(:view) \
+          .with('boombera/content_map', :key => '/foo') \
+          .and_return(map_view_result)
+        db.should_receive(:get) \
+          .with('123') \
+          .and_return(CouchRest::Document.new('path' => '/foo', 'maps_to' => '/bar'))
+        result = Boombera::ContentItem::MapResolver.new('/foo', db, :resolve_map => false).resolve
+        result.path.should == '/foo'
+        result.maps_to.should == '/bar'
+      end
+    end
+  end
+end

data/spec/lib/boombera/content_item_spec.rb

@@ -1,69 +1,6 @@
 require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'spec_helper'))
 
 describe Boombera::ContentItem do
-  describe '.get' do
-    context 'with an existing content item' do
-      it 'returns a ContentItem instance for the found document' do
-        view_result = {'rows' => [{'id' => '123', 'value' => '/foo'}]}
-        db = mock(CouchRest::Database)
-        db.should_receive(:view) \
-          .with('boombera/content_map', :key => '/foo') \
-          .and_return(view_result)
-        db.should_receive(:get) \
-          .with('123') \
-          .and_return(CouchRest::Document.new('path' => '/foo', 'body' => 'bar'))
-        result = Boombera::ContentItem.get('/foo', db)
-        result.path.should == '/foo'
-        result.body.should == 'bar'
-      end
-    end
-
-    context 'with a non-existant content item' do
-      it 'returns nil' do
-        view_result = {'rows' => []}
-        db = mock(CouchRest::Database)
-        db.should_receive(:view) \
-          .with('boombera/content_map', :key => '/foo') \
-          .and_return(view_result)
-        Boombera::ContentItem.get('/foo', db).should == nil
-      end
-    end
-
-    context 'with a path that maps to another content item' do
-      it 'returns the mapped content item' do
-        map_view_result = {'rows' => [{'id' => '123', 'value' => '/bar'}]}
-        content_view_result = {'rows' => [{'id' => '456', 'value' => '/bar'}]}
-        db = mock(CouchRest::Database)
-        db.should_receive(:view) \
-          .with('boombera/content_map', :key => '/foo') \
-          .and_return(map_view_result)
-        db.should_receive(:view) \
-          .with('boombera/content_map', :key => '/bar') \
-          .and_return(content_view_result)
-        db.should_receive(:get) \
-          .with('456') \
-          .and_return(CouchRest::Document.new('path' => '/bar', 'body' => 'bar'))
-        result = Boombera::ContentItem.get('/foo', db)
-        result.path.should == '/bar'
-        result.body.should == 'bar'
-      end
-
-      it 'returns the pointer content item when passed the :resolve_map option as false' do
-        map_view_result = {'rows' => [{'id' => '123', 'value' => '/bar'}]}
-        db = mock(CouchRest::Database)
-        db.should_receive(:view) \
-          .with('boombera/content_map', :key => '/foo') \
-          .and_return(map_view_result)
-        db.should_receive(:get) \
-          .with('123') \
-          .and_return(CouchRest::Document.new('path' => '/foo', 'maps_to' => '/bar'))
-        result = Boombera::ContentItem.get('/foo', db, :resolve_map => false)
-        result.path.should == '/foo'
-        result.maps_to.should == '/bar'
-      end
-    end
-  end
-
   describe '.new' do
     context 'when passed a path, body and database' do
       it 'sets the database from the database argument' do

data/spec/lib/boombera_spec.rb

@@ -40,9 +40,10 @@ describe Boombera do
   describe '#put' do
     context "to an existing path" do
       it 'updates and saves the existing content item' do
-        Boombera::ContentItem.should_receive(:get) \
+        resolver = stub(Boombera::ContentItem::MapResolver, :resolve => content_item)
+        Boombera::ContentItem::MapResolver.should_receive(:new) \
           .with('/foo', db, :resolve_map => false) \
-          .and_return(content_item)
+          .and_return(resolver)
         content_item.should_receive(:body=).with('bar')
         content_item.should_receive(:save).and_return(true)
         boombera.put('/foo', 'bar').should == true
@@ -51,7 +52,7 @@ describe Boombera do
 
     context "to a new path" do
       it 'creates and saves the content item' do
-        Boombera::ContentItem.stub!(:get => nil)
+        Boombera::ContentItem::MapResolver.stub!(:new => stub('resolver', :resolve => nil))
         Boombera::ContentItem.should_receive(:new) \
           .with('/foo', 'bar', db) \
           .and_return(content_item)
@@ -63,16 +64,19 @@ describe Boombera do
 
   describe '#get' do
     it 'gets the content item at the specified path from the current database' do
-      db.as_null_object
-      Boombera::ContentItem.should_receive(:get).with('/foo', db, {})
-      boombera.get('/foo')
+      resolver = stub(Boombera::ContentItem::MapResolver, :resolve => :a_content_item)
+      Boombera::ContentItem::MapResolver.should_receive(:new) \
+        .with('/foo', db) \
+        .and_return(resolver)
+      boombera.get('/foo').should == :a_content_item
     end
   end
 
   describe '#map' do
     context 'to a new path' do
       before(:each) do
-        Boombera::ContentItem.stub!(:get)
+        resolver = stub(Boombera::ContentItem::MapResolver, :resolve => nil)
+        Boombera::ContentItem::MapResolver.stub!(:new => resolver)
         Boombera::ContentItem.should_receive(:new).with('/bar', nil, db).and_return(content_item)
       end
 
@@ -91,9 +95,10 @@ describe Boombera do
 
     context 'to an existing path' do
       before(:each) do
-        Boombera::ContentItem.should_receive(:get) \
+        resolver = stub(Boombera::ContentItem::MapResolver, :resolve => content_item)
+        Boombera::ContentItem::MapResolver.should_receive(:new) \
           .with('/bar', db, :resolve_map => false) \
-          .and_return(content_item)
+          .and_return(resolver)
       end
 
       it 'updates ContentItem as pointer' do

metadata

@@ -2,7 +2,7 @@
 name: boombera
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors: 
 - John Wilger
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-30 00:00:00 -07:00
+date: 2011-05-31 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -148,6 +148,7 @@ files:
 - lib/boombera/content_item.rb
 - lib/boombera/information.rb
 - spec/integration/boombera_spec.rb
+- spec/lib/boombera/content_item_map_resolver_spec.rb
 - spec/lib/boombera/content_item_spec.rb
 - spec/lib/boombera_spec.rb
 - spec/spec_helper.rb
@@ -165,7 +166,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -422599235011708873
+      hash: -2154182263387291460
       segments: 
       - 0
       version: "0"