12.9 Expanding Top-Level Forms

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 12 | Macros

12.1 | Pattern-Based Syntax Matching
12.2 | Syntax Object Content
12.3 | Syntax Object Bindings
12.4 | Syntax Transformers
12.5 | Syntax Parameters
12.6 | Local Binding with Splicing Body
12.7 | Syntax Object Properties
12.8 | Syntax Taints
12.9 | Expanding Top-Level Forms
12.10 | File Inclusion
12.11 | Syntax Utilities

► | 12.9 | Expanding Top-Level Forms

12.9.1 | Information on Expanded Modules

On this page:

expand
expand-syntax
expand-once
expand-syntax-once
expand-to-top-form
expand-syntax-to-top-form
12.9.1`` Information on Expanded Modules

top ← prev up next →

#### 12.9`` Expanding Top-Level Forms

> procedure (expand top-level-form) → syntax?
> top-level-form : any/c

Expands all non-primitive syntax in top-level-form, and returns a syntax object for the expanded form that contains only core forms, matching the grammar specified by Fully Expanded Programs.

Before top-level-form is expanded, its lexical context is enriched with namespace-syntax-introduce, just as for eval. Use syntax->datum to convert the returned syntax object into a printable datum.

Here’s an example of using expand on a module:

> (parameterize ([current-namespace (make-base-namespace)])
> (expand
> (datum->syntax
> #f
> '(module foo scheme
> (define a 3)
> (+ a 4)))))

Here’s an example of using expand on a non-top-level form:

> (define-namespace-anchor anchor)
> (parameterize ([current-namespace
> (namespace-anchor->namespace anchor)])
> (expand
> (datum->syntax
> #f
> '(delay (+ 1 2)))))

> procedure (expand-syntax stx) → syntax?
> stx : syntax?

Like (expand stx), except that the argument must be a syntax object, and its lexical context is not enriched before expansion.

> procedure (expand-once top-level-form) → syntax?
> top-level-form : any/c

Partially expands top-level-form and returns a syntax object for the partially-expanded expression. Due to limitations in the expansion mechanism, some context information may be lost. In particular, calling expand-once on the result may produce a result that is different from expansion via expand.

Before top-level-form is expanded, its lexical context is enriched with namespace-syntax-introduce, as for eval.

> procedure (expand-syntax-once stx) → syntax?
> stx : syntax?

Like (expand-once stx), except that the argument must be a syntax object, and its lexical context is not enriched before expansion.

> procedure (expand-to-top-form top-level-form) → syntax?
> top-level-form : any/c

Partially expands top-level-form to reveal the outermost syntactic form. This partial expansion is mainly useful for detecting top-level uses of begin. Unlike the result of expand-once, expanding the result of expand-to-top-form with expand produces the same result as using expand on the original syntax.

Before stx-or-sexpr is expanded, its lexical context is enriched with namespace-syntax-introduce, as for eval.

> procedure (expand-syntax-to-top-form stx) → syntax?
> stx : syntax?

Like (expand-to-top-form stx), except that the argument must be a syntax object, and its lexical context is not enriched before expansion.

##### 12.9.1`` Information on Expanded Modules

Information for an expanded module declaration is stored in a set of syntax properties (see Syntax Object Properties) attached to the syntax object:

- 'module-direct-requires — a list of module path indexes (or symbols) representing the modules explicitly imported into the module.

- 'module-direct-for-syntax-requires — a list of module path indexes (or symbols) representing the modules explicitly for-syntax imported into the module.

- 'module-direct-for-template-requires — a list of module path indexes (or symbols) representing the modules explicitly for-template imported into the module.

- 'module-direct-for-meta-requires — a list of lists: each list is an integer or #f representing a phase level followed by a list of module path indexes (or symbols) representing the modules explicitly imported into the module at the corresponding phase.

  Added in version 6.4.0.1 of package base.

- 'module-variable-provides — a list of provided items, where each item is one of the following:

  - symbol — represents a locally defined variable that is provided with its defined name.

  - (cons provided-sym defined-sym) — represents a locally defined variable that is provided with renaming; the first symbol is the exported name, and the second symbol is the defined name.

  - (list* module-path-index provided-sym defined-sym) — represents a re-exported and possibly re-named variable from the specified module; module-path-index is either a module path index or symbol (see Compiled Modules and References), indicating the source module for the binding. The provided-sym is the external name for the re-export, and defined-sym is the originally defined name in the module specified by module-path-index.

- 'module-syntax-provides — like 'module-variable-provides, but for syntax exports instead of variable exports.

- 'module-indirect-provides — a list of symbols for variables that are defined in the module but not exported; they may be exported indirectly through macro expansions. Definitions of macro-generated identifiers create uninterned symbols in this list. The order of identifiers in the list corresponds to an order for access from bytecode.

- 'module-indirect-for-meta-provides — similar to 'module-indirect-provides: an association list from a phase level to a list of symbols for variables that are defined in the module at phases higher than 0 and not exported.

  Added in version 6.5.0.5 of package base.

- 'module-body-context — a syntax object whose lexical information corresponds to the inside of the module, so it includes the expansion’s outside-edge scope and its inside-edge scope; that is, the syntax object simulates an identifier that is present in the original module body and inaccessible to manipulation by any macro, so that its lexical information includes bindings for the module’s imports and definitions.

  Added in version 6.4.0.1 of package base.

- 'module-body-inside-context — a syntax object whose lexical information corresponds to an identifier that starts with no lexical context and is moved into the macro, so that it includes only the expansions’s inside-edge scope.

  Added in version 6.4.0.1 of package base.

- 'module-body-context-simple? — a boolean, where #t indicates that the bindings of the module’s body (as recorded in the lexical information of the value of the 'module-body-inside-context property) can be directly reconstructed from the values of 'module-direct-requires, 'module-direct-for-syntax-requires, 'module-direct-for-template-requires, and 'module-direct-for-meta-requires.

  Added in version 6.4.0.1 of package base.

top ← prev up next →