.RKT File Format – Control and loops

Tail calls and recursion

A call in tail position (the last expression of a procedure body, of the branch of an if, cond or case, of and and or, and of when and unless) does not add to the stack, so a procedure that calls itself in tail position runs in constant space however long it loops. A named let is the usual spelling of such a loop:

(define (sum-to n)
  (let loop ([i 1] [total 0])
    (if (> i n)
        total
        (loop (add1 i) (+ total i)))))

The for family

(for (for-clause …) body-or-break … body) runs the body once for each combination of elements that the clauses produce. A clause [id seq-expr] walks one sequence; [(id …) seq-expr] binds the several values each element supplies ([(k v) (in-hash h)]). In for the clauses walk their sequences in parallel, stopping at the shortest one; for* nests them, so the later clauses run once for each earlier element.

A #:when, #:unless, #:do, #:break or #:final clause splits the clauses: the sequences before it are walked in parallel, and the ones after it nest inside. Each variant below collects the bodies' results in a different way; every one has a * form (for*/list).

(for ([x '(a b c)] [i (in-naturals 1)])      ; parallel
  (printf "~a: ~a\n" i x))

(for*/list ([x (in-range 3)] [y (in-range x)])  ; nested
  (cons x y))                                   ; => '((1 . 0) (2 . 0) (2 . 1))

(for/hash ([w '("a" "bb" "c")]) (values w (string-length w)))

(for/fold ([sum 0] #:result (* 2 sum)) ([x (in-list '(1 2 3))])
  (+ sum x))                                    ; => 12

(for/list ([x (in-range 10)] #:when (even? x) #:break (> x 6)) x)  ; => '(0 2 4 6)

Sequences

A sequence is anything a for clause can walk. A list, mutable list, vector, flvector, fxvector, string, byte string, hash table (it supplies two values, key and value), dictionary, set, stream, input port, non-negative integer n (like (in-range n)) and any value with the prop:sequence property are all sequences. A bare sequence in a clause works, but a specific constructor is faster and says what is expected:

The library racket/sequence has sequence-map, sequence-filter, sequence-fold, sequence-ref, sequence-length, sequence-append, sequence->list and more, and racket/stream has lazy streams (stream-cons, stream-first, stream-rest, stream-map, stream-filter, stream-take).

Multiple values

A procedure can return several values: (values 1 2). A context that expects one value raises an error if it gets another number. (let-values ([(a b) (values 1 2)]) …), (define-values (a b) …), (call-with-values thunk receiver), match-define with (values …) and for clauses like [(k v) …] receive them. (values) returns no value at all. Several built-in procedures return multiple values, such as quotient/remainder, split-at and partition.

Exceptions

An exception is any value passed to raise; usually it is a structure of type exn, made by error and the raise-… functions. (with-handlers ([predicate handler] …) body …+) runs the body; if it raises a value that a predicate accepts, the handler is called with it, after the body's dynamic extent has been left, and its result is the result of the whole form. with-handlers* calls the handler in tail position with respect to the form.

The structure types of the exceptions that Racket itself raises form this tree (each name is the type and the predicate adds ?):

(with-handlers ([exn:fail:contract:divide-by-zero?
                 (lambda (e) 'infinity)]
                [exn:fail? (lambda (e) (exn-message e))])
  (/ 1 0))                                  ; => 'infinity

(with-handlers ([symbol? values])           ; any value can be raised
  (raise 'oops))                            ; => 'oops

(dynamic-wind
  (lambda () (displayln "enter"))
  (lambda () (error "oops"))                ; the post thunk runs on the way out
  (lambda () (displayln "leave")))

When no handler takes an exception, the uncaught-exception handler prints the message through the error display handler and, in a module run by racket, the program ends. (error-display-handler), (error-escape-handler) and (uncaught-exception-handler) can be set to change that. (exn-message e) and (exn-continuation-marks e) read an exn.

Continuations and prompts

• (let/ec k body …) and (call/ec proc) (call-with-escape-continuation) give k, a procedure that jumps out of the body and returns its argument as the value of the form. It can be used only while the body runs, and it is cheap. It is how Racket programs return early: (let/ec return (for ([x xs]) (when (bad? x) (return x))) #f).
• (let/cc k body …) and call/cc capture the full continuation up to the nearest prompt; calling k later replaces the current continuation, up to that prompt, with the saved one. Racket distinguishes prompts (call-with-continuation-prompt, abort-current-continuation, make-continuation-prompt-tag), composable continuations (call-with-composable-continuation) and continuation barriers.
• racket/control adds prompt, control, shift, reset and relatives for delimited control.
• racket/generator makes generators on top of continuations: (generator () (yield 1) (yield 2)), called repeatedly to get 1, 2, then the finishing value.
• (with-continuation-mark key value body) and continuation-mark-set-first attach values to stack frames; parameters (below) are implemented with them.
• (dynamic-wind pre thunk post) runs pre and post every time control enters and leaves the thunk, by return, by exception or by continuation jump.

Promises and parameters

(delay expr) makes a promise that computes expr the first time (force p) is called; lazy and racket/promise's delay/name, delay/strict, delay/sync, delay/thread and delay/idle vary when and where it runs. #lang lazy makes every function call lazy.

A parameter is a procedure that holds a dynamically scoped value: (define current-indent (make-parameter 0)), read by (current-indent), changed for the extent of a body by (parameterize ([current-indent 2]) …), and set outright by (current-indent 3). Racket's own settings are parameters: current-output-port, current-directory, current-command-line-arguments, error-print-width, current-namespace, read-case-sensitive. Each thread starts with the parameter values of the thread that made it.

Not described

Known, not yet covered

• Reference: the full argument lists and the many other for variants, racket/generator and racket/control beyond the names given, the details of continuation barriers, the stack behaviour of with-handlers against call-with-exception-handler, and exn:break handling with break-enabled were not described. Parts of the Reference chapters on control, exceptions and for (sections read in part) are summarised.
• Reference: what a bare input port yields as a sequence (bytes or characters) is not stated; use in-port (which reads with read by default), in-input-port-bytes, in-input-port-chars or in-lines to be explicit.

See also

• Functions – procedures, arity and keyword arguments
• Concurrency – threads, places and futures
• Scheme: continuations and dynamic-wind – the Scheme view of continuations