memories 0.3.0 → 0.3.1

data/README.markdown

@@ -131,36 +131,61 @@ If you want to access the version instance of a milestone, simply use the "data"
 By default, memories doesn't version attachments. If you'd like to version attachments, simply call the `remember_attachments!` class method in your 
 class definition: 
 
-  class MyDoc < CouchRest::Model::Base
-    use_database MY_DB
-    include Memories
+    class MyDoc < CouchRest::Model::Base
+      use_database MY_DB
+      include Memories
 
-    remember_attachments!
-  end
+      remember_attachments!
+    end
 
 If you only want specific attachments versioned, pass 
 strings and/or regular expressions to this macro. Any attachments
 with matching names will be versioned.
 
-  class HtmlPage < CouchRest::Model::Base
-    use_database MY_DB
-    include Memories
+    class HtmlPage < CouchRest::Model::Base
+      use_database MY_DB
+      include Memories
 
-    remember_attachments! "image.png", %r{stylesheets/.*}
-  end
+      remember_attachments! "image.png", %r{stylesheets/.*}
+    end
 
 ## Accessing Previous Versions
 
 You can access old versions of your document via the "versions" method; it will return a proxy with array-like and hash-like access to previous versions.
 
-  @doc.versions[1].instance # ==> returns version 1 of your document
-  @doc.versions[1].revision # ==> 'rev-1-jkfldsi32849032894032'
-  @doc.versions[1].version_number # ==> 1
-  @doc.versions['rev-1-kjfdsla3289430289432'].instance # ==> returns version 1 of your document
-  @doc.versions[1..7] # ==> returns version proxies 1 through 7 of your document
-  @doc.versions.count # ==> returns the number of versions of your document
-  @doc.versions.last # ==> returns the latest version of your document
-  @doc.versions.first # ==> returns the first version of your document
-  @doc.versions.each do |v|
-    puts v.some_property
-  end
+    @doc.versions[1].instance # ==> returns version 1 of your document
+    @doc.versions[1].revision # ==> 'rev-1-jkfldsi32849032894032'
+    @doc.versions[1].version_number # ==> 1
+    @doc.versions['rev-1-kjfdsla3289430289432'].instance # ==> returns version 1 of your document
+    @doc.versions[1..7] # ==> returns version proxies 1 through 7 of your document
+    @doc.versions.count # ==> returns the number of versions of your document
+    @doc.versions.last # ==> returns a proxy for the latest version of your document
+    @doc.versions.first # ==> returns a proxy for the first version of your document
+    @doc.versions.each do |v|
+      puts v.instance.some_property
+    end
+
+## Logical Revision Numbers
+
+As of version 0.3.1, when you soft revert a document (#revert_to), you can access the logical revision and logical version numbers of that document. 
+
+For example, suppose you soft revert a document with 10 versions to version 2. 
+    
+    @doc.current_version # ==> 10 
+    @doc.revert_to 2
+
+When you ask the logical revision, you'll receive the revision number of version 2:
+    
+    @doc.logical_revision #==> 'rev-2-kfdlsa432890432890432'
+
+Similarly, the logical version number:
+
+    @doc.logical_version_number #==> 2
+
+However, as soon as you save the document, the logical revision and logical version number will simply mirror those of the actual document
+    
+    @doc.save
+    @doc.rev #==> '11-qwerty1234567890'
+    @doc.logical_revision #==> 'rev-11-qwerty1234567890'
+    @doc.logical_version_number #==> 11
+

data/lib/memories/base.rb

@@ -17,6 +17,8 @@ module Memories
     base.before_update :add_version_attachment
     base.after_save :decode_attachments
     base.send :extend, ClassMethods
+    base.alias_method_chain :save, :destroying_logical_version_and_revision
+    base.alias_method_chain :save!, :destroying_logical_version_and_revision
   end
   
   module ClassMethods #:nodoc: all
@@ -313,6 +315,45 @@ module Memories
     self.milestones.last
   end
 
+  # When you soft revert a document, you can ask what the logical revision of it is.
+  # For example, suppose you soft revert a document with 10 versions to version 2. 
+  #     @doc.revert_to 2
+  # When you ask the logical revision, you'll receive the revision number of version 2:
+  #     @doc.logical_revision #==> 'rev-2-kfdlsa432890432890432'
+  # However, as soon as you save the document, the logical_revision will simply mirror the actual revision
+  #     @doc.save
+  #     @doc.rev #==> '11-qwerty1234567890'
+  #     @doc.logical_revision #==> 'rev-11-qwerty1234567890'
+  def logical_revision
+    @logical_revision || "rev-" + self.rev 
+  end
+
+  # When you soft revert a document, you can ask what the logical version number of it is.
+  # For example, suppose you soft revert a document with 10 versions to version 2. 
+  #   @doc.revert_to 2
+  # When you ask the logical version number, you'll receive 2:
+  #   @doc.logical_version_number #==> 2
+  # However, as soon as you save the document, the logical_revision will simply mirror the actual revision
+  #   @doc.save
+  #   @doc.current_version #==> 11
+  #   @doc.logical_version_number #==> 11
+  def logical_version_number
+    @logical_version_number || self.current_version
+  end
+
+  def save_with_destroying_logical_version_and_revision
+    @logical_version_number = nil
+    @logical_revision = nil
+    save_without_destroying_logical_version_and_revision
+  end
+
+  def save_with_destroying_logical_version_and_revision!
+    @logical_version_number = nil
+    @logical_revision = nil
+    save_without_destroying_logical_version_and_revision!
+  end
+
+
   private
   def verify_milestone_exists(n)
     raise StandardError, "This document does not have any milestones." if self.milestones.empty?
@@ -333,6 +374,8 @@ module Memories
     if properties = JSON.parse(self.read_attachment(version_id version))
       revert_attachments properties
       self.update_attributes_without_saving properties
+      @logical_version_number = version
+      @logical_revision = self.version_id version
       self.save if revert_type == :hard
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: memories
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 3
-  - 0
-  version: 0.3.0
+  - 1
+  version: 0.3.1
 platform: ruby
 authors: 
 - Matt Parker
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-12 00:00:00 -05:00
+date: 2011-01-15 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,9 +44,7 @@ extensions: []
 
 extra_rdoc_files: 
 - README.markdown
-- README.rdoc
 files: 
-- README.rdoc
 - lib/memories.rb
 - lib/memories/annotation.rb
 - lib/memories/attachment.rb

data/README.rdoc

@@ -1,163 +0,0 @@
-= 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
-
-== Documentation
-
-Browse the documentation on rubydoc.info: http://rubydoc.info/gems/memories/frames
-
-== 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
-
-If you'd like to explicitly define which properties to version, use the #remember method. It works just like #forget, but in reverse. Duh.
-
-=== 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.
-
-If you want to access the version instance of a milestone, simply use the "data" method: 
-    
-    a.milestones.first.data.title #==> returns the "title" attribute on the first milestone
-    a.milestones.each do |m|
-      puts "Version: " + m.version
-      puts "Title: " + m.data.title
-    end
-
-== Attachments
-
-By default, memories doesn't version attachments. If you'd like to version attachments, simply call the `remember\_attachments!` class method in your 
-class definition: 
-
-    class MyDoc < CouchRest::Model::Base
-      use_database MY_DB
-      include Memories
-
-      remember_attachments!
-    end
-
-If you only want specific attachments versioned, pass 
-strings and/or regular expressions to this macro. Any attachments
-with matching names will be versioned.
-
-    class HtmlPage < CouchRest::Model::Base
-      use_database MY_DB
-      include Memories
-
-      remember_attachments! "image.png", %r{stylesheets/.*}
-    end
-
-
-== Accessing Previous Versions
-
-You can access old versions of your document via the "versions" method; it will return a proxy with array-like and hash-like access to previous versions.
-
-    @doc.versions[1] # ==> returns version 1 of your document
-    @doc.versions['rev-1-kjfdsla3289430289432'] # ==> returns version 1 of your document
-    @doc.versions[1..20] # ==> returns versions 1 through 20 of your document
-    @doc.versions.count # ==> returns the number of versions of your document
-    @doc.versions.last # ==> returns the latest version of your document
-    @doc.versions.first # ==> returns the first version of your document
-    @doc.versions.each do |v|
-      puts v.some_property
-    end