patch.lua

Contents

• Functions
• Updaters

Modules

• patch

Topics

• Tour

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 and b, returns a patch p such that patch.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) where tbl is the input field. If pos 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) where tbl 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) where tbl 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 the original value.

• new is what your updater will replace original with.

• undo can be any patch that can turn new back into original.

Parameters:

• name string the name of the updater.
• mt table the metatable each instance of the updater will share.
• update function the update function.