You can use an error's location and code to decide whether to fix a token or the shape of an expression. Start with a quoted list, then compare errors from reading, form checking, and evaluation. The step that turns source text into tokens and values is called the reader.
Read a list as data
Paste this complete program into the Playground.
'(alpha 1 2/3 #u8(4 5))Result
(alpha 1 2/3 #u8(4 5))The leading quote keeps the list as data. It contains the symbol alpha, an integer, a rational, and a bytevector. Removing the quote makes alpha the name to look up for a procedure call.
Tell the three steps apart
A token is one piece of source text, such as alpha or 2/3. The reader recognizes these pieces and groups them into lists and other data structures.
The normalizer checks the shapes of expressions and rewrites shorthand into core forms. For example, it checks that if has a test and both branches. Evaluation then looks up names, calls procedures, and computes results.
Run each example below separately. The table shows the diagnostic code, not the full message.
| Source | Step that reports the error | What to fix |
|---|---|---|
(list 01) | reader, E100 | Write 1 without a leading zero |
(if #t 1) | normalizer, E130 | Add the other branch, as in (if #t 1 0) |
(alpha 1) | evaluation, E300 | Define alpha before calling it |
The last row assumes alpha has not been defined. The parentheses and tokens are valid in that example.
When you run a source file, Lispex reads and normalizes the whole file before evaluating it. A reading or form error therefore prevents even an earlier display from running.
Choose a notation
| You want | Write | Meaning |
|---|---|---|
| a name | alpha | a symbol used to look up a value |
| text | "alpha" | an immutable string |
| a list as data | '(alpha 1) | linked pairs ending in the empty list () |
| a pair with a different tail | '(alpha . 1) | one pair whose tail is 1 |
| values accessed by index | #(1 2) | a vector |
| bytes | #u8(1 2) | an immutable bytevector |
The reader also accepts characters, quasiquotation, and comments. Reference for Reading Code gives their spellings and the numeric rules.
Read the error location
Native diagnostics show a code, file, line, column, and message. For example, save (list 01) as the only line of bad-token.lspx. With the Native CLI installed, run:
lispex run bad-token.lspxThe command writes this diagnostic to standard error:
E100 bad-token.lspx:1:7 malformed numeric literal: `01`The exit code is 1. Standard output is empty, and the command creates no files. Column 7 points to the start of 01.
Reading errors include E100 for invalid tokens, E150 for invalid escapes, and E314 for a real literal outside the finite range. Check the message as well as the code.
Save source as UTF-8. Invalid UTF-8 is rejected before reading. Lispex preserves source spelling instead of automatically converting newlines, paths, or the calling application's encoding.