DOCS: Add xml converter documentation to the docsite.

This commit is contained in:
Jeremy Wall 2018-12-12 20:26:42 -06:00
parent 0a09f26aad
commit 825955d855

View File

@ -144,4 +144,113 @@ exec my-app --log-level debug --maxMem 2048M serve --port 8080
The items in the args should be either strings or tuples. The tuples are turned into
flags using the builtin flag converter.
XML
---
XML can be output using a custom xml DSL.
XML documents start with a tuple defining the document declaration and a root element.
```
{
version = "1.1" // Optional, Defaults to 1.1
encoding = "utf-8" // Optional, Defaults to UTF-8
standalone = true // Optional Defaults to false
root = { // Required defines the root element of the document.
name = "top",
}
};
```
Nodes in the document can be defined as either xml elements or text nodes. An
xml element is defined as a tuple with a required `name` field and the three
optional fields `attrs`, `ns`, and `children`.
The `name` field is required and may optionally contain a namespace prefix like so:
`prefix:element-name`.
`attrs` if set is required to be a
tuple or NULL. If NULL then no attributes are emitted If a tuple then each
field is turned into an attribute on the element. The tuple should have only
string values or null for each field. If NULL then the attribute is not set.
`ns` if set is required to be either a string in which case the default xml namespace
is set or a tuple with `prefix` and `uri` fields. which will define the prefix and uri for a namespace on that element.
`children` is required to be a list of elements and text nodes or NULL. If NULL then no children are output.
```
{
name = "ns:element-name",
ns = {
prefix = "myns",
uri = "http://example.org",
},
attrs = {
id = "foo",
},
children = [
// child elements go here.
],
};
```
Text nodes can be output via two ways. Either just a string or as a tuple with a
single field named text.
```
{
text = "This is a valid text node",
};
"This is also a valid text node";
```
### Example document
```
let doc = {
root = {
ns = {
prefix = "myns",
uri = "http://example.com",
},
name = "top",
attrs = {id = "foo"},
children = [
{
name = "child1",
ns = "http://example.org",
attrs = { attr1 = "value1", attr2 = "value2"},
children = [
"inner text node",
{
name = "myns:grandchild",
children = [
{
text = "Another text node",
},
],
},
],
},
],
},
};
out xml doc;
```
This will result in the following xml document.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<top xmlns:myns="http://example.com" id="foo">
<child1 xmlns="http://example.org/" attr1="value1" attr2="value2">inner text node<myns:grandchild>Another text node</myns:grandchild>
</child1>
</top>
```
### Caveats
We don't support character CDATA sections in our xml document DSL at this time.
Next: <a href="/how-to">HowTo Guides</a>