memories 0.2.0 → 0.2.1

data/README.markdown

@@ -0,0 +1,84 @@
+#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
+
+###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/base.rb

@@ -1,7 +1,7 @@
 module Memories
   def self.included(base)
     base.property(:milestone_memories) do |milestone_memory|
-      milestone_memory.property :version, Fixnum
+      milestone_memory.property :version
       milestone_memory.property :annotations, Memories::Annotation
     end
 
@@ -11,21 +11,40 @@ module Memories
   
   VERSION_REGEX = /(?:rev-)?(\d+)-[a-zA-Z0-9]+/
 
-  def revert_to!(version=nil)
-    version ||= previous_version
-    if (match = version.to_s.match(VERSION_REGEX)) && match[1]
-      version = match[1].to_i  
-    end
-    
-    if properties = JSON.parse(read_attachment(version_id version))
-      self.update_attributes properties
-    end
+  def revert_to!(version)
+    revert version, :hard
+  end
+
+  def revert_to(version)
+    revert version
+  end
+
+  def rollback
+    self.revert_to self.previous_version
+  end
+
+  def rollback!
+    self.revert_to! self.previous_version
   end
 
   def revert_to_milestone!(n)
+    verify_milestone_exists n
     self.revert_to! self.milestones[n.to_i-1].version
   end
   
+  def revert_to_milestone(n)
+    verify_milestone_exists n
+    self.revert_to self.milestones[n.to_i-1].version
+  end
+  
+  def rollback_to_latest_milestone
+    self.revert_to_milestone self.milestones.count
+  end
+
+  def rollback_to_latest_milestone!
+    self.revert_to_milestone! self.milestones.count
+  end
+  
   def version_id(version_num)
     self["_attachments"].keys.sort {|a,b| version_number(a) <=> version_number(b)}[version_num - 1] if self["_attachments"]
   end
@@ -45,7 +64,7 @@ module Memories
   def milestone!(&block)
     annotations = Memories::Annotation.new
     annotations.instance_eval(&block) if block
-    self.milestone_memories << {:version => self.current_version, :annotations => annotations}
+    self.milestone_memories << {:version => self.rev, :annotations => annotations}
     self.save
   end
 
@@ -58,6 +77,27 @@ module Memories
   end
 
   private
+  def verify_milestone_exists(n)
+    raise StandardError, "This document does not have any milestones." if self.milestones.empty?
+    raise StandardError, "Unknown milestone" if n > self.milestones.count
+  end
+
+  def revert(version, revert_type = :soft)
+    raise StandardError, "Unknown revert type passed to 'revert' method. Allowed types: :soft, :hard." if revert_type != :soft && revert_type != :hard
+
+    if (match = version.to_s.match(VERSION_REGEX)) && match[1]
+      version = match[1].to_i  
+    end
+    
+    if properties = JSON.parse(read_attachment(version_id version))
+      if revert_type == :soft
+        self.update_attributes_without_saving properties
+      elsif revert_type == :hard
+        self.update_attributes properties
+      end
+    end
+  end
+
   def add_version_attachment
     current_document_version = Attachment.new prep_for_versioning(self.database.get(self.id, :rev => self.rev)).to_json
     

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: memories
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Matt Parker
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-28 00:00:00 -04:00
+date: 2010-08-29 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,13 +41,14 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.markdown
 files: 
 - lib/memories.rb
 - lib/memories/annotation.rb
 - lib/memories/attachment.rb
 - lib/memories/base.rb
+- README.markdown
 has_rdoc: true
 homepage: http://github.com/moonmaster9000/memories
 licenses: []