Functions
The general functions bound in every module. Each is a value: it can be
called, passed to map or apply, and stored. Several names are also
special forms or macros, which compile inline when they head a form;
those entries carry an Also: line. Types and their NAME?
predicates are on Types and type predicates,
and the operators on Operators.
Predicates
Syntax: (instance? VALUE TYPE ...), (subclass? CLASS TYPE ...)
Python’s isinstance and issubclass: true when the first argument is
an instance, or a subclass, of any TYPE. A tuple of types is
accepted as one TYPE.
Also: special forms instance?,
subclass?.
(instance? 5 int) ; True
(instance? 5 #(str int)) ; True
(instance? '(1 2) list) ; False
(subclass? bool int) ; True
Syntax: (callable? VALUE)
True when VALUE can be called.
Syntax: (None? VALUE)
True only for None. nil is not None.
Syntax: (nil? VALUE)
True for nil and bracket-nil, false for everything else, including
None and empty Python collections.
Also: macros None? and nil?.
Syntax: (proper? VALUE), (recursive? VALUE)
proper? is true for a pair chain ending in nil, including nil
itself; a Python list is not proper. recursive? is true for a pair
chain that loops back on itself.
Syntax: (all? ITERABLE), (any? ITERABLE)
True when every element, or any element, is truthy. (all? #[]) is
true and (any? #[]) is false.
Syntax: (hasattr? OBJ NAME)
True when OBJ has the attribute NAME.
Syntax: (on-demand?)
Whether the current context is on the demand path. See on-demand?.
(callable? +) ; True
(None? nil) ; False
(nil? '()) ; True
(nil? #[]) ; False
(proper? (cons 1 2)) ; False
(any? (map (lambda [x] (> x 2)) #[1 3])) ; True
(hasattr? 5 "real") ; True
Pairs
nil is the empty list. (pair? nil) is true; test nil? to tell it
apart.
Syntax: (cons VALUE ... TAIL)
A chain of pairs holding each VALUE, ending in TAIL. nil
as the tail makes a proper list; any other tail an improper one.
Also: special form cons.
Syntax: (build-proper VALUE ...)
A proper list of the values; with none, nil.
(cons 1 2 3 nil) ; (1 2 3)
(cons 1 2) ; (1 . 2)
(cons 0 *: #[1 2] nil) ; (0 1 2)
(build-proper 1 2 3) ; (1 2 3)
(apply build-proper #[1 2]) ; (1 2)
Syntax: (car PAIR), (cdr PAIR)
The head and the tail of a pair. Both raise TypeError on nil and on
any value that is not a pair.
Syntax: (cadr P), (caddr P), (cadddr P), (caddddr P),
(cddr P), (cdddr P), (cddddr P)
Compositions of car and cdr: cadr is (car (cdr P)), cddr is
(cdr (cdr P)), and so on.
Also: macros cadr and family.
Syntax: (first P), (second P), (third P), (fourth P), (fifth P)
Aliases for car, cadr, caddr, cadddr, and caddddr.
(car '(1 2 3)) ; 1
(cdr '(1 2 3)) ; (2 3)
(cddr '(1 2 3)) ; (3)
(third '(1 2 3)) ; 3
(list (map car #['(1 2) '(3 4)])) ; #[1 3]
Syntax: (set-car PAIR VALUE), (set-cdr PAIR VALUE)
Replace the head or the tail of PAIR in place. nil cannot be
modified and raises TypeError. set! accepts car, cdr, and the
c[ad]+r forms as places and rewrites to these calls.
var p (cons 1 2 3 nil)
(set-car p 9) ; p is (9 2 3)
set! (cadr p) 8 ; p is (9 8 3)
(set-cdr p nil) ; p is (9)
A pair is one link: it unpacks to its two fields, the car and the cdr,
and len of any pair but nil is 2. len, list, for-each, map,
and *: see those two fields, not the elements of the chain.
(.length x) follows a proper chain and counts its elements. To
prepend, pass the chain as the tail of cons.
(len '(1 2 3)) ; 2
(.length '(1 2 3)) ; 3
(list '(1 2 3)) ; #[1 (2 3)]
(cons 0 '(1 2)) ; (0 1 2)
Syntax: (unpack VALUE)
An iterator over the elements of a pair chain. Any other iterable is
passed to iter.
(list (unpack '(1 2 3))) ; #[1 2 3]
(sorted (unpack '(3 1 2))) ; #[1 2 3]
Pattern binding walks the chain: (var [a b] '(1 2 3)) binds a to
1 and b to (2 3).
Syntax: (bracket-cons VALUE ... TAIL)
cons producing bracket pairs, the pairs the reader builds for [ ]
forms. A bracket pair compares equal to a plain pair and works with
every function above. bracket-nil is the empty [], and
(nil? bracket-nil) is true. See
Brackets and the call convention.
Also: special form bracket-cons.
Syntax: (bracket-splice SEGMENT ...)
Concatenate the elements of each SEGMENT – a pair chain, nil,
or any iterable – into one list whose head is a bracket pair. With no
elements, bracket-nil.
(== (bracket-cons 1 2 bracket-nil) '(1 2)) ; True
(bracket-splice '(1 2) #(3 4) nil) ; [1 2 3 4]
(is? (bracket-splice) bracket-nil) ; True
Collection builders
The reader forms #[...], #(...), and #{...} read to calls of
#list, #tuple, and #dict; see
Data structures. Each builder accepts
*: to splice an iterable into its arguments.
Also: special forms
#list, #tuple, #list-append,
#str.
Syntax: (#list VALUE ...), (#tuple VALUE ...), (#set VALUE ...)
A list, tuple, or set of the arguments; with none, an empty collection.
There is no set literal. The builders take the elements as arguments;
the types list, tuple, and set take one iterable.
(#list 1 2 3) ; #[1 2 3]
(#tuple) ; #()
(sorted (#set 1 2 2)) ; #[1 2]
(apply #tuple (range 3)) ; #(0 1 2)
(#list *: (range 3)) ; #[0 1 2]
Syntax: (#dict ITEM ... KEY: VALUE ...)
A dict from key-value items and keyword arguments. Each ITEM is a
two-element sequence #(KEY VALUE); a keyword argument adds its name
as a string key. Later entries replace earlier ones with the same key.
#{K: V ...} reads to (#dict #(K V) ...). A bare key and value,
(#dict "a" 1), raises ValueError.
(#dict #("a" 1) #("b" 2)) ; #{"a": 1 "b": 2}
(#dict a: 1) ; #{"a": 1}
(#dict #("a" 1) #("a" 2)) ; #{"a": 2}
Syntax: (#str VALUE ...)
The str of each argument, concatenated; with none, "". F-strings
read to #str calls.
(#str 1 "a" 2) ; "1a2"
(#str None True) ; "NoneTrue"
Syntax: (#list-append LIST VALUE)
Append VALUE to LIST in place. Exactly two arguments.
Called as a function value, it returns None.
Calling
Syntax: (apply FUNC [ARGS [KWARGS]])
Call FUNC with the positional arguments in the iterable
ARGS and the keyword arguments in the dict KWARGS. There
are no leading positional arguments before ARGS; put every
positional argument in it.
(apply + #[1 2]) ; 3
(apply (lambda [a b: 0] (+ a b)) #[1] #{"b": 5}) ; 6
(apply (lambda [] 7)) ; 7
Syntax: (identity VALUE), (constantly VALUE)
identity returns VALUE. constantly returns a function that
ignores its arguments and returns VALUE.
(list (filter identity #[0 1 "" "x"])) ; #[1 "x"]
((constantly 5) 1 2 x: 3) ; 5
Syntax: (partial FUNC ARG ... KEY: VALUE ...)
A function that calls FUNC with the given arguments followed by
its own. A Koskari function passed to it runs inside the evaluator and
may await; functools.partial over a Koskari function returns an
unawaited coroutine when Python calls it.
((partial + 10) 5) ; 15
((partial (lambda [a b: 0] (+ a b)) b: 2) 1) ; 3
Syntax: (demand FUNC), (demand-call FUNC ARG ...),
(demand-apply FUNC ARGS [KWARGS])
Run FUNC on the demand path, where it returns a value or raises
and never suspends; a suspension raises KoskariSyncViolation.
demand wraps FUNC and is usable as a decorator, @demand.
demand-call calls it with the arguments; demand-apply with the
arguments in a tuple and an optional dict. See
Demand, async, and defer.
((demand (lambda [x] (* x 3))) 2) ; 6
(demand-call (lambda [a] (* a 2)) 4) ; 8
(demand-apply (lambda [a b: 0] (- a b)) #(5) #{"b": 1}) ; 4
Syntax: (values VALUE ...)
Multiple results as one object. Pattern binding unpacks it.
var [a b] (values 1 2)
(+ a b) ; 3
Syntax: (decorate-wraps INNER WRAPPER)
Copy the name, docstring, and other metadata of INNER onto
WRAPPER and return WRAPPER, as functools.update_wrapper
does. When INNER is a coroutine function, WRAPPER is first
passed through coroutine-fn. See Decorators.
Async
Syntax: (defer THUNK)
A single-shot awaitable over the call of THUNK. It is not
awaited at the next use; an explicit (await ...) consumes it, and a
second await raises RuntimeError.
Syntax: (create-task AWAITABLE)
Schedule AWAITABLE on the running loop and return the
asyncio.Task. A task is not auto-awaited; (await TASK) resolves it.
Passing a defer consumes it.
Syntax: (coroutine-fn FUNC)
Wrap FUNC so asyncio.iscoroutinefunction accepts it. Usable as
a decorator, @coroutine-fn.
Syntax: (run-process ARG ...)
Run the argv in a subprocess to completion and return a
ProcessResult holding args, returncode, stdout, and stderr.
Its text, stderr_text, json, jsonl, and yaml decode the
output, and raise_for_status raises CalledProcessError on a nonzero
exit. A nonzero exit is not raised otherwise. See
fence/bash.
(await (defer (lambda [] 4))) ; 4
(import asyncio)
(asyncio.iscoroutinefunction (coroutine-fn (lambda [] 1))) ; True
Iteration
Syntax: (iter ITERABLE), (next ITERATOR [DEFAULT]),
(next ITERATOR default: DEFAULT)
An iterator over ITERABLE, and its next item. An exhausted
iterator returns DEFAULT when given, and otherwise raises
StopIteration.
Also: special forms
iter, next.
var it (iter #[1])
(next it) ; 1
(next it 9) ; 9
(next it default: 9) ; 9
Syntax: (sorted ITERABLE key: KEY reverse: REVERSE)
A new sorted list. KEY is wrapped in demand, so a Koskari
function works as the key.
(sorted #["aa" "b"] key: (lambda [s] (len s))) ; #["b" "aa"]
(sorted #[3 1 2] reverse: True) ; #[3 2 1]
Syntax: (max ITERABLE key: KEY), (max VALUE ...), and min the
same
The largest or smallest element. A Koskari function passed as key:
returns an unawaited coroutine, which does not compare; wrap it in
demand.
(max 3 7 5) ; 7
(max #["aa" "b"] key: len) ; "aa"
(min #["aa" "b"] key: (demand (lambda [s] (len s)))) ; "b"
Syntax: (len COLLECTION)
The number of elements. A pair is one link and counts as two;
(.length x) counts the elements of a proper chain.
Also: special form
len.
Syntax: (sum ITERABLE [START]), (enumerate ITERABLE [START]),
(reversed SEQUENCE)
The sum of the elements plus START; pairs of index and element
counting from START; a reverse iterator.
(sum #[1 2] 10) ; 13
(list (map list (enumerate "ab" 1))) ; #[#[1 "a"] #[2 "b"]]
(list (reversed (range 3))) ; #[2 1 0]
map, filter, and zip are lazy iterators that accept Koskari
functions; see map and filter. py-map,
py-filter, and py-zip are Python’s.
Conversion and display
Syntax: (repr VALUE), (py-repr VALUE)
repr writes Koskari syntax for symbols, pairs, and the other Koskari
types; py-repr is Python’s repr.
Also: special form
repr.
(repr '(1 2)) ; "(1 2)"
(py-repr '(1 2)) ; "cons(1, 2, nil)"
(repr 'a) ; "a"
(py-repr 'a) ; "<symbol 'a'>"
Syntax: (format VALUE [SPEC])
VALUE formatted by the format spec SPEC.
Also: special form format.
Name |
Does |
|---|---|
|
Absolute value |
|
Rounded, halves to even |
|
An integer as a binary, hexadecimal, or octal string |
|
Code point to one-character string, and back |
|
|
|
The hash of a value |
|
The identity of an object |
(format 3.14159 ".2f") ; "3.14"
(abs -3) ; 3
(round 2.5) ; 2
(hex 255) ; "0xff"
(chr 65) ; "A"
Input and output
Syntax: (print VALUE ...), (input [PROMPT]), (open PATH [MODE])
Write the values to standard output; read a line from standard input; open a file.
Attributes and items
Syntax: (getattr OBJ NAME [DEFAULT]), (setattr OBJ NAME VALUE)
Read or write the attribute NAME. A missing attribute returns
DEFAULT when given.
Syntax: (vars OBJ), (dir OBJ)
The __dict__ of OBJ, and its attribute names.
Also: special forms vars,
dir.
Syntax: (itemgetter KEY ...), (attrgetter NAME ...)
A function of one argument that returns its item KEY, or its
attribute NAME. With several keys or names, a tuple.
(getattr 5 "nope" 0) ; 0
(sorted #[#(2 "b") #(1 "a")] key: (itemgetter 0)) ; #[#(1 "a") #(2 "b")]
((itemgetter 1 0) #[10 20]) ; #(20 10)
((attrgetter "real") 5) ; 5
Syntax: (super [TYPE OBJ])
The parent-class proxy, inside a method.
Also: macro super.
Name |
Page |
|---|---|
|
getattr* and hasattr*: nested attribute access along a dotted path |
|
getitem* and hasitem*: nested item access along a key path |
|
build-slice: a slice object, the runtime behind |
|
koskari-vars: the calling frame’s namespace, or an object’s |
Refs, parameters, and the environment
Syntax: (deref REF)
The value a ref holds. See ref.
Also: special form deref.
Syntax: (parameter NAME [DEFAULT])
The value bound to the parameter NAME: the innermost
parameterize first, then the root scope. DEFAULT answers when
nothing is bound; with no default an unbound name raises NameError.
Also: special form parameter.
Syntax: (environ-ref KEY [DEFAULT])
A ref to the environment variable KEY. Without DEFAULT it
is an ItemRef, and reading an unset variable raises KeyError. With
DEFAULT it is a DynamicRef: reading an unset variable returns
DEFAULT, and clearing the ref, as take! on a name bound to it
does, deletes the variable. An empty key raises ValueError. The
function behind define-environ.
var v 5
(deref &v) ; 5
(apply parameter #['nope 3]) ; 3
var mode (environ-ref 'APP_MODE "dev")
(deref mode) ; "dev" while APP_MODE is unset
Compilation and expansion
Name |
Page |
|---|---|
|
compile: compile a source form without running it |
|
evaluate: compile a form if needed and run it |
|
get-compiler: the compiler that owns a namespace |
|
|
|
block layout expansion: expand |
|
help: documentation through the pager |
Also: macros evaluate,
get-compiler,
macroexpand,
help.
Syntax: (gensym [NAME])
A fresh symbol, distinct from every other symbol including other gensyms of the same name.
(== (gensym "x") (gensym "x")) ; False
Syntax: (active-pragma [KEY])
The pragma of the module being compiled, or the value of its KEY
setting; outside a compilation turn, a default pragma. Called as a
function value, the key is the keyword argument key:. See
Pragmas and feature settings.
Syntax: (help-pragma-key KEY)
Show the documentation for the pragma setting KEY through the
pager; (help (pragma KEY)) calls it. An unknown key raises
ValueError.
Syntax: build-syntax, build-macro, build-special,
build-bare-syntax
The functions the syntax-defining forms compile to:
syntax-rules and
syntax-match to build-syntax,
macro-rules to build-macro,
special-match to
build-special, and bare-syntax
to build-bare-syntax. Their arguments are matcher rows the compiler
produces; write the defining forms instead of calling these.
Constants
None, True, False, Ellipsis, ..., and NotImplemented are
Python’s constants; (is? Ellipsis ...) is true. nil and
bracket-nil are the empty lists; see Pairs.