tulisp 0.29.0

An embeddable lisp interpreter.
Documentation 
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

/*!
Built-in functions and macros registered on every [`TulispContext`].

Names match the [Emacs Lisp manual] where applicable; semantic
differences from Emacs are called out inline.

[`TulispContext`]: crate::TulispContext
[Emacs Lisp manual]: https://www.gnu.org/software/emacs/manual/html_node/elisp/

# Numbers

- **Arithmetic**: `+`, `-`, `*`, `/`, `mod`, `1+`, `1-`.
- **Comparison**: `=`, `<`, `>`, `<=`, `>=`, `eql`, `max`, `min`, `abs`.
- **Math**: `expt`, `sqrt`, `isnan`.
- **Numerical conversion**: `floor`, `ceiling`, `truncate`, `round`,
  `ffloor`, `fceiling`, `ftruncate`, `fround`. The integer-returning
  forms take an optional divisor; `round` uses banker's rounding.

# Strings

- **Construction**: `concat`, `format`, `make-string` (takes `(N CHAR)`
  where `CHAR` is an integer).
- **Comparison**: `string<` / `string-lessp`, `string>` / `string-greaterp`,
  `string=` / `string-equal`.
- **Output**: `princ`, `print` (behaves like `princ`, not Emacs's `print`),
  `prin1-to-string`.
- **Mutation**: `aset` (replaces a single char at an index).

# Lists

- **Construction**: `cons`, `list`, `append`.
- **Access**: `car`, `cdr`, every `c[ad]+r` form up to four `a`/`d`s,
  `nth`, `nthcdr`, `last` (errors on circular lists).
- **Modification**: `setcar`, `setcdr`.
- **Length / membership**: `length` (also for strings; cycle-safe),
  `memq`, `memql`, `member`.
- **Sequence operations**: `reverse`, `sort`, `mapcar`, `mapconcat`,
  `string-join`, `seq-map`, `seq-filter`, `seq-reduce`, `seq-find`,
  `seq-take`, `seq-drop`.
- **Alists**: `assoc`, `alist-get`.
- **Plists**: `plist-get`.

Tulisp has no vector type — sequence functions are list-only.

# Symbols and variables

- **Bindings**: `let`, `let*`, `setq`, `set`, `symbol-value`.
- **Symbols**: `intern` (always uses the default obarray), `make-symbol`,
  `gensym`.
- **Declaration**: `defvar` (sets only when unbound — preserves value
  across reloads).
- **Constants**: `nil`, `t`.

# Functions and macros

- **Definitions**: `defun`, `defmacro`, `lambda`, `declare`.
- **Invocation**: `eval`, `funcall`, `apply`, `macroexpand`.
- **Quoting**: `quote` (also written `'expr`), backquote / unquote /
  splice (`` ` ``, `,`, `,@`).
- **Threading**: `->` / `thread-first`, `->>` / `thread-last`.

Tail-call optimisation is applied to recursive functions automatically.

# Control flow

- **Branches and loops**: `if`, `cond`, `when`, `unless`, `progn`,
  `while`, `dolist`, `dotimes`.
- **Logic**: `and`, `or`, `not`, `xor`.
- **Pattern-matching binds**: `if-let`, `if-let*`, `when-let`,
  `while-let`.

# Predicates

- **Types**: `consp`, `listp`, `floatp`, `integerp`, `numberp`,
  `stringp`, `symbolp`, `keywordp`, `boundp`, `null`.
- **Equality**: `eq`, `equal`, `eql`.

# Hash tables

`make-hash-table` (no arguments; uses `eql` as the test function),
`puthash`, `gethash` (optional 3rd `default` argument).

# Time

`current-time` returns a `(ticks . hz)` pair (typically `hz =
1_000_000_000` for nanosecond resolution).

`time-add`, `time-subtract`, `time-less-p`, `time-equal-p` each take
two times — either integer Unix-epoch seconds or `(ticks . hz)`
pairs. `format-seconds` formats a duration.

# Errors

`error`, `throw`, `catch`, `condition-case`.
*/

pub(crate) mod functions;
pub(crate) mod macros;

use crate::{Error, TulispObject};

/// Validate that `target` is a writable variable cell. Used by both
/// the VM compiler (~setq~) and the TW ~setq~ defspecial so the two
/// dispatch paths reject the same inputs with the same error shape,
/// at compile time, before any value expression evaluates.
pub(crate) fn check_settable_target(target: &TulispObject) -> Result<(), Error> {
    if !target.symbolp() {
        return Err(
            Error::type_mismatch(format!("Expected Symbol: Can't assign to {}", target))
                .with_trace(target.clone()),
        );
    }
    if target.keywordp() {
        return Err(
            Error::type_mismatch(format!("Can't set constant symbol: {}", target))
                .with_trace(target.clone()),
        );
    }
    Ok(())
}