# `Md.Listener`
[🔗](https://github.com/am-kantox/md/blob/v0.15.1/lib/md/listener.ex#L1)

The listener behaviour to attach to the parser to receive callbacks
when the elements are encountered and processed.

# `attributes`

```elixir
@type attributes() :: XmlBuilder.Element.attrs()
```

# `branch`

```elixir
@type branch() :: XmlBuilder.Element.content()
```

# `callback`

```elixir
@type callback() :: (state() -> state())
```

# `context`

```elixir
@type context() ::
  :start
  | :break
  | :linefeed
  | :whitespace
  | :custom
  | {:substitute, {binary(), binary()}}
  | {:esc, binary()}
  | {:char, binary()}
  | {:tag, {binary(), element()}, atom()}
  | :finalize
  | :end
```

# `element`

```elixir
@type element() :: XmlBuilder.Element.name()
```

# `leaf`

```elixir
@type leaf() :: XmlBuilder.Element.content()
```

# `parse_mode`

```elixir
@type parse_mode() ::
  :idle
  | :finished
  | :raw
  | :skip
  | :comment
  | {:comment, binary()}
  | :magnet
  | :md
  | {:outer, :md}
  | {:linefeed, non_neg_integer()}
  | {:nested, element(), non_neg_integer()}
  | {:inner, :raw}
  | {:inner, element(), non_neg_integer()}
```

# `state`

```elixir
@type state() :: %Md.Parser.State{
  path: [trace()],
  mode: [parse_mode()],
  type: module(),
  ast: [branch()],
  listener: nil | module(),
  payload: any(),
  bag: %{
    indent: [non_neg_integer() | atom()],
    stock: [branch()],
    deferred: [{binary(), binary()}]
  }
}
```

# `trace`

```elixir
@type trace() :: branch()
```

# `element`

```elixir
@callback element(context(), state()) :: :ok | {:update, state()}
```

Called for every parsing event.

Return `:ok` to leave the parser state untouched, or `{:update, state}` to
replace it -- which is how a listener rewrites the AST as it is built.

# `__using__`
*macro* 

Generates a listener with no-op handlers for every event.

## Options

  * `:emoji` -- the marker used by the default debug logging. Default: `"📑"`.
  * `:debug` -- when `true`, the generated `handle_start/1`, `handle_end/1`
    and `handle_tag/2` log at `:debug` level. Default: `false`.

A listener should be silent unless it is explicitly asked to be: a library
that logs on every parsed element is unusable in production.

---

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