seam

Symbolic-Expressions As Markup.
git clone git://git.knutsen.co/seam
Log | Files | Refs | README | LICENSE

USAGE.md (2976B)

Usage

Syntax

Overview

The syntax consists of symbolic expressions, which may be any of: - Symbols (e.g. p, h1 or hello). - Numbers (e.g. 26, 2em or -4px). - Strings (e.g. "hello world" or """Probably a long string"""). - Attributes (e.g :key value, :count 6 or :href "https://crates.io/"). - Lists (e.g. (h1 Big Title!) or (p Hello (span :class highlight World))).

The most important part of this syntax is lists, every level of nesting or every tag is started with a ( and ended with a )

Example

For example,

(h1 :id heading Pound Cake)
(ul (li 1 pound of sugar)
    (li 1 pound of butter)
    (li 1 pound of (i self-raising) flor)
    (li 3 eggs, beaten)
    (li 1 teaspoon (a :href "https://wikipedia.org/wiki/Vanilla_extract" vanilla))
    (li 1 teaspoon baking powder))

would translate to HTML as

<h1 id="heading">Pound Cake</h1>
<ul>
    <li>1 pound of sugar</li>
    <li>1 pound of butter</li>
    <li>1 pound of <i>self-raising</i> flour</li>
    <li>3 eggs, beaten</li>
    <li>1 teaspoon <a href="https://wikipedia.org/wiki/Vanilla_extractr">vanilla</a></li>
    <li>1 teaspoin baking powder</li>
</ul>

Macros

In addition to the basic syntax, symbols prepended with a ‘%’ character, will be treated as macros.

Built-in Macros

Example

File head.sex:

(meta :name viewport :content "width=device-width, initial-scale=1.0")
(%ifdef title
    (title %title" -- My Website")
    (title "My Website"))
(style (%include "styles/main.sex"))

File styles/main.sex:

(body :font-size 16px
      :margin (0 auto)
      :background #fff)
(.important
  :color red)

File index.sex:

(!doctype html)
(html :lang en
  (head (%define title "Index page")
        (%include "head.sex"))
  (body
    (div :id container
      (%include "components/navbar.sex")
      (h1 Hello, World!)
      (p :class important Enjoy your stay!))))

File components/navbar.sex:

(nav
  (ul (li (a :href "/" Home))
      (li (a :href "/about" About Me))
      (li (a :href "/donate" Donate!))))

This way you can easily construct websites with reusable components, cut down on copy-pasting, and generate it statically. Ideal for a blog, especially using the (%markdown ...) macro.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
# Usage

## Syntax

### Overview

The syntax consists of *symbolic expressions*, which may be any of:
- Symbols (e.g. `p`, `h1` or `hello`).
- Numbers (e.g. `26`, `2em` or `-4px`).
- Strings (e.g. `"hello world"` or `"""Probably a long string"""`).
- Attributes (e.g `:key value`, `:count 6` or `:href "https://crates.io/"`).
- Lists (e.g. `(h1 Big Title!)` or `(p Hello (span :class highlight World))`).

The most important part of this syntax is *lists*, every level of nesting or
every tag is started with a `(` and ended with a `)`

### Example

For example,
```lisp
(h1 :id heading Pound Cake)
(ul (li 1 pound of sugar)
	(li 1 pound of butter)
	(li 1 pound of (i self-raising) flor)
	(li 3 eggs, beaten)
	(li 1 teaspoon (a :href "https://wikipedia.org/wiki/Vanilla_extract" vanilla))
	(li 1 teaspoon baking powder))
```
would translate to HTML as
```html
<h1 id="heading">Pound Cake</h1>
<ul>
	<li>1 pound of sugar</li>
	<li>1 pound of butter</li>
	<li>1 pound of <i>self-raising</i> flour</li>
	<li>3 eggs, beaten</li>
	<li>1 teaspoon <a href="https://wikipedia.org/wiki/Vanilla_extractr">vanilla</a></li>
	<li>1 teaspoin baking powder</li>
</ul>
```

## Macros

In addition to the basic syntax, *symbols* prepended with a ‘`%`’ character,
will be treated as macros.

### Built-in Macros
- `%define` allows for user defined macros, e.g. `(%define name "Samuel")`,
  ‘function’-like macros may also be defined to allow arguments, say
  `(%define (greet name) (p Hello there, %name))`.
- `%ifdef` checks if a symbol is defined, e.g. `(ifdef username (span Hello %username))`,
  or with an else-clause: `(ifdef title (title My Blog - %title) (title My Blog))`.
- `%include` will include an entire file's contents into another, e.g.
  `(%include "components/footer.sex")`.
- `%date` standard `strftime` function, works of current system time, e.g.
  `(span :id timestamp Uploaded on (%date "%Y-%m-%d"))`.
- `%log` will simply log any information to STDERR, e.g. `(%log Hello, World!)`.

### Example

*File `head.sex`:*
```lisp
(meta :name viewport :content "width=device-width, initial-scale=1.0")
(%ifdef title
	(title %title" -- My Website")
	(title "My Website"))
(style (%include "styles/main.sex"))
```

*File `styles/main.sex`:*
```lisp
(body :font-size 16px
      :margin (0 auto)
      :background #fff)
(.important
  :color red)
```

*File `index.sex`:*
```lisp
(!doctype html)
(html :lang en
  (head (%define title "Index page")
        (%include "head.sex"))
  (body
    (div :id container
      (%include "components/navbar.sex")
      (h1 Hello, World!)
      (p :class important Enjoy your stay!))))
```

*File `components/navbar.sex`:*
```lisp
(nav
  (ul (li (a :href "/" Home))
      (li (a :href "/about" About Me))
      (li (a :href "/donate" Donate!))))
```

This way you can easily construct websites with reusable components,
cut down on copy-pasting, and generate it statically. Ideal for a blog,
especially using the `(%markdown ...)` macro.