mirror of
https://github.com/zaphar/ucg.git
synced 2025-07-22 18:19:54 -04:00
DOCS: Add xml converter documentation to the docsite.
This commit is contained in:
parent
0a09f26aad
commit
825955d855
@ -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>
|
Loading…
x
Reference in New Issue
Block a user