# `Statifier.Parser.DOM`
[🔗](https://github.com/riddler/statifier-ex/blob/v2.0.0/lib/statifier/parser/dom.ex#L1)

The generic document tree `Statifier.Parser.parse/1` produces, and the three
accessors every lowering builder would otherwise re-implement.

A tree is `Statifier.Parser.DOM.Element` structs whose `children` interleave
further elements with `Statifier.Parser.DOM.Text` runs in document order,
each carrying a `Statifier.Parser.Location` span.

The tree is deliberately unvalidated: unknown names, duplicate attributes,
missing namespace declarations, and structurally nonsensical documents all
parse successfully. The DOM reports what was written and lets the validator
object.

# `attribute`

```elixir
@spec attribute(element :: Statifier.Parser.DOM.Element.t(), name :: binary()) ::
  Statifier.Parser.DOM.Attribute.t() | nil
```

The first attribute of `element` named `name`, or `nil`.

First, not only: duplicates are preserved in `attributes`, so a caller that
wants to report one has the whole list to look at.

# `elements`

```elixir
@spec elements(element :: Statifier.Parser.DOM.Element.t()) :: [
  Statifier.Parser.DOM.Element.t()
]
```

`element`'s children, filtered to elements.

The whitespace filter for readers that want structure rather than markup:
text runs between child elements are kept in the tree (the parser cannot
know which of them are significant without knowing the vocabulary), and
this is where a caller drops them.

# `text`

```elixir
@spec text(element :: Statifier.Parser.DOM.Element.t()) :: binary()
```

The concatenated decoded value of `element`'s direct text children.

Child elements contribute nothing - this is the text of `element` itself,
not of the subtree.

---

*Consult [api-reference.md](api-reference.md) for complete listing*