Module patch
Functions
patch.apply(input, patch) | Returns the patched version of the input value. |
patch.apply_inplace(input, patch) | Applies a patch to the input value directly. |
patch.join(...) | Joins multiple patches into a single patch. |
patch.diff(a, b) | Given two tables a and b , returns a patch p such that
patch.apply(a, p) == b |
Updaters
patch.Nil | The nil updater. |
patch.noop | The noop updater. |
patch.replace(value) | Returns a replace updater. |
patch.remove_i(pos) | Returns a table.remove updater. |
patch.insert_i(pos, value) | Returns a table.insert updater. |
patch.meta(metatable) | Returns a setmetatable updater. |
patch.chain(...) | Returns an updater that has the same effect as applying each input patch left-to-right. |
patch.register_updater(name, mt, update) | Registers a custom updater. |
Functions
- patch.apply(input, patch)
-
Returns the patched version of the input value. Patches are a compound
datatype that can be made of normal Lua values, as well as "updaters" that
have specific patching strategies.
Parameters:
- input the input value.
- patch the patch to apply.
Returns:
output, undo
- patch.apply_inplace(input, patch)
-
Applies a patch to the input value directly. This should return the same
thing as patch.apply(), but the input value is left in an undefined state.
Parameters:
- input the input value.
- patch the patch to apply.
Returns:
output, undo
- patch.join(...)
-
Joins multiple patches into a single patch. Trying to join patches that
change the same field in mutually exclusive ways will raise an error.
Parameters:
- ... the patches to join.
Returns:
-
The final patch. Note that
nil
is considered a no-op, so that's a valid return value. - patch.diff(a, b)
-
Given two tables
a
andb
, returns a patchp
such thatpatch.apply(a, p) == b
Parameters:
- a FIXME
- b apply allows for single-value diffs, so should we.
Updaters
- patch.Nil
-
The
nil
updater. When you want to set a field to nil, use this instead of nil directly. - patch.noop
- The noop updater. This will have the same effect as passing in a nil, but because it's a reified object you can use it where nil would cause issues.
- patch.replace(value)
-
Returns a replace updater. This is the equivalent of setting the field
directly to the given value. This can be used for anything, including
nil
, whole tables, or other updaters.Parameters:
- value the new value.
Returns:
-
An opaque updater.
- patch.remove_i(pos)
-
Returns a table.remove updater. This is equivalent to calling
table.remove(tbl, pos)
wheretbl
is the input field. Ifpos
is omitted or is nil, the last element is removed.Parameters:
- pos int the index of the thing to remove.
Returns:
-
An opaque updater.
- patch.insert_i(pos, value)
-
Returns a table.insert updater. This is equivalent to calling
table.insert(tbl, pos, value)
wheretbl
is the input field.Parameters:
- pos int the index to insert at.
- value the value to insert.
Returns:
-
An opaque updater.
- patch.meta(metatable)
-
Returns a setmetatable updater. This is equivalent to calling
setmetatable(tbl, metatable)
wheretbl
is the input field.Parameters:
- metatable table the metatable to set.
Returns:
-
An opaque updater.
- patch.chain(...)
-
Returns an updater that has the same effect as applying each input patch
left-to-right. The implementation strategy has special cases, but usually
this will in the form of a chain updater.
Contrast this with patch.join, which will return a simple precomputed
patch but can't express multiple changes to the same field.
Parameters:
- ... A patch
Returns:
-
An opaque updater
- patch.register_updater(name, mt, update)
-
Registers a custom updater. Each updater has a name, a metatable associated with it, and an update function. When patch.apply sees an object with the associated metatable in a diff, it will use the given
update()
function to apply the patch.Your
update()
function should have this signature:function(original, diff, mutate) return new, undo end
where
original
is the original value in the table.diff is your updater object.
mutate
will be true if your updater is allowed to directly modify theoriginal
value.new
is what your updater will replaceoriginal
with.undo
can be any patch that can turnnew
back intooriginal
.
Parameters: