3 XML Syntax Objects

8.17.0.3

3 XML Syntax Objects🔗ℹ

An XML syntax object encodes an XML document as a human-readable shrubbery form represented by a Rhombus syntax object. The xml.from_syntax function converts an XML syntax object to a xml.Document, and xml.to_syntax goes in the other direction. XML syntax objects can be produced from XML directly with xml.read_syntax, xml.string_to_syntax, and xml.bytes_to_syntax, and they can converted to XML directly with xml.write_syntax, xml.syntax_to_string, and xml.syntax_to_bytes.

The xml.syntax for is essentially an alias of '' (see #%quotes), but it checks that the result syntax object conforms to XML syntax object constraints.

def my_doc:
  xml.syntax:
    words:
      greeting:
        ~weight: "bold"
        "hello"
      parting:
        ~weight: "normal"
        ~size: $(to_string(2 * 12))
        "bye"

> xml.write_syntax(my_doc, ~indentation: #'peek)
<words>
<greeting weight="bold">hello</greeting>
<parting weight="normal" size="24">bye</parting>
</words>

XML application vary in whether tag and attribute names contain -, _, or both. XML syntax objects use shrubbery identifiers and keywords for tags and attributes, so writing names with - would normally require escapes. To improve usability for contexts where - names are common, conversion from XML syntax objects to a xml.Document or to XML can optionally swap - and _ characters in tags and attribute names. For example, xml.from_syntax accepts a ~swap_underscore_dash argument.

expression

xml.syntax:

id:

...

...

keyword: value_string

content

element

string

& entity_id_or_int

content ...

(content, ...)

[content, ...]

other

Returns the same syntax object as 'element', but with the constraint that the result conforms to the grammar of an XML syntax object. Although not shown above in the grammar for element, an escape using $ can appear anywhere in the block after xml.syntax, and it works the same as in 'element' (see #%quotes). Conformance is checked on the result after substituting escapes.

An element corresponds to an xml.Element. It always starts with an identifier, and it is followed by a block (possibly empty) for the element’s attributes and content. The attributes must appear first, where each attribute starts with a keyword and is followed by a block for the attribute’s value, together corresponding to xml.Attribute.

Each content can be one the following:

element: Corresponds to a nested xml.Element.
string: Corresponds to xml.Text.
&: Corresponds to xml.Entity.
content ..., (content, ...), or [content, ...]: Content can be spliced from multiple content forms with a group, within parentheses, or within square brackets. Note that this splicing accommodates @ forms, as in the example below.
other: Any value that is satisfies Content is allowed. For example, a xml.Comment value can appear here. Constructing such objects will require a $ escape with Syntax.inject.

> xml.write_syntax(
    xml.syntax:
      a: "hello <name>"
  )
<a>hello <name></a>
> xml.write_syntax(
    xml.syntax:
      a: &something
  )
<a>&something;</a>
> xml.write_syntax(
    xml.syntax:
      a: ("b", "c", [["d"], "e"])
  )
<a>bcde</a>
> xml.write_syntax(
    xml.syntax:
      a: @{say this: "hello <name>"}
  )
<a>say this: "hello <name>"</a>
> xml.write_syntax(
    xml.syntax:
      a: $(Syntax.inject(xml.Text(~text: "123", ~write_mode: #'cdata)))
  )
<a><![CDATA[123]]></a>

expression

xml.doc:

option

...

element

option

~swap_underscore_dash: swap_expr

Like xml.syntax, but converts the XML syntax object to a xml.Document using xml.from_syntax. The value of a swap_expr option is used as the ~swap_underscore_dash argument to xml.from_syntax.

function

fun xml.from_syntax(

xml_stx :: Syntax,

~swap_underscore_dash: swap :: Any.to_boolean() = #false