@spec collect_section_nodes(
  Ootempl.Xml.xml_element(),
  Ootempl.Xml.xml_element(),
  Ootempl.Xml.xml_element()
) :: {:ok, [Ootempl.Xml.xml_node()]} | {:error, :boundaries_not_found}

Collects all XML nodes between two boundary nodes, inclusive.

Returns all nodes from the start node to the end node, including both boundaries. Handles sections spanning single or multiple paragraphs.

Parameters

• xml_element - The XML element containing the section
• start_node - The starting boundary node
• end_node - The ending boundary node

Returns

• {:ok, nodes} - List of all nodes in the section (inclusive of boundaries)
• {:error, :boundaries_not_found} - If start or end nodes are not found in the element

Examples

# See integration tests for XML examples

@spec detect_conditionals(String.t()) :: [conditional()]

Detects all conditional markers in the given text.

Returns a list of conditional markers in order of appearance with their positions.

Parameters

• text - The text to scan for conditional markers

Returns

A list of conditional maps, each containing:

• :type - Either :if, :else, or :endif
• :condition - The condition variable (only for :if markers)
• :path - Parsed path segments (only for :if markers)
• :position - Character position in the text

Examples

iex> Ootempl.Conditional.detect_conditionals("{{if active}}content{{endif}}")
[
  %{type: :if, condition: "active", path: ["active"], position: 0},
  %{type: :endif, condition: nil, path: nil, position: 20}
]

iex> Ootempl.Conditional.detect_conditionals("no markers here")
[]

iex> Ootempl.Conditional.detect_conditionals("{{if show}}yes{{else}}no{{endif}}")
[
  %{type: :if, condition: "show", path: ["show"], position: 0},
  %{type: :else, condition: nil, path: nil, position: 14},
  %{type: :endif, condition: nil, path: nil, position: 24}
]

@spec evaluate_condition([String.t()], map()) :: {:ok, boolean()} | {:error, term()}

Evaluates a conditional expression by checking if the data path resolves to a truthy value.

Uses Ootempl.DataAccess.get_value/2 for case-insensitive nested data access, then evaluates the result using truthiness rules.

Parameters

• path - List of path segments to navigate (e.g., ["customer", "active"])
• data - The data map to evaluate against

Returns

• {:ok, true} if the condition evaluates to truthy
• {:ok, false} if the condition evaluates to falsy
• {:error, reason} if the path cannot be resolved

Examples

iex> Ootempl.Conditional.evaluate_condition(["active"], %{"active" => true})
{:ok, true}

iex> Ootempl.Conditional.evaluate_condition(["active"], %{"active" => false})
{:ok, false}

iex> Ootempl.Conditional.evaluate_condition(["count"], %{"count" => 0})
{:ok, false}

iex> Ootempl.Conditional.evaluate_condition(["count"], %{"count" => 5})
{:ok, true}

iex> Ootempl.Conditional.evaluate_condition(["name"], %{"name" => ""})
{:ok, false}

iex> Ootempl.Conditional.evaluate_condition(["name"], %{"name" => "John"})
{:ok, true}

iex> Ootempl.Conditional.evaluate_condition(["customer", "active"], %{"customer" => %{"active" => true}})
{:ok, true}

iex> Ootempl.Conditional.evaluate_condition(["missing"], %{"name" => "John"})
{:error, {:path_not_found, ["missing"]}}

@spec find_section_boundaries(Ootempl.Xml.xml_element(), String.t(), String.t()) ::
  {:ok, {Ootempl.Xml.xml_element(), Ootempl.Xml.xml_element()}}
  | {:error, :if_marker_not_found | :endif_marker_not_found}

Finds section boundaries in an XML document for a conditional section.

Locates the paragraph containing the {{if}} marker (start boundary) and the paragraph containing the {{endif}} marker (end boundary).

Parameters

• xml_element - The XML element to search within
• if_marker - The full if marker text to find (e.g., "{{if active}}")
• endif_marker - The endif marker text to find (e.g., "{{endif}}")

Returns

• {:ok, {start_paragraph, end_paragraph}} if both boundaries found
• {:error, :if_marker_not_found} if the if marker is not found
• {:error, :endif_marker_not_found} if the endif marker is not found

Examples

# See integration tests for XML examples

@spec validate_pairs([conditional()]) :: :ok | {:error, String.t()}

Validates that all conditional markers are properly paired.

Ensures each {{if}} has a corresponding {{endif}} and detects orphaned markers. Also validates that {{else}} markers are properly placed within if/endif blocks and that there is at most one {{else}} per block.

Parameters

• conditionals - List of conditional markers from detect_conditionals/1

Returns

• :ok if all markers are properly paired
• {:error, reason} if validation fails

Examples

iex> Ootempl.Conditional.validate_pairs([
...>   %{type: :if, condition: "name", path: ["name"], position: 0},
...>   %{type: :endif, condition: nil, path: nil, position: 10}
...> ])
:ok

iex> Ootempl.Conditional.validate_pairs([
...>   %{type: :if, condition: "name", path: ["name"], position: 0}
...> ])
{:error, "Unmatched {{if name}} at position 0"}

iex> Ootempl.Conditional.validate_pairs([
...>   %{type: :endif, condition: nil, path: nil, position: 0}
...> ])
{:error, "Orphan {{endif}} at position 0 (no matching {{if}})"}

iex> Ootempl.Conditional.validate_pairs([
...>   %{type: :else, condition: nil, path: nil, position: 0}
...> ])
{:error, "Orphan {{else}} at position 0 (no matching {{if}})"}

iex> Ootempl.Conditional.validate_pairs([
...>   %{type: :if, condition: "x", path: ["x"], position: 0},
...>   %{type: :else, condition: nil, path: nil, position: 10},
...>   %{type: :else, condition: nil, path: nil, position: 20},
...>   %{type: :endif, condition: nil, path: nil, position: 30}
...> ])
{:error, "Multiple {{else}} markers in conditional block starting at position 0"}