# Scheme Built-In Procedure Reference

Last Updated: Spring 2020

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
```

On macros, this has the effect of calling the macro without the initial quoting
or final evaluation. Thus, `apply`

treats a macro as if it were a function.

`display`

`(display <val>)`

Prints `val`

. If `val`

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

A newline will not be automatically included.

`displayln`

`(displayln <val>)`

Like `display`

, but includes a newline at the end.

`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 does not currently support `load`

.

`newline`

`(newline)`

Prints a newline.

`print`

`(print <val>...)`

Prints the Scheme representation of each `val`

, separated by spaces. Unlike `display`

, this will include
the outer quotes on a Scheme string, and a newline.

## 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 (i.e., it doesn't contain
a stream); false otherwise. If the list has a cycle, this may cause an
error or infinite loop.

```
scm> (list? '(1 2 3))
#t
scm> (list? (cons-stream 1 nil))
#f
```

`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
list. Returns `nil`

if no `lst`

s.

```
scm> (append '(1 2 3) '(4 5 6))
(1 2 3 4 5 6)
scm> (append)
()
scm> (append '(1 2 3) '(a b c) '(foo bar baz))
(1 2 3 a b c foo bar baz)
scm> (append '(1 2 3) 4)
Error
```

`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 list, this
will cause an error.

`list`

`(list <item> ...)`

Returns a list with the `item`

s in order as its elements.

`map`

`(map <proc> <lst>)`

Returns a list constructed by calling `proc`

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

.

`filter`

`(filter <pred> <lst>)`

Returns a list consisting of only the elements of `lst`

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`

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

`eqv?`

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

If `a`

and `b`

are both numbers, booleans, or symbols, 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> (eqv? '(1 2 3) '(1 2 3))
#f
scm> (define x '(1 2 3))
scm> (eqv? x x)
#t
```

`eq?`

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

If `a`

and `b`

are both booleans or symbols, 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.

This function is essentially equivalent to Python's `is`

operator. Generally,
we will not be using `eq?`

in this course, since `eqv?`

is usually the
operator we want.

```
scm> (eq? '(1 2 3) '(1 2 3))
#f
scm> (define x '(1 2 3))
scm> (eq? x x)
#t
>scm ; (eq? 1000000 1000000) ; #t or #f: not well-defined.
```

`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))
#t
```

`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.

`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".

`end_fill`

`(end_fill)`

Fill in shape drawn since last call to `begin_fill`

.

`exitonclick`

`(exitonclick)`

In pillow-turtle mode, this exits the current program. In tk-turtle mode, it exits the current program when the window is clicked. In the web interpreter, it does nothing.

In the local interpreter, you can pass `--turtle-save-path PATH`

to also effectively call
`(save-to-file PATH)`

right before exit.

`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.

*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*

`save-to-file`

`(save-to-file <f>)`

Saves the current canvas to a file specified by `f`

, with an added file extension.

For example, `(save-to-file "hi")`

- saves to
`./hi.png`

in the local interpreter using the pillow-turtle - saves to
`./hi.ps`

in the local interpreter using the tk-turtle (default) - has no effect in the web interpreter

`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.

*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.

On the local interpreter in tk-turtle mode, this changes the animation speed. This feature has no effect on the web interpreter and on the gui-less pillow-turtle mode.

## Additional Reading

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