Module xmlrat_parse_transform

Description
Data Types
Function Index
Function Details

A parse transform which provides attributes for compiling custom XML processing functions.

Description

A parse transform which provides attributes for compiling custom XML processing functions.

This parse transform defines several new attributes:

-xpath(...). compiles an XPath expression to a matching function of a given name (like xmlrat_xpath:compile/1).
-xpath_record(...). generates a function which runs multiple XPath expressions against a document and places their results into fields of a record. Supports type coercion based on the declared types of the record fields.
-xml_record(...). generates a function which takes a record as input and produces an XML document, based on the xmlrat_mini_xslt syntax.

You can enable these in your module by including a -compile() attribute directly after your -module() declaration. You will also need to include the records.hrl header:


-module(my_module).
-compile({parse_transform, xmlrat_parse_transform}).
-include_lib("xmlrat/include/records.hrl").

Attributes

-xpath()

Compiles an XPath expression to an Erlang function (like xmlrat_xpath:compile/1).


-xpath({FunctionName :: atom(),
        XPath :: string() | binary()}).
-xpath({FunctionName :: atom(),
        XPath :: string() | binary(),
        Namespaces :: #{binary() | default => uri()}}).
-spec FunctionName(document()) -> xpath_result().
-spec FunctionName(document(), varbinds()) -> xpath_result().

The -xpath(...) attribute generates both an arity-1 and arity-2 variant of the function with the provided name.

-xpath_record()

Generates a function which deserialises XML into an Erlang record using XPath expressions and the type signature of the record itself.

Each field of the record is mapped to an XPath expression in the argument XPathExprs to the attribute. The output of each expression is coerced into the type declared in the relevant -record() attribute.


-record(recname, {
    optional_field :: undefined | binary(),
    required_field :: integer(),
    list_field :: [binary()],
    nested_field :: #recname2{}
  }).
-xpath_record({FunctionName :: atom(),
               RecordName :: atom(),
               XPathExprs :: #{atom() => string() | binary()}}).
-xpath_record({FunctionName :: atom(),
               RecordName :: atom(),
               XPathExprs :: #{field() => string() | binary()},
               Namespaces :: #{binary() | default => uri()}}).
-spec FunctionName(document()) -> #RecordName{}.

The target record must be defined before the -xpath_record() attribute. Type aliases are supported in record fields, as long as the alias is local and defined in the current file.

If any nested fields are present (with a declared type of another record), their XPath expression must evaluate to a node set, and another -xpath_record() attribute with RecordName set to that record must appear in the same file before this attribute.

-xml_record()

Generates a function which serialises an Erlang record into an XML document (or part of one), using an XSLT-like template. Documentation for the template format is available in xmlrat_mini_xslt.

The template is provided as a string or binary to the attribute, which will parse it at compile-time. The generated code consists of the relevant #xml_element{} etc records from xmlrat/include/records.hrl. Substitutions are compiled completely to expressions within the record hierarchy.

Like -xpath_record(), the -xml_record() attribute uses the declared types of record fields to generate correct type coercion for each piece of data injected into the template.


-record(recname, {
    optional_field :: undefined | binary(),
    required_field :: integer(),
    list_field :: [binary()],
    nested_field :: #recname2{}
  }).
-xml_record({FunctionName :: atom(),
             RecordName :: atom(),
             Template :: binary() | string()}}).
-xml_record({FunctionName :: atom(),
             RecordName :: atom(),
             Template :: binary() | string(),
             Namespaces :: #{binary() | default => uri()}}).
-spec FunctionName(#RecordName{}) -> document().

parse_transform/2
parse_transform_info/0