Sax.Handler behaviour (sax v1.0.0) View Source

This module provides callbacks to implement SAX events handler.

Link to this section Summary

Link to this section Types

Specs

characters_data() :: String.t()

Specs

end_document_data() :: any()

Specs

end_element_data() :: name :: String.t()

Specs

Specs

event_name() ::
  :start_document | :end_document | :start_element | :characters | :end_element

Specs

start_document_data() :: Keyword.t()

Specs

start_element_data() ::
  {name :: String.t(),
   attributes :: [{name :: String.t(), value :: String.t()}]}

Link to this section Callbacks

Link to this callback

handle_event(event_type, data, user_state)

View Source

Specs

handle_event(
  event_type :: event_name(),
  data :: event_data(),
  user_state :: any()
) :: {:ok, user_state :: any()} | {:stop, returning :: any()}

Callback for event handling.

This callback takes an event type, an event data and user_state as the input.

The initial user_state is the third argument in Sax.parse_string/3 and Sax.parse_stream/3. It can be accumulated and passed around during the parsing time by returning it as the result of the callback implementation, which can be used to keep track of data when parsing is happening.

Returning {:ok, new_state} continues the parsing process with the new state.

Returning {:stop, anything} stops the prosing process immediately, and anything will be returned. This feature is usually handy when we want to get the desired return without parsing the whole file.

SAX Events

There are a couple of events that need to be handled in the handler.

  • :start_document.
  • :start_element.
  • :characters–the binary that matches CharData* and Reference. Note that it is not trimmed and includes ALL whitespace characters that match CharData.
  • :end_document.
  • :end_element.

Check out event_data() type for more information of what are emitted for each event type.

Examples

defmodule MyEventHandler do
  @behaviour Sax.Handler

  def handle_event(:start_document, prolog, state) do
    {:ok, [{:start_document, prolog} | state]}
  end

  def handle_event(:end_document, _data, state) do
    {:ok, [{:end_document} | state]}
  end

  def handle_event(:start_element, {name, attributes}, state) do
    {:ok, [{:start_element, name, attributes} | state]}
  end

  def handle_event(:end_element, name, state) do
    {:ok, [{:end_element, name} | state]}
  end

  def handle_event(:characters, chars, state) do
    {:ok, [{:chacters, chars} | state]}
  end
end