memories 0.2.1 → 0.2.2

data/README.markdown

@@ -34,6 +34,34 @@ Here's how basic versioning works. Every time you save your document, you get a
     b.name #==> "2001"
     b.current_version #==> 3
 
+If you'd like to exclude certain properties from versioning, use the #forget class method:
+
+    class Book < CouchRest::Model::Base
+      include Memories
+      use_database SOME_DATABASE
+
+      forget :notes
+      
+      property :name
+      property :notes
+      view_by :name
+    end
+
+    b = Book.create :name => "2001", :notes => "creating the book."
+    b.current_version #==> 1
+    b.name = "2001: A Space Odyssey"
+    b.notes += "updating the title. might ship today. 9/2/2010. MKP"
+    b.save
+    b.current_version #==> 2
+    b.previous_version #==> 1
+    p b.name #==> "2001: A Space Odyssey"
+    p b.notes # ==> "creating the book. updating the title. might ship today. 9/2/2010. MKP"
+    b.revert_to! 1
+    p b.name #==> "2001"
+    p b.notes # ==> "creating the book. updating the title. might ship today. 9/2/2010. MKP"
+    b.current_version #==> 3
+
+
 ###Milestones
 
 As of version 0.2.0, Memories also supports milestones. Milestones are special versions that you want to flag in some way.

data/README.rdoc

@@ -0,0 +1,111 @@
+= Introduction
+
+A simple gem for adding versioning to your CouchRest::Model::Base documents. When you update a document, the previous version gets 
+stored as an attachment on the document. This versioning strategy was originally created here: http://blog.couch.io/post/632718824/simple-document-versioning-with-couchdb
+
+== Installation
+
+    $ gem install memories
+
+== How does it work?
+
+Just "include Memories" in your "CouchRest::Model::Base" classes and let the auto-versioning begin.
+
+=== Basic Versioning
+
+Here's how basic versioning works. Every time you save your document, you get a new version. You have the ability to roll back to a previous version.
+
+    class Book < CouchRest::Model::Base
+      include Memories
+      use_database SOME_DATABASE
+      
+      property :name
+      view_by :name
+    end
+
+    b = Book.create :name => "2001"
+    b.current_version #==> 1
+    b.name = "2001: A Space Odyssey"
+    b.save
+    b.current_version #==> 2
+    b.previous_version #==> 1
+    b.name #==> "2001: A Space Odyssey"
+    b.revert_to! 1
+    b.name #==> "2001"
+    b.current_version #==> 3
+
+If you'd like to exclude certain properties from versioning, use the #forget class method:
+
+    class Book < CouchRest::Model::Base
+      include Memories
+      use_database SOME_DATABASE
+
+      forget :notes
+      
+      property :name
+      property :notes
+      view_by :name
+    end
+
+    b = Book.create :name => "2001", :notes => "creating the book."
+    b.current_version #==> 1
+    b.name = "2001: A Space Odyssey"
+    b.notes += "updating the title. might ship today. 9/2/2010. MKP"
+    b.save
+    b.current_version #==> 2
+    b.previous_version #==> 1
+    p b.name #==> "2001: A Space Odyssey"
+    p b.notes # ==> "creating the book. updating the title. might ship today. 9/2/2010. MKP"
+    b.revert_to! 1
+    p b.name #==> "2001"
+    p b.notes # ==> "creating the book. updating the title. might ship today. 9/2/2010. MKP"
+    b.current_version #==> 3
+
+=== Milestones
+
+As of version 0.2.0, Memories also supports milestones. Milestones are special versions that you want to flag in some way.
+For example, suppose you were creating a content management system, and every time someone publishes an article to the website, you want to flag the version
+they published as a milestone. 
+
+    class Article < CouchRest::Model::Base
+      include Memories
+      use_database SOME_DATABASE
+      
+      property :title
+      property :author
+      property :body
+
+      def publish!
+        # .... publishing logic
+      end
+    end
+
+    a = Article.create(
+      :title => "Memories gem makes versioning simple", 
+      :author => "moonmaster9000", 
+      :body => <<-ARTICLE
+        Check it out at http://github.com/moonmaster9000/memories
+      ARTICLE
+    )
+    a.save
+    a.publish!
+    a.current_version #==> 1 
+    a.milestone! do
+      name "First publish."
+      notes "Passed all relevant editing. Signed off by moonmaster10000"
+    end
+
+Notice that we annotated our milestone; we gave it a name, and some notes. You can annotate with whatever properties you desire. The annotation do block is entirely optional.
+Now that we've created a milestone, let's inspect it: 
+
+    a.milestones.count #==> 1
+    a.latest_milestone.version # ==> 1
+    a.latest_milestone.annotations.name ==> "First publish."
+    a.latest_milestone.annotations.notes ==> "Passed all relevant editing. Signed off by moonmaster 10000"
+
+Now, let's imagine that we've made some more edits / saves to the document, but they don't get approved. Now we want to revert to the version the document was
+at at the first milestone. How do we do that? Simple!
+
+    a.revert_to_milestone! 1
+
+And now our document properties are back to the where they were when we first published the document.

data/lib/memories/annotation.rb

@@ -1,5 +1,5 @@
 module Memories
-  class Annotation < Hash
+  class Annotation < Hash #:nodoc:
     def method_missing(method_name, *args, &block)
       if args.empty?
         self[method_name]

data/lib/memories/attachment.rb

@@ -1,5 +1,5 @@
 module Memories
-  class Attachment
+  class Attachment #:nodoc:
     def initialize(string)
       @string = string
     end

data/lib/memories/base.rb

@@ -1,3 +1,4 @@
+# Simply "include Memories" in your CouchRest::Model::Base derived classes to add versioning to your document.
 module Memories
   def self.included(base)
     base.property(:milestone_memories) do |milestone_memory|
@@ -7,60 +8,120 @@ module Memories
 
     base.before_update :add_version_attachment
     base.after_update :decode_attachments
+    base.send :extend, ClassMethods
   end
   
-  VERSION_REGEX = /(?:rev-)?(\d+)-[a-zA-Z0-9]+/
+  module ClassMethods
+    # If you'd like to exclude certain properties from versioning, simply pass those properties
+    # to this method: 
+    #   
+    #   class MyDocument < CouchRest::Model::Base
+    #     use_database MY_DATABASE
+    #     forget :prop1, :prop2
+    #
+    #     property :prop1 #not versioned
+    #     property :prop2 #not versioned
+    #     property :prop3 #versioned
+    #   end
+    def forget(*props)
+      self.forget_properties += props.map {|p| p.to_s}
+    end
+
+    def forget_properties #:nodoc:
+      @forget_properties ||= ["couchrest-type", "_id", "_rev", "_attachments", "milestone_memories"]
+    end
 
+    def forget_properties=(props) #:nodoc:
+      @forget_properties = props
+    end
+  end
+  
+  VERSION_REGEX = /(?:rev-)?(\d+)-[a-zA-Z0-9]+/
+  
+  # Revert the document to a specific version and save. 
+  # You can provide either a complete revision number ("1-u54abz3948302sjjej3jej300rj", or "rev-1-u54abz3948302sjjej3jej300rj")
+  # or simply a number (e.g, 1, 4, 100, etc.).
+  #   my_doc.revert_to! 3 # ==> would revert your document "my_doc" to version 3. 
   def revert_to!(version)
     revert version, :hard
   end
 
+  # Same as #revert_to!, except that it doesn't save.
   def revert_to(version)
     revert version
   end
 
+  # Same as #rollback!, but doesn't save.
   def rollback
     self.revert_to self.previous_version
   end
 
+  # Revert to the previous version, and resave the document. Shortcut for:
+  #   my_doc.revert_to! my_doc.previous_version
   def rollback!
     self.revert_to! self.previous_version
   end
 
+  # Revert to a given milestone and save. Milestones are stored in the .milestones array.
+  # Reverting to milestone "n" reverts to milestone represented in the nth element in the 
+  # milestones array.
   def revert_to_milestone!(n)
     verify_milestone_exists n
     self.revert_to! self.milestones[n.to_i-1].version
   end
-  
+ 
+  # Same as #revert_to_milestone!, except it doesn't save.
   def revert_to_milestone(n)
     verify_milestone_exists n
     self.revert_to self.milestones[n.to_i-1].version
   end
-  
+ 
+  # Same as #rollback_to_latest_milestone, but doesn't save. 
   def rollback_to_latest_milestone
     self.revert_to_milestone self.milestones.count
   end
 
+  # Reverts to the latest milestone. Shortcut for:
+  #   my_doc.revert_to_milestone! my_doc.milestones.count
   def rollback_to_latest_milestone!
     self.revert_to_milestone! self.milestones.count
   end
-  
+ 
+  # Retrieve the entire revision number, given an integer. 
+  # For example, suppose my doc has 5 versions. 
+  #   my_doc.version_id 4 #==> "rev-4-74fj838r838fhjkdfklasdjrieu4839493"
   def version_id(version_num)
     self["_attachments"].keys.sort {|a,b| version_number(a) <=> version_number(b)}[version_num - 1] if self["_attachments"]
   end
 
+  # Retrieve the version number, given a revision id. 
+  # For example,
+  #   my_doc.version_number "rev-5-kjfldsjaiu932489023rewar" #==> 5
+  #   my_doc.version_number "4-jkfldsjli3290843029irelajfldsa" # ==> 4
   def version_number(version_id)
     version_id.gsub(VERSION_REGEX, '\1').to_i
   end
 
+  # Shortcut for:
+  #   my_doc.current_version - 1
   def previous_version
     current_version - 1
   end
 
+  # Returns a simple version number (integer) corresponding to the current revision. 
+  # For example, suppose the current revision (_rev) is: "4-jkfdlsi9432943wklrejwalr94302". 
+  #   my_doc.current_version #==> 4
   def current_version
     version_number rev
   end
 
+  # Flag the current version as a milestone. You can optionally annotate the milestone by passing a do block to the method.
+  #   some_article.milestone! do
+  #     notes "Passed first round of editing."
+  #     approved_by "Joe the editor."
+  #   end
+  # 
+  # You may annotate with whatever properties you desire. "notes" and "approved_by" were simply examples.
   def milestone!(&block)
     annotations = Memories::Annotation.new
     annotations.instance_eval(&block) if block
@@ -68,10 +129,14 @@ module Memories
     self.save
   end
 
+  # returns an array of all milestones. Each milestone contains a "version" property (pointing to a specific revision)
+  # and an "annotations" property, containing a (possible empty) hash of key/value pairs corresponding to any annotations
+  # the creator of the milestone decided to write.
   def milestones
     self.milestone_memories
   end
 
+  # Returns the metadata (version, annotations) for the latest milestone created.
   def latest_milestone
     self.milestone_memories.last
   end
@@ -109,7 +174,7 @@ module Memories
   end
 
   def prep_for_versioning(doc)
-    doc.dup.delete_if {|k,v| ["couchrest-type", "_id", "_rev", "_attachments", "milestone_memories"].include? k}
+    doc.dup.delete_if {|k,v| self.class.forget_properties.include? k}
   end
 
   def decode_attachments

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: memories
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Matt Parker
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-29 00:00:00 -04:00
+date: 2010-09-04 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,7 +35,7 @@ dependencies:
         version: 1.0.0.beta7
   type: :runtime
   version_requirements: *id001
-description: CouchDB has built in document versioning, but you can't rely on it for version control. This is an implementation of a version-as-attachments approach suggested by @jchris.moonmaster9000@gmail.com
+description: CouchDB has built in document versioning, but you can't rely on it for version control. This is an implementation of a version-as-attachments approach created by @jchris.moonmaster9000@gmail.com
 email: moonmaster9000@gmail.com
 executables: []
 
@@ -43,7 +43,9 @@ extensions: []
 
 extra_rdoc_files: 
 - README.markdown
+- README.rdoc
 files: 
+- README.rdoc
 - lib/memories.rb
 - lib/memories/annotation.rb
 - lib/memories/attachment.rb