vidibus-versioning 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Andre Pankratz
+
+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.md

@@ -0,0 +1,111 @@
+# Vidibus::Versioning [![](http://travis-ci.org/vidibus/vidibus-versioning.png)](http://travis-ci.org/vidibus/vidibus-versioning) [![](http://stillmaintained.com/vidibus/vidibus-versioning.png)](http://stillmaintained.com/vidibus/vidibus-versioning)
+
+Vidibus::Versioning provides advanced versioning for Mongoid models including support for future and editable versions.
+
+This gem is part of [Vidibus](http://vidibus.org), an open source toolset for building distributed (video) applications.
+
+
+## Installation
+
+Add `gem "vidibus-versioning"` to your Gemfile. Then call `bundle install` on your console.
+
+
+## Usage
+
+To apply versioning to your model is easy. An example:
+
+```ruby
+class Article
+  include Mongoid::Document
+  include Vidibus::Uuid::Mongoid
+  include Vidibus::Versioning::Mongoid # this is mandatory
+
+  field :title, :type => String
+  field :text, :type => String
+
+  versioned :title, :text, :editing_time => 300 # this is optional
+end
+```
+
+### Versioned attributes
+
+Including the versioning engine by adding `include Vidibus::Versioning::Mongoid` will set all fields of your model as
+versioned ones, except those contained in `Article.unversioned_attributes`, which are `_id`, `_type`, `uuid`,
+`updated_at`, `created_at`, and `version_number`.
+
+An optional `versioned` call lets you specify the versioned attributes precisely by providing a list. For example, to
+set the title as only attribute to be versioned, call `versioned :title`.
+
+
+### Combined versioning
+
+`versioned` also takes options to tweak versioning behaviour. By calling `versioned :editing_time => 300` you set a
+timespan for the version to accept changes so all changes within 300 seconds will be treated as one version.
+That behaviour is especially useful if your model's UI allows changing attributes separately, like in-place editing.
+
+
+### Migrating
+
+The basic methods for migrating a versioned object - an article in this case - are:
+
+```ruby
+article.migrate!(32) # migrates to version 32
+article.undo!        # restores previous version
+article.redo!        # restores next version
+```
+
+
+### Version editing
+
+There is also a method `version` that loads an exisiting version of the record or instantiates a new one:
+
+```ruby
+article.version(3)            # returns version 3 of the article
+article.version(:previous)    # returns the previous version of the article
+article.version(:next)        # returns the next version of the article
+article.version(:new)         # returns a new version of the article
+```
+
+To apply a version on the current article itself, call `version` with a bang!:
+
+```ruby
+  article.version!(3) # applies version 3 to the article and returns nil
+```
+
+It is even possible to apply versioned attributes directly by adding it to the `version` call:
+
+```ruby
+  article.version(3, :title => "Wicked!") # returns version 3 with a new title applied
+```
+
+You may treat the article object with an applied version like the article itself. All changes will
+be applied to the loaded version instead of the current instance. An example:
+
+```ruby
+article.version!(3)         # applies version 3
+article.title = "Brand new" # sets a new title
+article.save                # saves version 3 of the article
+article.reload              # loads the current version of the article
+```
+
+
+### Version objects
+
+All versions of your models are stored in a separate model: `Vidibus::Versioning::Version`. To access the
+version object of an article's version, call `article.version_object`:
+
+```ruby
+article.version(3).version_object # => #<Vidibus::Versioning::Version ... >
+article.version_object            # => nil
+```
+
+
+## TODO
+
+* Handle embedded documents
+* Handle related documents
+
+
+## Copyright
+
+Copyright (c) 2011 Andre Pankratz. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,25 @@
+require "bundler"
+require "rdoc/task"
+require "rspec"
+require "rspec/core/rake_task"
+
+Bundler::GemHelper.install_tasks
+
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "vidibus/versioning/_version"
+
+RSpec::Core::RakeTask.new(:rcov) do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.rcov = true
+  t.rcov_opts = ["--exclude", "^spec,/gems/"]
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "vidibus-sysinfo #{Vidibus::Versioning::VERSION}"
+  rdoc.rdoc_files.include("README*")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+  rdoc.options << "--charset=utf-8"
+end
+
+task :default => :rcov

data/lib/vidibus/versioning/_version.rb

@@ -0,0 +1,5 @@
+module Vidibus
+  module Versioning
+    VERSION = "0.1.0"
+  end
+end

data/lib/vidibus/versioning/errors.rb

@@ -0,0 +1,6 @@
+module Vidibus
+  module Versioning
+    class Error < StandardError; end
+    class MigrationError < Error; end
+  end
+end

data/lib/vidibus/versioning/mongoid.rb

@@ -0,0 +1,281 @@
+module Vidibus
+  module Versioning
+    module Mongoid
+      extend ActiveSupport::Concern
+
+      included do
+        include ::Mongoid::Timestamps
+        include Vidibus::Uuid::Mongoid
+
+        has_many :versions, :as => :versioned, :class_name => "Vidibus::Versioning::Version", :dependent => :destroy
+
+        field :version_number, :type => Integer, :default => 1
+
+        after_initialize :original_attributes
+        before_update :reset_version_cache
+
+        mattr_accessor :versioned_attributes, :unversioned_attributes, :versioning_options
+        self.versioned_attributes = []
+        self.unversioned_attributes = %w[_id _type uuid updated_at created_at version_number]
+        self.versioning_options = {}
+
+        # Returns the attributes that should be versioned.
+        # If no versioned attributes have been defined on class level,
+        # all attributes will be returned except the unversioned ones.
+        def versioned_attributes
+          if self.class.versioned_attributes.any?
+            attributes.only(self.class.versioned_attributes)
+          else
+            attributes.except(self.class.unversioned_attributes)
+          end
+        end
+      end
+
+      module ClassMethods
+
+        # Defines versioned attributes and options
+        #
+        # Usage:
+        #   versioned :some, :fields, :editing_time => 300
+        #
+        def versioned(*args)
+          options = args.extract_options!
+
+          self.versioned_attributes = args.map {|a| a.to_s} if args.any?
+          self.versioning_options = options if options.any?
+        end
+      end
+
+      # Returns a copy of this object with versioned attributes applied.
+      #
+      # Valid arguments are:
+      #   :new       returns a new version of self
+      #   :next      returns the next version of self, may be new as well
+      #   :previous  returns the previous version of self
+      #   48         returns version 48 of self
+      #
+      def version(*args)
+        self.class.find(_id).tap do |copy|
+          copy.apply_version!(*args)
+        end
+      end
+
+      # Applies versioned attributes on this object. Returns nil.
+      # For valid arguments, see #version.
+      #
+      def version!(*args)
+        self.apply_version!(*args)
+      end
+
+      # Applies attributes of wanted version on self.
+      # Stores current attributes in a new version.
+      def migrate!(number = nil)
+        raise(MigrationError, "no version given") unless number or version_cache.wanted_version_number
+        version!(number) if number and number != version_cache.wanted_version_number
+        raise(MigrationError, "cannot migrate to current version") if version_cache.self_version
+
+        set_original_version_obj
+
+        self.attributes = version_attributes
+        self.version_number = version_cache.wanted_version_number
+        save!
+      end
+
+      # Calls #version!(:previous) and migrate!
+      def undo!
+        version!(:previous)
+        migrate!
+      end
+
+      # Calls #version!(:next) and migrate!
+      def redo!
+        version!(:next)
+        migrate!
+      end
+
+      # Saves the record and handles version persistence.
+      def save(*args)
+        return false if invalid?
+        saved = persist_version
+        (saved == nil) ? super(*args) : saved
+      end
+
+      # Raises a validation error if saving fails.
+      def save!(*args)
+        raise(::Mongoid::Errors::Validations, self) unless save(*args)
+      end
+
+      def delete
+        super if remove_version(:delete) == nil
+      end
+
+      def destroy
+        super if remove_version(:destroy) == nil
+      end
+
+      # Reloads this record and applies version attributes.
+      def reload_version(*args)
+        reloaded_self = self.reload
+        reloaded_self.version(*version_cache.version_args) if version_cache.version_args
+        reloaded_self
+      end
+
+      # Returns the currently set version object.
+      def version_object
+        version_cache.version_obj
+      end
+
+      # Returns true if version requested is a new one.
+      def new_version?
+        version_obj and version_obj.new_record?
+      end
+
+      protected
+
+      # Applies version on self. Returns nil
+      def apply_version!(*args)
+        raise ArgumentError if args.empty?
+        set_version_args(*args)
+        version_cache.self_version = (version_number == version_cache.wanted_version_number)
+        return if version_cache.self_version
+
+        self.attributes = version_attributes
+        self.version_number = version_cache.wanted_version_number
+        self.updated_at = version_obj.created_at if version_obj.created_at
+        nil
+      end
+
+      # Returns the originial attributes of the record.
+      # This method has to be called after_initialize.
+      def original_attributes
+        @original_attributes ||= versioned_attributes
+      end
+
+      # Returns true if versioned attributes were changed.
+      def versioned_attributes_changed?
+        versioned_attributes != original_attributes
+      end
+
+      # Returns original attributes with attributes of version object and wanted attributes merged in.
+      def version_attributes
+        # TODO: Setting the following line will cause DelayedJob to loop endlessly. The same should happen if an embedded document is defined as versioned_attribute!
+        # original_attributes.merge(version_obj.versioned_attributes).merge(version_cache.wanted_attributes.stringify_keys!)
+        version_obj.versioned_attributes.merge(version_cache.wanted_attributes.stringify_keys!)
+      end
+
+      # Sets instance variables used for versioning.
+      # Helper method for #version
+      def set_version_args(*args)
+        version_cache.version_args = args
+        version_cache.wanted_attributes = args.extract_options!
+        wanted_version_number = args.first
+
+        version_cache.wanted_version_number = case wanted_version_number
+        when :new       then new_version_number
+        when :next      then version_number + 1
+        when :previous  then version_number - 1
+        else
+          wanted_version_number.to_i
+        end
+
+        version_cache.wanted_version_number = 1 if version_cache.wanted_version_number < 1
+      end
+
+      # Finds or builds a version object containing the record's current attributes.
+      def set_original_version_obj
+        criteria = {:number => version_number_was}
+        version_cache.original_version_obj = versions.where(criteria).first || versions.build(criteria)
+        version_cache.original_version_obj.tap do |obj|
+          obj.versioned_attributes = original_attributes
+          obj.created_at = updated_at_was if obj.new_record?
+        end
+      end
+
+      # Returns the version object:
+      #
+      # * If a version is wanted, that version will be selected or instantiated and returned.
+      # * If an editing time has been defined which has not yet passed nil will be returned.
+      # * Otherwise a new version will be instantiated.
+      #
+      def version_obj
+        version_cache.version_obj ||= begin
+          if version_cache.wanted_version_number
+            obj = versions.where(:number => version_cache.wanted_version_number).first
+            unless obj or version_cache.self_version
+              # versions.to_a # TODO: prefetch versions before building a new one?
+              obj = versions.build(
+                :number => version_cache.wanted_version_number,
+                :versioned_attributes => versioned_attributes,
+                :created_at => updated_at_was)
+            end
+            obj
+          else
+            editing_time = self.class.versioning_options[:editing_time]
+            if !editing_time or updated_at <= (Time.now-editing_time.to_i) or updated_at > Time.now # allow future versions
+              versions.build(:created_at => updated_at_was)
+            end
+          end
+        end
+      end
+
+      # Returns the next available version number.
+      def new_version_number
+        version_cache.new_version_number ||= begin
+          latest_version = versions.desc(:number).limit(1).first
+          ver = latest_version.number if latest_version
+          [ver.to_i, version_number].max + 1
+        end
+      end
+
+      # Caching object for gathering versioning data.
+      # By storing this data inside a separate object, we can
+      # transfer it easily to a version copy of self.
+      def version_cache
+        @version_cache ||= Struct.new(
+          :wanted_version_number,
+          :wanted_attributes,
+          :new_version_number,
+          :version_obj,
+          :version_args,
+          :original_version_obj,
+          :self_version
+        ).new
+      end
+
+      # Stores changes on version object.
+      #
+      # If #migrate! was called and original_version_obj is present, the object will be saved.
+      # If #version was called and @wanted_version is present, changes will be applied to that version.
+      # Otherwise a new version object will be stored with original attributes.
+      #
+      def persist_version
+        return if new_record?
+        return unless versioned_attributes_changed?
+        if version_cache.original_version_obj
+          version_cache.original_version_obj.save!
+        elsif version_cache.wanted_version_number
+          if version_obj
+            saved = version_obj.update_attributes(:versioned_attributes => versioned_attributes, :created_at => updated_at)
+          end
+          return saved unless version_cache.self_version
+        elsif version_obj
+          version_obj.update_attributes!(:versioned_attributes => original_attributes)
+          self.version_number = version_obj.number + 1
+        end
+        nil
+      end
+
+      # Removes version object with given method.
+      def remove_version(method)
+        return unless version_cache.wanted_version_number
+        version_obj.send(method)
+      end
+
+      # Resets instance variables used for versioning.
+      def reset_version_cache
+        @original_attributes = versioned_attributes
+        @version_cache = nil
+      end
+    end
+  end
+end

data/lib/vidibus/versioning/version.rb

@@ -0,0 +1,45 @@
+module Vidibus
+  module Versioning
+    class Version
+      include ::Mongoid::Document
+      include ::Mongoid::Timestamps
+      include Vidibus::Uuid::Mongoid
+
+      belongs_to :versioned, :polymorphic => true
+
+      field :versioned_uuid, :type => String
+      field :versioned_attributes, :type => Hash, :default => {}
+      field :number, :type => Integer, :default => nil
+
+      index :versioned_uuid
+      index :number
+
+      validates :versioned_uuid, :versioned_attributes, :presence => true
+
+      before_validation :set_versioned_uuid
+      before_create :set_number
+
+      scope :timeline, desc(:created_at)
+
+      def past?
+        @is_past ||= created_at && created_at < Time.now
+      end
+
+      def future?
+        @is_future ||= !created_at || created_at >= Time.now
+      end
+
+      protected
+
+      def set_number
+        return if number
+        previous = Version.desc(:number).limit(1).first
+        self.number = previous ? previous.number + 1 : 1
+      end
+
+      def set_versioned_uuid
+        self.versioned_uuid = versioned.uuid
+      end
+    end
+  end
+end

data/lib/vidibus/versioning.rb

@@ -0,0 +1,3 @@
+require "vidibus/versioning/errors"
+require "vidibus/versioning/version"
+require "vidibus/versioning/mongoid"

data/lib/vidibus-versioning.rb

@@ -0,0 +1,5 @@
+require "mongoid"
+require "vidibus-core_extensions"
+require "vidibus-uuid"
+
+require "vidibus/versioning"

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification 
+name: vidibus-versioning
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Andre Pankratz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-14 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mongoid
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        version: "2"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: vidibus-core_extensions
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: vidibus-uuid
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        version: "2"
+  type: :development
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: rr
+  prerelease: false
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id009
+description: Versioning designed for advanced usage, like scheduling versions.
+email: andre@vidibus.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/vidibus/versioning/_version.rb
+- lib/vidibus/versioning/errors.rb
+- lib/vidibus/versioning/mongoid.rb
+- lib/vidibus/versioning/version.rb
+- lib/vidibus/versioning.rb
+- lib/vidibus-versioning.rb
+- LICENSE
+- README.md
+- Rakefile
+has_rdoc: true
+homepage: https://github.com/vidibus/vidibus-versioning
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: vidibus-versioning
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Advanced versioning for Mongoid models
+test_files: []
+