# Wasot Syntax Reference

Wasot is an event-driven markup language that bridges human readability and machine processability. It uses a **composite pattern** where documents are composed of nested **blocks** (elements) that can contain other blocks and text content.

## Quick Reference

| Syntax | Meaning |
|--------|---------|
| `.type` | Level 1 block |
| `..type` | Level 2 block |
| `.type text` | Block with inline text |
| `.type .. args` | Block with arguments |
| `.type :id` | Block with ID |
| `.#` | Self-closing heading |
| `.type:` | Void element (self-closing, no content) |
| `./` | Explicit close (close current block) |
| `./type` | Context line (metadata) |
| `((url))` | URL link |
| `((text\|url))` | Named link |
| `((:id))` | ID reference link |
| `((#))` | Footnote link |
| `[1]` | Footnote reference in text |
| `*1 text` | Footnote definition |
| `"quoted"` | Quoted string (preserves spaces) |
| `key=value` | Keyword argument |


## Blocks: The Fundamental Unit

A Wasot document is composed of **blocks**. Each block:
- Starts with a **meta-line** (a line beginning with one or more dots)
- Can contain **text content** (subsequent lines until the next meta-line)
- Can contain **child blocks** (nested blocks with more dots)

```wasot
.paragraph
This is the text content of the paragraph block.
```

The composite pattern means blocks can contain both text and other blocks:

```wasot
.article
Introduction text.
..section
Section content here.
```

---

## Meta-line Structure

A meta-line defines a block and follows this structure:

```
.<type> [inline-text] [.. arguments] [:id]
```

| Component | Required | Description |
|-----------|----------|-------------|
| Dots | Yes | One or more dots indicating nesting level |
| Type | No | Block type identifier |
| Inline text | No | Text on the same line as the type |
| `..` separator | No | Separates inline text from arguments |
| Arguments | No | Positional args and key=value pairs |
| `:id` | No | Block identifier (must be at end) |

Examples:

```wasot
.div
.div Hello World
.div .. class="container"
.div Hello World .. class="container"
.div :my-id
.div Hello World .. class="main" :my-id
```

---

## Block Types

### Simple Types

Block types are identifiers that follow the leading dot(s):

```wasot
.paragraph
..my-custom-type
........type123
."code block"
```

Even empty is possible

```wasot
.
```

## Inline Text

Inline text appears after the block type on the same line:

```wasot
.block Spaces are ok, just write
.block "You can write whatever you want, but if you need .. you need to quote"
.div "text with preserved   spaces"
.heading "Title with \"quotes\" inside"
```



## Arguments and Parameters

Arguments appear after the `..` separator.

### Positional Arguments

Unquoted words become positional arguments:

```wasot
.button .. primary large rounded
```

Quote arguments containing spaces:

```wasot
.button .. "primary button" large
```

### Keyword Arguments

Use `key=value` syntax:

```wasot
.div .. class="container" id="main"
.input .. type="text" required=true maxlength=50
```

### Mixed Arguments

Positional and keyword arguments can be mixed:

```wasot
.button .. primary large class="btn" onclick="submit()"
```

### Quoted Keys and Values

Both keys and values can be quoted:

```wasot
.widget .. "my key"="my value" style="color: red;"
```

---

## Block IDs

IDs use colon syntax and must appear at the end of the meta-line:

```wasot
.section :introduction
.div :my-element
.div Hello World :my-id
.div .. class="main" :my-id
.div Hello World .. class="main" :my-id
```

### ID Characters

IDs can contain letters, numbers, dashes, underscores, colons, and Unicode:

```wasot
.div :item-123
.div :user_profile
.div :namespace:sub:item
.div :cafe-resume
```

---

## Text Content

Lines following a meta-line (that don't start with a dot at column 0) are text content:

```wasot
.paragraph
This is the first line of text.
This is the second line.
This is the third line.
```

### Text That Looks Like Meta-lines

Lines with leading spaces before a dot are treated as text, not meta-lines:

```wasot
.paragraph
  .this is text because it has leading spaces
Regular text continues.
```

---

## Nesting and Hierarchy

The number of dots indicates the nesting level:

| Dots | Level |
|------|-------|
| `.`  | 1     |
| `..` | 2     |
| `...` | 3    |
| `....` | 4   |

### Parent-Child Relationships

More dots = deeper nesting:

```wasot
.container
..section
...paragraph
....span
```

### Sibling Blocks

Blocks at the same level are siblings:

```wasot
.parent
..child1
Child 1 content.
..child2
Child 2 content.
..child3
Child 3 content.
```

### Implicit Block Closing

Blocks close automatically when a same-level or lower-level block starts:

```wasot
.first
First content.
.second
Second content.
```

```wasot
.outer
..inner
Inner content.
.new-outer
New outer content.
```

### Level Skipping

You can skip levels:

```wasot
.level1
...level3
Level 3 content.
```

### Mixed Text and Children

Blocks can have both text content and child blocks:

```wasot
.article
Article introduction text.
..section
Section content.
More article text after section.
```

---

## Void Elements

Void elements are self-closing elements that cannot have any content - no children, no nested blocks, no text content. They are standalone markers in your document, inspired by HTML void elements like `<br>`, `<hr>`, and `<img>`.

### Syntax

A void element is marked with a **trailing colon (`:`)** immediately after the type name:

```wasot
.hr:
.img: alt text here
.img: alt text .. src="photo.jpg"
.img: alt text .. src="x.jpg" :img1
..hr:
...deep-void: with text
."page break":
.#: Introduction
```

Except of the `:` they are the same syntax as a metaline

### Comparison with Regular Blocks

| Component | Regular Block | Void Element |
|-----------|--------------|--------------|
| Type | `.paragraph` | `.paragraph:` |
| With inline text | `.note A note` | `.note: A note` |
| With arguments | `.img .. src="x.jpg"` | `.img: .. src="x.jpg"` |
| With ID | `.section :sec1` | `.section: :sec1` |
| Nested (level 2) | `..quote` | `..hr:` |
| Heading | `.# Title` (self-closing) | `.#: Title` (void) |

### Behavior

Void elements differ from regular blocks:

1. **No content**: Cannot contain text or nested blocks
2. **No closing**: Don't need (or accept) a `./` close marker
3. **No stack impact**: Don't affect block nesting - subsequent content continues as if the void element wasn't there
4. **Self-contained**: All information is on the single line

```wasot
.document
This is inside the document.
..hr:
Still inside the document.
./
```


## Explicit Close

Use `./` (dot-slash alone) to explicitly close the current block:

```wasot
.intro
Welcome text.
./
.content
Main content.
```

It is a special form of a context line

---

## Context Lines

Context lines provide metadata without being part of the content hierarchy. They use `./type` syntax where the first word after `./` is the type.

### Syntax

```wasot
./metadata
./author John Doe
./version 1.0
./meta :my-metadata
```

### Nested Context Lines

Use more dots for nested context lines:

```wasot
.outer
..inner
../version 1.0
Content here
```

### Difference from Meta-lines

| Line Type | Syntax | Purpose |
|-----------|--------|---------|
| Meta-line | `.type` | Defines content blocks |
| Context line | `./type` | Provides metadata |
| Explicit close | `./` | Closes current block |
| Text line | `text` | Content within blocks |

Context lines:
- Are **not part of the content hierarchy** - they don't create blocks
- Cannot have text content or children
- Don't affect block nesting

### Example

```wasot
.document
./author Alice
./date 2024-01-15
./version 1.0
Document content here.
```

---

## Links

Links use double parentheses `(( ))` syntax within text content.


```wasot
.paragraph
Check out ((Example Site :https://example.com)) here.
```

### ID Reference Links

Reference other blocks by their ID using `:` prefix:

```wasot
.paragraph
See the ((other block :123)) section below.
```

### Links with Arguments

Links can include arguments after `..`:

```wasot
.paragraph
Click ((submit .. class="btn" type="primary" :target)) to continue.
```


