# Ketos
Ketos is a Lisp dialect functional programming language, implemented in Rust
and mainly intended for extending and scripting for Rust programs.
Its types and semantics are, in some cases, closer to Rust than to Lisp.
## Environment variables
`KETOS_PATH` - A list of directories (separated by `:` on Unix systems; `;`
on Windows systems) that are added to the interpreter search path list, used
by the [`use` operator](operators.md#use).
## Syntax
Ketos syntax, the element most heavily borrowed from Lisp, consists of lists and
values. Function calls are represented as a list whose first argument is some
callable value and whose remaining arguments are passed to the function.
Every unit of Ketos code is an expression and yields a value.
```lisp
ketos=> (println "Hello, world!")
Hello, world!
()
ketos=> (+ 1 2)
3
```
### Comments
Line comments begin with a semicolon (`;`) and terminate at the end of a line.
Block comments begin with `#|` and end with `|#`.
These can be arbitrarily nested, unlike C block comments.
It is generally preferred to use line comments to document code. Block comments
should only be used when you want to "comment out" a chunk of code.
```lisp
; This is a comment!
(foo) ; This comment draws attention to a line of code.
```
#### Doc Comments
Line comments beginning with two semicolons (`;;`) can be used to document
expressions that create an item, such as `const`, `define`, `lambda`, `macro`,
and `struct`.
```lisp
;; Adds `1` to the given value.
(define (plus-1 a) (+ a 1))
```
Line comments beginning with three semicolons (`;;;`) at the top of a file can
be used to document a module.
### Functions
System functions perform basic functions on standard values.
[List of system functions](functions.md)
### Operators
Operators are interpreted by the compiler at compile time. Their input syntax
often differs from normal Ketos syntax.
[List of standard operators](operators.md)
### Macros
Macros are sort of like user-defined operators. They are executed at compile
time, given the syntactical input defined in the source code. Their result is
also Ketos syntax, which is then compiled.
### Quoting
Values preceded by a `'` token are quoted, causing them to be interpreted as
literal values without being evaluated.
```lisp
ketos=> (+ 1 2)
3
ketos=> '(+ 1 2)
(+ 1 2)
```
### Quasiquoting
Values preceded by a `` ` `` token are quasiquoted. Contained elements are
treated as if quoted unless preceded by a `,` token. Elements within a quasiquoted
list that are preceded by a `,@` token must evaluate to a list. The elements
of that list are inserted into the parent list.
```lisp
ketos=> `(foo ,(+ 1 2))
(foo 3)
ketos=> `(foo ,@(concat '(1 2) '(3 4)))
(foo 1 2 3 4)
```
## Execution
Local bindings and values in Ketos are immutable -- they cannot be modified
once assigned. Global bindings (those created with the
[`define` operator](operators.md#define)) can be replaced with another call
to `define`, but existing copies of the original value will remain unchanged.
Because values are immutable, iterative computation cannot be done with loops,
as it is typically done in imperative programming languages. Instead, these
computations are accomplished with recursive functions.
### Tail recursion
The Ketos interpreter implements tail call optimization for recursive functions.
This enables functions to perform a recursive tail calls without occupying more
space on the call stack.
Care must be taken to write functions in a tail recursive manner.
Consider this naive implementation of a factorial function:
```lisp
(define (factorial n)
(if (<= n 1)
1
(* n (factorial (- n 1)))))
```
This implementation cannot benefit from tail call optimization because the
final result of the second branch is computed by the `*` function.
The function can instead be written with an accumulator parameter -- which
collects the computation in each step and passes it to itself on the next call.
This function will take full advantage of tail call optimization:
```lisp
(define (factorial n)
(factorial-tail 1 n))
(define (factorial-tail acc n)
(if (<= n 1)
acc
(factorial-tail (* n acc) (- n 1))))
```
## Types
### Unit
Unit, or an empty list, is represented as `()`. Essentially, it's a type with
only one possible value. Functions that perform side effects often return `()`.
```lisp
ketos=> ()
()
```
### Boolean
Boolean values are `true` and `false`.
```lisp
ketos=> true
true
ketos=> false
false
ketos=> (not true)
false
```
### Integer
Ketos features arbitrary precision integers. Integer literals may be specified
in decimal, binary, octal, or hexadecimal.
```lisp
ketos=> 123
123
ketos=> 0b101010
42
ketos=> 0o100
64
ketos=> 0xdeadbeef
3735928559
```
### Float
Floating point values, specified using the Rust type `f64`.
```lisp
ketos=> 3.14159
3.14159
```
### Ratio
Arbitrary precision integer ratios.
```lisp
ketos=> 1/2
1/2
ketos=> 10/20
1/2
ketos=> 99/123
33/41
```
### List
Lists are a basic element of Ketos syntax. Normally, a list is interpreted as a
function call. In order to make a list that is interpreted as a value, the
quoting operator `'` is used. Lists can contain values of any type, including
nested lists. Only the outermost list needs to be quoted.
```lisp
ketos=> '(1 2 3)
(1 2 3)
ketos=> '(1 2/3 "foo")
(1 2/3 "foo")
ketos=> '(1 2 (3 4 (5 6)))
(1 2 (3 4 (5 6)))
```
### Name and Keyword
Names are values, too. Some languages call them an "atom." Keyword values
are similar to name values, but keywords have a special use in calling
functions. See [`define`](operators.md#define) for details.
```lisp
ketos=> 'foo
foo
ketos=> (= 'foo 'foo)
true
ketos=> (= 'foo 'bar)
false
ketos=> :foo
:foo
```
### String
Strings are encoded in UTF-8. Their syntax is identical to Rust.
```lisp
ketos=> "foo"
"foo"
ketos=> "\u{61}"
"a"
```
### Byte String
Byte strings are non-encoded strings of bytes.
```lisp
ketos=> #b"foo"
#b"foo"
```
### Path
At runtime, paths are encoded in operating system native format.
However, in Ketos code, they may contain only UTF-8 and their syntax
is identical to strings, aside from the `#p` prefix.
```lisp
ketos=> #p"foo"
#p"foo"
```
### Character
Characters are unicode code points. Because Ketos uses the `'` token for
quoting, character literals are prefixed with the character `#`. Otherwise,
the syntax is identical to Rust.
```lisp
ketos=> #'a'
#'a'
```
### Struct
Struct definitions and values are created through the `struct` operator
and the `new` function, respectively. Their fields are type-checked upon assignment.
```lisp
ketos=> (struct Foo ((a integer) (b string)))
Foo
ketos=> (new Foo :a 123 :b "foo")
Foo { a: 123, b: "foo" }
```
## Modules
[List of standard modules](modules.md)