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
|
The items in the args should be either strings or tuples. The tuples are turned into
|
||||||
flags using the builtin flag converter.
|
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>
|
Next: <a href="/how-to">HowTo Guides</a>
|
Loading…
x
Reference in New Issue
Block a user