# Scheme Built-In Procedure Reference

Last Updated: Summer 2018

This document serves as a reference for the built-in procedures in the Scheme project and staff Scheme interpreter. The web interpreter includes several additional built-in procedures.

In all of the syntax definitions below, `<x>`

refers to a required element `x`

that can vary, while `[x]`

refers to an optional element `x`

. Ellipses
indicate that there can be more than one of the preceding element. It is
assumed for all of these built-ins that the elements represent evaluated
arguments not the literal expressions typed in.

## Core Interpreter

`apply`

`(apply <procedure> <args>)`

Calls `procedure`

with the given list of `args`

.

```
scm> (apply + '(1 2 3))
6
```

`display`

`(display <val>)`

Prints `val`

. If `val`

is a Scheme string, it will be output without quotes.

A new line will not be automatically included.

`error`

`(error <msg>)`

Raises an `SchemeError`

with `msg`

as it's message. If there is no `msg`

,
the error's message will be empty.

`eval`

`(eval <expression>)`

Evaluates `expression`

in the current environment.

```
scm> (eval '(cons 1 (cons 2 nil)))
(1 2)
```

`exit`

`(exit)`

Exits the interpreter. In the web interpreter, this does nothing.

`load`

`(load <filename>)`

Loads the contents of the file with `filename`

and evaluates the code within.
`filename`

must be a symbol. If that file is not found, `filename`

.scm will
be attempted.

The web interpreter's does not currently support `load`

. The closest analog is
`import-inline`

, which takes a URL and evaluates the Scheme code in the current
environment.

`newline`

`(newline)`

Prints a new line.

`print`

`(print <val>)`

Prints the Scheme representation of `val`

. Unlike `display`

, this will include
the outer quotes on a Scheme string and will print a new line.

## Type Checking

`atom?`

`(atom? <arg>)`

Returns true if `arg`

is a boolean, number, symbol, string, or nil;
false otherwise.

`boolean?`

`(boolean? <arg>)`

Returns true if `arg`

is a boolean; false otherwise.

`integer?`

`(integer? <arg>)`

Returns true if `arg`

is a integer; false otherwise.

`list?`

`(list? <arg>)`

Returns true if `arg`

is a well-formed list; false otherwise.
If the list has a cycle, this may cause an error or infinite loop.

```
scm> (list? '(1 2 3))
True
scm> (list? '(1 2 . 3))
False
```

`number?`

`(number? <arg>)`

Returns true if `arg`

is a number; false otherwise.

`null?`

`(null? <arg>)`

Returns true if `arg`

is `nil`

(the empty list); false otherwise.

`pair?`

`(pair? <arg>)`

Returns true if `arg`

is a pair; false otherwise.

`procedure?`

`(procedure? <arg>)`

Returns true if `arg`

is a procedure; false otherwise.

`promise?`

`(promise? <arg>)`

Returns true if `arg`

is a promise; false otherwise.

`string?`

`(string? <arg>)`

Returns true if `arg`

is a string; false otherwise.

`symbol?`

`(symbol? <arg>)`

Returns true if `arg`

is a symbol; false otherwise.

## Pair and List Manipulation

`append`

`(append [lst] ...)`

Returns the result of appending the items of all `lst`

s in order into a single
well-formed list. Returns `nil`

if no `lst`

s. All `lst`

except for the last
must be well-formed lists. If the last `lst`

is not, it will be be added to the
end of a now dotted list (or just returned if it is the only `lst`

).

```
scm> (append '(1 2 3) '(4 5 6))
(1 2 3 4 5 6)
scm> (append)
()
scm> (append '(1 2 3) 4)
(1 2 3 . 4)
scm> (append '(1 2 3) '(4 . 5))
(1 2 3 4 . 5)
```

`car`

`(car <pair>)`

Returns the `car`

of `pair`

. Errors if `pair`

is not a pair.

`cdr`

`(cdr <pair>)`

Returns the `cdr`

of `pair`

. Errors if `pair`

is not a pair.

`cons`

`(cons <first> <rest>)`

Returns a new pair with `first`

as the `car`

and `rest`

as the `cdr`

`length`

`(length <arg>)`

Returns the length of `arg`

. If `arg`

is not a well-formed list, this
will cause an error.

`list`

`(list <item> ...)`

Returns a well-formed list with the `item`

s in order as its elements.

`map`

`(map <proc> <lst>)`

Returns a well-formed list constructed by calling `proc`

(a one-argument
procedure) on each item in `lst`

(a well-formed list).

`filter`

`(filter <pred> <lst>)`

Returns a well-formed list consisting of only the elements of `lst`

(a
well-formed list) that return true when called on `pred`

(a one-argument
procedure).

`reduce`

`(reduce <combiner> <lst>)`

Returns the result of sequentially combining each element in `lst`

(a
well-formed list) using `combiner`

(a two-argument procedure). `reduce`

works
from left-to-right, with the existing combined value passed as the first
argument and the new value as the second argument. `lst`

must contain at least
one item.

### Mutation

`set-car!`

`(set-car! <pair> <value>)`

Sets the `car`

of `pair`

to `value`

. `pair`

must be a pair.

`set-cdr!`

`(set-cdr! <pair> <value>)`

Sets the `cdr`

of `pair`

to `value`

. `pair`

must be a pair.

## Arithmetic Operations

`+`

`(+ [num] ...)`

Returns the sum of all `num`

s. Returns 0 if there are none. If any `num`

is not
a number, this will error.

`-`

`(- <num> ...)`

If there is only one `num`

, return its negation. Otherwise, return the first
`num`

minus the sum of the remaining `num`

s. If any `num`

is not a number, this
will error.

`*`

`(* [num] ...)`

Returns the product of all `num`

s. Returns 1 if there are none. If any `num`

is
not a number, this will error.

`/`

`(/ <dividend> [divisor] ...)`

If there are no `divisor`

s, return 1 divided by `dividend`

. Otherwise, return
`dividend`

divided by the product of the `divisors`

. This built-in does true
division, not floor division. `dividend`

and all `divisor`

s must be numbers.

```
scm> (/ 4)
0.25
scm> (/ 7 2)
3.5
scm> (/ 16 2 2 2)
2
```

`abs`

`(abs <num>)`

Returns the absolute value of `num`

, which must be a number.

`expt`

`(expt <base> <power>)`

Returns the `base`

raised to the `power`

power. Both must be numbers.

`modulo`

`(modulo <a> <b>)`

Returns `a`

modulo `b`

. Both must be numbers.

```
scm> (modulo 7 3)
1
scm> (modulo -7 3)
2
```

`quotient`

`(quotient <dividend> <divisor>)`

Returns `dividend`

integer divided by `divisor`

. Both must be numbers.

```
scm> (quotient 7 3)
2
```

`remainder`

`(remainder <dividend> <divisor>)`

Returns the remainder that results when `dividend`

is integer divided by
`divisor`

. Both must be numbers. Differs from `modulo`

in behavior when
negative numbers are involved.

```
scm> (remainder 7 3)
1
scm> (remainder -7 3)
-1
```

### Additional Math Procedures

The Python-based interpreter adds the following additional procedures whose behavior exactly match the corresponding Python functions in the math module.

- acos
- acosh
- asin
- asinh
- atan
- atan2
- atanh
- ceil
- copysign
- cos
- cosh
- degrees
- floor
- log
- log10
- log1p
- log2
- radians
- sin
- sinh
- sqrt
- tan
- tanh
- trunc

## Boolean Operations

### General

`eq?`

`(eq? <a> <b>)`

If `a`

and `b`

are both numbers, booleans, symbols, or strings, return true if
they are equivalent; false otherwise.

Otherwise, return true if `a`

and `b`

both refer to the same object in memory;
false otherwise.

```
scm> (eq? '(1 2 3) '(1 2 3))
False
scm> (define x '(1 2 3))
scm> (eq? x x)
True
```

`equal?`

`(equal? <a> <b>)`

Returns true if `a`

and `b`

are equivalent. For two pairs, they are equivalent
if their `car`

s are equivalent and their `cdr`

s are equivalent.

```
scm> (equal? '(1 2 3) '(1 2 3))
True
```

`not`

`(not <arg>)`

Returns true if `arg`

is false-y or false if `arg`

is truthy.

### On Numbers

`=`

`(= <a> <b>)`

Returns true if `a`

equals `b`

. Both must be numbers.

`<`

`(< <a> <b>)`

Returns true if `a`

is less than `b`

. Both must be numbers.

`>`

`(> <a> <b>)`

Returns true if `a`

is greater than `b`

. Both must be numbers.

`<=`

`(<= <a> <b>)`

Returns true if `a`

is less than or equal to `b`

. Both must be numbers.

`>=`

`(>= <a> <b>)`

Returns true if `a`

is greater than or equal to `b`

. Both must be numbers.

`even?`

`(even? <num>)`

Returns true if `num`

is even. `num`

must be a number.

`odd?`

`(odd? <num>)`

Returns true if `num`

is odd. `num`

must be a number.

`zero?`

`(zero? <num>)`

Returns true if `num`

is zero. `num`

must be a number.

## Promises and Streams

`force`

`(force <promise>)`

Returns the evaluated result of `promise`

. If `promise`

has already been
forced, its expression will not be evaluated again. Instead, the result from
the previous evaluation will be returned. `promise`

must be a promise.

`cdr-stream`

`(cdr-stream <stream>)`

Shorthand for `(force (cdr <stream>))`

.

## Turtle Graphics

`backward`

`(backward <n>)`

Moves the turtle backward `n`

units in its current direction from its current
position.

*Aliases: back, bk*

`begin_fill`

`(begin_fill)`

Starts a sequence of moves that outline a shape to be filled.
Call `end_fill`

to complete the fill.

`bgcolor`

`(bgcolor <c>)`

Sets the background color of the turtle window to a color `c`

(same rules as
when calling `color`

).

`circle`

`(circle <r> [extent])`

Draws a circle of radius `r`

, centered `r`

units to the turtle's left.
If `extent`

exists, draw only the first `extent`

degrees of the circle.
If `r`

is positive, draw in the counterclockwise direction. Otherwise, draw
in the clockwise direction.

The web interpreter has trouble accurately drawing partial circles.

`clear`

`(clear)`

Clears the drawing, leaving the turtle unchanged.

`color`

`(color <c>)`

Sets the pen color to `c`

, which is a Scheme string such as "red" or "#ffc0c0".

The web interpreter also allows `c`

to be a symbol. Available named colors may
vary depending on the interpreter.

`end_fill`

`(end_fill)`

Fill in shape drawn since last call to `begin_fill`

.

`exitonclick`

`(exitonclick)`

Sets the turtle window to close when it is clicked. This has no effect on the
web interpreter. Call `(exit_turtle)`

or `(exitturtle)`

to close the turtle
canvas on the web.

`forward`

`(forward <n>)`

Moves the turtle forward `n`

units in its current direction from its current
position.

*Alias: fd*

`hideturtle`

`(hideturtle)`

Makes the turtle invisible.

This procedure has no effect on the web interpreter, as the turtle is always invisible.

*Alias: ht*

`left`

`(left <n>)`

Rotates the turtle's heading `n`

degrees counterclockwise.

*Alias: lt*

`pendown`

`(pendown)`

Lowers the pen so that the turtle starts drawing.

*Alias: pd*

`penup`

`(penup)`

Raises the pen so that the turtle does not draw.

*Alias: pu*

`pixel`

`(pixel <x> <y> <c>)`

Draws a box filled with pixels starting at (`x`

, `y`

) in color `c`

(same rules
as in `color`

). By default the box is one pixel, though this can be changed
with `pixelsize`

.

`pixelsize`

`(pixelsize <size>)`

Changes the size of the box drawn by `pixel`

to be `size`

x`size`

.

`rgb`

`(rgb <r> <g> <b>)`

Returns a color string formed from `r`

, `g`

, and `b`

values between 0 and 1.

`right`

`(right <n>)`

Rotates the turtle's heading `n`

degrees clockwise.

*Alias: rt*

`screen_width`

`(screen_width)`

Returns the width of the turtle screen in pixels of the current size.

`screen_height`

`(screen_height)`

Returns the height of the turtle screen in pixels of the current size.

`setheading`

`(setheading <h>)`

Sets the turtle's heading `h`

degrees clockwise from the north.

*Alias: seth*

`setposition`

`(setposition <x> <y>)`

Moves the turtle to position (`x`

, `y`

) without changing its heading.

*Aliases: setpos, goto*

`showturtle`

`(showturtle)`

Makes the turtle visible.

This procedure has no effect on the web interpreter, as the turtle is always invisible.

*Alias: st*

`speed`

`(speed <s>)`

Sets the turtle's animation speed to some value between 0 and 10 with 0 indicating no animation and 1-10 indicating faster and faster movement.

This has no effect on the web interpreter, as everything is drawn immediately.

## Additional Reading

- Scheme Specification - the core specification of 61A Scheme
- R5RS Specification - the full Scheme specificaton that 61A Scheme most closely resembles.