Saxy v0.4.0 Saxy.Handler behaviour View Source

This module provides callbacks for implementing SAX events handler.

Link to this section Summary

Callbacks

Callback for entity reference conversion

Callback for event handling

Link to this section Callbacks

Link to this callback handle_entity_reference(reference_name) View Source
handle_entity_reference(reference_name :: binary()) :: binary()

Callback for entity reference conversion.

Saxy does not handle any entity reference conversion during parsing, this callback will be triggered every time the parser encounters an entity reference.

Examples

defmodule MyEventHandler do
  def handle_event(_event_type, _event_data, state) do
    {:ok, state}
  end

  def handle_entity_reference("amp") do
    "&"
  end

  def handle_entity_reference("gt") do
    "<"
  end

  def handle_entity_reference(_unknown) do
    ""
  end
end
Link to this callback handle_event(event_type, data, user_state) View Source
handle_event(event_type :: atom(), data :: any(), 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.

user_state is the third argument in Saxy.parse_string/3 and Saxy.parse_stream/3. It and can be accumulated, 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 is useful when we want to get the desired return without parsing the whole file.

SAX Events

There are 6 types of event need to be handled in the handler.

:start_document

The event data will be the XML prolog, which is a keyword list of :version, :encoding and :standalone respectively.

:start_element

The event data is the element, which is a two-element tuple, respectively tag name, attributes.

:characters

The event data is the binary that matches CharData* and Reference.

Note that it is not trimmed and includes all the whitespace characters that match CharData.

:end_document

The event data is an empty tuple.

:end_element

The event data is the tag name of the closing element.

Examples

defmodule MyEventHandler do
  @behaviour Saxy.Handler

  def handle_event(:start_document, prolog, state) do
    IO.inspect "Start parsing document"
    {:ok, [{:start_document, prolog} | state]}
  end

  def handle_event(:end_document, _data, state) do
    IO.inspect "Finish parsing document"
    {:ok, [{:end_document} | state]}
  end

  def handle_event(:start_element, {name, attributes}, state) do
    IO.inspect "Start parsing element #{name} with attributes #{inspect(attributes)}"
    {:ok, [{:start_element, name, attributes} | state]}
  end

  def handle_event(:end_element, name, state) do
    IO.inspect "Finish parsing element #{name}"
    {:ok, [{:end_element, name} | state]}
  end

  def handle_event(:characters, chars, state) do
    IO.inspect "Receive characters #{chars}"
    {:ok, [{:chacters, chars} | state]}
  end

  def handle_entity_reference(reference_name) do
    MyHTMLEntities.convert(reference_name)
  end
end