The main user interface for defining mapping definitions.

Saxaboom.Mapper exposes a micro-DSL for describing the expected structure of a given document. There are three components to the Saxaboom.Mapper interface:

• document/1: a directive describing the "envelope" of the incoming document (read: the whole document). This exposes the internal DSL.
• element/2: a directive to match zero to one element and collect into a single struct field
• elements/2: a directive to match zero to N elements and collect in a list in the order they are encountered
• attribute/2: a directive to match zero to one attribute and collect into a single struct field.

Please note that the element/2 and attribute/2 macros take a "last argument wins" approach, which is to say that if an element or attribute of the same name appears later in the document, the value extracted will overwrite any previously held value.

Examples

For example, the following mapper defines a bookstore catalog of books (see also: examples):

defmodule Book do
  use Saxaboom.Mapper

  document do
    attribute :id
    element :author
    element :title
    element :genre
    element :price, cast: :float
    element :publish_date, cast: &__MODULE__.parse_date/1
    element :description
  end

  def parse_date(value), do: Date.from_iso8601(value)
end


defmodule Catalog do
  use Saxaboom.Mapper

  document do
    elements :book, as: :books, into: %Book{}
  end
end

Which intuitively maps against the following XML body:

xml = """
  <?xml version="1.0"?>
  <catalog>
    <book id="bk101">
        <author>Gambardella, Matthew</author>
        <title>XML Developer's Guide</title>
        <genre>Computer</genre>
        <price>44.95</price>
        <publish_date>2000-10-01</publish_date>
        <description>An in-depth look at creating applications
        with XML.</description>
    </book>
  </catalog>
  """

Usage:

Saxaboom.parse(xml, %Catalog{})
#=> {:ok,
#  %Catalog{
#    books: [
#      %Book{
#        id: "bk101",
#        author: "Gambardella, Matthew",
#        title: "XML Developer's Guide",
#        genre: "Computer",
#       price: 44.95,
#        publish_date: {:ok, ~D[2000-10-01]},
#        description: "An in-depth look at creating applications\n        with XML."
#      }
#    ]
#  }}

use Saxaboom.Mapper

When you use Saxaboom.Mapper, the mapper module will import the element/2 and elements/2 macros into the current scope.

Consolidation

Saxaboom currently relies on dynamic dispatch via protocols, which are consolidated at compile time for a performance boost. If you'd like to use Saxaboom in iex and dynamically create Saxaboom.Mappers, you should read the docs on consolidation for the finer details and config options available. Turning off protocol consolidation is not generally recommended for production environments.