SweetXml Documentation

The ~x sigil allows you to define XPath 1.0 paths. Warning: Because SweetXml uses xmerl internally, only XPath 1.0 paths are supported.

If you do not import SweetXml, you must use the %SweetXpath{} struct instead of the sigil.

# Using the sigil after importing
import SweetXml
~x"//some/path"

# Using the struct without importing
%SweetXpath{path: '//some/path', is_value: false, is_list: false, cast_to: false}

SweetXml allows you to transform XML into complex Elixir structures using xpath/2 or xmap/2. You can define nested maps and lists by passing additional arguments to xpath/2 or by nesting ~x expressions.

# Mapping to a nested structure using xpath/2
doc
|> xpath(
  ~x"//li"l,
  name: [
    ~x"./name",
    first: ~x"./first/text()",
    last: ~x"./last/text()"
  ],
  age: ~x"./age/text()"i
)

To support namespaces, you must parse the XML with the namespace_conformant: true option. You can then use add_namespace/2 to map preferred prefixes to the document's URIs, allowing you to query nodes in a prefix-independent way.

import SweetXml

# 1. Parse with namespace_conformant: true
doc = parse(xml_str, namespace_conformant: true)

# 2. Use add_namespace to define prefixes for your XPath
result = doc
  |> xpath(~x"//ff:matchup/ff:name/text()"
           |> add_namespace("ff", "http://example.com/fantasy-league"))

Add sweet_xml to your project's mix.exs dependencies.

Note: SweetXml depends on :xmerl. On some Linux systems, you may need to manually install the erlang-xmerl package.

def deps do
  [{:sweet_xml, "~> 0.7.5"}]
end

When processing XML from untrusted sources, you should separate the parsing step from the mapping step to prevent unintended behavior via options. It is highly recommended to disable DTD processing by passing dtd: :none to the parsing functions.

For standard parsing and XPath extraction, use:

doc |> SweetXml.parse(dtd: :none) |> SweetXml.xpath(spec, subspec)

For streaming tags, use:

enum |> SweetXml.stream_tags(tags, dtd: :none)

# Recommended pattern for untrusted XML
doc |> SweetXml.parse(dtd: :none) |> SweetXml.xpath(spec, subspec)

# Recommended pattern for streaming untrusted XML
enum |> SweetXml.stream_tags(tags, dtd: :none)

For large XML files, use stream_tags/2 to process specific elements one by one without loading the entire document into memory. This works with any Elixir stream, such as one created by File.stream!/1.

Memory Management: When processing large documents, use the discard: [...] option in stream_tags/2 to prevent memory leaks by discarding processed tags.

file_stream = File.stream!("large_file.xml")

result = file_stream
|> stream_tags([:li, :special_match_key], discard: [:li, :special_match_key])
|> Stream.map(fn
    {_, doc} -> xpath(doc, ~x"./text()")
  end)
|> Enum.to_list()

The ~x sigil is a convenient way to create %SweetXpath{} structs. It allows you to define XPath 1.0 paths with modifiers that control the return type and behavior. To use it, you should first import SweetXml.

import SweetXml
~x"//some/path"l

When processing untrusted XML, it is highly recommended to restrict DTD (Document Type Definition) parsing to prevent attacks. Use the dtd option in parse/2.

Options for :dtd:

• :none: Prevents both internal and external entities. Recommended for untrusted XML.
• :all: Allows all DTDs (default).
• :internal_only: Blocks all attempts at external fetching.
• [only: entities]: Only allows specific entities (where entities is an atom or a list of atoms).

# Secure parsing pattern
doc
|> parse(dtd: :none)
|> xmap(specs)

You can apply Elixir functions to the results of an XPath query using transform_by/2. This is useful for data cleaning (e.g., capitalizing strings) or breaking complex parsing logic into reusable functions.

# Using a built-in function
doc |> xpath(
  ~x"//li"l,
  first: ~x"./first/text()"s |> transform_by(&String.capitalize/1)
)

# Using a custom function for complex nesting
parse_name = fn xpath_node ->
  xpath_node |>
    xmap(
      first: ~x"./first/text()"s |> transform_by(&String.capitalize/1),
      last: ~x"./last/text()"s |> transform_by(&String.capitalize/1)
    )
end

doc |> xpath(
  ~x"//li"l,
  name: ~x"./name" |> transform_by(parse_name)
)

The SweetXml.Options module is considered an internal API. It is used to manage the complex interaction between user-provided :rules (for XML scanning) and :dtd options.

Use at your own risk. Changes to this module's behavior or function signatures are not guaranteed to be stable for end-users. Most users should interact with SweetXml through its high-level parsing functions rather than manually manipulating these options.