# 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