# Wasot and XML

## Why Wasot?

There are formats that optimized for humans, which are hard for tools to work with, like markdown.
There are also formats that are optimized for computers, which are hard for humans to write in, like HTML.
Wasot is a language, that is optimized for humans and [tools](./tools.md), making collaboration easier.
The goal of Wasot is to enable humans to work at the speed of thought (see [design principles](./principles.md)).
To enable this, we need to outsource tasks to tools.
Thus, we need to make tool development easy so that they can help us.
We need a language that enables humans to work fast and tools to help us.
Wasot is that language.

## On lines and meta-lines

A vanilla text file is not enough when collaborating with tools.
We need semantics and data, which is not part of the content.
We may want to express that something is its own block or a heading.
There is also data, which tools want to add, like adding an ID to an area, which we want to link to.

There are lines, which represent the content of the file.
An there are lines, which add additional data about the content, meta-data in form of meta-lines.

Almost all formats support a mix of data and meta-data. Markdown has markers, that identify headlines,
XML has its tags, Json has key-value pairs and so on.

## XML almost works

XML is almost the perfect fit, at least for machines. It is hierarchical, easy to parse, mature,
and has great support for metadata. But it is awful for humans to write.
While Wasot was not inspired by XML, it is a great fit. Like so often, mature technologies come to a rescue.

Let's see what we need.

- Files are a bunch of lines, which are grouped into hierarchical blocks
- Each block has a type and optional inline-text, positional arguments, keyword-arguments, and id.
- A block contains content and children, which are blocks themself.
- A file has meta-data, and elements, which are either blocks or content outside a block.

That is it! Easy to represent in XML:

```xml
<file>
  <block type="paragraph" id="123">
    <arg>arg</arg>
    <arg>Second arg</arg>
    <kwarg><key>a-key</key><value>My value</value></kwarg>
    <arg>Third arg</arg>
    <inline-text>A special text of the block</inline-text>
    <text start="1" end="4">
      This is part of the actual text of the file. 
      The rest is meta-data. It can span multiple lines.
      Look, how litte of the file is the actual text with XML.
    </text>

    <block type="quote">
      <text start="6" end="9">
        Args, Kwargs, and inline-text are optional.
        The ID too, but if you want to link to the block, you need an ID.
        IDs are added by tooling. That is the point of wasot: Let tools do things.
      </text>
    </block>

    <text start="10" end="11">
      Look, there can be contents, even after child-blocks.
    </text>

    <block type="whatever">
      <text start="13" end="14">
        Block-Types are arbitrary strings, to tools you are using define which you 
        want to use.
      </text>
    </block>
  </block>

  <text start="16" end="18">
    There can be text on the top level as well. The top level is just a special 
    type of block in this regard. 
    The text remembers where the original lines came from.
    It is a left-inclusive range as in most programming languages.
  </text>
</file>
```

See, we can represent things with just a handful of tags. But writing these documents
is awful. Wasot comes to the rescue.

```wasot
.paragraph A special text of the block .. arg "Second arg" k="A value" "Third arg arg"  :123

This is part of the actual text of the file. 
The rest is meta-data. It can span multiple lines.
Look, how litte of the file is the actual text with XML.

..quote

Args, Kwargs, and inline-text are optional.
The ID too, but if you want to link to the block, you need an ID.
IDs are added by tooling. That is the point of wasot: Let tools do things.
../

Look, there can be contents, even after child-blocks.

..whatever

Block-Types are arbitrary strings, to tools you are using define which you 
want to use.

./

There can be text on the top level as well. The top level is just a special 
type of block in this regard. 
The text remembers where the original lines came from.
It is a left-inclusive range as in most programming languages.
```

*Notes on the example*: While arbitrary deep nesting is possible it is intented to
work on the first level, only one block and depending on the block adding one
level deep of child-blocks to give the blocks structure. So no more than two levels
of nesting.
Also `./` explicitly ends a block, which you would not use in practice.
A new block on the same level or above smartly closes other blocks implicitly.
This was just for the translation example.

Wasot reduces the (special-) characters you have to write, while keeping the same
expressiveness. Special characters, like the prefix-dot, the `..` or `:` are chosen to enable
fast writing by humans.

## Data Model

![Wasot Data Model](./wasot_data_model.png)

Nothing new here, basically just a class-diagram version of the XML above. See also the [AST definition](./ast.md).
A file has a sorted list of elements, where each element is either a `Block` or a `Text`.
Blocks can have other elements as children, texts are leafs. This structure is streamed as [events](./architecture.md).

```plantuml
@startuml wasot_data_model
!theme vibrant

title Wasot Data Model

' Set overall direction for a clean flow
top to bottom direction

' ----- Main File and Metadata -----
class File {
    elements: List<Element> = []
}

class Metadata {
    id: String
    title: String
    lastChanged: String
    data: Map<String, String> = {}
}

File "1" *-- "1" Metadata

' ----- Element Hierarchy (Composite Pattern) -----
package "Elements" {
    note as CompositePatternNote
        <b>Composite Pattern</b>
        A `Block` can recursively contain
        other `Element`s (Blocks or Texts),
        forming a tree structure.
    end note

    abstract class Element
    class Block {
        type: String
        id: String?
        inlineText: QuotedString?
        --
        arguments: List<Argument> = []
        children: List<Element> = []
        --
        getKwArg(key: String): List<String>
        getArg(index: int): String
    }
    class Text {
        from: int
        to: int
        --
        lines: List<String> = []
    }

    Element <|-- Block
    Element <|-- Text
}

class QuotedString {
    content: String
    quoted: bool
}

' ----- Argument Hierarchy -----
package "Arguments" {
    abstract class Argument
    class PositionalArgument {
        index: int
        value: QuotedString
    }
    class KeywordArgument {
        key: QuotedString
        value: QuotedString
    }
    Argument <|-- PositionalArgument
    Argument <|-- KeywordArgument
}

' ----- Relationships -----
File "1" *-- "0..*" Element : elements >
Block "1" *-- "0..*" Element : children >
Block "1" *-- "0..*" Argument : arguments >

@enduml
```

## Pretty Printing

- XML needs to contain all relevant infos to reproduce the original (for pretty printing)

## Events as Format

## Database design

## Required tooling

- Syntax Highlighting
- LSP
- [CLI tools](./cli.md)
- [Exporters](./exporter.md)
- Pretty Printers
- Neovim & VSCode integration

## Moving to Hyper-Texts Web-Technology to the resque

Semantic-Web(3.0), Stable Links as IDs, Namespaces, real Hyper-Documents
All good, make them suitable for humans / writeable.
