unspeaker/tengri
1
0
Fork 0
mirror of https://codeberg.org/unspeaker/tengri.git synced 2025-12-06 03:36:42 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

dsl: update docs

Browse source
This commit is contained in:
🪞👃🪞 2025-08-23 12:58:19 +03:00
parent 3e2b07158c
commit 0621793930
4 changed files with 39 additions and 94 deletions
Download patch file Download diff file Expand all files Collapse all files

97
dsl/README.md
View file

@ -1,14 +1,25 @@
# `ket`
[***dizzle***](https://codeberg.org/unspeaker/tengri/src/branch/main/dsl)
is a means of adding a tiny interpreted domain-specific language to your programs.
**ket** is the configuration language of **tek**.
it's based on [edn](https://en.wikipedia.org/wiki/Clojure#Extensible_Data_Notation)
but without all the features.
dizzle currently provides an s-expression based syntax.
## usage
dizzle parses source code by means of the `Dsl`, `DslExpr` and `DslWord` traits.
those are implemented for basic stringy types and their `Option` and `Result` wrapped analogs.
to customize parsing, define and use your own traits on top of the provided ones.
### with `tengri_output`
dizzle evaluates the parsed source code by means of the `DslNs` trait. the methods of
this trait match literals, words, and expressions, against pre-defined lists. the
`dsl_words` and `dsl_exprs` macros let you define those lists slightly less verbosely.
this is a `tengri_output` view layout defined using ket:
## goals
* [x] const parse
* [ ] live reload
* [ ] serialize modified code back to original indentation
## examples
### in [`tengri_output`](../output)
```edn
(bsp/s (fixed/y 2 :toolbar)
@ -16,9 +27,7 @@ this is a `tengri_output` view layout defined using ket:
(bsp/s :outputs (bsp/s :inputs (bsp/s :tracks :scenes)))))))
```
### with `tengri_input`
this is a `tengri_input` keymap defined using ket:
### in [`tengri_input`](../input)
```edn
(@u undo 1)
@ -29,70 +38,6 @@ this is a `tengri_input` keymap defined using ket:
(@tab pool toggle)
```
## tokens
ket has 4 "types", represented by variants of the `Value` enum:
* `Num` - numeric literal
* `Sym` - textual symbol
* `Key` - textual key
* `Exp` - parenthesized group of tokens
### numeric literal
numbers are passed through as is. only non-negative integers are supported.
```edn
0
123456
```
### keys
keys are the names of available operations. they look like this:
```edn
simple-key
multi-part/key
```
keys are implemented by the underlying subsystem:
* in `tengri_output`, keys are names of layout primitives
* in `tengri_input`, keys are names of commands
### symbols
symbols that start with `:` represent the names of variables
provided by the `Context` trait - such as command parameters,
or entire layout components:
```edn
:symbol-name
```
symbols that start with `@` represent keybindings.
they are parsed in `tengri_tui` and look like this:
```edn
@ctrl-alt-shift-space
```
### parenthesized groups
parenthesized groups represent things like expressions
or configuration statements, and look like this:
```edn
(some-key :symbol (some/other-key @another-symbol 123) 456)
```
## goals
* [ ] const parse
* [ ] live reload
* [ ] serialize modified code back to original indentation
## implementation notes
### `DslExpr` trait behavior
@ -114,9 +59,7 @@ this is the trait which differentiates "a thing" from
* e2: Unexpected 'b'
* e3: Unexpected 'd'
## todo
### operators
### possible design for operator-based syntax
* replace: `(:= :name :value1 :valueN)`
* append: `(:+ :name :value2 :valueN)`