Sassone.Builder protocol (Sassone v1.0.0)

Protocol to implement XML building and parsing for structs.

You can derive or implement this protocol for your structs. When deriving the protocol, these are the supported options:

:attribute_case - Rename the struct fields of type :attribute with the given strategy in XML. The default value is :snake.
:debug (boolean/0) - Enable debug for parser generation. The default value is false.
:element_case - Rename the struct fields of type :element with the given strategy in XML. The default value is :pascal.
:fields (keyword/0) - Required. Struct fields to map to XML. The order of elements will be preserved in the generated XML.
- :parse (boolean/0) - If false, the struct field won't be parsed from XML. The default value is true.
- :build (boolean/0) - If false, the field will be ignored when building the struct to XML. The default value is true.
- :many (boolean/0) - Specifies if the field must be handled as a list. The default value is false.
- :name (String.t/0) - Custom field name for parsing and building. It will be used as-is.
- :namespace - Namespace to apply to the field. It will be used as-is. The default value is nil.
- :struct (atom/0) - A struct deriving Sassone.Builder used to parse and build this element.
- :type - How the field is represented in XML: :element, :attribute, :content. The default value is :element.
:namespace - XML namespace of the element. The default value is nil.
:root_element (String.t/0) - XML root element. This applies only to the toplevel struct when parsing.

The builder allows nesting of other structs implementing Sassone.Builder via the struct field option.

The generated parser returns a map with atom keys you can pass to struct/2 or struct!/2 to obtain a struct.

Data validation

Transforming a map with nested structs and/or values into data types other than strings, such as dates, datetimes, etc. might prove complex and error prone and is out of scope for Sassone.

In this case, using a library to define your struct, validate and transform your data, both before building and after parsing, is probably a good idea.

Ecto with embedded schemas is a great way to do this, and naturally fits the Sassone.Builder model.

XML elements order

In XML documents, the order in which elements appear is meaningful.

The builder protocol preserves field ordering, so if you need fields to be mapped to elments appearing in a a specific order in XML when building with Sassone.XML.build/1, be sure to list them in that spefic order in the fields option.

Also note that ordering is not enforced by the parser, so parsing is not strict in that sense and the generated parser will parse elements refardless of the order in which they appear in the XML document.

Summary

Types

t()

A strut implementing Sassone.Builder

Functions

attributes(struct)

Returns the mapping of attributes for the struct.

elements(t)

Returns the mapping of elements for the struct.

handler(t)

Returns the Sassone.Handler implementation for the struct.

namespace(t)

Returns the XML namespace for the struct.

root_element(t)

Returns the XML root element name for the struct.