@spec parse_string(data :: binary(), options :: Keyword.t()) ::
  {:ok, t()} | {:error, exception :: Saxy.ParseError.t()}

Parse given string into simple form.

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 return CData as characters, false to wrap CData as {:cdata, data}. Defaults to true.

Note that it is recommended to disable :cdata_as_characters if the outcome simple form data is meant to be re-encoded later. Consider the following example, the encoded document has different sematics from the original one.

iex> xml = "<foo><![CDATA[<greeting>Hello, world!</greeting>]]></foo>"
iex> {:ok, simple_form} = Saxy.SimpleForm.parse_string(xml, cdata_as_characters: true)
{:ok, {"foo", [], ["<greeting>Hello, world!</greeting>"]}}
iex> Saxy.encode!(simple_form)
"<foo><greeting>Hello, world!</greeting></foo>"

Examples

Given this XML document.

iex> xml = """
...> <?xml version="1.0" encoding="utf-8" ?>
...> <menu>
...>   <movie url="https://www.imdb.com/title/tt0120338/" id="tt0120338">
...>     <name>Titanic</name>
...>     <characters>Jack &amp; Rose</characters>
...>   </movie>
...>   <movie url="https://www.imdb.com/title/tt0109830/" id="tt0109830">
...>     <name>Forest Gump</name>
...>     <characters>Forest &amp; Jenny</characters>
...>   </movie>
...> </menu>
...> """
iex> Saxy.SimpleForm.parse_string(xml)
{:ok,
 {"menu", [],
  [
    "\n  ",
    {
      "movie",
      [
        {"url", "https://www.imdb.com/title/tt0120338/"},
        {"id", "tt0120338"}
      ],
      [
        "\n    ",
        {"name", [], ["Titanic"]},
        "\n    ",
        {"characters", [], ["Jack & Rose"]},
        "\n  "]
    },
    "\n  ",
    {
      "movie",
      [
        {"url", "https://www.imdb.com/title/tt0109830/"},
        {"id", "tt0109830"}
      ],
      [
        "\n    ",
        {"name", [], ["Forest Gump"]},
        "\n    ",
        {"characters", [], ["Forest & Jenny"]},
        "\n  "
      ]
    },
    "\n"
  ]}}