sassone

defmodule Sassone do
  @moduledoc ~S"""
  Sassone is an XML SAX parser and encoder.

  Sassone provides functions to parse XML file in both binary and streaming way in compliant
  with [Extensible Markup Language (XML) 1.0 (Fifth Edition)](https://www.w3.org/TR/xml/).

  Sassone also offers DSL and API to transform structs to and from XML documents.
  See "Encoder" section below for more information.

  ## Parser

  Sassone parser supports two modes of parsing: SAX and simple form.

  ### SAX mode (Simple API for XML)

  SAX is an event driven algorithm for parsing XML documents. A SAX parser takes XML document as the input
  and emits events out to a pre-configured event handler during parsing.

  There are several types of SAX events supported by Sassone:

  * `:start_document` - after prolog is parsed.
  * `:start_element` - when open tag is parsed.
  * `:characters` - when a chunk of `CharData` is parsed.
  * `:cdata` - when a chunk of `CData` is parsed.
  * `:end_element` - when end tag is parsed.
  * `:end_document` - when the root element is closed.

  See `Sassone.Handler` for more information.

  ### Encoding

  Sassone **only** supports UTF-8 encoding. It also respects the encoding set in XML document prolog, which means
  that if the declared encoding is not UTF-8, the parser stops. Anyway, when there is no encoding declared,
  Sassone defaults the encoding to UTF-8.

  ### Reference expansion

  Sassone supports expanding character references and XML 1.0 predefined entity references, for example `A`
  is expanded to `"A"`, `&` to `"&"`, and `&` to `"&"`.

  Sassone does not expand external entity references, but provides an option to specify how they should be handled.
  See more in "Shared options" section.

  ### Creation of atoms

  Sassone does not create atoms during the parsing process.

  ### DTD and XSD

  Sassone does not support parsing DTD (Doctype Definition) and XSD schemas. When encountering DTD, the parser simply
  skips that.

  ### Shared options

  * `:expand_entity` - specifies how external entity references should be handled. Three supported strategies respectively are:
    * `:keep` - keep the original binary, for example `Orange ®` will be expanded to `"Orange ®"`, this is the default strategy.
    * `:skip` - skip the original binary, for example `Orange ®` will be expanded to `"Orange "`.
    * `{mod, fun, args}` - take the applied result of the specified MFA.
    * `:never` - keep the original binary, including predefined entity reference, e.g. `"Orange &"` will remain `"Orange &"`
  * `:cdata_as_characters` - `true` to emit CData events as `:characters`. Defaults to `true`.

  ## Encoder

  Sassone offers two APIs to build simple form and encode XML document.

  Use `Sassone.XML` to build and compose XML simple form, then `Sassone.encode!/2`
  to encode the built element into XML binary.

      iex> import Sassone.XML
      iex> element = element("person", [attribute("gender", "female")], ["Alice"])
      {nil, "person", [{nil, "gender", "female"}], ["Alice"]}
      iex> Sassone.encode!(element, [version: "1.0"])
      "<?xml version=\"1.0\"?><person gender=\"female\">Alice</person>"

  See `Sassone.XML` for more XML building APIs.
  """

  @compile {:inline, do_transform_stream: 4}

  alias Sassone.{Handler, ParseError, Parser, Prolog, XML}
  alias Sassone.Handler.Accumulating
  alias Sassone.Parser.State

  @doc ~S"""
  Parses XML binary data.

  This function takes XML binary, SAX event handler (see more at `Sassone.Handler`) and an initial state as the input, it returns
  `{:ok, state}` if parsing is successful, otherwise `{:error, exception}`, where `exception` is a
  `Sassone.ParseError` struct which can be converted into readable message with `Exception.message/1`.

  The third argument `state` can be used to keep track of data and parsing progress when parsing is happening, which will be
  returned when parsing finishes.

  ### Options

  See the “Shared options” section at the module documentation.

  ## Examples

      defmodule MyTestHandler do
        @behaviour Sassone.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, {namespace, 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

      iex> xml = "<?xml version='1.0' ?><foo bar='value'></foo>"
      iex> Sassone.parse_string(xml, Sassone.TestHandlers.MyTestHandler, [])
      {:ok,
       [{:end_document},
        {:end_element, {nil, "foo"}},
        {:start_element, nil, "foo", [{nil, "bar", "value"}]},
        {:start_document, [version: "1.0"]}]}
  """

  @spec parse_string(String.t(), Handler.t(), Handler.state(), options :: Keyword.t()) ::
          {:ok, state :: term()}
          | {:halt, Handler.state(), rest :: String.t()}
          | {:error, ParseError.t()}
  def parse_string(data, handler, initial_state, options \\ [])
      when is_binary(data) and is_atom(handler) do
    state = %State{
      prolog: nil,
      handler: handler,
      user_state: initial_state,
      expand_entity: options[:expand_entity] || :keep,
      cdata_as_characters: Keyword.get(options, :cdata_as_characters, true),
      character_data_max_length: :infinity
    }

    case Parser.Binary.parse_prolog(data, false, data, 0, state) do
      {:ok, state} ->
        {:ok, state.user_state}

      {:halt, state, {buffer, pos}} ->
        length = byte_size(buffer) - pos
        {:halt, state.user_state, binary_part(buffer, pos, length)}

      {:error, _reason} = error ->
        error
    end
  end

  @doc ~S"""
  Parses XML stream data.

  This function takes a stream, SAX event handler (see more at `Sassone.Handler`) and an initial state as the input, it returns
  `{:ok, state}` if parsing is successful, otherwise `{:error, exception}`, where `exception` is a
  `Sassone.ParseError` struct which can be converted into readable message with `Exception.message/1`.

  ## Examples

      defmodule MyTestHandler do
        @behaviour Sassone.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, {namespace, 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

      iex> stream = File.stream!("./test/support/fixture/foo.xml")
      iex> Sassone.parse_stream(stream, Sassone.TestHandlers.MyTestHandler, [])
      {:ok,
       [{:end_document},
        {:end_element, {nil, "foo"}},
        {:start_element, nil, "foo", [{nil, "bar", "value"}]},
        {:start_document, [version: "1.0"]}]}

  ## Memory usage

  `Sassone.parse_stream/3` takes a `File.Stream` or `Stream` as the input, so the amount of bytes to buffer in each
  chunk can be controlled by `File.stream!/3` API.

  During parsing, the actual memory used by Sassone might be higher than the number configured for each chunk, since
  Sassone holds in memory some parsed parts of the original binary to leverage Erlang sub-binary extracting. Anyway,
  Sassone tries to free those up when it makes sense.

  ### Options

  See the “Shared options” section at the module documentation.

  * `:character_data_max_length` - tells the parser to emit the `:characters` event when its length exceeds the specified
    number. The option is useful when the tag being parsed containing a very large chunk of data. Defaults to `:infinity`.

  """

  @spec parse_stream(Enumerable.t(), Handler.t(), Handler.state(), options :: Keyword.t()) ::
          {:ok, state :: term()}
          | {:halt, state :: term(), rest :: String.t()}
          | {:error, exception :: ParseError.t()}

  def parse_stream(stream, handler, initial_state, options \\ []) do
    expand_entity = Keyword.get(options, :expand_entity, :keep)
    character_data_max_length = Keyword.get(options, :character_data_max_length, :infinity)
    cdata_as_characters = Keyword.get(options, :cdata_as_characters, true)

    state = %State{
      prolog: nil,
      handler: handler,
      user_state: initial_state,
      expand_entity: expand_entity,
      cdata_as_characters: cdata_as_characters,
      character_data_max_length: character_data_max_length
    }

    init = {&Parser.Stream.parse_prolog(&1, &2, &1, 0, &3), state}

    case stream
         |> Stream.concat([:end_of_stream])
         |> Enum.reduce_while(init, &reduce_stream/2) do
      {:ok, state} ->
        {:ok, state.user_state}

      {:halt, state, {buffer, pos}} ->
        length = byte_size(buffer) - pos
        {:halt, state.user_state, binary_part(buffer, pos, length)}

      {:error, reason} ->
        {:error, reason}
    end
  end

  defp reduce_stream(:end_of_stream, {cont_fun, state}) do
    {:halt, cont_fun.(<<>>, false, state)}
  end

  defp reduce_stream(buffer, {cont_fun, state}) do
    case cont_fun.(buffer, true, state) do
      {:halted, cont_fun, state} ->
        {:cont, {cont_fun, state}}

      other ->
        {:halt, other}
    end
  end

  @doc """
  Parses XML stream and returns a stream of elements.

  This function takes a stream and returns a stream of xml SAX events.
  When any parsing error occurs, it raises a `Sassone.ParseError` exception.


  ## Examples

      iex> stream = File.stream!("./test/support/fixture/foo.xml")
      iex> Enum.to_list Sassone.stream_events stream
      [
        start_document: [version: "1.0"],
        start_element: {nil, "foo", [{nil, "bar", "value"}]},
        end_element: {nil, "foo"}
      ]
      iex> Enum.to_list Sassone.stream_events ["<foo>unclosed value"]
      ** (Sassone.ParseError) unexpected end of input, expected token: :chardata

  > #### Warning {: .warning }
  >
  > Input stream is evaluated lazily, therefore some events may be emitted before
  > exception is raised

  ## Memory usage

  `Sassone.stream_events/2` takes a `File.Stream` or `Stream` as the input, so the amount of bytes to buffer in each
  chunk can be controlled by `File.stream!/3` API.

  During parsing, the actual memory used by Sassone might be higher than the number configured for each chunk, since
  Sassone holds in memory some parsed parts of the original binary to leverage Erlang sub-binary extracting. Anyway,
  Sassone tries to free those up when it makes sense.

  ### Options

  See the “Shared options” section at the module documentation.

  * `:character_data_max_length` - tells the parser to emit the `:characters` event when its length exceeds the specified
    number. The option is useful when the tag being parsed containing a very large chunk of data. Defaults to `:infinity`.
  """
  @spec stream_events(Enumerable.t(), options :: Keyword.t()) :: Enumerable.t()
  def stream_events(stream, options \\ []) do
    expand_entity = Keyword.get(options, :expand_entity, :keep)
    character_data_max_length = Keyword.get(options, :character_data_max_length, :infinity)
    cdata_as_characters = Keyword.get(options, :cdata_as_characters, true)

    state = %State{
      prolog: nil,
      handler: Accumulating,
      user_state: [],
      expand_entity: expand_entity,
      cdata_as_characters: cdata_as_characters,
      character_data_max_length: character_data_max_length
    }

    init = {&Parser.Stream.parse_prolog(&1, &2, &1, 0, &3), state}

    stream
    |> Stream.concat([:end_of_stream])
    |> Stream.transform(init, &transform_stream/2)
  end

  defp transform_stream(:end_of_stream, {cont_fun, state}),
    do: do_transform_stream(<<>>, false, cont_fun, state)

  defp transform_stream(buffer, {cont_fun, state}),
    do: do_transform_stream(buffer, true, cont_fun, state)

  defp do_transform_stream(buffer, more?, cont_fun, state) do
    case cont_fun.(buffer, more?, state) do
      {:halted, cont_fun, %{user_state: user_state} = state} ->
        {:lists.reverse(user_state), {cont_fun, %{state | user_state: []}}}

      {:error, error} ->
        raise error

      other ->
        {:halt, other}
    end
  end

  @doc """
  Encodes a simple form XML element into string.

  This function encodes an element in simple form format and a prolog to an XML document.

  ## Examples

      iex> import Sassone.XML
      iex> root = element("foo", [attribute("foo", "bar")], ["bar"])
      iex> prolog = [version: "1.0"]
      iex> Sassone.encode!(root, prolog)
      "<?xml version=\\"1.0\\"?><foo foo=\\"bar\\">bar</foo>"
      iex> prolog = [version: "1.0", encoding: "UTF-8"]
      iex> Sassone.encode!(root, prolog)
      "<?xml version=\\"1.0\\" encoding=\\"UTF-8\\"?><foo foo=\\"bar\\">bar</foo>"
  """
  @spec encode!(XML.element(), Prolog.t() | Keyword.t() | nil) :: String.t()
  def encode!(root, prolog \\ nil) do
    root
    |> encode_to_iodata(prolog)
    |> IO.iodata_to_binary()
  end

  @doc """
  Encodes a simple form element into IO data.

  Same as `encode!/2` but this encodes the document into IO data.

  ## Examples

      iex> import Sassone.XML
      iex> root = element("foo", [attribute("foo", "bar")], ["bar"])
      iex> prolog = [version: "1.0"]
      iex> Sassone.encode_to_iodata!(root, prolog)
      [
        [~c'<?xml', [32, ~c'version', 61, 34, "1.0", 34], [], [], ~c'?>'],
        [60, "foo", 32, "foo", 61, 34, "bar", 34],
        62,
        ["bar"],
        [60, 47, "foo", 62]
      ]

  """
  @spec encode_to_iodata!(XML.element(), Prolog.t() | Keyword.t() | nil) :: iodata()
  def encode_to_iodata!(root, prolog \\ nil), do: encode_to_iodata(root, prolog)

  defp encode_to_iodata(root, prolog) do
    prolog = prolog(prolog)
    element = element(root)

    [prolog | element]
  end

  defp prolog(%Prolog{} = prolog) do
    [
      ~c"<?xml",
      version(prolog.version),
      encoding(prolog.encoding),
      standalone(prolog.standalone),
      ~c"?>"
    ]
  end

  defp prolog(prolog) when is_list(prolog) do
    prolog
    |> Prolog.from_keyword()
    |> prolog()
  end

  defp prolog(nil), do: []

  defp version(version), do: [?\s, ~c"version", ?=, ?", version, ?"]

  defp encoding(nil), do: []
  defp encoding(:utf8), do: [?\s, ~c"encoding", ?=, ?", ~c"utf-8", ?"]

  defp encoding(encoding) when encoding in ["UTF-8", "utf-8"],
    do: [?\s, ~c"encoding", ?=, ?", ~c(#{encoding}), ?"]

  defp standalone(true), do: [?\s, ~c"standalone", ?=, ?", "yes", ?"]
  defp standalone(_standalone), do: []

  defp element({ns, tag_name, attributes, []}), do: [start_tag(ns, tag_name, attributes), ?/, ?>]

  defp element({ns, tag_name, attributes, content}) do
    [
      start_tag(ns, tag_name, attributes),
      ?>,
      content(content),
      end_tag(ns, tag_name, content)
    ]
  end

  defp start_tag(nil, tag_name, attributes), do: [?<, tag_name | attributes(attributes)]
  defp start_tag(ns, tag_name, attributes), do: [?<, ns, ?:, tag_name | attributes(attributes)]

  defp attributes([]), do: []

  defp attributes([{nil, name, value} | attributes]),
    do: [?\s, name, ?=, ?", escape(value, 0, value), ?" | attributes(attributes)]

  defp attributes([{namespace, name, value} | attributes]),
    do: [?\s, namespace, ?:, name, ?=, ?", escape(value, 0, value), ?" | attributes(attributes)]

  defp content([]), do: []

  defp content([{:characters, characters} | elements]) do
    [characters(characters) | content(elements)]
  end

  defp content([{:cdata, cdata} | elements]) do
    [cdata(cdata) | content(elements)]
  end

  defp content([{:reference, reference} | elements]) do
    [reference(reference) | content(elements)]
  end

  defp content([{:comment, comment} | elements]) do
    [comment(comment) | content(elements)]
  end

  defp content([{:processing_instruction, name, content} | elements]) do
    [processing_instruction(name, content) | content(elements)]
  end

  defp content([characters | elements]) when is_binary(characters) do
    [characters | content(elements)]
  end

  defp content([element | elements]) do
    [element(element) | content(elements)]
  end

  defp end_tag(nil, tag_name, _other), do: [?<, ?/, tag_name, ?>]
  defp end_tag(ns, tag_name, _other), do: [?<, ?/, ns, ?:, tag_name, ?>]

  defp characters(characters), do: escape(characters, 0, characters)

  escapes = [{?<, ~c"&lt;"}, {?>, ~c"&gt;"}, {?&, ~c"&amp;"}, {?", ~c"&quot;"}, {?', ~c"&apos;"}]

  for {match, insert} <- escapes do
    defp escape(<<unquote(match), rest::bits>>, len, original),
      do: [binary_part(original, 0, len), unquote(insert) | escape(rest, 0, rest)]
  end

  defp escape(<<>>, _len, original), do: original

  defp escape(<<_, rest::bits>>, len, original), do: escape(rest, len + 1, original)

  defp cdata(characters), do: [~c"<![CDATA[", characters | ~c"]]>"]

  defp reference({:entity, reference}), do: [?&, reference, ?;]
  defp reference({:hexadecimal, reference}), do: [?&, ?x, Integer.to_string(reference, 16), ?;]
  defp reference({:decimal, reference}), do: [?&, ?x, Integer.to_string(reference, 10), ?;]

  defp comment(comment), do: [~c"<!--", escape_comment(comment, comment) | ~c"-->"]

  defp escape_comment(<<?->>, original), do: [original, ?\s]
  defp escape_comment(<<>>, original), do: original
  defp escape_comment(<<_char, rest::bits>>, original), do: escape_comment(rest, original)

  defp processing_instruction(name, content), do: [~c"<?", name, ?\s, content | ~c"?>"]
end