GovLisp is the source language of GOVERNMENT. It is a strict, lexically scoped Lisp-1. All values are immutable.
| Type | Range | Printed as |
|---|---|---|
| Integer | Signed 64 bits | -42 |
| Float | IEEE 754 double, always finite | 3.25, 1.0, 1.0e+21 |
| String | A sequence of Unicode code points | "a\"b", with ", \, line feed and tab escaped |
| Boolean | T or F | T, F |
| Symbol | A name | foo |
| Pair | A head and a tail | (1 2 3), (1 . 2) |
| Empty list | One value | () |
| Function | A closure or a builtin function | #<fn sq>, #<fn>, #<builtin +> |
| Result | A success holding any value, or an error holding a message | #<ok 42>, #<err "not a number: \"x\""> |
A float prints in the shortest form that reads back as the same double, always with a dot. Magnitudes below 1e-6 or at or above 1e21 use an exponent: 1.0e+21, 1.5e-07.
A list is a chain of pairs that ends in (). Only F is false. Every other value is true, including 0, 0.0, "" and ().
| Form | Result |
|---|---|
| (quote d) | d, not evaluated. See below. |
| (if c a b) | a if c is not F, otherwise b. (if c a) gives () when c is F. |
| (def name expr) | Binds name to the value of expr, and returns the symbol name. See below. |
| (fn (p1 ... pk) body...) | A closure over the current scope. See below. |
| (and x...) | The first F from the left, or else the last value. (and) is T. |
| (or x...) | The first value from the left that is not F, or else F. (or) is F. |
| (cond (test body...) ...) | The value of the body of the first clause whose test is not F, or (). See below. |
| (let ((name expr) ...) body...) | The value of the body, with each name bound to the value of its expression. See below. |
| (let? ((name expr) ...) body...) | let for results: the first error, or the value of the body. See below. |
| (handle r ((ok v) body...) ((err e) body...)) | The value of the body for a success or for an error, whichever r is. See below. |
The wrong number of operands is E-SYNTAX.
quote turns a special form or function node into the symbol with that name, so '+ is the symbol +. T, F and () stay constants.
name in def must be a symbol that is not reserved. If expr is an fn written directly in the def, the closure takes name for printing and errors.
The parameters of fn must be distinct symbols that are not reserved. (fn () ...) takes none. The body is zero or more def forms, then one or more expressions. The value of the last expression is the result. A call with a different number of arguments than parameters is E-ARITY.
cond evaluates each clause's test in order. At the first test that is not F, it evaluates that clause's body and returns the value of its last expression. Each clause is a list of a test and one or more expressions. Use T as the last test for a default.
The bindings of let are sequential: each expression sees the names bound before it. The names must be distinct symbols that are not reserved. The body is the same as an fn body: zero or more def forms, then one or more expressions. The value of the last expression is the result.
Each expression in let? must give a result. If it is a success, its name is bound to the value inside it. If it is an error, that error is the value of the whole form, and no later binding or body expression is evaluated. The rules for names and the body are the same as for let. The body's value is returned as it is, so it is usually a result too. See Results.
handle evaluates r, which must be a result. For a success, it binds v to the value inside and evaluates the first clause's body; for an error, it binds e to the error and evaluates the second's. The two clauses can come in either order, and each must appear once. v and e stand for any names that are not reserved. The value of the chosen body's last expression is the result.
A wrong number of arguments is E-ARITY. An argument of the wrong type is E-TYPE.
| Function | Result |
|---|---|
| + * | The sum or product. (+) is 0 and (*) is 1. |
| - / | The first argument minus, or divided by, each later one. (- x) is -x, and (/ x) is (/ 1 x). |
| % | (% a b) is the remainder of (/ a b), with the sign of a. |
| < > <= >= | Compare two numbers. |
| min max | The smallest or largest of one or more numbers. |
| == <> | Compare any two values. |
| not | T if the argument is F, otherwise F. |
| cons | A new pair of the two arguments. |
| head tail | The head or tail of a pair. Any other argument, () included, is E-TYPE. |
| list | A new list of the arguments, in order. (list) is (). |
| apply | (apply f args) calls f with the elements of the list args. |
| len | The number of elements in a list. |
| @ | (@ xs i) is the element at index i, as a result. See below. |
| @! | (@! xs i) is the element at index i. An index out of range stops the program with E-PANIC. |
| cat | The lists joined in order. (cat) is (). |
| range | (range n) is (0 1 ... n-1), and (range a b) is (a a+1 ... b-1). |
| repeat | (repeat x n) is a list of n elements, each x. |
| rev | A list in reverse order. |
| map | (map f xs) is the list of (f x) for each element x of xs. |
| fmap | (fmap f xs) is the lists (f x) for each element x of xs, joined: (apply cat (map f xs)). |
| filter | (filter f xs) is the elements x of xs for which (f x) is not F. |
| fold | (fold f init xs) combines the elements from the left, starting with init. |
| has? | (has? x xs) is T if an element of xs is equal to x, by ==, otherwise F. |
| find | (find x xs) is the index of the first element of xs equal to x, in a result. See below. |
| find! | (find! x xs) is the index itself. An x that is not in xs stops the program with E-PANIC. |
| sort | (sort less? xs) is xs in order, where (less? a b) says that a goes before b. |
| Type tests | T if the argument has the type, otherwise F. See below. |
| trunc | A number truncated toward zero, as an integer. |
| num | A string read as a number, as a result. See Results. |
| $ | A value as a string. |
| $len | The number of code points in a string. |
| $cat | The strings joined in order. ($cat) is "". |
| $@ | ($@ s i) is the code point at index i, as a string, in a result. See below. |
| $@! | ($@! s i) is the code point itself. Out of range stops the program with E-PANIC. |
| $sub | ($sub s start len) is len code points from index start, in a result. See below. |
| $sub! | ($sub! s start len) is the substring itself. Out of range stops the program with E-PANIC. |
| $spl | ($spl s sep) is the list of the parts of s between each sep. |
| $join | ($join xs sep) is the strings in the list xs, joined with sep between them. |
| $trim | A string without the spaces, tabs, line feeds and carriage returns at either end. |
| $find | ($find s sub) is the index of the first sub in s, in a result. See below. |
| $find! | ($find! s sub) is the index itself. A sub that is not in s stops the program with E-PANIC. |
| $f | ($f format arg...) is format with each directive replaced by the next argument. See below. |
| ok | A success holding the value. |
| err | An error holding the message. |
| ok? err? | T if the argument is a success, or an error. |
| ?! | The value inside a success. An error stops the program with E-PANIC. |
| ?!-or | (?!-or r default) is the value inside a success, or default for an error. |
| !msg | The message of an error. |
| !!! | Stops the program with E-PANIC. |
Arithmetic goes from left to right, one argument at a time. Two integers give an integer. If either is a float, the result is a float. Integer / truncates toward zero. Integer overflow, division by zero, and a float result that is not finite are E-ARITH.
% takes the remainder after /, so it has the sign of the first argument: (% 7 3) is 1, (% -7 3) is -1, and (+ (* (/ a b) b) (% a b)) is a for any integers. For floats, (% 7.5 2) is 1.5. A second argument of zero is E-ARITH.
min and max compare as < does. Each gives the first of its smallest or largest arguments as it is, so (min 1 1.0) is 1 and (min 1.0 1) is 1.0.
Comparisons can mix integers and floats, and compare them exactly. For == and <>, numbers compare by value, so (== 1 1.0) is T. Pairs compare by structure. Two successes are equal if the values inside them are, and two errors if their messages are. Other values are equal only if they have the same type and value. A function in either argument is E-TYPE.
The list functions take lists that end in (). Any other value where a list is expected is E-TYPE. Where a function is expected, a value that is not one is E-NOT-A-FUNCTION, as for a call. apply, map, filter and fold call the function on the elements from left to right, and an error from the function stops the program as usual.
fold calls f with the result so far and the next element: (fold f init '(a b c)) is (f (f (f init a) b) c), and (fold f init ()) is init. So (fold + 0 '(1 2 3)) is 6, and (fold (fn (acc x) (cons x acc)) () xs) is (rev xs).
sort calls (less? a b) on pairs of elements, and puts a before b when the result is not F. The sort is stable: elements that neither goes before keep their order. So (sort < '(3 1 2)) is (1 2 3), and sorting pairs by their heads keeps pairs with equal heads in order. less? is called O(n log n) times, in an order that is not specified.
find is to lists what $find is to strings. It compares as has? does, and counts from 0, as @ does. An x that is not in xs gives an error. find! is (?! (find x xs)).
(find 'c '(a b c)) => #<ok 2> (find 2.0 '(1 2 3)) => #<ok 1> (find 'd '(a b c)) => #<err "d is not in (a b c)">
range and repeat take integers. A range whose end is not above its start, and a repeat of 0 or fewer, give (). So (range 1 4) is (1 2 3), (range 3) is (0 1 2), (range 4 1) is (), and (repeat "." 3) is ("." "." ".").
fmap maps, then joins the results, so each (f x) must be a list: (fmap (fn (x) (list x x)) '(1 2)) is (1 1 2 2). A function that gives () for an element drops it.
@ counts elements from 0, and takes an integer index. So (@ xs 0) is the head of xs and (@ xs 1) is the head of its tail, each in a success. An index that is negative, or that reaches past the end of the list, gives an error:
(@ '(a b c) 1) => #<ok b> (@ '(a b c) 3) => #<err "index 3 is past the end of a list of length 3">
(@! xs i) is (?! (@ xs i)): the element itself, or E-PANIC with the error's message.
The type tests are: str? for a string, pair? for a pair, nil? for (), int? for an integer, float? for a float, sym? for a symbol, bool? for T or F, and fn? for a closure or a builtin function. ok? and err? test results; see Results.
trunc drops the fraction of a float: (trunc -2.7) is -2. An integer is returned as it is. A float outside the integer range is E-ARITH.
$ gives a string as it is and a symbol's name. Any other value gives its printed form: ($ 42) is "42" and ($ '(1 "a")) is "(1 \"a\")". A function is E-TYPE.
$@ and $sub count code points from 0, and take integer indexes and lengths. An index or a length that is negative, or that reaches past the end of the string, gives an error. ($sub s ($len s) 0) is #<ok "">. Without a length, $sub gives the rest of the string: ($sub s i) is ($sub s i (- ($len s) i)).
($@ "abc" 1) => #<ok "b"> ($@ "abc" 3) => #<err "index 3 is past the end of a string of length 3"> ($sub "abc" 1 2) => #<ok "bc"> ($sub "abc" 2 2) => #<err "index 4 is past the end of a string of length 3"> ($sub "abc" 1) => #<ok "bc">
$@! and $sub! are to $@ and $sub what @! is to @: ($@! s i) is (?! ($@ s i)).
$spl splits at every sep, so two separators in a row give an empty part, and a string with no sep gives a list of one part. An empty sep splits between code points. $join reverses it: ($join ($spl s sep) sep) is s.
($spl "a > b" " > ") => ("a" "b")
($spl "a,,b" ",") => ("a" "" "b")
($spl "abc" "") => ("a" "b" "c")
($spl "" ",") => ("")
($join '("a" "b" "c") ", ") => "a, b, c"
$find counts code points from 0, as $@ does. A sub that is not in s gives an error. An empty sub is at index 0. $find! is (?! ($find s sub)).
($find "héllo" "l") => #<ok 2> ($find "abc" "x") => #<err "\"x\" is not in \"abc\"">
($f format arg...) copies format, and replaces each directive in it with the next argument. A directive is %, then the flags - and 0 if any, then a width if any, then . and a precision if any, then a verb:
| Verb | Argument | Gives |
|---|---|---|
| s | Any value but a function | The value as $ gives it. |
| v | Any value but a function | The value as it prints, so a string is in quotes. |
| d | An integer | The integer in decimal. |
| f | A number | The number with precision digits after the point, or 6 if none. |
| e | An error | The error's message. |
| % | None | A %. %% takes no flags, width or precision. |
($f "hello, %s" "world") => "hello, world"
($f "%s has %d votes" 'ada 12) => "ada has 12 votes"
($f "%.1f%%" 51.6129) => "51.6%"
($f "[%6.2f] [%-4s] [%05d]" 3.14159 "ab" -42)
=> "[ 3.14] [ab ] [-0042]"
($f "%v is not %s" "1" 1) => "\"1\" is not 1"
($f "could not add: %e" (num "x")) => "could not add: not a number: \"x\""
A directive with no argument left for it, or an argument left over, is E-ARITY. An argument of the wrong type for its verb is E-TYPE: a float for d, a success for e, or a function for anything. A malformed directive is E-SYNTAX: an unknown verb, a % at the end of format, a precision on a verb other than f, 0 on a verb other than d or f, or 0 with -.
A result is a value that says whether something succeeded. A success contains any value: (ok 42) prints as #<ok 42>. An error contains a message: (err "msg") prints as #<err "msg">. ok? and err? tell them apart, and !msg gives an error's message. Both kinds are true, like every value other than F, and making an error does not stop the program.
A builtin that can fail on ordinary input returns a result: a success with its value, or an error that says why it failed. A mistake in the program, such as an argument of the wrong type, is a runtime error instead, and stops the program.
num, @, $@, $sub, $find and find return results. A string or a list is often shorter than a program expects, so an index past the end is an error result, not a runtime error; see Builtin functions. Each indexing function has a version ending in ! that gives the value itself, and stops the program with E-PANIC on an error. num reads a string by rules 2 and 3 of Atoms in the full specification. A number gives a success, as it is:
(num "42") => #<ok 42> (num "2.5") => #<ok 2.5> (num 7) => #<ok 7> (num "4x2") => #<err "not a number: \"4x2\"">
A program gets the value out of a result in one of these ways:
| Form | For a success | For an error |
|---|---|---|
| (?! r) | The value | Stops the program with E-PANIC and the error's message |
| (?!-or r default) | The value | default |
| (let? ((x r) ...) body...) | Binds x to the value and goes on | The error is the result of the whole form |
| (handle r ((ok v) ...) ((err e) ...)) | Runs the ok clause with v bound | Runs the err clause with e bound |
Any other use of a result is an ordinary type error: (* 2 (num "21")) is E-TYPE, because a result is not a number.
let? passes the first error on, so a run of steps that can each fail needs one form, not one check per step:
(def add-strings (fn (a b)
(let? ((x (num a))
(y (num b)))
(ok (+ x y)))))
(add-strings "40" "2") => #<ok 42>
(add-strings "40" "x") => #<err "not a number: \"x\"">
handle deals with both cases where they happen:
(handle (add-strings "40" "x") ((ok v) ($ v)) ((err e) ($cat "could not add: " (!msg e)))) => "could not add: not a number: \"x\""
?!, ?!-or, let? and handle need a result. Any other value is E-TYPE.
!!! stops the program with the runtime error E-PANIC. Its argument is an error or a string, and gives the message.
The interpreter evaluates the top-level forms in order. It prints the value of each form that is not a def, one per line.
A runtime error stops the program with exit code 1. The message gives the error code, the OID and depth of the node that failed, and the nearest note. For a shared node, the note comes from the first parent that has one.
| Runtime error | Cause |
|---|---|
| E-UNBOUND | A symbol is not bound, or is used before its definition is complete. |
| E-SYNTAX | A special form or a call is malformed. |
| E-SPECIAL-FORM | A special form's name is used as a value. |
| E-NOT-A-FUNCTION | The head of a call is not a function. |
| E-ARITY | A call has the wrong number of arguments. |
| E-TYPE | An argument has the wrong type. |
| E-ARITH | Overflow, division by zero, or a float result that is not finite. |
| E-IMMUTABLE | A name is defined twice in the same scope. |
| E-PANIC | !!! was called, or ?! or a ! function got an error. |