@spec cleanup_semantic(t(), Otzel.Content.t() | nil, list() | nil) :: t()

Performs semantic cleanup on a diff, simplifying interleaved delete/insert sequences into cleaner delete-then-insert patterns when the common text is minimal.

This makes diffs more human-readable by avoiding overly granular changes.

The optional dst_content parameter provides the destination content, which is needed to extract retained content when converting retains to inserts. The optional dst_attrs_index parameter provides the destination attributes index, which maps positions to their attributes for proper attr handling.

@spec compact(t()) :: t()

Compacts Delta to satisfy compactness requirement.

iex> delta = [Otzel.insert("Hel"), Otzel.insert("lo"), Otzel.insert("World", %{"bold" => true})]
iex> Otzel.compact(delta) |> JSON.encode!() |> JSON.decode!()
[%{"insert" => "Hello"}, %{"insert" => "World", "attributes" => %{"bold" => true}}]

@spec compose(t(), t()) :: t()

Composes two deltas into a single delta with the same effect as applying them sequentially.

Given deltas A and B, compose(A, B) returns a delta C such that applying C to a document has the same effect as applying A then B.

Examples

iex> doc = [Otzel.insert("Hello")]
iex> change = [Otzel.retain(5), Otzel.insert(" World")]
iex> result = Otzel.compose(doc, change)
iex> result |> JSON.encode!() |> JSON.decode!()
[%{"insert" => "Hello World"}]

iex> a = [Otzel.insert("abc")]
iex> b = [Otzel.retain(1), Otzel.delete(1), Otzel.retain(1)]
iex> Otzel.compose(a, b) |> JSON.encode!() |> JSON.decode!()
[%{"insert" => "ac"}]

Properties

Compose is associative: compose(compose(a, b), c) == compose(a, compose(b, c))

@spec concat(t(), t()) :: t()

Concatenates two transformations into one

iex> Otzel.concat([Otzel.insert("Hel")], [Otzel.insert("lo")]) |> JSON.encode!() |> JSON.decode!()
[%{"insert" => "Hello"}]

@spec delete(non_neg_integer()) :: Otzel.Op.Delete.t()

Creates a Delete operation with the given count.

@spec diff(t(), t()) :: t()

Computes the difference between two transformations, returning a new transformation that represents the changes needed to convert src into dst. Both src and dst should be strictly lists of Insert operations.

Note that the following invariant holds for compact transformation a: a == Otzel.compose(b, Otzel.diff(a, b))

iex> Otzel.diff([Otzel.insert("Hello")], [Otzel.insert("Hello!")])
[Otzel.retain(5), Otzel.insert("!")]

Parses a delta from JSON format.

Accepts a list of operation maps in the Quill Delta JSON format.

Options

• :embed_encoder - A {module, function} tuple that will be called with the raw content to convert embedded content back to structs. The function should return the appropriate struct or pass through the content unchanged.

Examples

iex> json = [%{"insert" => "Hello"}, %{"insert" => " World", "attributes" => %{"bold" => true}}]
iex> delta = Otzel.from_json(json)
iex> length(delta)
2

@spec insert(String.t() | Otzel.Content.t(), attrs :: nil | map()) ::
  Otzel.Op.Insert.t()

Creates an Insert operation with the given content and attributes.

@spec invert(t(), t()) :: t()

Computes an inverted transformation transformation, that has the opposite effect against a base transformation.

Note that the following invariant holds for base a list of inserts and change a transformation with retains and deletes fewer than the size of base:

base == compose(compose(base, change), compose(invert(change, base)))

iex> alias Otzel.Op.{Insert, Retain, Delete}
iex> Otzel.invert([%Retain{target: 6, attrs: %{"bold" => true}}, %Delete{count: 5}, %Insert{content: "!"}], [%Insert{content: "Hello\nWorld"}])
[
  %Retain{target: 6, attrs: %{"bold" => nil}},
  %Insert{content: "World"},
  %Delete{count: 1}
]

@spec retain(non_neg_integer() | Otzel.Content.t(), attrs :: nil | map()) ::
  Otzel.Op.Retain.t()

Creates a Retain operation with the given target and attributes.

Note: if a the target is an embedded Otzel.Content.t/0 then the "retain" operation signifies that the target should be treated as a delta for the embedded content.

@spec seek(t(), non_neg_integer()) :: t()

Takes operations beyond count operations from the list of operations.

iex> alias Otzel.Op.{Insert, Retain}
iex> Otzel.seek([%Insert{content: "Hello"}, %Retain{target: 3}], 3)
[%Insert{content: "lo"}, %Retain{target: 3}]

@spec size(t()) :: non_neg_integer()

Returns the total size of the operations in the transformation. For strings, the size is the number of codepoints in the string.

iex> alias Otzel.Op.{Insert, Retain}
iex> Otzel.size([%Insert{content: "Hello"}])
5
iex> Otzel.size([%Insert{content: "Howdy🤠!"}])
7
iex> Otzel.size([%Insert{content: "Hello"}, %Retain{target: 3}])
8

@spec slice(t(), start :: non_neg_integer(), count :: non_neg_integer()) :: t()

Returns a slice of operations starting from start with a given count

iex> alias Otzel.Op.{Insert, Retain}
iex> Otzel.slice([%Insert{content: "Hello"}, %Retain{target: 3}], 2, 5)
[%Insert{content: "llo"}, %Retain{target: 2}]

@spec split(
  t(),
  non_neg_integer() | split_fun() | {split_fun_ctx(), context :: term()}
) :: {t(), t()}

splits a transformation into two parts at the supplied index

iex> alias Otzel.Op.{Insert, Retain}
iex> Otzel.split([%Insert{content: "Hello"}, %Retain{target: 3}], 2)
{[%Insert{content: "He"}], [%Insert{content: "llo"}, %Retain{target: 3}]}

Takes the first count operations from the list of operations.

iex> alias Otzel.Op.{Insert, Retain}
iex> Otzel.take([%Insert{content: "Hello"}, %Retain{target: 3}], 6)
[%Insert{content: "Hello"}, %Retain{target: 1}]

@spec transform(t(), t(), priority()) :: t()

Transforms a delta against another concurrent delta.

When two users make edits concurrently, their deltas need to be transformed against each other to maintain consistency. Given deltas A and B that were created from the same base document:

• transform(A, B, :right) returns B' that can be applied after A
• transform(B, A, :left) returns A' that can be applied after B

The result satisfies: compose(A, B') == compose(B, A')

Parameters

• from - The delta that was applied first
• into - The delta to transform
• priority - Which delta wins when both insert at the same position

Examples

iex> a = [Otzel.insert("A")]
iex> b = [Otzel.insert("B")]
iex> Otzel.transform(a, b, :right) |> JSON.encode!() |> JSON.decode!()
[%{"insert" => "B"}]

Priority

The priority parameter determines what happens when both deltas insert at the same position:

• :right - The into delta's insert comes after
• :left - The into delta's insert comes before

@spec transform_index(non_neg_integer(), t(), priority()) :: non_neg_integer()

Transforms a cursor/selection index against a delta.

When a delta is applied to a document, cursor positions need to be adjusted. This function computes where an index should move to after the delta is applied.

Parameters

• index - The original cursor position
• delta - The delta being applied
• priority - Whether the cursor should be pushed by inserts at the same position

Examples

iex> Otzel.transform_index(5, [Otzel.insert("abc")], :right)
8

iex> Otzel.transform_index(5, [Otzel.retain(3), Otzel.delete(2)], :right)
3