Scheme Programmer's Manual

NAME

begin - wrapper for multiple expressions

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

SYNOPSIS

(begin expression or definition ...)
(begin expression expression ...)

DESCRIPTION

The begin keyword has different roles, depending on its context:

It may appear as a form in a body, library body, or top-level body, or directly nested in a begin form that appears in a body. In this case, the begin form must have the shape specified in the first synopsis line. This use of begin acts as a splicing form[em]the forms inside the body are spliced into the surrounding body, as if the begin wrapper were not actually present. A begin form in a body or library body must be non-empty if it appears after the first expression within the body.

It may appear as an ordinary expression and must have the shape specified in the second synopsis line. In this case, the expressions are evaluated sequentially from left to right, and the values of the last expression are returned. This expression type is used to sequence side effects such as assignments or input and output.

In R7RS a third form of begin appears in define-library, where it is used to begin the body of the library.

RETURN VALUES

The values of the last expression are returned.

For the splicing form the rules of wherever the splice appears instead apply.

EXAMPLES

;; This example is poor style but demonstrates the ordering ;; provided by "begin". (define x 0) (begin (set! x 5)
       (+ x 1))      => 6 ;; If "begin" did not guarantee the evaluation order then the ;; above might have evaluated to 1.

(begin (display "4 plus 1 equals ")
       (display (+ 4 1)))
     ; prints 4 plus 1 equals 5

APPLICATION USAGE

The splicing form of begin does not usually appear in code written by programmers.

The sequencing form is sometimes used in conditional expressions, which is a matter of personal style. Others prefer to use cond, when, or unless, which make begin unnecessary.

In R7RS define-library the begin form is often not used in favor of using include instead.

RATIONALE

R7RS
This form is commonly used in the output of macros which need to generate multiple definitions and splice them into the context in which they are expanded.

COMPATIBILITY

The splicing form of begin does not appear in R4RS and IEEE Scheme. The sequencing form enjoys wide compatibility among Lisp dialects, but outside of Scheme it can be named something else (progn in Common Lisp and do in Clojure).

R7RS clarifies that the splicing form may appear in the REPL.

ERRORS

This form can raise exceptions with the following condition types:
&syntax (R6RS)
Raised if the splicing form is used outside of a body or as a consequence when splicing results in an invalid body. Also raised if the keyword is misused.
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

SEE ALSO

cond(3), unless(3), when(3)

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at

Index

NAME
LIBRARY
SYNOPSIS
DESCRIPTION
RETURN VALUES
EXAMPLES
APPLICATION USAGE
RATIONALE
COMPATIBILITY
ERRORS
SEE ALSO
STANDARDS
AUTHORS
Return to Main Contents