Control blocks are called on ActiveRecord::Base instances as to not cause any conflict with other instances of the versioned class whose behavior could be inadvertently altered within a control block.
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.
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.
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.
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
Overrides the basal create_version?
method to make sure that
new versions are not created when inside any of the control blocks (until
the block terminates).
# File lib/vestal_versions/control.rb, line 164 def create_version_with_control? !skip_version? && !merge_version? && !append_version? && create_version_without_control? end
Overrides the basal update_version?
method to allow the last
version of an versioned ActiveRecord::Base instance to be updated at the
end of an append_version
block.
# File lib/vestal_versions/control.rb, line 170 def update_version_with_control? append_version? end
Used for each control block, the with_version_flag
method sets
a given variable to true and then executes the given block, ensuring that
the variable is returned to a nil value before returning. This is useful to
be certain that one of the control flag instance variables isn't
inadvertently left in the “on” position by execution within the block
raising an exception.
# File lib/vestal_versions/control.rb, line 153 def with_version_flag(flag) begin instance_variable_set("@#{flag}", true) yield ensure instance_variable_set("@#{flag}", nil) end end