memories 0.3.5 → 0.3.6

data/VERSION

@@ -0,0 +1 @@
+0.3.6

data/lib/memories/versions_proxy.rb

@@ -23,7 +23,7 @@ module Memories
 
     def count
       populate_proxies
-      @versions.count - 1
+      @versions.count == 0 ? 0 : @versions.count - 1
     end
 
     def [](arg)
@@ -43,7 +43,7 @@ module Memories
 
     private
     def populate_proxies
-      if (@versions.count - 1) < @doc.current_version.to_i
+      if !@doc.new_record? && (@versions.count - 1) < @doc.current_version.to_i
         (1..@doc.current_version.to_i).each do |i|
           @versions[i] ||= VersionProxy.new @doc, i
         end

data/readme.markdown

@@ -0,0 +1,191 @@
+#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 via the `milestones` array: 
+
+    a.milestones.count #==> 1
+    a.milestones.last.version # ==> 'rev-1-893428ifldlfds9832'
+    a.milestones.last.version_number # ==> 1
+    a.milestones.last.annotations.name # ==> "First publish."
+    a.milestones.last.annotations.notes # ==> "Passed all relevant editing. Signed off by moonmaster 10000"
+    a.milestones.last.instance.title # ==> Memories gem makes versioning simple
+
+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 "instance" method: 
+    
+    a.milestones.first.instance.title #==> returns the "title" attribute on the first milestone
+    a.milestones.each do |m|
+      puts "Version: " + m.version
+      puts "Title: " + m.instance.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].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
+

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: memories
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 31
   prerelease: 
   segments: 
   - 0
   - 3
-  - 5
-  version: 0.3.5
+  - 6
+  version: 0.3.6
 platform: ruby
 authors: 
 - Matt Parker
@@ -16,8 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-16 00:00:00 -04:00
-default_executable: 
+date: 2011-07-26 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: couchrest_model
@@ -35,7 +34,35 @@ dependencies:
         version: 1.0.0
   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 created by @jchris.moonmaster9000@gmail.com
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+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.
 email: moonmaster9000@gmail.com
 executables: []
 
@@ -44,13 +71,14 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/memories.rb
 - lib/memories/annotation.rb
 - lib/memories/attachment.rb
 - lib/memories/base.rb
 - lib/memories/milestones_proxy.rb
 - lib/memories/versions_proxy.rb
-has_rdoc: true
+- lib/memories.rb
+- VERSION
+- readme.markdown
 homepage: http://github.com/moonmaster9000/memories
 licenses: []
 
@@ -80,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.0
+rubygems_version: 1.8.5
 signing_key: 
 specification_version: 3
 summary: Versioning for your couchrest_model documents.