Starlark (experimental)
Experimental. rontolisp reads
Starlark, the Python dialect
Bazel's build files are written in, and lowers it to the same core forms as Common Lisp, so
a .star program runs on every backend. Conformance is partial by design and nothing here
is a compatibility promise. Use it to try a Starlark program on the JVM or WebAssembly;
write Common Lisp for anything you need to keep working.
A .star file is read as Starlark; --source-language starlark says so for any other
file and for -e. The language is picked per file. --starlark-standard spec applies the
specification's rules on the top level and recursion, which the default relaxes
(Deviations).
rontolisp hello.star # interpreter
rontolisp hello.star -o Hello.class && java Hello # JVM
rontolisp hello.star -o hello.wasm && wasmtime run hello.wasm
rontolisp hello.star -o hello-c.wasm --component && wasmtime run hello-c.wasm
rontolisp -e 'print(1 + 2)' --source-language starlark
--no-gc is refused: that backend has no structures, hash tables or closures.
--source-language starlark with no program starts a REPL with a starlark> prompt. An
expression shows its repr, and None shows nothing. A def, if or for ends at a
blank line. Each input sees what the inputs before it defined.
The examples in this section run in your browser: Run runs each one as a program of its own, on a fresh interpreter. The playground reads Starlark when you pick it under language.
examples/starlark/
holds a runnable program with its expected output.
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 354224848179261915075
f(1, 2.5, None, x="a", y=[1, (2,)])
["quick", "brown", "jumps"] {"quick": 5, "brown": 5, "jumps": 5}
What is read
The whole grammar of the specification:
defwith default values,*args, keyword-only parameters and**kwargs;lambda; nested functions that read the variables around them.if/elif/else,forwithbreakandcontinue,return,pass.- Assignment to a name, to an element (
a[i] = v) and to a tuple or list of targets, and the augmented forms (+=,//=,<<=, ...). - List and dict comprehensions, conditional expressions, indexing and slicing,
and/or/not, the comparisons,in, the arithmetic and bitwise operators, and%on a string. load, for another Starlark file (Modules) and for the functions of a Common Lisp package (Mixing with Common Lisp).
The values are None, True and False, integers of any size, floats, strings, bytes,
lists, tuples, dicts, sets, ranges and functions.
Built-in functions
| Function | Answers |
|---|---|
abs(x) | the absolute value of an int or a float |
all(x), any(x) | whether every element, or any, is true |
bool(x=False) | the truth of x |
bytes(x) | a bytes: x itself, the UTF-8 encoding of a string, or the ints 0-255 of an iterable |
dict(pairs, **kwargs) | a new dict: the entries of a dict or of an iterable of pairs, then the named arguments |
dir(x) | a new sorted list of the names of the methods of x |
enumerate(x, start=0) | a list of (index, element) tuples |
fail(*args, sep=" ") | nothing: it ends the program with the arguments as the error |
float(x=0) | a float from an int, a float, a bool or a string ("1e3", "inf", "nan") |
getattr(x, name, default) | the method name of x bound to it, else default, else an error |
hasattr(x, name) | whether x has the method name |
hash(x) | the hash of a string or a bytes |
int(x, base) | an int from an int, a float, a bool, or a string in base 2 to 36 (base=0 reads a 0x, 0o or 0b prefix) |
len(x) | the number of elements of a string, bytes, list, tuple, dict, set or range |
list(x), tuple(x) | a new list, or a tuple, of the elements of an iterable |
max(*args, key=None), min(*args, key=None) | the greatest, or least, of the arguments or of the one iterable |
print(*args, sep=" ") | None, after writing the str of the arguments and a newline to standard output |
range(stop), range(start, stop, step=1) | a range of integers |
repr(x), str(x) | x as a string; repr writes a string between double quotes |
reversed(x) | a new list in reverse order |
set(x) | a new set of the elements of an iterable, in their order; set() is empty |
sorted(x, key=None, reverse=False) | a new sorted list; equal elements keep their order |
type(x) | the name of the type of x |
zip(*iterables) | a list of tuples, as long as the shortest iterable |
Methods
| Type | Methods |
|---|---|
| list | append, clear, extend, index, insert, pop, remove |
| dict | clear, get, items, keys, pop, popitem, setdefault, update, values |
| set | add, clear, difference, difference_update, discard, intersection, intersection_update, isdisjoint, issubset, issuperset, pop, remove, symmetric_difference, symmetric_difference_update, union, update |
| bytes | elems |
| string | capitalize, codepoint_ords, codepoints, count, elem_ords, elems, endswith, find, format, index, isalnum, isalpha, isdigit, islower, isspace, istitle, isupper, join, lower, lstrip, partition, removeprefix, removesuffix, replace, rfind, rindex, rpartition, rsplit, rstrip, split, splitlines, startswith, strip, title, upper |
A method is called on its receiver, or taken as a value bound to it:
<built-in method append of list value> ["a"] 2 0
A set keeps its elements in the order they were first added. |, &, - and ^ answer a
new set, and |=, &=, -= and ^= change the set on the left (|= a dict too). A bytes
is an immutable sequence of ints 0-255: indexing answers an int, slicing a bytes, and str
decodes it as UTF-8.
set([3, 1, 2]) set([1, 2]) True b"hé" 3 104 é
A list, a dict or a set is not changed while a loop runs over it. Like every error, the attempt ends the program:
$ cat loop.star
xs = [1, 2]
for x in xs:
xs.append(x)
$ rontolisp loop.star
Unhandled condition: cannot append to list during iteration
at loop.star:3
A variable read before it is assigned is an error the same way, a local or a global, and
so is a call of a def written above it.
Modules
load("words.star", "shout", count = "COUNT") runs another file and binds names of the
loading file to its globals: shout to the module's shout, count to its COUNT. The
path is relative to the file holding the statement.
- A module runs once per program, where the first
loadof it stands, however many files load it. - Its globals are its own: two files may both define
helper. - A name starting with an underscore cannot be loaded, and neither can a name the module loaded itself.
- A file that is not there, a name the module does not define and a file loading the one that loads it are errors before the program starts.
- A module is read when the program is compiled, so a compiled program carries it.
When a file has run, the lists, dicts and sets made while it ran are frozen: changing one is an error from then on. A list, dict or set that a function of the file makes when it is called later belongs to the caller. A frozen list is a dict key.
$ cat words.star
print("words runs")
seen = ["start"]
def shout(s):
return s.upper() + "!"
$ cat main.star
load("words.star", "shout", "seen")
print(shout("hello"), seen, {seen: 1})
seen.append("more")
$ rontolisp main.star
words runs
HELLO! ["start"] {["start"]: 1}
Unhandled condition: cannot append to frozen list
at main.star:3
This section
- Mixing with Common Lisp -- what a Common Lisp file and a Starlark file of one program see of each other.
- Deviations -- where this front end departs from the specification, then what is not there yet.