suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refine compiler/zo-parse docs

Browse Source 
svn: r12948
This commit is contained in:
Matthew Flatt 2008-12-28 19:21:15 +00:00
parent 7aec6b8761
commit 836e108401
1 changed files with 66 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
collects/scribblings/mzc/zo-parse.scrbl
View File

@ -24,14 +24,14 @@ subject to frequent changes across PLT Scheme versons.}
@defstruct+[compilation-top ([max-let-depth exact-nonnegative-integer?] @defstruct+[compilation-top ([max-let-depth exact-nonnegative-integer?]
[prefix prefix?] [prefix prefix?]
[code (or/c form? any/c)])]{ [code (or/c form? indirect? any/c)])]{
Wraps compiled code. The @scheme[max-let-depth] field indicates the Wraps compiled code. The @scheme[max-let-depth] field indicates the
maximum stack depth that @scheme[code] creates (not counting the maximum stack depth that @scheme[code] creates (not counting the
@scheme[prefix] array). The @scheme[prefix] field contains global @scheme[prefix] array). The @scheme[prefix] field describes top-level
variable, cross-module variable, and syntax-object literal variables, module-level variables, and quoted syntax-objects accessed
mappings. The @scheme[code] field contains executable code; it is by @scheme[code]. The @scheme[code] field contains executable code; it
normally a @scheme[form], but a literal value is represented as is normally a @scheme[form], but a literal value is represented as
itself.} itself.}
@ -39,32 +39,33 @@ itself.}
[toplevels (listof (or/c #f symbol? global-bucket? module-variable?))] [toplevels (listof (or/c #f symbol? global-bucket? module-variable?))]
[stxs (listof stx?)])]{ [stxs (listof stx?)])]{
Represents a closure ``prefix'' that is pushed onto the stack before Represents a ``prefix'' that is pushed onto the stack to initiate
evaluating a top-level sequence. The prefix is an array, where buckets evaluation. The prefix is an array, where buckets holding the values
holding the values for @scheme[toplevels] are first, then a bucket for for @scheme[toplevels] are first, then a bucket for another array if
another array if @scheme[stxs] is non-empty, then @scheme[num-lifts] @scheme[stxs] is non-empty, then @scheme[num-lifts] extra buckets for
extra buckets for lifted local procedures. lifted local procedures.
In @scheme[toplevels]: In @scheme[toplevels], each element is one of the following:
@itemize[ @itemize[
@item{@scheme[#f] indicates a dummy variable that is used to access @item{a @scheme[#f], which indicates a dummy variable that is used to
the enclosing module/namespace at run time} access the enclosing module/namespace at run time;}
@item{a symbol is a reference to a variable defined in the enclosing @item{a symbol, which is a reference to a variable defined in the
module} enclosing module;}
@item{a @scheme[global-bucket] is a top-level variable, and it @item{a @scheme[global-bucket], which is a top-level variable
appears only outside of modules} (appears only outside of modules); or}
@item{a @scheme[module-variable] indicates a variable imported from @item{a @scheme[module-variable], which indicates a variable imported
another module} from another module.}
] ]
The variable buckets and syntax objects recorded by a prefix are The variable buckets and syntax objects that are recorded in a prefix
accessed by @scheme[toplevel] and @scheme[topsyntax] expression forms.} are accessed by @scheme[toplevel] and @scheme[topsyntax] expression
forms.}
@defstruct+[global-bucket ([name symbol?])]{ @defstruct+[global-bucket ([name symbol?])]{
@ -79,9 +80,9 @@ Represents a top-level variable, and used only in a @scheme[prefix].}
Represents a top-level variable, and used only in a @scheme[prefix]. Represents a top-level variable, and used only in a @scheme[prefix].
The @scheme[pos] may record the variable's offset within its module, The @scheme[pos] may record the variable's offset within its module,
or it can be @scheme[-1] if the variable is always accessed by name. or it can be @scheme[-1] if the variable is always located by name.
The @scheme[phase] indicates the phase level of the definition within The @scheme[phase] indicates the phase level of the definition within
it module.} its module.}
@defstruct+[stx ([encoded wrapped?])]{ @defstruct+[stx ([encoded wrapped?])]{
@ -94,13 +95,16 @@ Wraps a syntax object in a @scheme[prefix].}
@defstruct+[form ()]{ @defstruct+[form ()]{
A supertype for all forms that can appear in compiled code, except for A supertype for all forms that can appear in compiled code (including
literals that are represented as themselves.} @scheme[expr]s), except for literals that are represented as
themselves and @scheme[indirect] structures to create cycles.}
@defstruct+[(def-values form) ([ids (listof toplevel?)] @defstruct+[(def-values form) ([ids (listof toplevel?)]
[rhs (or/c expr? seq? indirect? any/c)])]{ [rhs (or/c expr? seq? indirect? any/c)])]{
Represents a @scheme[define-values] form. Represents a @scheme[define-values] form. Each element of @scheme[ids]
will reference via the prefix either a top-level variable or a local
module variable.
After @scheme[rhs] is evaluated, the stack is restored to its depth After @scheme[rhs] is evaluated, the stack is restored to its depth
from before evaluating @scheme[rhs].} from before evaluating @scheme[rhs].}
@ -120,7 +124,9 @@ Represents a @scheme[define-syntaxes] or
@scheme[define-values-for-syntax] form. The @scheme[rhs] expression @scheme[define-values-for-syntax] form. The @scheme[rhs] expression
has its own @scheme[prefix], which is pushed before evaluating has its own @scheme[prefix], which is pushed before evaluating
@scheme[rhs]; the stack is restored after obtaining the result @scheme[rhs]; the stack is restored after obtaining the result
values.} values. The @scheme[max-let-depth] field indicates the maximum size of
the stack that will be created by @scheme[rhs] (not counting
@scheme[prefix]).}
@defstruct+[(req form) ([reqs (listof module-path?)] @defstruct+[(req form) ([reqs (listof module-path?)]
[dummy toplevel?])]{ [dummy toplevel?])]{
@ -134,8 +140,9 @@ to the top-level namespace.}
[self-modidx module-path-index?] [self-modidx module-path-index?]
[prefix prefix?] [prefix prefix?]
[provides (listof symbol?)] [provides (listof symbol?)]
[requires (listof (cons/c (or/c exact-integer? #f) (listof module-path-index?)))] [requires (listof (cons/c (or/c exact-integer? #f)
[body (listof (or/c form? any/c))] (listof module-path-index?)))]
[body (listof (or/c form? indirect? any/c))]
[syntax-body (listof (or/c def-syntaxes? def-for-syntax?))] [syntax-body (listof (or/c def-syntaxes? def-for-syntax?))]
[max-let-depth exact-nonnegative-integer?])]{ [max-let-depth exact-nonnegative-integer?])]{
@ -145,10 +152,13 @@ declaration itself (and each @scheme[syntax-body] has its own
prefix). The @scheme[body] field contains the module's run-time code, prefix). The @scheme[body] field contains the module's run-time code,
and @scheme[syntax-body] contains the module's compile-time code. The and @scheme[syntax-body] contains the module's compile-time code. The
@scheme[max-let-depth] field indicates the maximum stack depth created @scheme[max-let-depth] field indicates the maximum stack depth created
by @scheme[body] forms (not counting the @scheme[prefix] array).} by @scheme[body] forms (not counting the @scheme[prefix] array).
After each form in @scheme[body] is evaluated, the stack is restored
to its depth from before evaluating the form.}
@defstruct+[(seq form) ([forms (listof (or/c form? any/c))])]{ @defstruct+[(seq form) ([forms (listof (or/c form? indirect? any/c))])]{
Represents a @scheme[begin] form, either as an expression or at the Represents a @scheme[begin] form, either as an expression or at the
top level (though the latter is more commonly a @scheme[splice] form). top level (though the latter is more commonly a @scheme[splice] form).
@ -159,7 +169,7 @@ After each form in @scheme[forms] is evaluated, the stack is restored
to its depth from before evaluating the form.} to its depth from before evaluating the form.}
@defstruct+[(splice form) ([forms (listof (or/c form? any/c))])]{ @defstruct+[(splice form) ([forms (listof (or/c form? indirect? any/c))])]{
Represents a top-level @scheme[begin] form where each evaluation is Represents a top-level @scheme[begin] form where each evaluation is
wrapped with a continuation prompt. wrapped with a continuation prompt.
@ -174,8 +184,9 @@ to its depth from before evaluating the form.}
@defstruct+[(expr form) ()]{ @defstruct+[(expr form) ()]{
A supertype for all expression forms that can appear in compiled code, A supertype for all expression forms that can appear in compiled code,
except for literals that are represented as themselves, and except for except for literals that are represented as themselves,
@scheme[seq] (which can appear as an expression as long as it contains @scheme[indirect] structures to create cycles, and some @scheme[seq]
structures (which can appear as an expression as long as it contains
only other things that can be expressions).} only other things that can be expressions).}
@ -189,7 +200,7 @@ only other things that can be expressions).}
Represents a @scheme[lambda] form. The @scheme[name] field is a name Represents a @scheme[lambda] form. The @scheme[name] field is a name
for debugging purposes. The @scheme[num-params] field indicates the for debugging purposes. The @scheme[num-params] field indicates the
number of argumets accepted by the procedure, not counting a rest number of arguments accepted by the procedure, not counting a rest
argument; the @scheme[rest?] field indicates whether extra arguments argument; the @scheme[rest?] field indicates whether extra arguments
are accepted and collected into a ``rest'' variable. The are accepted and collected into a ``rest'' variable. The
@scheme[closure-map] field is a vector of stack positions that are @scheme[closure-map] field is a vector of stack positions that are
@ -278,19 +289,20 @@ each shell's closure using the created shells, and then evaluates
@defstruct+[(boxenv expr) ([pos nonnegative-exact-integer?] @defstruct+[(boxenv expr) ([pos nonnegative-exact-integer?]
[body (or/c expr? seq? indirect? any/c)])]{ [body (or/c expr? seq? indirect? any/c)])]{
Sets the stack slot @scheme[pos] elements deep into the stack to a new Skips @scheme[pos] elements of the stack, setting the slot afterward
box containing the slot's old value. This form appears when a to a new box containing the slot's old value, and then runs
@scheme[lambda] argument is mutated using @scheme[set!] within its @scheme[body]. This form appears when a @scheme[lambda] argument is
body; calling the function initially pushes the value directly on the mutated using @scheme[set!] within its body; calling the function
stack, and this form boxes the value so that it can be mutated later.} initially pushes the value directly on the stack, and this form boxes
the value so that it can be mutated later.}
@defstruct+[(localref expr) ([unbox? boolean?] @defstruct+[(localref expr) ([unbox? boolean?]
[pos nonnegative-exact-integer?] [pos nonnegative-exact-integer?]
[clear? boolean?])]{ [clear? boolean?])]{
Represents a local-variable reference; access the value in the stack Represents a local-variable reference; it accesses the value in the
slot skipping the first @scheme[pos] slots. If @scheme[unbox?] is stack slot after the first @scheme[pos] slots. If @scheme[unbox?] is
@scheme[#t], the stack slot contains a box, and a value is extracted @scheme[#t], the stack slot contains a box, and a value is extracted
from the box. If @scheme[clear?] is @scheme[#t], then after the value from the box. If @scheme[clear?] is @scheme[#t], then after the value
is obtained, the stack slot is cleared (to avoid retaining a reference is obtained, the stack slot is cleared (to avoid retaining a reference
@ -305,10 +317,14 @@ that can prevent reclamation of the value as garbage).}
Represents a reference to a top-level or imported variable via the Represents a reference to a top-level or imported variable via the
@scheme[prefix] array. The @scheme[depth] field indicates the number @scheme[prefix] array. The @scheme[depth] field indicates the number
of stack slots to skip to reach the prefix array, and @scheme[pos] is of stack slots to skip to reach the prefix array, and @scheme[pos] is
the offset into the array. If @scheme[const?] is @scheme[#t], then the the offset into the array.
variable will definitely have a value and the value stays constant. If
@scheme[ready?] is @scheme[#t], then the variable will definitely have If @scheme[const?] is @scheme[#t], then the variable definitely will
a value (but the value might change in the future).} be defined, and its value stays constant. If @scheme[ready?] is
@scheme[#t], then the variable definitely will be defined (but its
value might change in the future). If @scheme[const?] and
@scheme[ready?] are both @scheme[#f], then a check is needed to
determine whether the variable is defined.}
@defstruct+[(topsyntax expr) ([depth nonnegative-exact-integer?] @defstruct+[(topsyntax expr) ([depth nonnegative-exact-integer?]
@ -370,8 +386,8 @@ Represents a @scheme[#%variable-reference] form.}
[undef-ok? boolean?])]{ [undef-ok? boolean?])]{
Represents a @scheme[set!] expression that assigns to a top-level or Represents a @scheme[set!] expression that assigns to a top-level or
module-level variable. (Assignments to local variables are converted module-level variable. (Assignments to local variables are represented
to @scheme[install-value] expression.) by @scheme[install-value] expressions.)
After @scheme[rhs] is evaluated, the stack is restored to its depth After @scheme[rhs] is evaluated, the stack is restored to its depth
from before evaluating @scheme[rhs].} from before evaluating @scheme[rhs].}
@ -398,12 +414,12 @@ kernel.}
Represents a syntax object, where @scheme[wraps] contain the lexical Represents a syntax object, where @scheme[wraps] contain the lexical
information and @scheme[certs] is certificate information. When the information and @scheme[certs] is certificate information. When the
@scheme[datum] part it itself compound, its pieces are wrapped, too.} @scheme[datum] part is itself compound, its pieces are wrapped, too.}
@defstruct+[wrap ()]{ @defstruct+[wrap ()]{
A supertype for lexical information elements.} A supertype for lexical-information elements.}
@defstruct+[(lexical-rename wrap) ([alist (listof (cons/c identifier? identifier?))])]{ @defstruct+[(lexical-rename wrap) ([alist (listof (cons/c identifier? identifier?))])]{