Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: revamp explanation of implicit begin #4146

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
38 changes: 23 additions & 15 deletions pkgs/racket-doc/scribblings/guide/begin.scrbl
Original file line number Diff line number Diff line change
Expand Up @@ -34,24 +34,16 @@ tail position with respect to the @racket[begin] form.
(print-triangle 4)
]

Many forms, such as @racket[lambda] or @racket[cond] support a
sequence of expressions even without a @racket[begin]. Such positions are
sometimes said to have an @deftech{implicit begin}.
The @racket[begin] form is special at the top level, at module level,
or as a @racket[_body] (e.g. of @racket[let] or @racket[lambda];
see @tech{internal definition} for more details).
sorawee marked this conversation as resolved.
Show resolved Hide resolved
Such @racket[begin] form has a slightly different grammar:
sorawee marked this conversation as resolved.
Show resolved Hide resolved

@defexamples[
(define (print-triangle height)
(cond
[(positive? height)
(display (make-string height #\*))
(newline)
(print-triangle (sub1 height))]))
(print-triangle 4)
]
@specform[(begin def-or-expr ...)]{}

The @racket[begin] form is special at the top level, at module level,
or as a @racket[body] after only internal definitions. In those
positions, instead of forming an expression, the content of
In those positions, instead of forming an expression, the content of
sorawee marked this conversation as resolved.
Show resolved Hide resolved
@racket[begin] is spliced into the surrounding context.
The content could contain definitions.

@defexamples[
(let ([curly 0])
Expand All @@ -64,6 +56,22 @@ positions, instead of forming an expression, the content of
This splicing behavior is mainly useful for macros, as we discuss
later in @secref["macros"].

The whole @racket[_body] sequence is sometimes said to have an @deftech{implicit begin}.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why sometimes? Probably best to always or never (at least in the documentation we control).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I'm not sure it's clear that the metavariable body here refers to internal-definition contexts, so maybe The whole @racket[_body] sequence of an internal-definition context?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One complication is that the Racket Guide doesn't really define what internal-definition context is, so I've been avoiding it. But perhaps we should define it, perhaps in the section "Internal Definitions".

The restriction of an @tech{implicit begin} follows the restriction of the @racket[_body] sequence:
the sequence should end with an expression.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An implicit begin is restricted in the same way as a @racket[_body]; it must end with an expression.

@defexamples[
(code:comment @#,t{Implicit @racket[begin]})
(let ()
(define num 1)
(add1 num))
(code:comment @#,t{Explicit @racket[begin]})
(let ()
(begin
(define num 1)
(add1 num)))
]

@;------------------------------------------------------------------------
@section{Effects After: @racket[begin0]}

Expand Down
4 changes: 2 additions & 2 deletions pkgs/racket-doc/scribblings/guide/define.scrbl
Original file line number Diff line number Diff line change
Expand Up @@ -194,10 +194,10 @@ equivalent to a @racket[define-values] form with a single @racket[_id].

When the grammar for a syntactic form specifies @racket[_body], then
the corresponding form can be either a definition or an expression.
A definition as a @racket[_body] is an @defterm{internal definition}.
A definition as a @racket[_body] is an @deftech{internal definition}.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"A definition in", I'd say.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you treating the metavariable body as the whole sequence? IIUC, elsewhere, the metavariable body is treated as a single form in the sequence (hence the usage of @racket[body]s in various places). So I think "a definition as a @racket[_body]" is correct already.


Expressions and internal definitions in a @racket[_body] sequence can
be mixed, as long as the last @racket[_body] is an expression.
be mixed, as long as the sequence ends with an expression.

For example, the syntax of @racket[lambda] is

Expand Down
9 changes: 5 additions & 4 deletions pkgs/racket-doc/scribblings/reference/syntax.scrbl
Original file line number Diff line number Diff line change
Expand Up @@ -2787,13 +2787,14 @@ For backward compatibility only; equivalent to @racket[syntax-local-introduce].
@defform*[[(begin form ...)
(begin expr ...+)]]{

The first form applies when @racket[begin] appears at the top level,
at module level, or in an internal-definition position (before any
expression in the internal-definition sequence). In that case, the
The first form applies when @racket[begin] appears at the @tech{top-level context},
sorawee marked this conversation as resolved.
Show resolved Hide resolved
at @tech{module context}, or in an @tech{internal-definition context}. In that case, the
@racket[begin] form is equivalent to splicing the @racket[form]s into
the enclosing context.
The @tech{internal-definition context} itself is said to have an
@deftech{implicit begin} of this first form.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"of the first form" is correct, but how about "The internal-definition context itself is treated as a begin containing definitions" or something more like that?


The second form applies for @racket[begin] in an expression position.
The second form applies for @racket[begin] in an @tech{expression context}.
In that case, the @racket[expr]s are evaluated in order, and the
results are ignored for all but the last @racket[expr]. The last
@racket[expr] is in tail position with respect to the @racket[begin]
Expand Down