simply_versioned 0.9.3.2

data/CHANGES

@@ -0,0 +1,51 @@
+0.9.3.1 - 20-05-2008 Jérôme Lipowicz
+
+Pragmatic branch (using dirty parameters, rails 2.1 only)
+New records are not versioned: two versions are created at once  upon first record update.
+Unchanged records are not versioned too.
+
+0.9.3	- 28-01-2008
+
+Fixed #version_number to versioned instances as a shortcut
+
+0.9.2 - 28-01-2008
+
+Fixed :exclude => :column now equivalent to :exclude => [:column]
+
+0.9.1 - 24-01-2008
+
+Improved implementation of revert_to_version with further tests.
+Provided clean aliases for methods in VersionProxy.
+
+0.9 - 24-01-2008
+
+Added an :exclude option (default: [])
+
+0.8 - 08-01-2008
+
+Added an :automatic option (default: true)
+
+0.7 - 04-01-2008
+
+The without_versioning method becomes with_versioning( exp )
+
+0.6 - 01-01-2008
+
+The default is now to keep all versions, specify :keep if you want to set a limit.
+Dropped the updated_at column from revisions as unnecessary.
+
+0.5 - 30-12-2007
+
+The revert_to_version call now takes an :except => [:name,:and,:so,:on] list of attributes whose value will not be reverted. The defautl is [:created_at,:updated_at].
+
+0.4 - 30-12-2007
+
+Changed some method names to reduce possibility of conflicts. Added more tests. Changed some method implementations w.r.t. empty versions to try and tease out a bug in production.
+
+0.3 - 30-12-2007
+
+Added versioning_enabled? and without_versioning( &block ) to allow save without a version being generated.
+
+0.2 - 30-12-2007
+
+Added a test & some documentation, shaved a yak or two

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Matt Mower
+
+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/README

@@ -0,0 +1,140 @@
+SimplyVersioned
+===============
+
+Release:	0.9.3.2
+Date:			05-04-2010
+Author:		Matt Mower <self@mattmower.com>
+Fork:			Jerôme Lipowicz <yayel.com>
+
+SimplyVersioned is a simple, non-invasive, approach to versioning ActiveRecord models.
+
+SimplyVersioned does not require any structural change to the models to be versioned and requires only one versions table to be created (a migration generator is supplied with the plugin) regardless of the number of models being versioned.
+
+The plugin introduces a 'Version' ActiveRecord model (that reflects changes to model attributes) to which versioned models are polymorphically associated. Version records store the model information as a YAML hash.
+	
+SimplyVersioned meets a simple need for model versioning. If your needs are more complex maybe try Rick Olsen's acts_as_versioned (http://svn.techno-weenie.net/projects/plugins/acts_as_versioned/).
+
+SimplyVersioned is only compatible with Rails 2.1. This pragmatic branch only versions altered records.
+
+Usage
+=====
+
+1. Install the lib
+
+  1.1 as a plugin:
+  
+  ./script/plugin install git://github.com/jerome/simply_versioned.git
+  
+  1.2 or as a gem:
+  
+  gem install simply_versioned
+  
+  # environment.rb
+  config.gem "simply_versioned" 
+
+2. Generate the migration
+
+  ./script/generate simply_versioned_migration
+
+	Note that the migration defaults to storing the version info in a TEXT field. On MySQL this will default to a
+	limit of 64K. If you are versioning particularly large models you will want to modify the migration to include
+	a :limit => n condition to promote the yaml column to a MEDIUMTEXT or (god forbid) a LONGTEXT.
+
+3. Create the versions table
+
+  rake db:migrate
+
+4. Annotate the models you want to version specifying how many versions to keep
+
+	class Thing < ActiveRecord::Base
+	  simply_versioned :keep => 10
+	end
+	
+	If you do not specify a limit then old versions are never automatically deleted. You can
+	manually delete them like this:
+	
+	thing.versions.purge( 10 )
+	
+	which would delete all the but the last ten versions.
+	
+	If you want fine-grained control over when versions are created you can use:
+	
+	class Thing < ActiveRecord::Base
+		simply_versioned :automatic => false
+	end
+	
+	and new versions will no longer be created by default. You will then need to use
+	the with_versioning method to create a version.
+	
+	Lastly you can control which columns will be versioned by specifying an exclude parameter.
+	
+	class Thing < ActiveRecord::Base
+		simply_versioned :exclude => :awkward_column
+	end
+		
+	or	
+	
+	class Thing < ActiveRecord::Base
+		simply_versioned :exclude => [:first_awkward_column,:second_awkward_column,...]
+	end
+	
+	This may be helpful if you run into conflicts with other plugins which try to manage columns.
+
+5. Create versions
+
+	thing = Thing.create!( :foo => bar ) # creates v1
+	thing.foo = baz
+	thing.save! # creates v2
+	
+	If you need to control whether a version is created or not, use #with_versioning. For example:
+	
+	thing.with_versioning( false ) do |t|
+		t.save!
+	end
+	
+	or, using the "magic pen" (http://dablog.rubypal.com/2007/2/18/the-magic-pens-of-ruby thanks hmj):
+	
+	thing.with_versioning( false, &:save! )
+
+6. Find versions
+
+	thing.versions.each do |version| ... end
+	render :partial => 'thing_version', :collection => thing.versions
+	thing.versions.current
+	thing.versions.first
+	thing.versions.get( 3 )
+	
+	To find a version number:
+	
+	thing.version_number
+
+7. Revert to a previous version
+
+	thing.revert_to_version( 5 )
+	
+	If a specific reversion needs to avoid overwriting some column values pass
+	an :except option, e.g.
+	
+	thing.revert_to_version( 1, :except => [:name,:age] )
+	
+	The revert_to_version method also takes an existing Version instance, e.g.
+	
+	version = thing.versions.find( ... )
+	thing.revert_to_version( version )
+
+8. Traverse versions
+
+	thing.versions.current.previous
+	thing.versions.first.next
+
+9. Obtain a copy of a previous versioned model
+
+	thing.versions.first.model # => Instantiated Thing with versioned values
+	
+Thanks to:
+
+	Josh Susser (http://blog.hasmanythrough.com/) for useful suggestions and feedback
+	Rick Olson (http://techno-weenie.net/) for all the many plugins whose code i've read
+	
+Copyright (c) 2007 Matt Mower <self@mattmower.com> and released under the MIT license
+Copyright (c) 2008 Jérôme Lipowicz <yayel.com> and released under the MIT license

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the simply_versioned plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the simply_versioned plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SimplyVersioned'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc 'Measures test coverage using rcov'
+task :rcov do
+  rm_f "coverage"
+  rm_f "coverage.data"
+  rcov = "rcov --rails --aggregate coverage.data --text-summary -Ilib"
+  system("#{rcov} --html #{Dir.glob('test/**/*_test.rb').join(' ')}")
+  system("open coverage/index.html") if PLATFORM['darwin']
+end

data/generators/simply_versioned_migration/simply_versioned_migration_generator.rb

@@ -0,0 +1,11 @@
+class SimplyVersionedMigrationGenerator < Rails::Generator::Base 
+  def manifest 
+    record do |m| 
+      m.migration_template 'migration.rb', 'db/migrate' 
+    end 
+  end
+  
+  def file_name
+    "simply_versioned_migration"
+  end
+end

data/generators/simply_versioned_migration/templates/migration.rb

@@ -0,0 +1,18 @@
+class SimplyVersionedMigration < ActiveRecord::Migration
+  
+  def self.up
+    create_table :versions do |t|
+      t.integer   :versionable_id
+      t.string    :versionable_type
+      t.integer   :number
+      t.text      :yaml
+      t.datetime  :created_at
+    end
+    
+    add_index :versions, [:versionable_id, :versionable_type]
+  end
+  
+  def self.down
+    drop_table :versions
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'simply_versioned'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/simply_versioned.rb

@@ -0,0 +1,229 @@
+# SimplyVersioned 0.9.3
+#
+# Simple ActiveRecord versioning
+# Copyright (c) 2007,2008 Matt Mower <self@mattmower.com>
+# Released under the MIT license (see accompany MIT-LICENSE file)
+#
+
+module SoftwareHeretics
+  
+  module ActiveRecord
+  
+    module SimplyVersioned
+      
+      class BadOptions < StandardError
+        def initialize( keys )
+          super( "Keys: #{keys.join( "," )} are not known by SimplyVersioned" )
+        end
+      end
+      
+      module ClassMethods
+        
+        # Marks this ActiveRecord model as being versioned. Calls to +create+ or +save+ will,
+        # in future, create a series of associated Version instances that can be accessed via
+        # the +versions+ association.
+        #
+        # Options:
+        # +limit+ - specifies the number of old versions to keep (default = nil, never delete old versions)
+        # +automatic+ - controls whether versions are created automatically (default = true, save versions)
+        # +exclude+ - specify columns that will not be saved (default = [], save all columns)
+        #
+        # To save the record without creating a version either set +versioning_enabled+ to false
+        # on the model before calling save or, alternatively, use +without_versioning+ and save
+        # the model from its block.
+        #
+        
+        def simply_versioned( options = {} )
+          bad_keys = options.keys - [:keep,:automatic,:exclude]
+          raise SimplyVersioned::BadOptions.new( bad_keys ) unless bad_keys.empty?
+          
+          options.reverse_merge!( {
+            :keep => nil,
+            :automatic => true,
+            :exclude => [:updated_at, :position]
+          })
+          
+          has_many :versions, :order => 'number DESC', :as => :versionable, :dependent => :destroy, :extend => VersionsProxyMethods
+
+          before_save :save_new_record_status
+          before_save :simply_versioned_keep_dirty_version
+          after_save  :simply_versioned_create_versions
+          after_save  :unset_new_record_status
+                              
+          cattr_accessor :simply_versioned_keep_limit
+          self.simply_versioned_keep_limit = options[:keep]
+          
+          cattr_accessor :simply_versioned_save_by_default
+          self.simply_versioned_save_by_default = options[:automatic]
+          
+          cattr_accessor :simply_versioned_excluded_columns
+          self.simply_versioned_excluded_columns = Array( options[ :exclude ] ).map( &:to_s )
+          
+          class_eval do
+            def versioning_enabled=( enabled )
+              self.instance_variable_set( :@simply_versioned_enabled, enabled )
+            end
+            
+            def versioning_enabled?
+              enabled = self.instance_variable_get( :@simply_versioned_enabled )
+              if enabled.nil?
+                enabled = self.instance_variable_set( :@simply_versioned_enabled, self.simply_versioned_save_by_default )
+              end
+              enabled
+            end
+          end
+        end
+
+      end
+
+      # Methods that will be defined on the ActiveRecord model being versioned
+      module InstanceMethods
+        
+        # Revert the attributes of this model to their values as of an earlier version.
+        #
+        # Pass either a Version instance or a version number.
+        #
+        # options:
+        # +except+ specify a list of attributes that are not restored (default: created_at, updated_at)
+        #
+        def revert_to_version( version, options = {} )
+          options.reverse_merge!({
+            :except => [:created_at,:updated_at]
+          })
+          
+          version = if version.kind_of?( Version )
+            version
+          elsif version.kind_of?( Fixnum )
+            self.versions.find_by_number( version )
+          end
+          
+          raise "Invalid version (#{version.inspect}) specified!" unless version
+          
+          options[:except] = options[:except].map( &:to_s )
+          
+          self.update_attributes( YAML::load( version.yaml ).except( *options[:except] ) )
+        end
+        
+        # Invoke the supplied block passing the receiver as the sole block argument with
+        # versioning enabled or disabled depending upon the value of the +enabled+ parameter
+        # for the duration of the block.
+        def with_versioning( enabled, &block )
+          versioning_was_enabled = self.versioning_enabled?
+          self.versioning_enabled = enabled
+          begin
+            block.call( self )
+          ensure
+            self.versioning_enabled = versioning_was_enabled
+          end
+        end
+        
+        def unversioned?
+          self.versions.nil? || self.versions.size == 0
+        end
+        
+        def versioned?
+          !unversioned?
+        end
+        
+        def version_number
+          if self.versions.empty?
+            0
+          else
+            self.versions.current.number
+          end
+        end
+        
+        protected
+        
+        def save_new_record_status
+          @was_new_record = self.new_record?
+          true
+        end
+
+        def unset_new_record_status
+          @was_new_record = false
+          true
+        end
+        
+        def simply_versioned_keep_dirty_version
+          changed_attr = self.changes.except(*simply_versioned_excluded_columns)
+          @dirty_attributes = if self.versioning_enabled? && !self.new_record? && !changed_attr.empty?
+            changed_attr.each {|k,v| changed_attr[k] = v.first }
+          else
+            { }
+          end
+          true
+        end
+        
+        def simply_versioned_create_versions
+          # new or unchanged records are not versioned while first time
+          # versioning will create two versions in the same time
+          unless @was_new_record
+            if self.versioning_enabled? && !@dirty_attributes.empty?
+              if self.unversioned?
+                self.versions.create( :yaml => self.attributes.except( *simply_versioned_excluded_columns).merge(@dirty_attributes).to_yaml )
+              end
+
+              if self.versions.create( :yaml => self.attributes.except( *simply_versioned_excluded_columns ).to_yaml )
+                self.versions.clean_old_versions( simply_versioned_keep_limit.to_i ) if simply_versioned_keep_limit
+              end
+            end
+          end
+          true
+        end
+        
+      end
+
+      module VersionsProxyMethods
+        
+        # Get the Version instance corresponding to this models for the specified version number.
+        def get_version( number )
+          find_by_number( number )
+        end
+        alias_method :get, :get_version
+        
+        # Get the first Version corresponding to this model.
+        def first_version
+          find( :first, :order => 'number ASC' )
+        end
+        alias_method :first, :first_version
+
+        # Get the current Version corresponding to this model.
+        def current_version
+          find( :first, :order => 'number DESC' )
+        end
+        alias_method :current, :current_version
+        
+        # If the model instance has more versions than the limit specified, delete all excess older versions.
+        def clean_old_versions( versions_to_keep )
+          find( :all, :conditions => [ 'number <= ?', self.maximum( :number ) - versions_to_keep ] ).each do |version|
+            version.destroy
+          end
+        end
+        alias_method :purge, :clean_old_versions
+        
+        # Return the Version for this model with the next higher version
+        def next_version( number )
+          find( :first, :order => 'number ASC', :conditions => [ "number > ?", number ] )
+        end
+        alias_method :next, :next_version
+        
+        # Return the Version for this model with the next lower version
+        def previous_version( number )
+          find( :first, :order => 'number DESC', :conditions => [ "number < ?", number ] )
+        end
+        alias_method :previous, :previous_version
+      end
+
+      def self.included( receiver )
+        receiver.extend         ClassMethods
+        receiver.send :include, InstanceMethods
+      end
+    
+    end
+  
+  end
+
+end
+
+ActiveRecord::Base.send( :include, SoftwareHeretics::ActiveRecord::SimplyVersioned )