Adds a resource to the list of resources. If possible, merges it with the head of the list using merge/2. Ensures that the added resource has an ID by calling add_id/1 if necessary.

Examples

Adding a resource without an ID to an empty list:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.Text
iex> [%Text{text: "Hello", styling: [:bold], id: id}] = add([], %Text{text: "Hello", styling: [:bold], id: nil})
[%Text{text: "Hello", styling: [:bold], id: id}]
iex> Ecto.UUID.cast(id)
{:ok, id}

Adding a resource that can be merged with the head of the list:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.Text
iex> res1 = %Text{id: "1", text: "Hello", styling: [:bold]}
iex> res2 = %Text{id: "2", text: " World", styling: [:bold]}
iex> add([res1], res2)
[%Text{id: "1", styling: [:bold], text: "Hello World"}]

Adding a resource that cannot be merged:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.Text
iex> res1 = %Text{id: "1", text: "Hello", styling: [:bold]}
iex> res2 = %Text{id: "2", text: " World", styling: [:italic]}
iex> add([res1], res2)
[res2, res1]

@spec add_all([NLdoc.Spec.object()], [NLdoc.Spec.object()]) :: [NLdoc.Spec.object()]

Adds all resources from the second list to the first list, using add/2 to merge them where possible.

Examples

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.Text
iex> existing_resources = [
...>   %Text{text: " ", styling: [:bold]},
...>   %Text{text: "message:", styling: [:italic]}
...> ]
iex> new_resources = [
...>   %Text{text: " World", styling: [:bold]},
...>   %Text{text: "Hello", styling: [:bold]}
...> ]
iex> add_all(existing_resources, new_resources)
[
  %Text{text: " Hello World", styling: [:bold]},
  %Text{text: "message:", styling: [:italic]}
]

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.Text
iex> new_resources = [
...>   %Text{text: "Hello", styling: [:bold]},
...>   %Text{text: "World", styling: [:italic]}
...> ]
iex> [%{id: id1}, %{id: id2}] = add_all([], new_resources)
[
  %Text{styling: [:bold], text: "Hello", id: id1},
  %Text{styling: [:italic], text: "World", id: id2}
]

Adds a child to the resource's list of children.

Examples

Adding a child to a resource without children:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.{Paragraph, Text}
iex> resource = %Paragraph{children: []}
iex> child = %Text{styling: [:bold], text: "Hello World"}
iex> %Paragraph{children: [%Text{id: id}]} =  add_child(resource, child)
%Paragraph{children: [%Text{id: id, styling: [:bold], text: "Hello World"}]}

Adding a child to a resource with matching text children, effectively merging:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.{Paragraph, Text}
iex> resource = %Paragraph{children: [%Text{id: "abc", styling: [:bold], text: "Hello"}]}
iex> child = %Text{styling: [:bold], text: " World"}
iex> add_child(resource, child)
%Paragraph{children: [%Text{id: "abc", styling: [:bold], text: "Hello World"}]}

Adding a child to a resource with children:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.{Paragraph, Text}
iex> first_text = %Text{id: "abc", styling: [:bold], text: "Hello"}
iex> second_text = %Text{id: "xyz", styling: [:italic], text: " World"}
iex> resource = %Paragraph{children: [first_text]}
iex> add_child(resource, second_text)
%Paragraph{children: [second_text, first_text]}

Adds multiple children to the resource's list of children.

Examples

Adding multiple children to a resource without children:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.{Paragraph, Text}
iex> resource = %Paragraph{children: []}
iex> children = [
...>   %Text{styling: [:bold], text: "Hello"},
...>   %Text{styling: [:italic], text: " World"}
...> ]
iex> %{children: [%{id: id1}, %{id: id2}]} = add_children(resource, children)
%Paragraph{children: [%Text{id: id1, styling: [:bold], text: "Hello"}, %Text{id: id2, styling: [:italic], text: " World"}]}

Adding multiple children to a resource with children, with merging:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> alias NLdoc.Spec.{Paragraph, Text}
iex> first_text = %Text{id: "abc", styling: [:bold], text: "Hello"}
iex> second_text = %Text{id: "xyz", styling: [:bold], text: " World"}
iex> resource = %Paragraph{children: [first_text]}
iex> add_children(resource, [second_text])
%Paragraph{children: [%Text{id: "abc", styling: [:bold], text: "Hello World"}]}

@spec add_id(resource) :: resource when resource: NLdoc.Spec.object()

@spec add_id(resource :: map()) :: NLdoc.Spec.object() | map()

Assigns a new unique identifier (UUID) to the resource if it doesn't already have one. If the resource already has an id, it is returned unchanged.

Examples

When the resource doesn't have an id:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> %{name: "test", id: id} = add_id(%{name: "test", id: nil})
iex> Ecto.UUID.cast(id)
{:ok, id}

When the resource already has an id:

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> existing_id = Ecto.UUID.generate()
iex> resource = %{name: "test", id: existing_id}
iex> add_id(resource)
%{name: "test", id: existing_id}

@spec new_id() :: String.t()

Generates a new unique identifier (UUID) as a string.

Examples

iex> import NLdoc.Conversion.Reader.Docx.Util.Helpers
iex> id = new_id()
iex> Ecto.UUID.cast(id)
{:ok, id}