text_delta v1.1.0 TextDelta
Delta is a format used to describe documents and changes.
Delta can describe any rich text changes or a rich document itself, preserving all the formatting.
At the baseline level, delta is an array of operations (constructed via
TextDelta.Operation
). Operations can be either
TextDelta.Operation.insert/0
, TextDelta.Operation.retain/0
or
TextDelta.Operation.delete/0
. None of the operations contain index,
meaning that delta aways describes document or a change staring from the very
beginning.
Delta can describe both changes to and documents themselves. We can think of a
document as an artefact of all the changes applied to it. This way, newly
imported document can be thinked of as simply a sequence of insert
s applied
to an empty document.
Deltas are composable. This means that a document delta can be composed with another delta for that document, resulting in a shorter, optimized delta.
Deltas are also transformable. This attribute of deltas is what enables Operational Transformation - a way to transform one operation against the context of another one. Operational Transformation allows us to build optimistic, non-locking collaborative editors.
The format for deltas was deliberately copied from Quill - a rich text editor for web. This library aims to be an Elixir counter-part for Quill, enabling us to build matching backends for the editor.
Example
iex> delta = TextDelta.insert(TextDelta.new(), "Gandalf", %{bold: true})
%TextDelta{ops: [
%{insert: "Gandalf", attributes: %{bold: true}}]}
iex> delta = TextDelta.insert(delta, " the ")
%TextDelta{ops: [
%{insert: "Gandalf", attributes: %{bold: true}},
%{insert: " the "}]}
iex> TextDelta.insert(delta, "Grey", %{color: "#ccc"})
%TextDelta{ops: [
%{insert: "Gandalf", attributes: %{bold: true}},
%{insert: " the "},
%{insert: "Grey", attributes: %{color: "#ccc"}}]}
Summary
Types
A document represented as delta. Any rich document can be represented as a set
of TextDelta.Operation.insert/0
operations
Delta is a set of TextDelta.Operation.retain/0
,
TextDelta.Operation.insert/0
, or TextDelta.Operation.delete/0
operations
Functions
Appends given operation to the delta
Creates and appends new delete
operation to the delta
Creates and appends new insert
operation to the delta
Calculates the length of a given delta
Creates new delta
Returns set of operations for a given delta
Creates and appends new retain
operation to the delta
Trims trailing retains from the end of a given delta
Types
A document represented as delta. Any rich document can be represented as a set
of TextDelta.Operation.insert/0
operations.
Delta is a set of TextDelta.Operation.retain/0
,
TextDelta.Operation.insert/0
, or TextDelta.Operation.delete/0
operations.
Functions
Appends given operation to the delta.
Before adding operation to the delta, this function attempts to compact it by applying 2 simple rules:
- Delete followed by insert is swapped to ensure that insert goes first.
- Same operations with the same attributes are merged.
These two rules ensure that our deltas are always as short as possible and canonical, making it easier to compare, compose and transform them.
Example
iex> operation = TextDelta.Operation.insert("hello")
iex> TextDelta.append(TextDelta.new(), operation)
%TextDelta{ops: [%{insert: "hello"}]}
Creates and appends new delete
operation to the delta.
TextDelta.append/2
is used undert the hood to add operation to the delta
after construction. So all append
rules apply.
Example
iex> TextDelta.delete(TextDelta.new(), 3)
%TextDelta{ops: [%{delete: 3}]}
Creates and appends new insert
operation to the delta.
Same as with underlying TextDelta.Operation.insert/2
function, attributes
are optional.
TextDelta.append/2
is used undert the hood to add operation to the delta
after construction. So all append
rules apply.
Example
iex> TextDelta.insert(TextDelta.new(), "hello", %{bold: true})
%TextDelta{ops: [%{insert: "hello", attributes: %{bold: true}}]}
length(t, [TextDelta.Operation.type]) :: non_neg_integer
Calculates the length of a given delta.
Length of delta is a sum of its operations length.
Example
iex> TextDelta.length(TextDelta.new([%{insert: "hello"}, %{retain: 5}]))
10
The function also allows to select which types of operations we include in the summary with optional second argument:
iex> TextDelta.length(TextDelta.new([%{insert: "hi"}]), [:retain])
0
Creates new delta.
Examples
iex> TextDelta.new()
%TextDelta{ops: []}
You can also pass set of operations using optional argument:
iex> TextDelta.new([TextDelta.Operation.insert("hello")])
%TextDelta{ops: [%{insert: "hello"}]}
Returns set of operations for a given delta.
Example
iex> TextDelta.operations(TextDelta.new([%{delete: 5}, %{retain: 3}]))
[%{delete: 5}, %{retain: 3}]
Creates and appends new retain
operation to the delta.
Same as with underlying TextDelta.Operation.retain/2
function, attributes
are optional.
TextDelta.append/2
is used undert the hood to add operation to the delta
after construction. So all append
rules apply.
Example
iex> TextDelta.retain(TextDelta.new(), 5, %{italic: true})
%TextDelta{ops: [%{retain: 5, attributes: %{italic: true}}]}