Module: VestalVersions::Control

Extended by:
ActiveSupport::Concern
Defined in:
lib/vestal_versions/control.rb

Overview

The control feature allows use of several code blocks that provide finer control over whether a new version is created, or a previous version is updated.

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Instance Method Details

#_with_version_flag(flag) ⇒ Object

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.



144
145
146
147
148
149
 
# File 'lib/vestal_versions/control.rb', line 144

def _with_version_flag(flag)
  instance_variable_set("@#{flag}", true)
  yield
ensure
  remove_instance_variable("@#{flag}")
end

#append_version ⇒ Object

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.



110
111
112
113
114
115
116
117
118
 
# File 'lib/vestal_versions/control.rb', line 110

def append_version
  _with_version_flag(:merge_version) do
    yield if block_given?
  end

  _with_version_flag(:append_version) do
    save
  end
end

#append_version! ⇒ Object

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.



123
124
125
126
127
128
129
130
131
 
# File 'lib/vestal_versions/control.rb', line 123

def append_version!
  _with_version_flag(:merge_version) do
    yield if block_given?
  end

  _with_version_flag(:append_version) do
    save!
  end
end

#append_version? ⇒ Boolean

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

Returns:

  • (Boolean) 


135
136
137
 
# File 'lib/vestal_versions/control.rb', line 135

def append_version?
  !!@append_version
end

#create_version? ⇒ Boolean

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).

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/vestal_versions/control.rb', line 153

def create_version?
  !_skip_version? && !merge_version? && !append_version? && super
end

#merge_version ⇒ Object

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.



67
68
69
70
71
72
 
# File 'lib/vestal_versions/control.rb', line 67

def merge_version
  _with_version_flag(:merge_version) do
    yield if block_given?
  end
  save
end

#merge_version! ⇒ Object

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.



77
78
79
80
81
82
 
# File 'lib/vestal_versions/control.rb', line 77

def merge_version!
  _with_version_flag(:merge_version) do
    yield if block_given?
  end
  save!
end

#merge_version? ⇒ Boolean

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

Returns:

  • (Boolean) 


86
87
88
 
# File 'lib/vestal_versions/control.rb', line 86

def merge_version?
  !!@merge_version
end

#skip_version ⇒ Object

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



31
32
33
34
35
36
 
# File 'lib/vestal_versions/control.rb', line 31

def skip_version
  _with_version_flag(:_skip_version) do
    yield if block_given?
    save
  end
end

#skip_version! ⇒ Object

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.



41
42
43
44
45
46
 
# File 'lib/vestal_versions/control.rb', line 41

def skip_version!
  _with_version_flag(:_skip_version) do
    yield if block_given?
    save!
  end
end

#update_version? ⇒ Boolean

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.

Returns:

  • (Boolean) 


159
160
161
 
# File 'lib/vestal_versions/control.rb', line 159

def update_version?
  append_version?
end