113 lines
2.8 KiB
Markdown
113 lines
2.8 KiB
Markdown
# OATS
|
|
|
|
**O**utput **A**gnostic **T**agging **S**ystem aka. OATS reference
|
|
implementation in Lua.
|
|
|
|
This repository serves both as a description of the OATS language and the Lua
|
|
implementation.
|
|
|
|
## Format
|
|
|
|
### Overview
|
|
|
|
- Tree structure like XML
|
|
- No attributes, only children
|
|
- No namespaces
|
|
- Nesting by Indentation
|
|
|
|
Nodes are enclosed with square brackets
|
|
|
|
```
|
|
[document]
|
|
```
|
|
|
|
Nested elements are indented
|
|
|
|
```
|
|
[document]
|
|
[nested-tag]
|
|
nested text
|
|
```
|
|
|
|
Tags with only one text node can be shortened to one-line tags:
|
|
|
|
```
|
|
[tag-name] single text node
|
|
|
|
evaluates to the same as
|
|
|
|
[tag-name]
|
|
single text node
|
|
```
|
|
|
|
Text nodes mixed with one-line tags can further be shortened with inline tags:
|
|
|
|
```
|
|
Plain text with some
|
|
[bold] tagged
|
|
text
|
|
[emphasis] in between
|
|
|
|
evaluates to the same as
|
|
|
|
Plain text with some [bold tagged] text [emphasis in between]
|
|
```
|
|
|
|
(NOT YET IMPLEMENTED)
|
|
|
|
Any special or non-special character inside a line can be escaped with a single
|
|
backslash, including the backslash itself. A backslash at the end of a line will
|
|
be ignored. This works both in text nodes and inside tag names.
|
|
|
|
A backslash character followed by a space will be replaced by an ASCII newline
|
|
character.
|
|
|
|
### Out of scope
|
|
|
|
Several features are intentionally left to the consuming application, with OATS
|
|
only providing suggestions to avoid bikeshedding.
|
|
|
|
#### String joining
|
|
|
|
Consumers may have a better understanding of whether and how to join text
|
|
elements together, while the interpreter would have to decide on a joining
|
|
strategy (most likely concatenation with a space character in between).
|
|
|
|
#### Comments
|
|
|
|
Comments could be implemented either as a node type or a string prefix or both.
|
|
|
|
The preferred node names for comments are `comment`, while the preferred text
|
|
node prefix is a double dash `--`.
|
|
|
|
#### Namespacing
|
|
|
|
The recommended namespace separator in namespaces is the single colon `:` with
|
|
nesting going from left (outermost namespace) to right (node name).
|
|
|
|
Specific namespacing semantics have proven to be a cause of both bikeshedding
|
|
and reasonable disagreements in other languages like XML.
|
|
|
|
#### Encoding
|
|
|
|
OATS is designed and described in terms of ASCII characters, but in a technical
|
|
sense, only reserves a small number of 8-bit characters for control purposes.
|
|
|
|
### Data Type
|
|
|
|
OATS makes no attempts to interpret text.
|
|
Everything is considered a string and it is left up to the consuming application
|
|
to decide how to interpret the textual representation.
|
|
|
|
### Conventions
|
|
|
|
OATS is a very simple format without many restrictions.
|
|
Nevertheless, the following suggestions are provided to ensure some reasonable
|
|
degree of uniformity between applications:
|
|
|
|
OATS tag names preserve case, but applications consuming OATS structures should
|
|
generally ignore case.
|
|
|
|
Tag names should use lowercase kebab-case.
|
|
|
|
## Interface
|