peace_love 0.1.0 → 0.1.1

data/License

@@ -0,0 +1,21 @@
+Copyright (c) 2010 Lachie Cox
+
+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

@@ -8,6 +8,8 @@ begin
     gemspec.homepage = "http://github.com/lachie/peace_love"
     gemspec.authors = ["Lachie Cox"]
 
+    gemspec.test_files = []
+
     gemspec.add_dependency("mongo", ['~>1.0.0'])
     gemspec.add_dependency("angry_hash", ['=0.0.5'])
   end

data/Readme.md

@@ -0,0 +1,205 @@
+# PeaceLove & Mongo
+
+PeaceLove is a simple mixin layer for enhancing hashes retrieved from MongoDB. PeaceLove eschews the mapping compulsion of ruby Mongo libraries.
+
+## Install
+
+    gem install peace_love
+
+## Basic Usage
+
+    require 'rubygems'
+
+    require 'bson_ext'
+    require 'mongo'
+
+    require 'peace_love'
+
+(Right now you have to set up your database before defining any mixins. This limitation will be fixed soon.)
+
+    mongo = Mongo::Connection.new
+    PeaceLove.db = mongo['bean_db']
+
+Now define some mixins
+
+    module Bean
+      include PeaceLove::Doc
+      mongo_collection 'beans'
+
+      def is_a_bean?; true end
+    end
+
+Now lets insert something:
+
+    lima_bean  = { :name => 'lima' }
+    human_bean = { :name => 'Arthur', :prefered_drinks => %w[tea] }
+
+    PeaceLove['beans'].insert(lima_bean)
+    PeaceLove['beans'].insert(human_bean)
+
+`PeaceLove['beans']` returns a `PeaceLove::Collection` which thinly wraps a `Mongo::Collection`. See how to use it in the [Mongo Ruby API][monapi]
+
+Notice how we're inserting hashes. PeaceLove only mixes in hashes coming _out_ of Mongo.
+
+Also note that the wrapping of `Mongo::Collection` may not yet be complete.
+
+### Fetching single documents
+
+Let's fetch Arthur:
+
+    arthur = PeaceLove['beans'].find_one(:name => 'Arthur')
+
+Now what can we do with him?
+
+    arthur.is_a_bean?        #=> true
+
+`#is_a_bean?` was defined on the module `Bean`. Nice.
+
+Now fetch some plain values:
+
+    arthur[:prefered_drinks] #=> [ 'tea' ]
+    arthur.prefered_drinks   #=> [ 'tea' ]
+
+    arthur.is_a?(Hash)       #=> true
+    arthur.class             #=> AngryHash
+
+Among other things, [`AngryHash`][ah] adds dot-notation accessors to hashes.
+
+### Updating
+
+Arthur discovered a new drink. Let's update:
+
+    PeaceLove['beans'].update({:_id => arthur._id}, '$push' => {'prefered_drinks' => 'pan-galactic gargle blaster'})
+
+    arthur = PeaceLove['beans'].find_one(:name => 'Arthur')
+
+    arthur.prefered_drinks #=> [ 'tea', 'pan-galactic gargle blaster' ]
+
+Here we're using normal Mongo powers to do an atomic push onto `arthur.prefered_drinks`
+
+### Fetching a list
+
+    PeaceLove['beans'].find(:name => 'lima').each {|bean| # ... work}
+
+`#find` returns a `PeaceLove::Cursor` which thinly wraps a `Mongo::Cursor`. It mixes in `Enumerable`.
+
+### Building
+
+To build a hash imbued with module powers, without touching mongo, use `#build`:
+
+    arthur = PeaceLove['beans'].build(:name => 'arthur')
+    
+## Sub structure
+
+### Sub documents
+
+Sub documents allow you to mix modules into parts of the document.
+
+    module Taste
+      def zesty?
+        spicy? && sour?
+      end
+    end
+
+    module Bean
+      include PeaceLove::Doc
+      mongo_collection 'beans'
+      
+      sub_doc :taste, Taste
+    end
+
+    chaos = PeaceLove['beans'].build(:name => 'chaos', :taste => {:sour => true, :spicy => true})
+    chaos.taste.zesty? #=> true
+
+### Sub collections
+
+Sub collections allow you to mix modules into each element of arrays (and in the future hashes) contained in the document.
+
+    module Colour
+      def happy?
+        name == 'red' || name == 'yellow'
+      end
+    end
+
+    module Bean
+      include PeaceLove::Doc
+      mongo_collection 'beans'
+      
+      sub_col :taste, Taste
+    end
+
+    bean = PeaceLove['beans'].build(:name => 'jelly-belly', :colours => [
+                                                                          {:name => 'red'},
+                                                                          {:name => 'green'},
+                                                                          {:name => 'magenta'}
+                                                                        ])
+
+    bean.colours[0].name   #=> 'red'
+    bean.colours[0].happy? #=> true
+    bean.colours[1].name   #=> 'green'
+    bean.colours[1].happy? #=> false
+
+### Railtie
+
+There's a simple rails 3 `railtie` for setting up the MongoDB connection using details in `database.yml`.
+
+It will probably become more sophisticated over time.
+
+## Rationale
+
+or: why not map Mongo?
+
+### Mongo's ruby driver is unusually good
+
+Unusually good for database drivers, that is. By contrast SQL drivers (& underlying SQL engines) tend to be a bit shaggy due 
+to the profusion of databases and sellers thereof.
+Thus, part of the attraction of an ORM is papering over all the SQL driver shagginess.
+
+There's only one MongoDB implementation so far, and only one vendor, 10gen.
+
+10gen has created a good, rubyish driver for it (though apparently it can be a mite laggy, versionwise)
+
+Therefore, lets enjoy what we have.
+
+### Mongo's data approach is good.
+
+BSON is binary JSON, and Mongo's interface is (mostly) based on it (the notable exception being MapReduce, for which you use Javascript).
+
+Day-to-day querying and commanding of the database is done through BSON, which means that its logic free & injection safe.
+
+You can do so much with the BSON interface, simply and neatly; I don't quite see the point in abstracting it away behind an expensive ruby interface.
+
+### DIY or don't.
+
+If you want to abstract or DRY stuff away, do it yourself, in a `PeaceLove::Doc` module. 
+
+Or, use one of the mappers :)
+
+## Limitations
+
+Documents are hashes. This means that if your hash keys collide with method names, you'll either have to access them using normal `[:key]` syntax
+or you can override the method:
+
+    def key; self['key'] end # Hash#key is defined in ruby 1.9.
+
+The only exception is `Object#id`. In late ruby 1.8's its deprecated but still exists. In ruby 1.9 its been removed. I therefore decided to override it
+in `PeaceLove::Doc` since I wanted to use `#id` to store my own non-mongo ids.
+
+## TODO
+
+* The core mixin mechanics of PeaceLove aren't actually bound to MongoDB at all. I'd like to split out the mongo-specific & -non-specific parts.
+* Sub collections can only be arrays. They should be able to be hashes too.
+
+## About
+
+Please report problems at http://github.com/lachie/peace_love/issues.
+
+PeaceLove is by Lachie Cox.
+
+The code is hosted on GitHub and can be found at http://github.com/lachie/peace_love.
+
+You're free to use PeaceLove under the MIT license, see License for details.
+
+[ah]: http://github.com/plus2/angry_hash
+[monapi]: http://api.mongodb.org/ruby/1.0.5/Mongo/Collection.html
+

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/examples/usage.eg.rb

@@ -12,6 +12,9 @@ require 'peace_love'
 PeaceLove.db = $db
 
 module Kind
+  include PeaceLove::Doc
+  defaults :a_value => {:defaults => 'values'}
+
   def healthy; "healthy" end
 
   def kids_love?
@@ -23,9 +26,12 @@ module Bean
   include PeaceLove::Doc
   sub_doc :kind  , Kind
   sub_col :examples, Bean
+  sub_hash :examples_hash, Bean
 
   mongo_collection 'beans'
 
+  defaults :ham => {:sandwich => 'golly yes!'}
+
   def texture; super.upcase end
 end
 
@@ -100,6 +106,15 @@ eg 'loading a list of documents' do
   }
 end
 
+eg 'loading a hash of documents' do
+  mongo_beans.insert(:name => 'baked', :examples_hash => { 'yummy' => {:named => 'yummy', :texture => 'sandy'}, 'yucky' => {:named => 'yiccko'} } )
+
+  baked = peace_love_beans.find_one(:name => 'baked')
+
+  Assert( baked.examples_hash.yummy.named == 'yummy' )
+  Assert( baked.examples_hash.yummy.texture == 'SANDY' )
+end
+
 eg 'looking into an array sub collection' do
   mongo_beans.insert(:name => 'jelly', :texture => 'wibbly', :kind => {:fictional => false},
                      :examples => [
@@ -135,6 +150,27 @@ eg 'the id accessor works in ruby 1.8 & 1.9' do
   Assert( Bean.build(:id => 'abc').id == 'abc' )
 end
 
+eg 'setting defaults on the mixin - via build' do
+  bean = Bean.build(:id => 'myd', :ham => {:with_pickles => 'also yes'} )
+
+  Assert( bean.ham.sandwich == 'golly yes!' )
+  Assert( bean.ham.with_pickles == 'also yes' )
+
+  Assert( bean.kind.a_value.defaults == 'values' )
+end
+
+eg 'setting defaults on the mixin - from db' do
+  mongo_beans.insert(:name => 'baked'  , :ham => {'pigglish' => true}, :kind => {:a_value => {:other => 'apples'}})
+
+  bean = peace_love_beans.find_one(:name => 'baked')
+
+  Assert( bean.ham.sandwich == 'golly yes!' )
+  Assert( bean.ham.pigglish ==  true)
+
+  Assert( bean.kind.a_value.defaults == 'values' )
+  Assert( bean.kind.a_value.other    == 'apples' )
+end
+
 __END__
 
 eg 'looking into a hash sub collection' do

data/lib/peace_love/collection.rb

@@ -43,12 +43,13 @@ module PeaceLove
       hash
     end
 
-    def __extend(hash)
+    def __extend(doc)
       if mixin
-        hash.extend mixin 
-        hash.__source_collection = self if hash.respond_to?(:__source_collection=)
+        doc.extend mixin 
+        doc.__source_collection = self if doc.respond_to?(:__source_collection=)
       end
-      hash
+
+      doc
     end
 
     (Mongo::Collection.instance_methods - self.instance_methods).each do |name|

data/lib/peace_love/document.rb

@@ -18,11 +18,15 @@ module PeaceLove
         @object_extensions ||= {}
       end
 
-      def mark_extension(obj,with)
-        if (previously_with = object_extensions[obj.__id__]) && previously_with != with
-          raise "object #{obj} has already been extended by a different PeaceLove::Doc (was: #{previously_with}, now: #{with})"
+      def mark_extension(doc,mod)
+        # puts "mark_extension doc=#{doc.class} mod=#{mod}"
+        
+        if (previous_mod = object_extensions[doc.__id__]) && previous_mod != mod
+          raise "doc #{doc} has already been extended by a different PeaceLove::Doc (was: #{previous_mod}, now: #{mod})"
         end
-        object_extensions[obj.__id__] = with
+        object_extensions[doc.__id__] = mod
+
+        setup_extended_doc(doc,mod)
       end
 
       def mixin_registry
@@ -37,9 +41,25 @@ module PeaceLove
         mixin_registry[target_class][field.to_s] = [:array, mod, options]
       end
 
+      def register_mixin_hash(target_class, field, mod, options)
+        mixin_registry[target_class][field.to_s] = [:hash, mod, options]
+      end
+
       def extend_doc(doc,mod,parent_obj)
+        # puts "extend_doc doc=#{doc.class} mod=#{mod} parent_obj=#{parent_obj.class}"
+
+        if !parent_obj.nil? && doc.nil?
+          doc = AngryHash.new
+        end
+
         doc.extend mod
-        doc.__parent_doc = parent_obj if doc.respond_to?(:__parent_doc=)
+
+        doc.__parent_doc = parent_doc if doc.respond_to?(:__parent_doc=)
+        doc
+      end
+
+      def setup_extended_doc(doc,mod)
+        mod.fill_in_defaults(doc) if mod.respond_to?(:fill_in_defaults)
         doc
       end
 
@@ -57,12 +77,15 @@ module PeaceLove
 
           case kind
           when :single
-            extend_doc(obj,mod,parent_obj)
+            obj = extend_doc(obj,mod,parent_obj)
           when :array
             # XXX - this is ok for now... we really need to typecheck, perhaps wrap in a smart-array
-
-
-            obj.map! {|elt| extend_doc elt, mod, parent_obj}
+            obj = obj.map {|elt| extend_doc(elt, mod, parent_obj)}
+          when :hash
+            obj = obj.inject(AngryHash.new) do |h,(k,elt)|
+              h[k] = extend_doc(elt,mod,parent_obj)
+              h
+            end
           end
         end
 
@@ -105,6 +128,19 @@ module PeaceLove
       def collection
         @collection
       end
+
+      def defaults(default_form=nil)
+        if default_form
+          @default_form = default_form
+        end
+        @default_form
+      end
+
+      def fill_in_defaults(doc)
+        if defaults
+          doc.reverse_deep_update(defaults)
+        end
+      end
       
       def sub_document(field,mod,options={})
         Doc.register_mixin(self,field,mod,options)
@@ -116,8 +152,13 @@ module PeaceLove
       end
       alias_method :sub_col, :sub_collection
 
+      def sub_hash(field,mod,options={})
+        Doc.register_mixin_hash(self,field,mod,options)
+      end
+
       def build(seed={})
         doc = AngryHash[ seed ]
+        self.fill_in_defaults(doc)
         doc.extend self
         doc
       end

data/peace_love.gemspec

@@ -5,17 +5,19 @@
 
 Gem::Specification.new do |s|
   s.name = %q{peace_love}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Lachie Cox"]
-  s.date = %q{2010-07-18}
+  s.date = %q{2010-08-02}
   s.description = %q{A simple mixin layer for enhancing hashes retrieved from MongoDB. It eschews the normal 'mapping' compulsion of mongo libraries.}
   s.email = %q{lachie@smartbomb.com.au}
   s.files = [
     ".gitignore",
      "Gemfile",
+     "License",
      "Rakefile",
+     "Readme.md",
      "VERSION",
      "examples/eg.helper.rb",
      "examples/usage.eg.rb",
@@ -31,13 +33,6 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.6}
   s.summary = %q{Peace, Love and Mongo.}
-  s.test_files = [
-    "examples/collections.eg.rb",
-     "examples/documents.eg.rb",
-     "examples/eg.helper.rb",
-     "examples/readme.eg.rb",
-     "examples/usage.eg.rb"
-  ]
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Lachie Cox
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-18 00:00:00 +10:00
+date: 2010-08-02 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -56,7 +56,9 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- License
 - Rakefile
+- Readme.md
 - VERSION
 - examples/eg.helper.rb
 - examples/usage.eg.rb
@@ -96,9 +98,5 @@ rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Peace, Love and Mongo.
-test_files: 
-- examples/collections.eg.rb
-- examples/documents.eg.rb
-- examples/eg.helper.rb
-- examples/readme.eg.rb
-- examples/usage.eg.rb
+test_files: []
+

data/examples/readme.eg.rb

@@ -1,58 +0,0 @@
-require 'eg.helper'
-require 'peace_love'
-
-PeaceLove.db = $db
-
-eg.setup do
-  PeaceLove['beans'].remove
-end
-
-module Bean
-  include PeaceLove::Doc
-  mongo_collection 'beans'
-
-  def is_a_bean?; true end
-end
-
-eg 'arthur' do
-  lima_bean  = { :name => 'lima' }
-  human_bean = { :name => 'Arthur', :prefered_drinks => %w[tea] }
-
-  PeaceLove['beans'].insert(lima_bean)
-  PeaceLove['beans'].insert(human_bean)
-
-  arthur = PeaceLove['beans'].find_one(:name => 'Arthur')
-
-  Show(arthur)
-
-  Show( arthur.prefered_drinks ) #=> [ 'tea' ]
-  Show( arthur.is_a_bean? )      #=> true
-
-  Show(arthur.is_a? Hash)
-  Show(arthur.class)
-
-  PeaceLove['beans'].update({:name => 'Arthur'}, '$push' => {'prefered_drinks' => 'pan-galactic gargle blaster'})
-  arthur = PeaceLove['beans'].find_one(:name => 'Arthur')
-
-  Show( arthur.prefered_drinks )
-end
-
-eg 'chaos taste' do
-  module Taste
-    def zesty?
-      spicy? && sour?
-    end
-  end
-
-  module Bean2
-    include PeaceLove::Doc
-    mongo_collection 'beans'
-    
-    sub_doc :taste, Taste
-  end
-
-  PeaceLove['beans'].mixin = Bean2
-
-  chaos = PeaceLove['beans'].build(:name => 'chaos', :taste => {:sour => true, :spicy => true})
-  Show( chaos.taste.zesty? ) #=> true
-end