Scheme Primitives Reference

This document serves as a reference for the primitive procedures in the Scheme project and staff Scheme interpreter. Additional primitives only found in the web interpreter are documented here, though the page may be out of date.

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

The web interpreter will concatenate multiple arguments into a single output.

error
(error <msg>)

Raises an SchemeError with msg as it's message. If there is no msg, the error's message will be empty.

The web interpreter will concatentate multiple arguments into a single message.

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 will refresh the page but not actually close it.

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 behavior for this primitive is described in the web primitives reference.

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, 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 lsts in order into a single well-formed list. Returns nil if no lsts. 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 items 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.

Arithmetic Operations

+
(+ [num] ...)

Returns the sum of all nums. 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 nums. If any num is not a number, this will error.

*
(* [num] ...)

Returns the product of all nums. Returns 1 if there are none. If any num is not a number, this will error.

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

If there are no divisors, return 1 divided by dividend. Otherwise, return dividend divided by the product of the divisors. This primitive does true division, not floor division. dividend and all divisors 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 floor divided by divisor. Both must be numbers.

scm> (quotient 7 3)
2
remainder
(remainder <dividend> <divisor>)

Returns the remainder that results when dividend is floor 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 Primitives

The student and staff interpreters add 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 cars are equivalent and their cdrs 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.

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

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

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.

Mutation (Staff Interpreter Only)

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.

Additional Reading

  • Scheme Specification - the core specification of 61A Scheme
  • R5RS Specification - the full Scheme specificaton that 61A Scheme most closely resembles.
  • Web Interpreter Help - a broad overview of the features of the web interpreter
  • Web Primitives - covers the primitive procedures at the web level but not the staff or student levels
  • JS Interop - a detailed description of the web interpreter's support for JavaScript interop.