Known Limits
Ling is young and moves quickly. This page collects the behaviours that surprise people
most, so you can recognise them in minutes instead of hours. Everything here was checked
against the current ling binary (2030.1.53) on both engines: the default JIT
(ling run) and the interpreter (ling run --interp).
Tip: When a program misbehaves, run it once with
ling run --interp. The interpreter reports unknown functions and runtime errors that the JIT quietly turns into().
JIT and interpreter at a glance
| Situation | JIT (default) | Interpreter |
|---|---|---|
| Unknown function name | returns () silently | unknown function error |
| Runtime error (missing file, bad index, …) | returns () or an empty value, keeps going | stops with an error and a traceback |
1 / 0 | () | inf |
pi as a bare name | () (write pi()) | the value |
"" or [] in a condition | true | false |
| Index past the end of a list | empty value | index N out of bounds error |
One character of text, s[i] | empty value | the character (use substr(s, i, 1) on both) |
for c in "text" | empty values | each character |
Ordering text, "a" < "b" | false | error |
bind inside do { } | visible afterwards | discarded |
Closure stored in a variable, f(3) | () | unknown function 'f' error |
Function or closure passed to a builtin (try, list_map, …) | becomes () | works |
wait expr | () | the value |
Printing a range value 0..5 | [0, 5] | [0, 1, 2, 3, 4] |
| Constructor with the wrong number of fields | () | error |
| Missing function argument, when used | () | undefined error |
return directly inside start | ends the program quietly | unexpected top-level return error |
A program that avoids these corners behaves the same on both engines.
There is no assignment
x = x + 1 is a parse error. Rebind instead: bind x = x + 1. See
Bindings.
Loops and scope
| Construct | Does a bind inside update the outer variable? |
|---|---|
while body | yes |
if body | yes |
for body | no: each pass gets a fresh copy of the scope |
do { } block | yes on the JIT, no on the interpreter; don’t rely on either |
To accumulate a total or build a list, use a while loop with a counter.
There is no break or continue. stop and again are reserved words that do nothing:
on the JIT the loop just keeps going, and on the interpreter they are undefined
errors. Put the loop in a function and return, or use while with a flag.
Range bounds must be simple
0..n and 0..(n + 1) work. 0..n + 1 is a parse error, and 0..len(xs) silently
does the wrong thing (an empty loop on the JIT, an error on the interpreter). Wrap
anything but a plain name or number in parentheses: 0..(len(xs)).
&& and || always evaluate both sides
Neither engine short-circuits. In x != 0 && 10 / x > 1 the division still runs when
x is 0. Use nested ifs when the right side must not run.
Numbers and text
- Number literals are decimal digits with at most one fractional part. There is no
1e3,0xff,1_000,.5or3.. Worse,1e3and0xffaren’t parse errors: they read as1or0followed by an unknown name. - Text uses double quotes only and has no interpolation. Build text with
+andstr(). printandprintlnboth end the line, and both join their arguments with no separator:println("sum", 1 + 2)printssum3.!xmeansx == false, so!0and!""arefalse. Use!on booleans only.
Comparing structured values
== on lists, records, enum values and results is always false, even for identical
contents. Compare elements or fields yourself. See
Types and Values.
What the type system does and doesn’t do
Ling is dynamically typed. Type annotations such as x: number and -> T are parsed
and ignored. There is no map or dictionary, no set, no tuple and no JSON parser. Use
records or parallel lists, or store data in SQLite with the db_* builtins.
Keywords that do nothing
These words are reserved but have no effect:
stop, again, change, post, give, fit, can, sure, maybe, pure, spawn,
none
The ownership words own, lend, share, move and copy are parsed and ignored,
with no borrow or move checking. async fn runs synchronously. type declarations are
thrown away and swallow what follows them. See Keywords.
Closures and function values
A closure expression called directly, (|x| x + 1)(5), works everywhere. Beyond that:
- A closure stored in a variable can’t be called by name on the interpreter, and is unreliable on the JIT.
- The JIT can’t pass a function or closure to a builtin.
list_map,list_filterand similar builtins return(), andtry()always returnsbad("try: first argument must be a function"). They work on the interpreter. - Programs that call
http_serverun on the interpreter automatically, so closures andtrywork in request handlers.
Prefer named top-level fns and plain loops.
Modules
use "file"loads into one shared namespace. If two files define the same function, the last one loaded silently wins, even for callers in the earlier file. This also applies tostart, so a library must never bindstart.- Inside a
mod, call sibling functions with the qualified name (geo::area). A bare call fails. - Values bound inside a
modare not usable. Expose constants as functions.
Prefix your library functions with the library name, for example geom_area. See
Modules and Projects.
Tooling
lingfu newcreatessrc/start.ling, butlingfu buildlooks formain.lingunless the manifest says otherwise. Addentry = "src/start.ling"to the[spirit]section ofLing.toml.lingfu check,lingfu fmtandlingfu translatecalllingsubcommands that don’t exist. They printling’s usage text and do nothing;checkandfmtstill report success. Useling run --interpto check a program andlingfu normalize <lang>to translate one (it rewrites every.lingfile in the current folder, so use it on a copy).lingfu normalizegets a few keywords wrong. It writesformas a word the lexer doesn’t accept in Chinese, Korean and Thai (use the spelling from Keywords), leaveschoosein English, and in Japanese and Thai writesok/badwith builtin names that don’t work asmatchpatterns. Some ownership words (copy,lend,share) also come out wrong in Japanese and Thai. Run the result and fix those words by hand.lingfu buildcompiles generated Rust with Cargo, so it needs a Rust toolchain.
Testing
lingfu test runs tests on the JIT, which doesn’t stop on runtime errors, so it can
print All tests passed! for a test that failed. Make your tests print a clear PASS
or FAIL line and check it, or run them with ling run --interp. A helper file inside
tests/ is treated as a test and fails with no entry point, so keep helpers
elsewhere.
Parse traps
- A line that starts with
-or[continues the previous line. form P { x: number, y: number }is a parse error. End annotated field lists with a comma:form P { x: number, y: number, }.- An empty closure needs a space,
| | expr, because||is “or”. fn main() { ... }is not an entry point. Usebind main = do { ... }.assert,panic,exit,append_fileanddelta_timeare not builtins. For frame timing, subtract successivetime_now()values.