begin(7scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💖 begin(7scm) — your lil' wrapper for multiple expressions 💖

okay so real talk, this page is from the Scheme Programmer's Manual and it's all about begin, which is genuinely one of those keywords that does like three different jobs depending on where you drop it. main character energy fr.

✨ NAME ✨

begin — wrapper for multiple expressions

🎀 LIBRARY 🎀

like, import it from whichever flavor you're on bestie:

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

🦋 SYNOPSIS 🦋

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

two shapes, one keyword, no cap.

🌸 DESCRIPTION 🌸

so begin is like that one friend who has a different personality in every group chat. the keyword's role depends on its context:

the splicing era 💅

it can show up as a form in a body, a library body, or a top-level body, or directly nested inside a begin form that itself appears in a body. in that case the begin form has to have the shape from the first synopsis line.

and this use is a splicing form — the forms inside the body get spliced into the surrounding body, as if the begin wrapper literally was never there. iconic behavior honestly.

⚠️ heads up: a begin form in a body or library body must be non-empty if it appears after the first expression within the body.

the ordinary expression era ✨

it can also appear as an ordinary expression, and then it has to have the shape from the second synopsis line. in this case the expressions get evaluated sequentially, left to right, and the values of the last expression are returned. this is the sequencing era — you use it for side effects like assignments or input and output.

the R7RS plot twist 😭

in R7RS a third form of begin appears in define-library, where it's used to begin the body of the library. yeah. three eras. we love a versatile queen.

🫶 RETURN VALUES 🫶

the values of the last expression are returned, periodt.

but for the splicing form, the rules of wherever the splice appears instead apply. (yes, it defers. it's giving "I'm not the main character here".)

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

like, if begin didn't guarantee ordering that whole thing could've been 1 and we'd all be in shambles 😭

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

it prints 4 plus 1 equals 5. slay.

💜 APPLICATION USAGE 💜

  • the splicing form of begin doesn't usually appear in code written by programmers. lowkey it's a macro-output thing.
  • the sequencing form is sometimes used in conditional expressions — that's a personal style thing. others prefer to use cond, when, or unless, which make begin unnecessary. both are valid, it's just vibe check.
  • 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're expanded. it's the macro workhorse, fr fr.

🌈 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. iykyk.

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. (yes, catastrophically. no I'm not being dramatic, that's literally the word.)

🍓 SEE ALSO 🍓

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

👑 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 https://github.com/schemedoc/manpages/.

k bye bestie 🎀 this page is begin(7scm), dated 2020-05-10 — go splice something cute ✨💖
📦 where this page comes from