SweetXml

https://hexdocs.pm/sweet_xml/
Admin
SweetXml is a thin wrapper around Erlang's xmerl that enables elegant XML parsing and querying in...
Tokens:10,053
Snippets:97
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Sample XML document

Source: https://hexdocs.pm/sweet_xml/index.html

Example XML structure used for demonstration purposes.

```xml
<?xml version="1.05" encoding="UTF-8"?>
<game>
  <matchups>
    <matchup winner-id="1">
      <name>Match One</name>
      <teams>
        <team>
          <id>1</id>
          <name>Team One</name>
        </team>
        <team>
          <id>2</id>
          <name>Team Two</name>
        </team>
      </teams>
    </matchup>
    <matchup winner-id="2">
      <name>Match Two</name>
      <teams>
        <team>
          <id>2</id>
          <name>Team Two</name>
        </team>
        <team>
          <id>3</id>
          <name>Team Three</name>
        </team>
      </teams>
    </matchup>
    <matchup winner-id="1">
      <name>Match Three</name>
      <teams>
        <team>
          <id>1</id>
          <name>Team One</name>
        </team>
        <team>
          <id>3</id>
          <name>Team Three</name>
        </team>
      </teams>
    </matchup>
  </matchups>
</game>
```

--------------------------------

### Define XML document

Source: https://hexdocs.pm/sweet_xml/readme.html

Example XML document structure used for namespace demonstration.

```xml
<?xml version="1.05" encoding="UTF-8"?>
<game xmlns="http://example.com/fantasy-league" xmlns:ns1="http://example.com/baseball-stats">
  <matchups>
    <matchup winner-id="1">
      <name>Match One</name>
      <teams>
        <team>
          <id>1</id>
          <name>Team One</name>
          <ns1:runs>5</ns1:runs>
        </team>
        <team>
          <id>2</id>
          <name>Team Two</name>
          <ns1:runs>2</ns1:runs>
        </team>
      </teams>
    </matchup>
  </matchups>
</game>
```

--------------------------------

### Sample XML document structure

Source: https://hexdocs.pm/sweet_xml/readme.html

An example XML document used for demonstrating streaming capabilities.

```xml
<?xml version="1.05" encoding="UTF-8"?>
<html>
  <head>
    <title>XML Parsing</title>
    <head><title>Nested Head</title></head>
  </head>
  <body>
    <p>Neato €</p><ul>
      <li class="first star" data-index="1">
        First</li><li class="second">Second
      </li><li
            class="third">Third</li>
    </ul>
    <div>
      <ul>
        <li>Forth</li>
      </ul>
    </div>
    <special_match_key>first star</special_match_key>
  </body>
</html>
```

--------------------------------

### Streaming XML Tags with SweetXml

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Process large XML documents efficiently using `SweetXml.stream_tags/3`. This example demonstrates streaming list items (`:li`) and extracting their text content using `SweetXml.xpath/2` within a stream pipeline.

```elixir
iex> import SweetXml
iex> doc = ["<ul><li>l1</li><li>l2", "</li><li>l3</li></ul>"]
iex> SweetXml.stream_tags(doc, :li)
...> |> Stream.map(fn {:li, doc} ->
...>      doc |> SweetXml.xpath(~x"./text()")
...>    end)
...> |> Enum.to_list
['l1', 'l2', 'l3']
```

--------------------------------

### Initialize SweetXml

Source: https://hexdocs.pm/sweet_xml/index.html

Import the module and prepare the document variable.

```elixir
import SweetXml
doc = "..." # as above
```

--------------------------------

### Query with single namespace

Source: https://hexdocs.pm/sweet_xml/readme.html

Uses add_namespace to map a custom prefix to a specific URI.

```elixir
result = doc
  |> xpath(~x"//ff:matchup/ff:name/text()"
           |> add_namespace("ff", "http://example.com/fantasy-league"))

assert result == 'Match One'
```

--------------------------------

### Query with multiple namespaces

Source: https://hexdocs.pm/sweet_xml/readme.html

Demonstrates chaining multiple add_namespace calls for complex queries.

```elixir
result = doc
  |> xpath(~x"//ff:matchup//bb:runs/text()"
           |> add_namespace("ff", "http://example.com/fantasy-league")
           |> add_namespace("bb", "http://example.com/baseball-stats"))

assert result == '5'
```

--------------------------------

### Parse XML with namespaces

Source: https://hexdocs.pm/sweet_xml/readme.html

Initializes the document with namespace_conformant set to true to enable prefix-independent node identification.

```elixir
import SweetXml
xml_str = "..." # as above
doc = parse(xml_str, namespace_conformant: true)
```

--------------------------------

### Verify ~x sigil structure

Source: https://hexdocs.pm/sweet_xml/readme.html

Demonstrates the internal structure of the SweetXpath struct when using the ~x sigil.

```elixir
assert ~x"//some/path"e == %SweetXpath{path: '//some/path', is_value: false, is_list: false, cast_to: false}
```

--------------------------------

### Simple XPath Query in SweetXml

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Demonstrates a basic XPath query to extract text content from an XML element. Ensure SweetXml is imported before use.

```elixir
iex> import SweetXml
iex> doc = "<h1><a>Some linked title</a></h1>"
doc |> xpath(~x"//a/text()")
'Some linked title'copy
```

--------------------------------

### Import SweetXml Module

Source: https://hexdocs.pm/sweet_xml/readme.html

Import the SweetXml module to use its functions, such as `xpath` and `xmap`, in your Elixir code.

```elixir
import SweetXml
doc = "..." # XML document as a string
```

--------------------------------

### Add SweetXml Dependency

Source: https://hexdocs.pm/sweet_xml/readme.html

Add the SweetXml dependency to your project's mix.exs file to include it in your project.

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

--------------------------------

### Simple XPath Query with SweetXml

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Use `SweetXml.xpath/2` to extract text content from an XML document using a simple XPath expression. Ensure `SweetXml` is imported for direct use of the `~x` sigil.

```elixir
iex> import SweetXml
iex> doc = "<h1><a>Some linked title</a></h1>"
iex> doc |> xpath(~x"//a/text()")
'Some linked title'
```

--------------------------------

### stream/2

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Creates an element stream from an XML document using an options callback.

```APIDOC
## stream(doc, options_callback)

### Description
Creates an element stream from an XML doc. This is a lower level API for fine control of data streaming.

### Parameters
#### Request Body
- **doc** (Enumerable) - Required - The XML document source.
- **options_callback** (function) - Required - Anonymous function to define xmerl callbacks and emit data.
```

--------------------------------

### Use XPath Sigil

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Creates a %SweetXpath{} struct using the ~x sigil, with various modifiers to control return types and behavior.

```elixir
iex> SweetXml.sigil_x("//some/path", 'e')
%SweetXpath{path: '//some/path', is_value: false, cast_to: false, is_list: false, is_keyword: false}
```

```elixir
iex> import SweetXml
iex> ~x"//some/path"e
%SweetXpath{path: '//some/path', is_value: false, cast_to: false, is_list: false, is_keyword: false}
```

--------------------------------

### XPath Query with Optional Mapping in SweetXml

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Shows how to use XPath with optional mapping to extract specific data points from an XML document. The mapping uses keyword lists to define data extraction paths.

```elixir
iex> import SweetXml
iex> doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
doc |> xpath(~x"//header", message: ~x"./p/text()", a_in_li: ~x".//li/a/text()"l)
%{a_in_li: ['Two'], message: 'Message'}copy
```

--------------------------------

### Streaming XML with File.stream!/1

Source: https://hexdocs.pm/sweet_xml/readme.html

Process XML files using streams to handle large documents without loading them entirely into memory.

```elixir
File.stream!("file_above.xml") |> xpath(...)
```

--------------------------------

### SweetXml.xmap/2

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Maps XML content into an Elixir map using a keyword list of XPath expressions.

```APIDOC
## SweetXml.xmap/2

### Description
Returns a map with keys mapped to values returned from XPath queries.

### Parameters
- **parent** (String/xmlElement) - Required - The XML document or element.
- **mapping** (Keyword) - Required - A keyword list where keys are map keys and values are XPath specifications.

### Request Example
```elixir
import SweetXml
doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
doc |> xpath(~x"//header", message: ~x"./p/text()", a_in_li: ~x".//li/a/text()"l)
```

### Response
- **result** (map) - A map containing the extracted values.
```

--------------------------------

### Nest XPath queries

Source: https://hexdocs.pm/sweet_xml/readme.html

Allows complex data extraction by nesting XPath definitions within the mapping structure.

```elixir
doc
|> xpath(
  ~x"//li"l,
  name: [
    ~x"./name",
    first: ~x"./first/text()",
    last: ~x"./last/text()"
  ],
  age: ~x"./age/text()"
)
```

--------------------------------

### Extract text with xpath

Source: https://hexdocs.pm/sweet_xml/index.html

Retrieve the text content of the first matching node.

```elixir
result = doc |> xpath(~x"//matchup/name/text()") # `sigil_x` for (x)path
assert result == 'Match One'
```

--------------------------------

### xmap/3

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Maps XML structures into Elixir maps or keyword lists using XPath specifications.

```APIDOC
## xmap(parent, mapping, options)

### Description
Returns a mapping where each value is the result of an xpath query. Supports nested structures.

### Parameters
#### Arguments
- **parent** (doc | xmlElement) - Required - The XML source.
- **mapping** (keyword) - Required - The mapping specification.
- **options** (boolean | map) - Optional - If true, returns a keyword list instead of a map.

### Response
- **map | keyword** - The resulting mapped data structure.
```

--------------------------------

### Extract List of Text Contents with xpath

Source: https://hexdocs.pm/sweet_xml/readme.html

Use the `xpath` function with the `~x"//path/text()"l` sigil (l for list) to extract all text contents of matching elements as a list of strings.

```elixir
result = doc |> xpath(~x"//matchup/name/text()"l)
assert result == ['Match One', 'Match Two', 'Match Three']
```

--------------------------------

### XPath Query without ~x Sigil

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

When `SweetXml` is not imported, you can still use XPath queries by explicitly passing a `%SweetXpath{}` struct to the `SweetXml.xpath/2` function. This method requires defining the path and other options within the struct.

```elixir
iex> doc = "<h1><a>Some linked title</a></h1>"
iex> doc |> SweetXml.xpath(%SweetXpath{path: '//a/text()', is_value: true, cast_to: false, is_list: false, is_keyword: false})
'Some linked title'
```

--------------------------------

### Map XML to Custom Structure with xmap

Source: https://hexdocs.pm/sweet_xml/readme.html

Use the `xmap` function to directly map XML elements to a custom map structure. This is useful for creating complex nested data representations.

```elixir
result = doc |> xmap(
  matchups: [
    ~x"//matchups/matchup"l,
    name: ~x"./name/text()",
    winner: [
      ~x".//team/id[.=ancestor::matchup/@winner-id]/..",
      name: ~x"./name/text()"
    ]
  ],
  last_matchup: [
    ~x"//matchups/matchup[last()]",
    name: ~x"./name/text()",
    winner: [
      ~x".//team/id[.=ancestor::matchup/@winner-id]/..",
      name: ~x"./name/text()"
    ]
  ]
)
assert result == %{
  matchups: [
    %{name: 'Match One', winner: %{name: 'Team One'}},
    %{name: 'Match Two', winner: %{name: 'Team Two'}},
    %{name: 'Match Three', winner: %{name: 'Team One'}}
  ],
  last_matchup: %{name: 'Match Three', winner: %{name: 'Team One'}}
}
```

--------------------------------

### XPath Querying API

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

This section details the `xpath` function for querying XML documents using XPath expressions and demonstrates various usage patterns.

```APIDOC
## XPath Querying API

### Description
`xpath` allows you to query an XML document with XPath. The second argument to xpath is a `%SweetXpath{}` struct. The optional third argument is a keyword list, such that the value of each keyword is also either a `%SweetXpath{}` or a list with head being a `%SweetXpath{}` and tail being another keyword list exactly like before.

### Method
Pipe operator (`|>`) with `xpath` function

### Endpoint
N/A (Function composition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
#### Simple XPath Query
```elixir
import SweetXml
doc = "<h1><a>Some linked title</a></h1>"
doc |> xpath(~x"//a/text()")
```

#### XPath Query with Optional Mapping
```elixir
import SweetXml
doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
doc |> xpath(~x"//header", message: ~x"./p/text()", a_in_li: ~x".//li/a/text()"l)
```

#### XPath Query with Optional Mapping and Nesting
```elixir
import SweetXml
doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
doc |> xpath(
      ~x"//header",
      ul: [
        ~x"./ul",
        a: ~x"./li/a/text()"
      ]
    )
```

### Response
#### Success Response (200)
- **any()**: The result of the XPath query, which can be a string, a map, or a list depending on the query and mapping.

#### Response Example
#### Simple XPath Query Result
```elixir
'Some linked title'
```

#### XPath Query with Optional Mapping Result
```elixir
%{a_in_li: ['Two'], message: 'Message'}
```

#### XPath Query with Optional Mapping and Nesting Result
```elixir
%{ul: %{a: 'Two'}}
```

### Security Note
When using `xpath` after parsing, it is recommended to combine it with secure parsing practices:

```elixir
doc
|> parse(dtd: :none)
|> xpath(spec, subspec)
```
```

--------------------------------

### sigil_x/2

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Creates a SweetXpath struct from an XPath string with optional modifiers.

```APIDOC
## sigil_x(path, modifiers)

### Description
Returns a %SweetXpath{} struct, with modifiers converted to boolean fields. Modifiers include 'e' (entity), 'l' (list), 'k' (keyword), 's' (string), 'i' (integer), 'f' (float), and 'o' (optional).

### Parameters
#### Request Body
- **path** (String.t) - Required - The XPath expression.
- **modifiers** (charlist) - Optional - Modifiers to control return type and behavior.
```

--------------------------------

### Chain XPath calls

Source: https://hexdocs.pm/sweet_xml/readme.html

Performs manual iteration over nodes using standard Elixir Enum functions.

```elixir
doc
|> xpath(~x"//li"l)
|> Enum.map fn (li_node) ->
  %{
    name: li_node |> xpath(~x"./name/text()"),
    age: li_node |> xpath(~x"./age/text()")
  }
end
```

--------------------------------

### Extract List of Attributes with xpath

Source: https://hexdocs.pm/sweet_xml/readme.html

Use the `xpath` function with the `~x"//path/@attribute"l` sigil to extract the values of a specific attribute from multiple elements as a list of strings.

```elixir
result = doc |> xpath(~x"//matchup/@winner-id"l)
assert result == ['1', '2', '1']
```

--------------------------------

### Stream XML Elements

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Creates a stream of XML elements from a document using a callback function for fine-grained control.

```elixir
iex> import Record
iex> doc = ["<h1", "><a>Som", "e linked title</a><a>other</a></h1>"]
iex> SweetXml.stream(doc, fn emit ->
...>   [
...>     hook_fun: fn
...>       entity, xstate when is_record(entity, :xmlElement)->
...>         emit.(entity)
...>         {entity, xstate}
...>       entity, xstate ->
...>         {entity,xstate}
...>     end
...>   ]
...> end) |> Enum.count
3
```

--------------------------------

### Extract XML Entity with xpath

Source: https://hexdocs.pm/sweet_xml/readme.html

Use the `xpath` function with the `~x"//path"e` sigil (e for entity) to extract the full XML element record, including its attributes, children, and content.

```elixir
result = doc |> xpath(~x"//matchup/name"e)
assert result == {:xmlElement, :name, :name, [], {:xmlNamespace, [], []},
        [matchup: 2, matchups: 2, game: 1], 2, [],
        [{:xmlText, [name: 2, matchup: 2, matchups: 2, game: 1], 1, [],
          'Match One', :text}], [],
        ...}
```

--------------------------------

### Extract list of results

Source: https://hexdocs.pm/sweet_xml/index.html

Use the 'l' modifier to return a list of all matches.

```elixir
result = doc |> xpath(~x"//matchup/name/text()"l) # `l` stands for (l)ist
assert result == ['Match One', 'Match Two', 'Match Three']
```

--------------------------------

### Define SweetXml Types

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Core type definitions used throughout the library for documents, XPath specifications, and XML elements.

```elixir
@type doc() :: iodata() | String.t() | Enum.t()
```

```elixir
@type spec() :: %SweetXpath{
  cast_to: term(),
  is_keyword: term(),
  is_list: term(),
  is_optional: term(),
  is_value: term(),
  namespaces: term(),
  path: term(),
  transform_fun: term()
}
```

```elixir
@type xmlElement() ::
  {:xmlElement, name :: term(), expanded_name :: term(), nsinfo :: term(),
   namespace :: term(), parents :: term(), pos :: term(), attributes :: term(),
   content :: term(), language :: term(), xmlbase :: term(),
   elementdef :: term()}
```

--------------------------------

### SweetXml.DTDError Exception

Source: https://hexdocs.pm/sweet_xml/SweetXml.DTDError.html

Details regarding the SweetXml.DTDError exception raised by the sweet_xml library.

```APIDOC
## SweetXml.DTDError

### Description
An error raised when a non-allowed DTD (Document Type Definition) is encountered during XML processing.

### Exception Details
- **Library**: sweet_xml v0.7.5
- **Purpose**: Indicates that the XML parser encountered a DTD that is not permitted by the current configuration.
```

--------------------------------

### Map to structure

Source: https://hexdocs.pm/sweet_xml/readme.html

Uses the built-in mapping capability of xpath to transform nodes into a map.

```elixir
doc
|> xpath(
  ~x"//li"l,
  name: ~x"./name/text()",
  age: ~x"./age/text()"
)
```

--------------------------------

### SweetXml.xpath/2

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Queries an XML document or element using an XPath expression and returns the result.

```APIDOC
## SweetXml.xpath/2

### Description
Returns a value based on the provided XPath expression.

### Parameters
- **parent** (String/xmlElement) - Required - The XML document or element to query.
- **spec** (SweetXpath) - Required - The XPath specification defined via the ~x sigil.

### Request Example
```elixir
import SweetXml
doc = "<h1><a>Some linked title</a></h1>"
doc |> xpath(~x"//a/text()")
```

### Response
- **result** (any) - The value extracted from the XML based on the XPath and modifiers.
```

--------------------------------

### Map XML Elements to Elixir Maps

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Maps XML elements to Elixir maps using XPath queries. Supports nested mappings and can return results as a map or a keyword list.

```Elixir
iex> import SweetXml
iex> doc = "<h1><a>Some linked title</a></h1>"
iex> doc |> xmap(a: ~x"//a/text()")
%{a: 'Some linked title'}
```

```Elixir
iex> import SweetXml
iex> doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
iex> doc |> xmap(message: ~x"//p/text()", a_in_li: ~x".//li/a/text()"l)
%{a_in_li: ['Two'], message: 'Message'}
```

```Elixir
iex> import SweetXml
iex> doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
iex> doc
...> |> xmap(
...>      message: ~x"//p/text()",
...>      ul: [
...>        ~x"//ul",
...>        a: ~x"./li/a/text()"
...>      ]
...>    )
%{message: 'Message', ul: %{a: 'Two'}}
```

```Elixir
iex> doc
...> |> xmap(
...>      message: ~x"//p/text()",
...>      ul: [
...>        ~x"//ul"k,
...>        a: ~x"./li/a/text()"
...>      ]
...>    )
%{message: 'Message', ul: [a: 'Two']}
```

```Elixir
iex> doc
...> |> xmap([
...>      message: ~x"//p/text()",
...>      ul: [
...>        ~x"//ul",
...>        a: ~x"./li/a/text()"
...>      ]
...>    ], true)
[message: 'Message', ul: %{a: 'Two'}]
```

--------------------------------

### Extract Text Content with xpath

Source: https://hexdocs.pm/sweet_xml/readme.html

Use the `xpath` function with the `~x"//path/text()"` sigil to extract the text content of an XML element. The result is a string.

```elixir
result = doc |> xpath(~x"//matchup/name/text()")
assert result == 'Match One'
```

--------------------------------

### parse/2

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Parses an XML document into an xmlElement structure ready for XPath queries.

```APIDOC
## parse(doc, opts)

### Description
Parses a document into a form ready to be used by xpath/3 and xmap/2.

### Parameters
#### Request Body
- **doc** (iodata | String.t | Enum.t) - Required - The XML document to parse.
- **opts** (list) - Optional - Options for xmerl or DTD handling (e.g., :none, :all, :internal_only).

### Response
#### Success Response (200)
- **xmlElement** (tuple) - Returns an xmlElement record.
```

--------------------------------

### XPath Query with Nested Mapping in SweetXml

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Illustrates nested mapping within an XPath query to extract data from hierarchical XML structures. This allows for more complex data extraction and structuring.

```elixir
iex> import SweetXml
iex> doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
doc
...> |> xpath(
...>      ~x"//header",
...>      ul: [
...>        ~x"./ul",
...>        a: ~x"./li/a/text()"
...>      ]
...>    )
%{ul: %{a: 'Two'}}copy
```

--------------------------------

### Securing XML parsing

Source: https://hexdocs.pm/sweet_xml/readme.html

Prevent default behavior vulnerabilities by disabling DTD processing when handling untrusted XML.

```elixir
doc |> parse(dtd: :none) |> xpath(spec, subspec)
enum |> stream_tags(tags, dtd: :none)
```

--------------------------------

### transform_by/2

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Applies a transformation function to the result of an XPath query.

```APIDOC
## transform_by(sweet_xpath, fun)

### Description
Tags a %SweetXpath{} struct with a function to be applied at the end of an xpath query.

### Parameters
#### Arguments
- **sweet_xpath** (%SweetXpath{}) - Required - The xpath specification.
- **fun** (function) - Required - The transformation function to apply.
```

--------------------------------

### Extract XML entity

Source: https://hexdocs.pm/sweet_xml/index.html

Use the 'e' modifier to return the raw XML entity record.

```elixir
result = doc |> xpath(~x"//matchup/name"e) # `e` is the modifier for (e)ntity
assert result == {:xmlElement, :name, :name, [], {:xmlNamespace, [], []},
        [matchup: 2, matchups: 2, game: 1], 2, [],
        [{:xmlText, [name: 2, matchup: 2, matchups: 2, game: 1], 1, [],
          'Match One', :text}], [],
        ...}
```

--------------------------------

### Transform XML Data with XPath and Functions

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Applies a transformation function to the result of an XPath query. Useful for converting extracted string data into other types, like ranges.

```Elixir
iex> import SweetXml
iex> string_to_range = fn str ->
...>     [first, last] = str |> String.split("-", trim: true) |> Enum.map(&String.to_integer/1)
...>     first..last
...>   end
iex> doc = "<weather><zone><name>north</name><wind-speed>5-15</wind-speed></zone></weather>"
iex> doc
...> |> xpath(
...>      ~x"//weather/zone"l,
...>      name: ~x"//name/text()"s |> transform_by(&String.capitalize/1),
...>      wind_speed: ~x"./wind-speed/text()"s |> transform_by(string_to_range)
...>    )
[%{name: "North", wind_speed: 5..15}]
```

--------------------------------

### Stream XML Tags with Discard Option

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Streams specified tags from an XML document, discarding certain elements to manage memory for large files. Each matched tag produces its own tree.

```Elixir
iex> import SweetXml
iex> doc = ["<ul><li>l1</li><li>l2", "</li><li>l3</li></ul>"]
iex> SweetXml.stream_tags(doc, :li, discard: [:li])
...> |> Stream.map(fn {:li, doc} -> doc |> SweetXml.xpath(~x"./text()") end)
...> |> Enum.to_list
['l1', 'l2', 'l3']
```

```Elixir
iex> SweetXml.stream_tags(doc, [:ul, :li])
...> |> Stream.map(fn {_, doc} -> doc |> SweetXml.xpath(~x"./text()") end)
...> |> Enum.to_list
['l1', 'l2', 'l3', nil]
```

--------------------------------

### Security: Preventing DTD Parsing and Fetching

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

This snippet shows how to prevent DTD parsing and fetching to mitigate security risks when parsing untrusted XML.

```APIDOC
## Security: Preventing DTD Parsing and Fetching

### Description
Whenever you are working with some xml that was not generated by your system, it is highly recommended that you restrain some functionalities of XML during the parsing. SweetXml allows in particular to prevent DTD parsing and fetching. Unless you know exactly what kind of DTD you want to permit in your xml, it is recommended that you use the following code example to prevent possible attacks:

### Method
Pipe operator (`|>`)

### Endpoint
N/A (Function composition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
doc
|> parse(dtd: :none)
|> xmap(specs, options)
```

### Response
#### Success Response (200)
Depends on the subsequent functions (`xmap` in this case).

#### Response Example
N/A
```

--------------------------------

### Element streaming with stream_tags/2

Source: https://hexdocs.pm/sweet_xml/readme.html

Extract specific tags from a stream and optionally discard them to prevent memory leaks.

```elixir
file_stream = File.stream!("file_above.xml")

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

assert result == ['\n        First', 'Second\n      ', 'Third', 'Forth', 'first star']
```

```elixir
result = file_stream
|> stream_tags([:li, :special_match_key], discard: [:li, :special_match_key])
```

--------------------------------

### Transforming XML values with transform_by/2

Source: https://hexdocs.pm/sweet_xml/readme.html

Use transform_by/2 to apply functions to extracted XML values during the xpath parsing process.

```elixir
doc = "<li><name><first>john</first><last>doe</last></name><age>30</age></li>"

result = doc |> xpath(
  ~x"//li"l,
  name: [
    ~x"./name",
    first: ~x"./first/text()"s |> transform_by(&String.capitalize/1),
    last: ~x"./last/text()"s |> transform_by(&String.capitalize/1)
  ],
  age: ~x"./age/text()"i
)

^result = [%{age: 30, name: %{first: "John", last: "Doe"}}]
```

```elixir
doc = "<li><name><first>john</first><last>doe</last></name><age>30</age></li>"

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

result = doc |> xpath(
  ~x"//li"l,
  name: ~x"./name" |> transform_by(parse_name),
  age: ~x"./age/text()"i
)

^result = [%{age: 30, name: %{first: "John", last: "Doe"}}]
```

--------------------------------

### stream_tags/3 and stream_tags!/3

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Streams specific XML tags from an enumerable document, with options to discard elements to save memory.

```APIDOC
## stream_tags(doc, tags, options)

### Description
Streams a given tag or list of tags from an enumerable document. Optionally discards elements to free memory during streaming.

### Parameters
#### Arguments
- **doc** (enumerable) - Required - The XML document source.
- **tags** (atom | list) - Required - The tag(s) to extract.
- **options** (keyword) - Optional - Options including :discard (list of tags to ignore).

### Response
- **Stream** - A stream of tuples in the format {:tagname, xmlelem}.
```

--------------------------------

### Nested Mapping with SweetXml XPath

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Utilize `SweetXml.xpath/3` for nested mapping, allowing extraction of multiple values from an XML document based on different XPath expressions within a single call. The `l` modifier ensures that results are returned as lists.

```elixir
iex> import SweetXml
iex> doc = "<body><header><p>Message</p><ul><li>One</li><li><a>Two</a></li></ul></header></body>"
iex> doc |> xpath(~x"//header", message: ~x"./p/text()", a_in_li: ~x".//li/a/text()"l)
%{a_in_li: ['Two'], message: 'Message'}
```

--------------------------------

### Prevent DTD Parsing in SweetXml

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Use this code to prevent DTD parsing and fetching when working with untrusted XML to avoid potential attacks. It's recommended unless you specifically need to permit certain DTDs.

```elixir
doc
|> parse(dtd: :none)
|> xmap(specs, options)copy
```

```elixir
doc
|> parse(dtd: :none)
|> xpath(spec, subspec)copy
```

--------------------------------

### Parse XML Documents

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Parses an XML document into an internal representation suitable for XPath queries.

```elixir
@spec parse(doc(), opts :: list()) :: xmlElement()
```

--------------------------------

### Extract Nested Data with Custom Map Structure

Source: https://hexdocs.pm/sweet_xml/readme.html

Use `xpath` with a custom map structure to extract nested data. Define child elements or attributes as keys in the map, using nested `xpath` queries.

```elixir
result = doc |> xpath(
  ~x"//matchups/matchup"l,
  name: ~x"./name/text()",
  winner: [
    ~x".//team/id[.=ancestor::matchup/@winner-id]/..",
    name: ~x"./name/text()"
  ]
)
assert result == [
  %{name: 'Match One', winner: %{name: 'Team One'}},
  %{name: 'Match Two', winner: %{name: 'Team Two'}},
  %{name: 'Match Three', winner: %{name: 'Team One'}}
]
```

--------------------------------

### Stream XML Tags with Nested Discard

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Streams specified tags from an XML document, demonstrating how discarding nested tags affects accessibility. Be cautious when discarding tags nested within kept tags.

```Elixir
iex> import SweetXml
iex> doc = ["<header>", "<title>XML</title", "><header><title>Nested</title></header></header>"]
iex> SweetXml.stream_tags(doc, :header)
...> |> Stream.map(fn {_, doc} -> SweetXml.xpath(doc, ~x".//title/text()") end)
...> |> Enum.to_list
['Nested', 'XML']
```

```Elixir
iex> SweetXml.stream_tags(doc, :header, discard: [:title])
...> |> Stream.map(fn {_, doc} -> SweetXml.xpath(doc, ~x"./title/text()") end)
...> |> Enum.to_list
[nil, nil]
```

--------------------------------

### SweetXml.stream_tags/3

Source: https://hexdocs.pm/sweet_xml/SweetXml.html

Streams specific tags from an XML document, useful for processing large files that do not fit in memory.

```APIDOC
## SweetXml.stream_tags/3

### Description
Streams a given tag or list of tags, optionally discarding elements to free memory.

### Parameters
- **doc** (Enumerable) - Required - The XML document source.
- **tags** (Atom/List) - Required - The tag or list of tags to stream.
- **options** (List) - Optional - Additional configuration options.

### Request Example
```elixir
import SweetXml
doc = ["<ul><li>l1</li><li>l2", "</li><li>l3</li></ul>"]
SweetXml.stream_tags(doc, :li)
```

### Response
- **stream** (Enumerable) - A stream of the matched XML elements.
```
Tokens:
Raw