module VestalVersions::Control::InstanceMethods

Appending versions with the append_version block acts similarly to the merge_version block in that all would-be version creations within the block are defered until the block closes. The major difference is that with append_version, a new version is not created. Rather, the cumulative changes are appended to the serialized changes of the instance’s last version. A new version is not created, so the version number is not incremented.

Example

user = User.find_by_first_name("Steve")
user.version # => 2
user.versions.last.changes
# => {"first_name" => ["Stephen", "Steve"]}
user.append_version do
  user.last_name = "Jobs"
end
user.versions.last.changes
# => {"first_name" => ["Stephen", "Steve"], "last_name" => ["Richert", "Jobs"]}
user.version # => 2

See VestalVersions::Changes for an explanation on how changes are appended.

# File lib/vestal_versions/control.rb, line 118
def append_version
  with_version_flag(:merge_version) do
    yield if block_given?
  end

  with_version_flag(:append_version) do
    save
  end
end

Behaving almost identically to the append_version block, the only difference with the append_version! block is that the save automatically performed at the close of the block is a save!, meaning that an exception will be raised if the object cannot be saved.

# File lib/vestal_versions/control.rb, line 131
def append_version!
  with_version_flag(:merge_version) do
    yield if block_given?
  end

  with_version_flag(:append_version) do
    save!
  end
end

A convenience method for determining whether a versioned instance is set to append its next version’s changes into the last version changes.

# File lib/vestal_versions/control.rb, line 143
def append_version?
  !!@append_version
end

Merging versions with the merge_version block will take all of the versions that would be created within the block and merge them into one version and pushing that single version onto the ActiveRecord::Base instance’s version history. A new version will be created and the instance’s version number will be incremented.

Example

user = User.find_by_first_name("Steve")
user.version # => 1
user.merge_version do
  user.update_attributes(:first_name => "Steven", :last_name => "Tyler")
  user.update_attribute(:first_name, "Stephen")
  user.update_attribute(:last_name, "Richert")
end
user.version # => 2
user.versions.last.changes
# => {"first_name" => ["Steve", "Stephen"], "last_name" => ["Jobs", "Richert"]}

See VestalVersions::Changes for an explanation on how changes are appended.

# File lib/vestal_versions/control.rb, line 75
def merge_version
  with_version_flag(:merge_version) do
    yield if block_given?
  end
  save
end

Behaving almost identically to the merge_version block, the only difference with the merge_version! block is that the save automatically performed at the close of the block is a save!, meaning that an exception will be raised if the object cannot be saved.

# File lib/vestal_versions/control.rb, line 85
def merge_version!
  with_version_flag(:merge_version) do
    yield if block_given?
  end
  save!
end

A convenience method for determining whether a versioned instance is set to merge its next versions into one before version creation.

# File lib/vestal_versions/control.rb, line 94
def merge_version?
  !!@merge_version
end

The skip_version block simply allows for updates to be made to an instance of a versioned ActiveRecord model while ignoring all new version creation. The :if and :unless conditions (if given) will not be evaulated inside a skip_version block.

When the block closes, the instance is automatically saved, so explicitly saving the object within the block is unnecessary.

Example

user = User.find_by_first_name("Steve")
user.version # => 1
user.skip_version do
  user.first_name = "Stephen"
end
user.version # => 1

# File lib/vestal_versions/control.rb, line 33
def skip_version
  with_version_flag(:skip_version) do
    yield if block_given?
    save
  end
end

Behaving almost identically to the skip_version block, the only difference with the skip_version! block is that the save automatically performed at the close of the block is a save!, meaning that an exception will be raised if the object cannot be saved.

# File lib/vestal_versions/control.rb, line 43
def skip_version!
  with_version_flag(:skip_version) do
    yield if block_given?
    save!
  end
end

A convenience method for determining whether a versioned instance is set to skip its next version creation.

# File lib/vestal_versions/control.rb, line 52
def skip_version?
  !!@skip_version
end