7d145e37a8
and functionality improvements (including support for measuring
coverage), primitive argument-checking fixes, and object-file changes
resulting in reduced load times (and some backward incompatibility):
- annotations are now preserved in object files for debug
only, for profiling only, for both, or not at all, depending
on the settings of generate-inspector-information and
compile-profile. in particular, when inspector information
is not enabled but profiling is, source information does
not leak into error messages and inspector output, though it is
still available via the profile tools. The mechanics of this
involved repurposing the fasl a? parameter to hold an annotation
flags value when it is not #f and remaking annotations with
new flags if necessary before emitting them.
compile.ss, fasl.ss, misc.ms
- altered a number of mats to produce correct results even
when the 's' directory is profiled.
misc.ms, cp0.ms, record.ms
- profile-release-counters is now generation-friendly; that is,
it doesn't look for dropped code objects in generations that have
not been collected since the last call to profile-release-counters.
also, it no longer allocates memory when it releases counters.
pdhtml.ss,
gc.c, gcwrapper.c, globals.h, prim5.c
- removed unused entry points S_ifile, S_ofile, and S_iofile
alloc.c, externs.h
- mats that test loading profile info into the compiler's database
to guide optimization now weed out preexisting entries, in case
the 's' directory is profiled.
4.ms, mat.ss, misc.ms, primvars.ms
- counters for dropped code objects are now released at the start
of each mat group.
mat.ss
- replaced ehc (enable-heap-check) option with hci (heap-check-interval)
option that allows heap checks to be performed periodically rather
than on each collection. hci=0 is equivalent to ehc=f (disabling
heap checks) and hci=1 is equivalent to ehc=t (enabling heap
checks every collection), while hci=100 enables heap checks only
every 100th collection. allx and bullyx mats use this feature
to reduce heap-checking overhead to a more reasonable level. this
is particularly important when the 's' directory is profiled,
since the amount of static memory to be checked is greatly increased
due to the counters.
mats/Mf-base, mat.ss, primvars.ms
- added a mat that calls #%show-allocation, which was otherwise not
being tested.
misc.ms
- removed a broken primvars mat and updated two others. in each case,
the mat was looking for information about primitives in the wrong
(i.e., old) place and silently succeeding when it didn't find any
primitives to tests. the revised mats (along with a few others) now
check to make sure at least one identifier has the information they
look for. the removed mat was checking for library information that
is now compiled in, so the mat is now unnecessary. the others were
(not) doing argument-error checks. fixing these turned up a handful of
problems that have also been fixed: a couple of unbound variables in the
mat driver, two broken primdata declarations, a tardy argument check
by profile-load-data, and a bug in char-ready?, which was requiring
an argument rather than defaulting it to the current input port.
primdata.ss, pdhtml.ss, io.ms,
primdvars.ms, 4.ms, 6.ms, misc.ms, patch*
- added initial support for recording coverage information. when the
new parameter generate-covin-files is set, the compiler generates
.covin files containing the universe of all source objects for which
profile forms are present in the expander output. when profiling
and generation of covin files are enabled in the 's' directory, the
mats optionally generate .covout files for each mat file giving
the subset of the universe covered by the mat file, along with an
all.covout in each mat output directory aggregating the coverage
for the directory and another all.covout in the top-level mat
directory aggregating the coverage for all directories.
back.ss, compile.ss, cprep.ss, primdata.ss, s/Mf-base,
mat.ss, mats/Mf-base, mats/primvars.ms
- support for generating covout files is now built in. with-coverage-output
gathers and dumps coverage information, and aggregate-coverage-output
combines (aggregates) covout files.
pdhtml.ss, primdata.ss, compile.ss,
mat.ss, mats/Mf-base, primvars.ms
- profile-clear now adjusts active coverage trackers to avoid losing
coverage information.
pdhtml.ss,
prim5.c
- nested with-coverage calls are now supported.
pdhtml.ss
- switched to a more compact representation for covin and covout files;
reduces disk space (compressed or not) by about a factor of four
and read time by about a factor of two with no increase in write time.
primdata.ss, pdhtml.ss, cprep.ss, compile.ss,
mat.ss, mats/Mf-base
- added support for determining coverage for an entire run, including
coverage for expressions hit during boot time. 'all' mats now produce
run.covout files in each output directory, and 'allx' mats produce
an aggregate run.covout file in the mat directory.
pdhtml.ss,
mat.ss, mats/Mf-base
- profile-release-counters now adjusts active coverage trackers to
account for the counters that have been released.
pdhtml.ss,
prim5.c
- replaced the artificial "examples" target with a real "build-examples"
target so make won't think it always has to mats that depend upon
the examples directory having been compiled. mats make clean now
runs make clean in the examples directory.
mats/Mf-base
importing a library from an object file now just visits the object
file rather than doing a full load so that the run-time code for
the library is not retained. The run-time code is still read
because the current fasl format forces the entire file to be read,
but not retaining the code can lower heap size and garbage-collection
cost, particularly when many object-code libraries are imported.
The downside is that the file must be revisited if the run-time
code turns out to be required. This change exposed several
places where the code was failing to check if a revisit is needed.
syntax.ss,
7.ms, 8.ms, misc.ms, root-experr*
- fixed typos: was passing unquoted load rather than quoted load
to $load-library along one path (where it is loading source code
and therefore irrelevant), and was reporting src-path rather than
obj-path in a message about failing to define a library.
syntax.ss
- compile-file and friends now put all recompile information in
the first fasl object after the header so the library manager can
find it without loading the entire fasl file. The library manager
now does so. It also now checks to see if library object files
need to be recreated before loading them rather than loading them and
possibly recompiling them after discovering they are out of date, since
the latter requires loading the full object file even if it's out of
date, while the former takes advantage of the ability to extract just
recompile information. as well as reducing overhead, this eliminates
possibly undesirable side effects, such as creation and registration
of out-of-date nongenerative record-type descriptors. because the
library manager expects to find recompile information at the front of
an object file, it will not find all recompile information if object
files are "catted" together. also, compile-file has to hold in memory
the object code for all expressions in the file so that it can emit the
unified recompile information, rather than writing to the object file
incrementally, which can significantly increase the memory required
to compile a large file full of individual top-level forms. This does
not affect top-level programs, which were already handled as a whole,
or a typical library file that contains just a single library form.
compile.ss, syntax.ss
- the library manager now checks include files before library dependencies
when compile-imported-libraries is false (as it already did when
compile-imported-libraries is true) in case a source change affects
the set of imported libraries. (A library change can affect the set
of include files as well, but checking dependencies before include
files can cause unneeded libraries to be loaded.) The include-file
check is based on recompile-info rather than dependencies, but the
library checks are still based on dependencies.
syntax.ss
- fixed check for binding of scheme-version. (the check prevents
premature treatment of recompile-info records as Lexpand forms
to be passed to $interpret-backend.)
scheme.c
- strip-fasl-file now preserves recompile-info when compile-time info
is stripped.
strip.ss
- removed include-req* from library/ct-info and ctdesc records; it
is no longer needed now that all recompile information is maintained
separately.
expand-lang.ss, syntax.ss, compile.ss, cprep.ss, syntax.ss
- changed the fasl format and reworked a lot of code in the expander,
compiler, fasl writer, and fasl reader to allow the fasl reader
to skip past run-time information when it isn't needed and
compile-time information when it isn't needed. Skipping past
still involves reading and decoding when encrypted, but the fasl
reader no longer parses or allocates code and data in the portions
to be skipped. Side effects of associating record uids with rtds
are also avoided, as are the side effects of interning symbols
present only in the skipped data. Skipping past code objects
also reduces or eliminates the need to synchronize data and
instruction caches. Since the fasl reader no longer returns
compile-time (visit) or run-time (revisit) code and data when not
needed, the fasl reader no longer wraps these objects in a pair
with a 0 or 1 visit or revisit marker. To support this change,
the fasl writer generates separate top-level fasl entries (and
graphs) for separate forms in the same top-level source form
(e.g., begin or library). This reliably breaks eq-ness of shared
structure across these forms, which was previously broken only
when visit or revisit code was loaded at different times (this
is an incompatible change). Because of the change, fasl "groups"
are no longer needed, so they are no longer handled.
7.ss, cmacros.ss, compile.ss, expand-lang.ss, strip.ss,
externs.h, fasl.c, scheme.c,
hash.ms
- the change above is surfaced in an optional fasl-read "situation"
argument (visit, revisit, or load). The default is load. visit
causes it to skip past revisit code and data; revisit causes it
to skip past visit code and data; and load causes it not to skip
past either. visit-revisit data produced by (eval-when (visit
revisit) ---) is never skipped.
7.ss, primdata.ss,
io.stex
- to improve compile-time and run-time error checking, the
Lexpand recompile-info, library/rt-info, library-ct-info, and
program-info forms have been replaced with list-structured forms,
e.g., (recompile-info ,rcinfo).
expand-lang.ss, compile.ss, cprep.ss, interpret.ss, syntax.ss
- added visit-compiled-from-port and revisit-compiled-from-port
to complement the existing load-compiled-from-port.
7.ss, primdata.ss,
7.ms,
system.stex
- increased amount read when seeking an lz4-encrypted input
file from 32 to 1024 bytes at a time
compress-io.c
- replaced the fasl a? parameter value #t with an "all" flag value
so it's value is consistently a mask.
cmacros.ss, fasl.ss, compile.ss
- split off profile mats into a separate file
misc.ms, profile.ms (new), root-experr*, mats/Mf-base
- added coverage percent computations to mat allx/bullyx output
mat.ss, mats/Mf-base, primvars.ms
- replaced coverage tables with more generic and generally useful
source tables, which map source objects to arbitrary values.
pdhtml.ss, compile.ss, cprep.ss, primdata.ss,
mat.ss, mats/Mf-base, primvars.ms, profile.ms,
syntax.stex
- reduced profile counting overhead by using calls to fold-left
instead of calls to apply and map and by using fixnum operations
for profile counts on 64-bit machines.
pdhtml.ss
- used a critical section to fix a race condition in the calculations
of profile counts that sometimes resulted in bogus (including
negative) counts, especially when the 's' directory is profiled.
pdhtml.ss
- added discard flag to declaration for hashtable-size
primdata.ss
- redesigned the printed representation of source tables and rewrote
get-source-table! to read and store incrementally to reduce memory
overhead.
compile.ss
- added generate-covin-files to the set of parameters preserved
by compile-file, etc.
compile.ss,
system.stex
- moved covop argument before the undocumented machine and hostop
arguments to compile-port and compile-to-port. removed the
undocumented ofn argument from compile-to-port; using
(port-name ip) instead.
compile.ss, primdata.ss,
7.ms,
system.stex
- compile-port now tries to come up with a file position to supply
to make-read, which it can do if the port's positions are character
positions (presently string ports) or if the port is positioned
at zero.
compile.ss
- audited the argument-type-error fuzz mat exceptions and fixed a
host of problems this turned up (entries follow). added #f as
an invalid argument for every type for which #f is indeed invalid
to catch places where the maybe- prefix was missing on the argument
type. the mat tries hard to determine if the condition raised
(if any) as the result of an invalid argument is appropriate and
redirects the remainder to the mat-output (.mo) file prefixed
with 'Expected error', causing them to show up in the expected
error output so developers will be encouraged to audit them in
the future.
primvars.ms, mat.ss
- added an initial symbol? test on machine type names so we produce
an invalid machine type error message rather than something
confusing like "machine type #f is not supported".
compile.ss
- fixed declarations for many primitives that were specified as
accepting arguments of more general types than they actually
accept, such as number -> real for various numeric operations,
symbol -> endianness for various bytevector operations,
time -> time-utc for time-utc->date, and list -> list-of-string-pairs
for default-library-search-handler. also replaced some of the
sub-xxxx types with specific types such as sub-symbol -> endianness
in utf16->string, but only where they were causing issues with
the primvars argument-type-error fuzz mat. (this should be done
more generally.)
primdata.ss
- fixed incorrect who arguments (was map instead of fold-right,
current-date instead of time-utc->date); switched to using
define-who/set-who! generally.
4.ss, date.ss
- append! now checks all arguments before any mutation
5_2.ss
- with-source-path now properly supplies itself as who for the
string? argument check; callers like load now do their own checks.
7.ss
- added missing integer? check to $fold-bytevector-native-ref whose
lack could have resulted in a compile-time error.
cp0.ss
- fixed typo in output-port-buffer-mode error message
io.ss
- fixed who argument (was fx< rather than fx<?)
library.ss
- fixed declaration of first source-file-descriptor argument (was
sfd, now string)
primdata.ss
- added missing article 'a' in a few error messages
prims.ss
- fixed the copy-environment argument-type error message for the list
of symbols argument.
syntax.ss
- the environment procedure now catches exceptions that occur and
reraises the exception with itself as who if the condition isn't
already a who condition.
syntax.ss
- updated experr and allx patch files for changes to argument-count
fuzz mat and fixes for problems turned up by them.
root-experr*, patch*
- fixed a couple of issues setting port sizes: string and bytevector
output port put handlers don't need room to store the character
or byte, so they now set the size to the buffer length rather
than one less. binary-file-port-clear-output now sets the index
rather than size to zero; setting the size to zero is inappropriate
for some types of ports and could result in loss of buffering and
even suppression of future output. removed a couple of redundant
sets of the size that occur immediately after setting the buffer.
io.ss
- it is now possible to return from a call to with-profile-tracker
multiple times and not double-count (or worse) any counts.
pdhtml.ss, profile.ms
- read-token now requires a file position when it is handed a
source-file descriptor (since the source-file descriptor isn't
otherwise useful), and the source-file descriptor argument can
no longer be #f. the input file position plays the same role as
the input file position in get-datum/annotations. these extra
read-token arguments are now documented.
read.ss,
6.ms,
io.stex
- the source-file descriptor argument to get-datum/annotations can
no longer be #f. it was already documented that way.
read.ss
- read-token and do-read now look for the character-positions port
flag before asking if the port has port-position, since the latter
is slightly more expensive.
read.ss
- rd-error now reports the current port position if it can be determined
when fp isn't already set, i.e., when reading from a port without
character positions (presently any non string port) and fp has not
been passed in explicitly (to read-token or get-datum/annotations).
the port position might not be a character position, but it should be
better than nothing.
read.ss
- added comment noting an invariant for s_profile_release_counters.
prim5.c
- restored accidentally dropped fasl-write formdef and dropped
duplicate fasl-read formdef
io.stex
- added a 'coverage' target that tests the coverage of the Scheme-code
portions of Chez Scheme by the mats.
Makefile.in, Makefile-workarea.in
- added .PHONY declarations for all of the targets in the top-level
and workarea make files, and renamed the create-bintar, create-rpm,
and create-pkg targets bintar, rpm, and pkg.
Makefile.in, Makefile-workarea.in
- added missing --retain-static-relocation command-line argument and
updated the date
scheme.1.in
- removed a few redundant conditional variable settings
configure
- fixed declaration of condition wait (timeout -> maybe-timeout)
primdata.ss
original commit: 88501743001393fa82e89c90da9185fc0086fbcb
2174 lines
80 KiB
Plaintext
2174 lines
80 KiB
Plaintext
% Copyright 2005-2017 Cisco Systems, Inc.
|
|
%
|
|
% Licensed under the Apache License, Version 2.0 (the "License");
|
|
% you may not use this file except in compliance with the License.
|
|
% You may obtain a copy of the License at
|
|
%
|
|
% http://www.apache.org/licenses/LICENSE-2.0
|
|
%
|
|
% Unless required by applicable law or agreed to in writing, software
|
|
% distributed under the License is distributed on an "AS IS" BASIS,
|
|
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
% See the License for the specific language governing permissions and
|
|
% limitations under the License.
|
|
\chapter{Syntactic Extension and Modules\label{CHPTSYNTAX}}
|
|
|
|
This chapter describes the {\ChezScheme} extensions to the
|
|
syntax-case syntactic abstraction mechanism now standardized in
|
|
the Revised$^6$ Report.
|
|
These extensions include
|
|
the module system (Section~\ref{SECTSYNTAXMODULES}),
|
|
meta definitions (Section~\ref{SECTSYNTAXMETA}),
|
|
conditional expansion (Section~\ref{SECTSYNTAXMETACOND})
|
|
\scheme{syntax-rules} fenders,
|
|
\scheme{fluid-let-syntax},
|
|
and \scheme{include}.
|
|
|
|
|
|
\section{Fluid Keyword Bindings\label{SECTSYNTAXDEFINITIONS}}
|
|
|
|
Keyword bindings established via the Revised$^6$ Report
|
|
\scheme{define-syntax}, \scheme{let-syntax}, or \scheme{letrec-syntax}
|
|
forms may be rebound temporarily with \scheme{fluid-let-syntax}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{fluid-let-syntax}{\categorysyntax}{(fluid-let-syntax ((\var{keyword} \var{expr}) \dots) \var{form_1} \var{form_2} \dots)}
|
|
\returns see explanation
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
Each \var{expr} must evaluate to a transformer.
|
|
\scheme{fluid-let-syntax} is similar to the standard \scheme{let-syntax}, except
|
|
that instead of introducing new bindings for the keywords
|
|
\scheme{\var{keyword} \dots},
|
|
\scheme{fluid-let-syntax} temporarily alters the existing bindings
|
|
for the keywords during the expansion of its body.
|
|
That is, during the expansion of \scheme{\var{form_1} \var{form_2} \dots},
|
|
the visible lexical (or top-level) binding
|
|
for each \scheme{keyword} is temporarily replaced by a new association
|
|
between the keyword and the corresponding transformer.
|
|
This affects any references to the keyword that resolve
|
|
to the same lexical (or top-level) binding whether the references occur
|
|
in the text of the body or are introduced during its expansion.
|
|
In contrast, \scheme{let-syntax} captures only those references that
|
|
occur within the text of its body.
|
|
|
|
The following example shows how \scheme{fluid-let-syntax}
|
|
differs from \scheme{let-syntax}.
|
|
|
|
\schemedisplay
|
|
(let ([f (lambda (x) (+ x 1))])
|
|
(let-syntax ([g (syntax-rules ()
|
|
[(_ x) (f x)])])
|
|
(let-syntax ([f (syntax-rules ()
|
|
[(_ x) x])])
|
|
(g 1)))) ;=> 2
|
|
|
|
(let ([f (lambda (x) (+ x 1))])
|
|
(let-syntax ([g (syntax-rules ()
|
|
[(_ x) (f x)])])
|
|
(fluid-let-syntax ([f (syntax-rules ()
|
|
[(_ x) x])])
|
|
(g 1)))) ;=> 1
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The two expressions are identical except that the inner
|
|
\scheme{let-syntax} form
|
|
in the first expression is a \scheme{fluid-let-syntax} form in the second.
|
|
In the first expression, the \scheme{f} occurring in the expansion of
|
|
\scheme{(g 1)} refers to
|
|
the \scheme{let}-bound variable \scheme{f}, whereas in the second it refers
|
|
to the keyword \scheme{f} by virtue of the fluid syntax binding for
|
|
\scheme{f}.
|
|
|
|
\index{integrable procedures}\index{\scheme{define-integrable}}%
|
|
The following code employs \scheme{fluid-let-syntax} in the definition
|
|
of a \scheme{define-integrable} form that is similar
|
|
to \scheme{define} for procedure definitions except that it causes the
|
|
code for the procedure to be \emph{integrated}, or inserted, wherever
|
|
a direct call to the procedure is found.
|
|
No semantic difference is visible between procedures defined with
|
|
\scheme{define-integrable} and those defined with \scheme{define}, except that
|
|
a top-level \scheme{define-integrable} form must appear before the first
|
|
reference to the defined identifier.
|
|
Lexical scoping is preserved, the actual parameters
|
|
in an integrated call are evaluated once and at the proper time,
|
|
integrable procedures may be used as first-class values, and
|
|
recursive procedures do not cause indefinite recursive expansion.
|
|
|
|
\schemedisplay
|
|
(define-syntax define-integrable
|
|
(syntax-rules (lambda)
|
|
[(_ name (lambda formals form1 form2 ...))
|
|
(begin
|
|
(define xname
|
|
(fluid-let-syntax ([name (identifier-syntax xname)])
|
|
(lambda formals form1 form2 ...)))
|
|
(define-syntax name
|
|
(lambda (x)
|
|
(syntax-case x ()
|
|
[_ (identifier? x) #'xname]
|
|
[(_ arg (... ...))
|
|
#'((fluid-let-syntax ([name (identifier-syntax xname)])
|
|
(lambda formals form1 form2 ...))
|
|
arg
|
|
(... ...))]))))]))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
A \scheme{define-integrable} has the following form.
|
|
|
|
\schemedisplay
|
|
(define-integrable \var{name} \var{lambda-expression})
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
A \scheme{define-integrable} form expands into a pair of definitions: a syntax
|
|
definition of \var{name} and a variable definition of \scheme{xname}.
|
|
The transformer for \var{name} converts apparent calls to
|
|
\var{name} into direct calls to \var{lambda-expression}.
|
|
Since the resulting forms are merely direct \scheme{lambda} applications
|
|
(the equivalent of \scheme{let} expressions),
|
|
the actual parameters are evaluated exactly once and before evaluation
|
|
of the procedure's body, as required.
|
|
All other references to \var{name} are replaced with references to
|
|
\scheme{xname}.
|
|
The definition of \scheme{xname} binds it to the value of
|
|
\var{lambda-expression}.
|
|
This allows the procedure to be used as a first-class value.
|
|
Because \scheme{xname} is introduced by the transformer, the binding for
|
|
\scheme{xname} is not visible anywhere except where references to it
|
|
are introduced by the transformer for \var{name}.
|
|
|
|
Within \var{lambda-expression}, wherever it appears, \var{name}
|
|
is rebound to a transformer that expands all references into references
|
|
to \scheme{xname}.
|
|
The use of \index{\scheme{fluid-let-syntax}}\scheme{fluid-let-syntax}
|
|
for this purpose prevents indefinite
|
|
expansion from indirect recursion among integrable procedures.
|
|
This allows the procedure to be recursive without causing indefinite
|
|
expansion.
|
|
Nothing special is done by \scheme{define-integrable} to maintain lexical
|
|
scoping, since lexical scoping is maintained automatically by the
|
|
expander.
|
|
|
|
{\ChezScheme} integrate locally defined procedures automatically when it is
|
|
appropriate to do so.
|
|
It cannot integrate procedures defined at top-level,
|
|
however, since code that assigns top-level variables can be introduced
|
|
into the system (via \scheme{eval} or \scheme{load}) at any time.
|
|
\scheme{define-integrable} can be used to force the integration of
|
|
procedures bound at top-level, even if the integration of locally bound
|
|
procedures is left to the compiler.
|
|
It can also be used to force the integration of large procedures that
|
|
the compiler would not normally integrate.
|
|
(The \scheme{expand/optimize} procedure is useful for determining when
|
|
integration does or does not take place.)
|
|
|
|
\section{Syntax-Rules Transformers\label{SECTSYNTAXRULES}}
|
|
|
|
{\ChezScheme} extends \scheme{syntax-rules} to permit clause to include
|
|
fenders just like those allowed within \scheme{syntax-case} clauses.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{syntax-rules}{\categorysyntax}{(syntax-rules (\var{literal} \dots) \var{clause} \dots)}
|
|
\returns a transformer
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
Each \index{literals}\var{literal} must be an identifier other than
|
|
an underscore (~\scheme{_}~) or ellipsis (~\scheme{...}~).
|
|
Each clause must take the form below.
|
|
|
|
\schemedisplay
|
|
(\var{pattern} \var{template})
|
|
(\var{pattern} \var{fender} \var{template})
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The first form is the only form supported by the Revised$^6$ Report.
|
|
|
|
|
|
\section{Syntax-Case Transformers\label{SECTSYNTAXCASE}}
|
|
|
|
{\ChezScheme} provides several procedures and syntactic forms that may
|
|
be used to simplify the coding of certain syntactic abstractions.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{syntax->list}{\categoryprocedure}{(syntax->list \var{syntax-object})}
|
|
\returns a list of syntax objects
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
This procedure takes a syntax object representing
|
|
a list-structured form and returns a list of syntax objects, each representing
|
|
the corresponding subform of the input form.
|
|
|
|
%Programmers are encouraged to use this procedure even when the current
|
|
%{\ChezScheme} implementation of \scheme{syntax-case} guarantees that
|
|
%the output of a \scheme{syntax} form is a list, since future versions of
|
|
%{\ChezScheme} may remove these guarantees in the interest of maintaining
|
|
%better source information.
|
|
|
|
\scheme{syntax->list} may be defined as follows.
|
|
|
|
\schemedisplay
|
|
(define syntax->list
|
|
(lambda (ls)
|
|
(syntax-case ls ()
|
|
[() '()]
|
|
[(x . r) (cons #'x (syntax->list #'r))])))
|
|
|
|
#'(a b c) ;=> #<syntax (a b c)>
|
|
(syntax->list #'(a b c)) ;=> (#<syntax a> #<syntax b> #<syntax c>)
|
|
\endschemedisplay
|
|
|
|
\scheme{syntax->list} is not required for list structures constructed
|
|
from individual pattern variable values or sequences of pattern-variable
|
|
values, since such structures are already lists.
|
|
For example:
|
|
|
|
\schemedisplay
|
|
(list? (with-syntax ([x #'a] [y #'b] [z #'c]) #'(x y z)))) ;=> #t
|
|
(list? (with-syntax ([(x ...) #'(a b c)]) #'(x ...))) ;=> #t
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{syntax->vector}{\categoryprocedure}{(syntax->vector \var{syntax-object})}
|
|
\returns a vector of syntax objects
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
This procedure takes a syntax object representing
|
|
a vector-structured form and returns a vector of syntax objects, each representing
|
|
the corresponding subform of the input form.
|
|
|
|
%Programmers are encouraged to use this procedure even when the current
|
|
%{\ChezScheme} implementation of \scheme{syntax-case} guarantees that
|
|
%the output of a \scheme{syntax} form is a vector, since future versions of
|
|
%{\ChezScheme} may remove these guarantees in the interest of maintaining
|
|
%better source information.
|
|
|
|
\scheme{syntax->vector} may be defined as follows.
|
|
|
|
\schemedisplay
|
|
(define syntax->vector
|
|
(lambda (v)
|
|
(syntax-case v ()
|
|
[#(x ...) (apply vector (syntax->list #'(x ...)))])))
|
|
|
|
#'#(a b c) ;=> #<syntax #(a b c)>
|
|
(syntax->vector #'#(a b c)) ;=> #(#<syntax a> #<syntax b> #<syntax c>)
|
|
\endschemedisplay
|
|
|
|
\scheme{syntax->vector} is not required for vector structures constructed
|
|
from individual pattern variable values or sequences of pattern-variable
|
|
values, since such structures are already vectors.
|
|
For example:
|
|
|
|
\schemedisplay
|
|
(vector? (with-syntax ([x #'a] [y #'b] [z #'c]) #'#(x y z)))) ;=> #t
|
|
(vector? (with-syntax ([(x ...) #'(a b c)]) #'#(x ...))) ;=> #t
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{syntax-object->datum}{\categoryprocedure}{(syntax-object->datum \var{obj})}
|
|
\returns \var{obj} stripped of syntactic information
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{syntax-object->datum} is identical to the Revised$^6$ Report
|
|
\scheme{syntax->datum}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{datum}{\categorysyntax}{(datum \var{template})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{(datum \var{template})} is a convenient shorthand syntax for
|
|
|
|
\schemedisplay
|
|
(syntax->datum (syntax \var{template}))
|
|
\endschemedisplay
|
|
|
|
\var{datum} may be defined simply as follows.
|
|
|
|
\schemedisplay
|
|
(define-syntax datum
|
|
(syntax-rules ()
|
|
[(_ t) (syntax->datum #'t)]))
|
|
|
|
(with-syntax ((a #'(a b c))) (datum a)) ;=> (a b c)
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{datum->syntax-object}{\categoryprocedure}{(datum->syntax-object \var{template-identifier} \var{obj})}
|
|
\returns a syntax object
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{datum->syntax-object} is identical to the Revised$^6$ Report
|
|
\scheme{datum->syntax}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{with-implicit}{\categorysyntax}{(with-implicit (\var{id_0} \var{id_1} \dots) \var{body_1} \var{body_2} \dots)}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
This form abstracts over the common usage of \scheme{datum->syntax}
|
|
for creating implicit identifiers (see above).
|
|
The form
|
|
|
|
\schemedisplay
|
|
(with-implicit (\var{id_0} \var{id_1} \dots)
|
|
\var{body_1} \var{body_2} \dots)
|
|
\endschemedisplay
|
|
|
|
is equivalent to
|
|
|
|
\schemedisplay
|
|
(with-syntax ([\var{id_1} (datum->syntax #'\var{id_0} '\var{id_1})] \dots)
|
|
\var{body_1} \var{body_2} \dots)
|
|
\endschemedisplay
|
|
|
|
\scheme{with-implicit} can be defined simply as follows.
|
|
|
|
\schemedisplay
|
|
(define-syntax with-implicit
|
|
(syntax-rules ()
|
|
[(_ (tid id ...) b1 b2 ...)
|
|
(with-syntax ([id (datum->syntax #'tid 'id)] ...)
|
|
b1 b2 ...)]))
|
|
\endschemedisplay
|
|
|
|
We can use \scheme{with-implicit} to simplify the (correct version of)
|
|
\scheme{loop} above.
|
|
|
|
\schemedisplay
|
|
(define-syntax loop
|
|
(lambda (x)
|
|
(syntax-case x ()
|
|
[(k e ...)
|
|
(with-implicit (k break)
|
|
#'(call-with-current-continuation
|
|
(lambda (break)
|
|
(let f () e ... (f)))))])))
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{include}{\categorysyntax}{(include \var{path})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{include} expands into a \scheme{begin} expression containing
|
|
the forms found in the file named by \var{path}.
|
|
For example, if the file \scheme{f-def.ss} contains
|
|
% the expression
|
|
\scheme{(define f (lambda () x))}, the expression
|
|
|
|
\schemedisplay
|
|
(let ([x "okay"])
|
|
(include "f-def.ss")
|
|
(f))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
evaluates to \scheme{"okay"}.
|
|
An include form is treated as a definition if it appears within a
|
|
sequence of definitions and the forms on the file named by
|
|
\var{path} are all definitions, as in the above example.
|
|
If the file contains expressions instead, the \scheme{include} form is
|
|
treated as an expression.
|
|
|
|
\scheme{include} may be defined portably as follows, although
|
|
{\ChezScheme} uses an implementation-dependent definition that allows
|
|
it to capture and maintain source information for included code.
|
|
|
|
\schemedisplay
|
|
(define-syntax include
|
|
(lambda (x)
|
|
(define read-file
|
|
(lambda (fn k)
|
|
(let ([p (open-input-file fn)])
|
|
(let f ([x (read p)])
|
|
(if (eof-object? x)
|
|
(begin (close-input-port p) '())
|
|
(cons (datum->syntax k x)
|
|
(f (read p))))))))
|
|
(syntax-case x ()
|
|
[(k filename)
|
|
(let ([fn (datum filename)])
|
|
(with-syntax ([(exp ...) (read-file fn #'k)])
|
|
#'(begin exp ...)))])))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The definition of \scheme{include} uses \scheme{datum->syntax} to convert
|
|
the objects read from the file into syntax objects in the proper
|
|
lexical context, so that identifier references and definitions within
|
|
those expressions are scoped where the \scheme{include} form appears.
|
|
|
|
In {\ChezScheme}'s implementation of \scheme{include},
|
|
the parameter \scheme{source-directories} (Section~\ref{SECTSYSTEMSOURCE})
|
|
determines the set of directories searched for source files not identified
|
|
by absolute path names.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader\label{desc:syntax-error}
|
|
\formdef{syntax-error}{\categoryprocedure}{(syntax-error \var{obj} \var{string} \dots)}
|
|
\returns does not return
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
Syntax errors may be reported with \scheme{syntax-error}, which produces
|
|
a message by concatenating \scheme{\var{string} \dots} and a printed
|
|
representation of \var{obj}.
|
|
If no string arguments are provided, the string \scheme{"invalid syntax"}
|
|
is used instead.
|
|
When \var{obj} is a syntax object, the syntax-object wrapper is
|
|
stripped (as with \scheme{syntax->datum}) before the printed representation
|
|
is created.
|
|
If source file information is present in the syntax-object wrapper,
|
|
\scheme{syntax-error} incorporates this information into the error
|
|
message.
|
|
|
|
\scheme{syntax-case} and \scheme{syntax-rules} call \scheme{syntax-error}
|
|
automatically if the input fails to match one of the clauses.
|
|
|
|
We can use \scheme{syntax-error} to precisely report the cause
|
|
of the errors detected in the following definition of
|
|
(unnamed) \scheme{let}.
|
|
|
|
\schemedisplay
|
|
(define-syntax let
|
|
(lambda (x)
|
|
(define check-ids!
|
|
(lambda (ls)
|
|
(unless (null? ls)
|
|
(unless (identifier? (car ls))
|
|
(syntax-error (car ls) "let cannot bind non-identifier"))
|
|
(check-ids! (cdr ls)))))
|
|
(define check-unique!
|
|
(lambda (ls)
|
|
(unless (null? ls)
|
|
(let ([x (car ls)])
|
|
(when (let mem? ([ls (cdr ls)])
|
|
(and (not (null? ls))
|
|
(or (bound-identifier=? x (car ls))
|
|
(mem? (cdr ls)))))
|
|
(syntax-error x "let cannot bind two occurrences of")))
|
|
(check-unique! (cdr ls)))))
|
|
(syntax-case x ()
|
|
[(_ ((i e) ...) b1 b2 ...)
|
|
(begin
|
|
(check-ids! #'(i ...))
|
|
(check-unique! #'(i ...))
|
|
#'((lambda (i ...) b1 b2 ...) e ...))])))
|
|
\endschemedisplay
|
|
|
|
With this change, the expression
|
|
|
|
\schemedisplay
|
|
(let ([a 3] [a 4]) (+ a a))
|
|
\endschemedisplay
|
|
|
|
produces the error message ``let cannot bind two occurrences of \scheme{a}.''
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{literal-identifier=?}{\categoryprocedure}{(literal-identifier=? \var{identifier_1} \var{identifier_2})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
This procedure is identical to the Revised$^6$ Report
|
|
\scheme{free-identifier=?}, and is provided for backward
|
|
compatibility only.
|
|
|
|
\section{Compile-time Values and Properties\label{SECTSYNTAXCTVS}}
|
|
|
|
When defining sets of dependent macros, it is often convenient to attach
|
|
information to identifiers in the same \emph{compile time environment}
|
|
that the expander uses to record information about variables, keywords,
|
|
module names, etc.
|
|
For example, a record-type definition macro, like
|
|
\scheme{define-record-type}, might need to attach information to the
|
|
record-type name in the compile-time environment for use in handling child
|
|
record-type definitions.
|
|
|
|
{\ChezScheme} provides two mechanisms for attaching information to
|
|
identifiers in the compile-time environment: compile-time values and
|
|
compile-time properties.
|
|
A compile-time value is a kind of transformer that can be
|
|
associated with an identifier via \scheme{define-syntax},
|
|
\scheme{let-syntax}, \scheme{letrec-syntax}, and \scheme{fluid-let-syntax}.
|
|
When an identifier is associated with a compile-time value, it cannot
|
|
also have any other meaning, and an attempt to reference it as an
|
|
ordinary identifier results in a syntax error.
|
|
A compile-time property, on the other hand, is maintained alongside
|
|
an existing binding, providing additional information about the
|
|
binding.
|
|
Properties are ignored when ordinary references to an identifier
|
|
occur.
|
|
|
|
The mechanisms used by a macro to obtain compile-time values and
|
|
properties are similar.
|
|
In both cases, the macro's transformer returns a procedure \var{p}
|
|
rather than a syntax object.
|
|
The expander invokes \var{p} with one argument, an environment-lookup
|
|
procedure \var{lookup}, which \var{p} can then use to obtain compile-time
|
|
values and properties for one or more identifiers before it constructs the
|
|
macro's final output.
|
|
\var{lookup} accepts one or two identifier arguments.
|
|
With one argument, \var{id}, \var{lookup} returns the compile-time
|
|
value of \var{id}, or \scheme{#f} if \var{id} has no compile-time value.
|
|
With two arguments, \var{id} and \var{key}, \var{lookup} returns the
|
|
value of \var{id}'s \var{key} property, or \scheme{#f} if \var{id}
|
|
has no \var{key} property.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{make-compile-time-value}{\categoryprocedure}{(make-compile-time-value \var{obj})}
|
|
\returns a compile-time value
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
A compile time value is a kind of transformer with which a keyword may
|
|
be associated by any of the keyword binding constructs, e.g., \scheme{define-syntax}
|
|
or \scheme{let-syntax}.
|
|
The transformer encapsulates the supplied \var{obj}.
|
|
The encapsulated object may be retrieved as described above.
|
|
|
|
The following example illustrates how this feature might be used to define
|
|
a simple syntactic record-definition mechanism where the record type descriptor
|
|
is generated at expansion time.
|
|
|
|
\schemedisplay
|
|
(define-syntax drt
|
|
(lambda (x)
|
|
(define construct-name
|
|
(lambda (template-identifier . args)
|
|
(datum->syntax template-identifier
|
|
(string->symbol
|
|
(apply string-append
|
|
(map (lambda (x)
|
|
(if (string? x)
|
|
x
|
|
(symbol->string (syntax->datum x))))
|
|
args))))))
|
|
(define do-drt
|
|
(lambda (rname fname* prtd)
|
|
(with-syntax ([rname rname]
|
|
[rtd (make-record-type-descriptor
|
|
(syntax->datum rname) prtd #f #f #f
|
|
(list->vector
|
|
(map (lambda (fname)
|
|
`(immutable ,(syntax->datum fname)))
|
|
fname*)))]
|
|
[make-rname (construct-name rname "make-" rname)]
|
|
[rname? (construct-name rname rname "?")]
|
|
[(rname-fname ...)
|
|
(map (lambda (fname)
|
|
(construct-name fname rname "-" fname))
|
|
fname*)]
|
|
[(i ...) (enumerate fname*)])
|
|
#'(begin
|
|
(define-syntax rname (make-compile-time-value 'rtd))
|
|
(define rcd (make-record-constructor-descriptor 'rtd #f #f))
|
|
(define make-rname (record-constructor rcd))
|
|
(define rname? (record-predicate 'rtd))
|
|
(define rname-fname (record-accessor 'rtd i))
|
|
...))))
|
|
(syntax-case x (parent)
|
|
[(_ rname (fname ...))
|
|
(for-all identifier? #'(rname fname ...))
|
|
(do-drt #'rname #'(fname ...) #f)]
|
|
[(_ rname pname (fname ...))
|
|
(for-all identifier? #'(rname pname fname ...))
|
|
(lambda (lookup)
|
|
(let ([prtd (lookup #'pname)])
|
|
(unless (record-type-descriptor? prtd)
|
|
(syntax-error #'pname "unrecognized parent record type"))
|
|
(do-drt #'rname #'(fname ...) prtd)))])))
|
|
\endschemedisplay
|
|
|
|
\schemedisplay
|
|
(drt prec (x y))
|
|
(drt crec prec (z))
|
|
(define r (make-crec 1 2 3))
|
|
(prec? r) ;=> #t
|
|
(prec-x r) ;=> 1
|
|
(crec-z r) ;=> 3
|
|
prec ;=> \var{exception: invalid syntax prec}
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{compile-time-value?}{\categoryprocedure}{(compile-time-value? \var{obj})}
|
|
\returns \scheme{#t} if \var{obj} is a compile-time value; \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\schemedisplay
|
|
(define-syntax x (make-compile-time-value "eggs"))
|
|
(compile-time-value? (top-level-syntax 'x)) ;=> #t
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{compile-time-value-value}{\categoryprocedure}{(compile-time-value-value \var{ctv})}
|
|
\returns the value of a compile-time value
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\schemedisplay
|
|
(define-syntax x (make-compile-time-value "eggs"))
|
|
(compile-time-value-value (top-level-syntax 'x)) ;=> "eggs"
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{define-property}{\categorysyntax}{(define-property \var{id} \var{key} \var{expr})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
A \scheme{define-property} form attaches a property to an
|
|
existing identifier binding without disturbing the existing meaning
|
|
of the identifier in the scope of that binding.
|
|
It is typically used by one macro to record information about a binding
|
|
for use by another macro.
|
|
Both \var{id} and \var{key} must be identifiers.
|
|
The expression \var{expr} is evaluated when the \scheme{define-property}
|
|
form is expanded, and a new property associating \var{key} with the
|
|
value of \var{expr} is attached to the existing binding of
|
|
\var{id}, which must have a visible local or top-level binding.
|
|
|
|
\scheme{define-property} is a definition and can appear anywhere
|
|
other definitions can appear.
|
|
The scope of a property introduced by \scheme{define-property} is the
|
|
entire body in which the \scheme{define-property} form appears or global
|
|
if it appears at top level, except
|
|
where it is replaced by a property for the same \var{id} and
|
|
\var{key} or where the binding to which it is attached is shadowed.
|
|
Any number of properties can be attached to the same binding with
|
|
different keys.
|
|
Attaching a new property with the same name as an property already
|
|
attached to a binding shadows the existing property with the new
|
|
property.
|
|
|
|
The following example defines a macro, \scheme{get-info}, that retrieves
|
|
the \scheme{info} property of a binding, defines the variable \scheme{x},
|
|
attaches an \scheme{info} property to the binding of \scheme{x}, retrieves
|
|
the property via \scheme{get-info}, references \scheme{x} to show that
|
|
its normal binding is still intact, and uses \scheme{get-info} again
|
|
within the scope of a different binding of \scheme{x} to show that the
|
|
properties are shadowed as well as the outer binding of \scheme{x}.
|
|
|
|
\schemedisplay
|
|
(define info)
|
|
(define-syntax get-info
|
|
(lambda (x)
|
|
(lambda (lookup)
|
|
(syntax-case x ()
|
|
[(_ q)
|
|
(let ([info-value (lookup #'q #'info)])
|
|
#`'#,(datum->syntax #'* info-value))]))))
|
|
(define x "x-value")
|
|
(define-property x info "x-info")
|
|
(get-info x) ;=> "x-info"
|
|
x ;=> "x-value"
|
|
(let ([x "inner-x-value"]) (get-info x)) ;=> #f
|
|
\endschemedisplay
|
|
|
|
For debugging, it is often useful to have a form that retrieves
|
|
an arbitrary property, given an identifier and a key.
|
|
The \index{\scheme{get-property}}\scheme{get-property} macro below does
|
|
just that.
|
|
|
|
\schemedisplay
|
|
(define-syntax get-property
|
|
(lambda (x)
|
|
(lambda (r)
|
|
(syntax-case x ()
|
|
[(_ id key)
|
|
#`'#,(datum->syntax #'* (r #'id #'key))]))))
|
|
(get-property x info) ;=> "x-info"
|
|
\endschemedisplay
|
|
|
|
The bindings for both identifiers must be visible where
|
|
\scheme{get-property} is used.
|
|
|
|
The version of \scheme{drt} defined below is like the one defined using
|
|
\scheme{make-compile-time-value} above, except that it defines the
|
|
record name as a macro that raises an exception with a more descriptive
|
|
message, while attaching the record type descriptor to the binding as a
|
|
separate property.
|
|
The variable \scheme{drt-key} defined along with \scheme{drt} is used
|
|
only as the key for the property that \scheme{drt} attaches to a record
|
|
name.
|
|
Both \scheme{drt-key} and \scheme{drt} are defined within a module that
|
|
exports only the latter, ensuring that the properties used by \scheme{drt}
|
|
cannot be accessed or forged.
|
|
|
|
\schemedisplay
|
|
(library (drt) (export drt) (import (chezscheme))
|
|
(define drt-key)
|
|
(define-syntax drt
|
|
(lambda (x)
|
|
(define construct-name
|
|
(lambda (template-identifier . args)
|
|
(datum->syntax template-identifier
|
|
(string->symbol
|
|
(apply string-append
|
|
(map (lambda (x)
|
|
(if (string? x)
|
|
x
|
|
(symbol->string (syntax->datum x))))
|
|
args))))))
|
|
(define do-drt
|
|
(lambda (rname fname* prtd)
|
|
(with-syntax ([rname rname]
|
|
[rtd (make-record-type-descriptor
|
|
(syntax->datum rname) prtd #f #f #f
|
|
(list->vector
|
|
(map (lambda (fname)
|
|
`(immutable ,(syntax->datum fname)))
|
|
fname*)))]
|
|
[make-rname (construct-name rname "make-" rname)]
|
|
[rname? (construct-name rname rname "?")]
|
|
[(rname-fname ...)
|
|
(map (lambda (fname)
|
|
(construct-name fname rname "-" fname))
|
|
fname*)]
|
|
[(i ...) (enumerate fname*)])
|
|
#'(begin
|
|
(define-syntax rname
|
|
(lambda (x)
|
|
(syntax-error x "invalid use of record name")))
|
|
(define rcd (make-record-constructor-descriptor 'rtd #f #f))
|
|
(define-property rname drt-key 'rtd)
|
|
(define make-rname (record-constructor rcd))
|
|
(define rname? (record-predicate 'rtd))
|
|
(define rname-fname (record-accessor 'rtd i))
|
|
...))))
|
|
(syntax-case x (parent)
|
|
[(_ rname (fname ...))
|
|
(for-all identifier? #'(rname fname ...))
|
|
(do-drt #'rname #'(fname ...) #f)]
|
|
[(_ rname pname (fname ...))
|
|
(for-all identifier? #'(rname pname fname ...))
|
|
(lambda (lookup)
|
|
(let ([prtd (lookup #'pname #'drt-key)])
|
|
(unless prtd
|
|
(syntax-error #'pname "unrecognized parent record type"))
|
|
(do-drt #'rname #'(fname ...) prtd)))]))))
|
|
\endschemedisplay
|
|
|
|
\schemedisplay
|
|
(import (drt))
|
|
(drt prec (x y))
|
|
(drt crec prec (z))
|
|
(define r (make-crec 1 2 3))
|
|
(prec? r) ;=> #t
|
|
(prec-x r) ;=> 1
|
|
(crec-z r) ;=> 3
|
|
prec ;=> \var{exception: invalid use of record name prec}
|
|
\endschemedisplay
|
|
|
|
\section{Modules\label{SECTSYNTAXMODULES}}
|
|
|
|
\index{modules}Modules are used to help organize programs into separate
|
|
parts that interact cleanly via declared interfaces.
|
|
Although modular programming is typically used to facilitate the development
|
|
of large programs possibly written by many individuals, it may also be
|
|
used in {\ChezScheme} at a ``micro-modular'' level, since {\ChezScheme}
|
|
module and import forms are definitions and may appear anywhere any other
|
|
kind of definition may appear, including within a \scheme{lambda} body
|
|
or other local scope.
|
|
|
|
Modules control visibility of bindings and can be viewed as extending
|
|
lexical scoping to allow more precise control over where bindings are
|
|
or are not visible.
|
|
Modules export identifier bindings, i.e., variable bindings, keyword
|
|
bindings, or module name bindings.
|
|
Modules may be \emph{named} or \emph{anonymous}.
|
|
Bindings exported from a named module may be made visible via an import
|
|
form wherever the module's name is visible.
|
|
Bindings exported from an anonymous module are implicitly imported where
|
|
the module form appears.
|
|
Anonymous modules are useful for hiding some of a set of bindings while
|
|
allowing the remaining bindings in the set to be visible.
|
|
|
|
Some of the text and examples given in this section are
|
|
adapted from the paper
|
|
``Extending the scope of syntactic
|
|
abstraction''~\cite{waddell:modules}, which describes modules and their
|
|
implementation in more detail.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{module}{\categorysyntax}{(module \var{name} \var{interface} \var{defn} \dots \var{init} \dots)}
|
|
\formdef{module}{\categorysyntax}{(module \var{interface} \var{defn} \dots \var{init} \dots)}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{name} is an identifier, \scheme{\var{defn} \dots}
|
|
are definitions, and \scheme{\var{init} \dots} are expressions.
|
|
\var{interface} is a list of exports \scheme{(\var{export} \dots)},
|
|
where each \var{export} is either an identifier \var{identifier}
|
|
or of the form \scheme{(\var{identifier} \var{export} \dots)}.
|
|
|
|
The first syntax for \scheme{module} establishes a named scope that
|
|
encapsulates a set of identifier bindings.
|
|
The exported bindings may be made visible via \scheme{import} or
|
|
\scheme{import-only} (Section~\ref{SECTLIBRARYIMPORTEXPORTFORMS})
|
|
anywhere the module name is visible.
|
|
The second syntax for \scheme{module} introduces an anonymous module
|
|
whose bindings are implicitly imported (as if by \scheme{import} of a
|
|
hidden module name) where the module form appears.
|
|
|
|
A module consists of a (possibly empty) set of
|
|
definitions and a (possibly empty) sequence of initialization expressions.
|
|
The identifiers defined within a module are visible within the body
|
|
of the module and, if exported, within the scope of an import for the
|
|
module.
|
|
Each identifier listed in a module's interface must be defined within
|
|
or imported into that module.
|
|
A \scheme{module} form is a definition and can appear anywhere other
|
|
definitions can appear, including
|
|
at the top level of a program, nested within the bodies of
|
|
\scheme{lambda} expressions, nested within \scheme{library} and
|
|
top-level program forms, and nested within other modules.
|
|
Also, because module names are scoped like other identifiers,
|
|
modules and libraries may export module names as well as variables and keywords.
|
|
|
|
When an interface contains an export of the form
|
|
\scheme{(\var{identifier} \var{export} \dots)}, only \var{identifier} is
|
|
visible in the importing context.
|
|
The identifiers within \scheme{\var{export} \dots} are
|
|
\emph{indirect imports}, as if declared via an
|
|
\scheme{indirect-export} form (Section~\ref{SECTLIBRARYIMPORTEXPORTFORMS}).
|
|
|
|
Module names occupy the same namespace as other identifiers and follow
|
|
the same scoping rules.
|
|
Unless exported, identifiers defined within a module are visible only
|
|
within that module.
|
|
|
|
Expressions within a module can reference identifiers bound outside of
|
|
the module.
|
|
|
|
\schemedisplay
|
|
(let ([x 3])
|
|
(module m (plusx)
|
|
(define plusx (lambda (y) (+ x y))))
|
|
(import m)
|
|
(let ([x 4])
|
|
(plusx 5))) ;=> 8
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Similarly, \scheme{import} does not prevent access to identifiers that
|
|
are visible where the import form appears, except for those variables
|
|
shadowed by the imported identifiers.
|
|
|
|
\schemedisplay
|
|
(module m (y) (define y 'm-y))
|
|
(let ([x 'local-x] [y 'local-y])
|
|
(import m)
|
|
(list x y)) ;=> (local-x m-y)
|
|
\endschemedisplay
|
|
|
|
On the other hand, use of \scheme{import-only} within a module
|
|
establishes an isolated scope in
|
|
which the only visible identifiers are those exported by the
|
|
imported module.
|
|
|
|
\schemedisplay
|
|
(module m (y) (define y 'm-y))
|
|
(let ([x 'local-x] [y 'local-y])
|
|
(import-only m)
|
|
x) ;=> Error: x is not visible
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
This is sometimes desirable for static verification that no
|
|
identifiers are used except those explicitly imported into a
|
|
module or local scope.
|
|
|
|
Unless a module imported via \scheme{import-only} exports
|
|
\scheme{import} or
|
|
\scheme{import-only} and the name of at least one module, subsequent
|
|
imports within the scope of the \scheme{import-only} form are not
|
|
possible.
|
|
To create an isolated scope containing the exports of more than one
|
|
module without making \scheme{import} or \scheme{import-only}
|
|
visible, all of the modules to be imported must be listed in the
|
|
same \scheme{import-only} form.
|
|
|
|
Another solution is to create a single module that contains
|
|
the exports of each of the other modules.
|
|
|
|
\schemedisplay
|
|
(module m2 (y) (define y 'y))
|
|
(module m1 (x) (define x 'x))
|
|
(module mega-module (cons x y)
|
|
(import m1)
|
|
(import m2)
|
|
(import scheme))
|
|
(let ([y 3])
|
|
(import-only mega-module)
|
|
(cons x y)) ;=> (x . y)
|
|
\endschemedisplay
|
|
|
|
\bigskip
|
|
Before it is compiled, a source program is translated into
|
|
a core language program containing no syntactic abstractions, syntactic
|
|
definitions, library definitions, module definitions, or import forms.
|
|
Translation is performed by a \emph{syntax expander} that
|
|
processes the forms in the source program via recursive descent.
|
|
|
|
A \scheme{define-syntax} form associates a keyword
|
|
with a transformer in a translation-time environment.
|
|
When the expander encounters a keyword, it invokes the
|
|
associated transformer and reprocesses the resulting form.
|
|
A \scheme{module} form associates a module name with an interface.
|
|
When the expander encounters an \scheme{import} form, it extracts the
|
|
corresponding module interface from the translation-time environment and makes
|
|
the exported bindings visible in the scope where the \scheme{import} form
|
|
appears.
|
|
|
|
Internal definitions and definitions within a \scheme{module}
|
|
body are processed from left to right so that a module's definition
|
|
and import may appear within the same sequence of definitions.
|
|
Expressions appearing within a body and the right-hand sides of variable
|
|
definitions, however, are translated
|
|
only after the entire set of definitions has been processed, allowing
|
|
full mutual recursion among variable and syntactic definitions.
|
|
|
|
Module and import forms affect only the visibility of identifiers in
|
|
the source program, not their meanings.
|
|
In particular, variables are bound to locations whether defined within or
|
|
outside of a module, and \scheme{import} does not introduce new locations.
|
|
Local variables are renamed as necessary to preserve the scoping
|
|
relationships established by both modules and syntactic abstractions.
|
|
Thus, the expression:
|
|
|
|
\schemedisplay
|
|
(let ([x 1])
|
|
(module m (x setter)
|
|
(define-syntax x (identifier-syntax z))
|
|
(define setter (lambda (x) (set! z x)))
|
|
(define z 5))
|
|
(let ([y x] [z 0])
|
|
(import m)
|
|
(setter 3)
|
|
(+ x y z))) ;=> 4
|
|
\endschemedisplay
|
|
|
|
is equivalent to the following program
|
|
in which identifiers have been consistently renamed as indicated by
|
|
subscripts.
|
|
|
|
\schemedisplay
|
|
(let ([x\var{_0} 1])
|
|
(define-syntax x\var{_1} (identifier-syntax z\var{_1}))
|
|
(define setter\var{_1} (lambda (x\var{_2}) (set! z\var{_1} x\var{_2})))
|
|
(define z\var{_1} 5)
|
|
(let ([y\var{_3} x\var{_0}] [z\var{_3} 0])
|
|
(setter\var{_1} 3)
|
|
(+ x\var{_1} y\var{_3} z\var{_3})))
|
|
\endschemedisplay
|
|
|
|
Definitions within a top-level \scheme{begin}, \scheme{lambda}, top-level program,
|
|
\scheme{library}, or \scheme{module} body
|
|
are processed from left to right by the expander at expand time, and the
|
|
variable definitions are evaluated from left-to-right at run time.
|
|
Initialization expressions appearing within a \scheme{module} body
|
|
are evaluated in sequence after the evaluation of the variable
|
|
definitions.
|
|
|
|
Mutually recursive modules can be defined in several ways.
|
|
In the following program, \scheme{a} and \scheme{b} are mutually recursive
|
|
modules exported by an anonymous module whose local scope is used to
|
|
statically link the two.
|
|
For example,
|
|
the free variable \scheme{y} within module \scheme{a} refers to
|
|
the binding for \scheme{y}, provided by importing \scheme{b},
|
|
in the enclosing module.
|
|
|
|
\schemedisplay
|
|
(module (a b)
|
|
(module a (x) (define x (lambda () y)))
|
|
(module b (y) (define y (lambda () x)))
|
|
(import a)
|
|
(import b))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The following syntactic abstraction generalizes this pattern to
|
|
permit the definition of multiple mutually recursive modules.
|
|
|
|
\schemedisplay
|
|
(define-syntax rec-modules
|
|
(syntax-rules (module)
|
|
[(_ (module m (id ...) form ...) ...)
|
|
(module (m ...)
|
|
(module m (id ...) form ...) ...
|
|
(import m) ...)]))
|
|
\endschemedisplay
|
|
|
|
Because a module can re-export imported bindings,
|
|
it is quite easy to provide multiple views on a single
|
|
module, as \scheme{s} and \scheme{t} provide for \scheme{r}
|
|
below, or to combine several modules into a compound,
|
|
as \scheme{r} does.
|
|
|
|
\schemedisplay
|
|
(module p (x y)
|
|
(define x 1) (define y 2))
|
|
(module q (y z)
|
|
(define y 3) (define z 4))
|
|
(module r (a b c d)
|
|
(import* p (a x) (b y))
|
|
(import* q (c y) (d z)))
|
|
(module s (a c) (import r))
|
|
(module t (b d) (import r))
|
|
\endschemedisplay
|
|
|
|
To allow interfaces to be separated from implementations,
|
|
the following syntactic abstractions support the definition and use of
|
|
named interfaces.
|
|
|
|
\schemedisplay
|
|
(define-syntax define-interface
|
|
(syntax-rules ()
|
|
[(_ name (export ...))
|
|
(define-syntax name
|
|
(lambda (x)
|
|
(syntax-case x ()
|
|
[(_ n defs)
|
|
(with-implicit (n export ...)
|
|
#'(module n (export ...) .
|
|
defs))])))]))
|
|
|
|
(define-syntax define-module
|
|
(syntax-rules ()
|
|
[(_ name interface defn ...)
|
|
(interface name (defn ...))]))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
\scheme{define-interface} creates an interface macro that, given a module
|
|
name and a list of definitions, expands into a module definition with
|
|
a concrete interface.
|
|
|
|
\scheme{with-implicit} is used to ensure that the introduced
|
|
\scheme{export} identifiers are visible in the same scope as the name of
|
|
the module in the \scheme{define-module} form.
|
|
|
|
\noindent
|
|
\scheme{define-interface} and \scheme{define-module} can be used as
|
|
follows.
|
|
|
|
\schemedisplay
|
|
(define-interface simple (a b))
|
|
(define-module m simple
|
|
(define-syntax a (identifier-syntax 1))
|
|
(define b (lambda () c))
|
|
(define c 2))
|
|
(let () (import m) (+ a (b))) ;=> 3
|
|
\endschemedisplay
|
|
|
|
The abstract module facility defined below allows a module interface to
|
|
be satisfied incrementally when module forms are evaluated.
|
|
This permits flexibility in the separation between the interface and
|
|
implementation, supports separate compilation of mutually recursive
|
|
modules, and permits redefinition of module implementations.
|
|
|
|
\schemedisplay
|
|
(define-syntax abstract-module
|
|
(syntax-rules ()
|
|
[(_ name (ex ...) (kwd ...) defn ...)
|
|
(module name (ex ... kwd ...)
|
|
(declare ex) ...
|
|
defn ...)]))
|
|
|
|
(define-syntax implement
|
|
(syntax-rules ()
|
|
[(_ name form ...)
|
|
(module () (import name) form ...)]))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Within an \scheme{abstract-module} form,
|
|
each of the exports in the list \scheme{\var{ex} \dots} must be
|
|
variables.
|
|
The values of these variables are supplied by one or more separate
|
|
\scheme{implement} forms.
|
|
Since keyword bindings must be present at compile time,
|
|
they cannot be satisfied incrementally and are instead listed as
|
|
separate exports and defined within the abstract module.
|
|
|
|
Within an \scheme{implement} form,
|
|
the sequence of forms \scheme{\var{form} \dots} is a sequence of
|
|
zero or more definitions followed by a sequence of zero or more
|
|
expressions.
|
|
Since the module used in the expansion of \scheme{implement} does
|
|
not export anything, the definitions are all local to the
|
|
\scheme{implement} form.
|
|
The expressions may be arbitrary expressions, but should include
|
|
one \scheme{satisfy} form for each variable whose definition is
|
|
supplied by the \scheme{implement} form.
|
|
A \scheme{satisfy} form has the syntax
|
|
|
|
\schemedisplay
|
|
(satisfy \var{variable} \var{expr})
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
\scheme{declare} and \scheme{satisfy} may simply be the equivalents of
|
|
\scheme{define} and \scheme{set!}.
|
|
|
|
\schemedisplay
|
|
(define-syntax declare (identifier-syntax define))
|
|
(define-syntax satisfy (identifier-syntax set!))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Alternatively, \scheme{declare} can initialize the declared variable to
|
|
the value of a flag known only to \scheme{declare} and \scheme{satisfy},
|
|
and \scheme{satisfy} can verify that this flag is still present to insure
|
|
that only one attempt to satisfy the value of a given identifier is
|
|
made.
|
|
|
|
\schemedisplay
|
|
(module ((declare cookie) (satisfy cookie))
|
|
(define cookie "chocolate chip")
|
|
(define-syntax declare
|
|
(syntax-rules () [(_ var) (define var cookie)]))
|
|
(define-syntax satisfy
|
|
(syntax-rules ()
|
|
[(_ var exp)
|
|
(if (eq? var cookie)
|
|
(set! var exp)
|
|
(assertion-violationf 'satisfy
|
|
"value of variable ~s has already been satisfied"
|
|
'var))])))
|
|
\endschemedisplay
|
|
|
|
Using \scheme{abstract-module} and \scheme{implement}, we can define
|
|
mutually recursive and separately compilable modules as follows.
|
|
|
|
\schemedisplay
|
|
(abstract-module e (even?) (pred)
|
|
(define-syntax pred
|
|
(syntax-rules () [(_ exp) (- exp 1)])))
|
|
|
|
(abstract-module o (odd?) ())
|
|
|
|
(implement e
|
|
(import o)
|
|
(satisfy even?
|
|
(lambda (x)
|
|
(or (zero? x) (odd? (pred x))))))
|
|
|
|
(implement o
|
|
(import e)
|
|
(satisfy odd?
|
|
(lambda (x) (not (even? x)))))
|
|
|
|
(let () (import-only e) (even? 38)) ;=> #t
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{only}{\categorysyntax}{only}
|
|
\formdef{except}{\categorysyntax}{except}
|
|
\formdef{add-prefix}{\categorysyntax}{add-prefix}
|
|
\formdef{drop-prefix}{\categorysyntax}{drop-prefix}
|
|
\formdef{rename}{\categorysyntax}{rename}
|
|
\formdef{alias}{\categorysyntax}{alias}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
These identifiers are auxiliary keywords for \scheme{import}
|
|
and \scheme{import-only}.
|
|
It is a syntax violation to reference these identifiers except in
|
|
contexts where they are recognized as auxiliary keywords.
|
|
|
|
\section{Standalone import and export forms\label{SECTSYNTAXIMPORTEXPORTFORMS}}
|
|
|
|
The local import and export forms described in
|
|
Section~\ref{SECTLIBRARYIMPORTEXPORTFORMS} can be used
|
|
equally well for and within modules.
|
|
|
|
\section{Built-in Modules\label{SECTSYNTAXBUILTINMODULES}}
|
|
|
|
Five modules are built-in to {\ChezScheme}: \index{\scheme{scheme} module}\scheme{scheme},
|
|
\index{\scheme{r5rs} module}\scheme{r5rs}, \index{\scheme{r5rs-syntax} module}\scheme{r5rs-syntax}, \index{\scheme{ieee} module}\scheme{ieee}, and
|
|
\index{\scheme{$system} module}\scheme{$system}.
|
|
Each module is immutable, i.e., the exported bindings cannot be
|
|
altered.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{scheme}{\categorymodule}{scheme}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{scheme} contains all user-visible top-level bindings
|
|
(variables, keywords, and module names) built into {\ChezScheme}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{r5rs}{\categorymodule}{r5rs}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{r5rs} contains all top-level bindings
|
|
(variables and keywords) defined in the
|
|
Revised$^5$ Report on Scheme.
|
|
The bindings exported from \scheme{r5rs} are precisely those that are
|
|
available within an expression evaluated via \scheme{eval} with the
|
|
environment specifier returned by
|
|
\index{\scheme{scheme-report-environment}}\scheme{scheme-report-environment}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{r5rs-syntax}{\categorymodule}{r5rs-syntax}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{r5rs-syntax} contains all top-level keyword bindings
|
|
defined in the Revised$^5$ Report on Scheme.
|
|
The bindings exported from \scheme{r5rs-syntax} are precisely those that are
|
|
available within an expression evaluated via \scheme{eval} with the
|
|
environment specifier returned by
|
|
\index{\scheme{null-environment}}\scheme{null-environment}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{ieee}{\categorymodule}{ieee}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{ieee} contains all top-level bindings
|
|
(variables and keywords) defined in the
|
|
ANSI/IEEE standard for Scheme.
|
|
The bindings exported from \scheme{ieee} are precisely those that are
|
|
available within an expression evaluated via \scheme{eval} with the
|
|
environment specifier returned by
|
|
\index{\scheme{ieee-environment}}\scheme{ieee-environment}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{$system}{\categorymodule}{$system}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{$system} contains all user-visible top-level bindings built
|
|
into {\ChezScheme} along with various undocumented system bindings.
|
|
|
|
|
|
\section{Meta Definitions\label{SECTSYNTAXMETA}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{meta}{\categorysyntax}{(meta . \var{definition})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
The \scheme{meta} keyword is actually a prefix that can be placed in
|
|
front of any definition keyword, e.g.,
|
|
|
|
\schemedisplay
|
|
(meta define x 3)
|
|
\endschemedisplay
|
|
|
|
It tells the expander that any variable definition resulting
|
|
from the definition is to be an expand-time definition available only
|
|
to the right-hand sides of other meta definitions and, most importantly,
|
|
transformer expressions.
|
|
It is used to define expand-time helpers and other information for use
|
|
by one or more \scheme{syntax-case} transformers.
|
|
|
|
% (module count-let (count let)
|
|
% (meta define counter 0)
|
|
% (define-syntax count (lambda (x) counter))
|
|
% (define-syntax let
|
|
% (lambda (x)
|
|
% (import scheme)
|
|
% (set! counter (+ counter 1))
|
|
% (syntax-case x () [(_ . stuff) #'(let . stuff)]))))
|
|
|
|
\schemedisplay
|
|
(module M (helper1 a b)
|
|
(meta define helper1
|
|
(lambda (---)
|
|
---))
|
|
(meta define helper2
|
|
(lambda (---)
|
|
--- (helper2 ---) ---))
|
|
(define-syntax a
|
|
(lambda (x)
|
|
--- (helper1 ---) ---))
|
|
(define-syntax b
|
|
(lambda (x)
|
|
--- (helper1 ---) ---
|
|
--- (helper2 ---) ---)))
|
|
\endschemedisplay
|
|
|
|
The right-hand-side expressions of a syntax definition or meta definition
|
|
can refer only to identifiers whose values are already available in the
|
|
compile-time environment.
|
|
Because of the left-to-right expansion order for \scheme{library},
|
|
\scheme{module}, \scheme{lambda}, and similar bodies, this implies a
|
|
semantics similar to \scheme{let*} for a sequence of meta definitions,
|
|
in which each right-hand side can refer only to the variables defined
|
|
earlier in the sequence.
|
|
An exception is that the right-hand side of a meta definition can refer
|
|
to its own name as long as the reference is not evaluated until after
|
|
the value of the expression has been computed.
|
|
This permits meta definitions to be self-recursive but not mutually
|
|
recursive.
|
|
The right-hand side of a meta definition can, however, build syntax
|
|
objects containing occurrences of any identifiers defined in the body
|
|
in which the meta definition appears.
|
|
|
|
Meta definitions propagate through macro expansion, so one can write,
|
|
for example:
|
|
|
|
\schemedisplay
|
|
(module (a)
|
|
(meta define-record foo (x))
|
|
(define-syntax a
|
|
(let ([q (make-foo #''q)])
|
|
(lambda (x) (foo-x q)))))
|
|
a ;=> q
|
|
\endschemedisplay
|
|
|
|
where define-record is a macro that expands into a set of defines.
|
|
|
|
It is also sometimes convenient to write
|
|
|
|
\schemedisplay
|
|
(meta begin defn \dots)
|
|
\endschemedisplay
|
|
|
|
or
|
|
|
|
\schemedisplay
|
|
(meta module {exports} defn \dots)
|
|
\endschemedisplay
|
|
|
|
or
|
|
|
|
\schemedisplay
|
|
(meta include "\var{path}")
|
|
\endschemedisplay
|
|
|
|
to create groups of meta bindings.
|
|
|
|
\section{Conditional expansion\label{SECTSYNTAXMETACOND}}
|
|
|
|
Expansion-time decisions can be made via \scheme{meta-cond}, which is
|
|
similar to \scheme{cond} but evaluates the test expressions at
|
|
expansion time and can be used in contexts where definitions are
|
|
expected as well as in expression contexts.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{meta-cond}{\categorysyntax}{(meta-cond \var{clause_1} \var{clause_2} \dots)}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
Each \var{clause} but the last must take the form:
|
|
|
|
\schemedisplay
|
|
(\var{test} \var{expr_1} \var{expr_2} \dots)
|
|
\endschemedisplay
|
|
|
|
The last may take the same form or be an \scheme{else} clause of the form:
|
|
|
|
\schemedisplay
|
|
(\var{else} \var{expr_1} \var{expr_2} \dots)
|
|
\endschemedisplay
|
|
|
|
During expansion, the \var{test} expressions are evaluated in order until
|
|
one evaluates to a true value or until all of the tests have been
|
|
evaluated.
|
|
If a \var{test} evaluates to a true value, the \scheme{meta-cond} form
|
|
expands to a \scheme{begin} form containing the corresponding
|
|
expressions \scheme{\var{expr_1} \var{expr_2} \dots}.
|
|
If no \var{test} evaluates to a true value and an \scheme{else} clause
|
|
is present, the \scheme{meta-cond} form expands to a \scheme{begin} form
|
|
containing the expressions \scheme{\var{expr_1} \var{expr_2} \dots} from
|
|
the \scheme{else} clause.
|
|
Otherwise the \scheme{meta-cond} expression expands into a call to
|
|
the \scheme{void} procedure.
|
|
|
|
\scheme{meta-cond} might be defined as follows.
|
|
|
|
\schemedisplay
|
|
(define-syntax meta-cond
|
|
(syntax-rules ()
|
|
[(_ [a0 a1 a2 ...] [b0 b1 b2 ...] ...)
|
|
(let-syntax ([expr (cond
|
|
[a0 (identifier-syntax (begin a1 a2 ...))]
|
|
[b0 (identifier-syntax (begin b1 b2 ...))]
|
|
...)])
|
|
expr)]))
|
|
\endschemedisplay
|
|
|
|
\scheme{meta-cond} is used to choose, at expansion time, from among a
|
|
set of possible forms.
|
|
For example, one might have safe (error-checking) and unsafe
|
|
(non-error-checking) versions of a procedure and decide which to
|
|
call based on the compile-time optimization level, as shown
|
|
below.
|
|
|
|
\schemedisplay
|
|
(meta-cond
|
|
[(= (optimize-level) 3) (unsafe-frob x)]
|
|
[else (safe-frob x)])
|
|
\endschemedisplay
|
|
|
|
\section{Aliases\label{SECTSYNTAXALIAS}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{alias}{\categorysyntax}{(alias \var{id_1} \var{id_2})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{alias} is a definition and can appear anywhere
|
|
other definitions can appear.
|
|
It is used to transfer the binding from one identifier to
|
|
another.
|
|
|
|
\schemedisplay
|
|
(let ([x 3]) (alias y x) (set! y 4) (list x y)) ;=> (4 4)
|
|
|
|
(module lisp (if)
|
|
(module (scheme:if)
|
|
(import scheme)
|
|
(alias scheme:if if))
|
|
(define-syntax if
|
|
(syntax-rules ()
|
|
[(_ e_1 e_2 e_3)
|
|
(scheme:if (not (memq e_1 '(#f ()))) e_2 e_3)])))
|
|
(define (length ls)
|
|
(import lisp)
|
|
(if ls (+ (length (cdr ls)) 1) 0))
|
|
(length '(a b c)) ;=> 3
|
|
\endschemedisplay
|
|
|
|
Because of left-to-right expansion order, aliases should appear after
|
|
the definition of the right-hand-side identifier, e.g.:
|
|
|
|
\schemedisplay
|
|
(let ()
|
|
(import-only (chezscheme))
|
|
(define y 3)
|
|
(alias x y)
|
|
x) ;=> 3
|
|
\endschemedisplay
|
|
|
|
rather than:
|
|
|
|
\schemedisplay
|
|
(let ()
|
|
(import-only (chezscheme))
|
|
(alias x y)
|
|
(define y 3)
|
|
x) ;=> \var{exception: unbound identifier}
|
|
\endschemedisplay
|
|
|
|
|
|
\section{Annotations\label{SECTSYNTAXANNOTATIONS}}
|
|
|
|
\index{annotations}%
|
|
When source code is read from a file by \scheme{load},
|
|
\scheme{compile-file}, or variants of these, such as
|
|
\scheme{load-library}, the reader attaches \emph{annotations} to each
|
|
object read from the file.
|
|
These annotations identify the file and the position of the object within
|
|
the file.
|
|
Annotations are tracked through the compilation process and associated
|
|
with compiled code at run time.
|
|
The expander and compiler use the annotations to produce syntax errors
|
|
and compiler warnings that identify the location of the offending form,
|
|
and the inspector uses them to identify the locations of calls and
|
|
procedure definitions.
|
|
The compiler and run time also use annotations to associate source
|
|
positions with profile counts.
|
|
|
|
While these annotations are usually maintained ``behind the scenes,''
|
|
the programmer can manipulate them directly via a set
|
|
of routines for creating and accessing annotations.
|
|
|
|
Annotations are values of a type distinct from other types and have
|
|
four components: an expression, possibly with annotated subexpressions,
|
|
a \emph{source object}, a stripped version of the expression, and
|
|
usage options.
|
|
Annotations can be created via
|
|
\index{\scheme{make-annotation}}\scheme{make-annotation}, which has
|
|
three required arguments corresponding to the first three components
|
|
and an optional fourth argument corresponding to the fourth component.
|
|
The second argument must be a source object, and the third argument should be a
|
|
stripped version of the first argument, i.e., equivalent to the first
|
|
argument with each annotation replaced by its expression component.
|
|
An annotation is essentially equivalent to its stripped component as a
|
|
representation of source code, with the source information attached and
|
|
available to the expander or evaluator.
|
|
The optional fourth argument, if present, must be an enumeration set over
|
|
the symbols \scheme{debug} and \scheme{profile} and defaults to an
|
|
enumeration set containing both \scheme{debug} and \scheme{profile}.
|
|
|
|
Annotations marked \scheme{debug} are used for compile-time error
|
|
reporting and run-time error reporting and inspection; annotations
|
|
marked \scheme{profile} are used for profiling.
|
|
Annotations created by the Scheme reader are always marked both
|
|
\scheme{debug} and \scheme{profile}, but other readers and parsers
|
|
might choose to mark some annotations only \scheme{debug} or only
|
|
\scheme{profile}.
|
|
In particular, it might be useful to annotate multiple
|
|
expressions in the output of a parser with the same source object
|
|
for debugging purposes and mark only one of them \scheme{profile}
|
|
to avoid duplicate counts.
|
|
It might also be useful to mark no expressions \scheme{profile} and
|
|
instead introduce explicit \scheme{profile} forms
|
|
(Section~\ref{SECTMISCPROFILE}) to identify the set of source
|
|
locations to be profiled.
|
|
|
|
\index{source objects}%
|
|
Source objects are also values of a type distinct from other types and
|
|
also have three or five components: a \emph{source-file descriptor} (sfd),
|
|
a beginning file position (bfp), an ending file position (efp),
|
|
an optional beginning line, and an optional beginning
|
|
column. The sfd identifies the file from which an expression is read and the
|
|
bfp and efp identify the range of character positions occupied by the object
|
|
in the file, with the bfp being inclusive and the efp being exclusive.
|
|
The line and column are either both numbers or both not present.
|
|
A source object can be created via
|
|
\index{\scheme{make-source-object}}\scheme{make-source-object}, which
|
|
takes either three or five arguments corresponding to these components.
|
|
The first argument must be a source-file descriptor, the second and
|
|
third must be nonnegative exact integers, the second must not be
|
|
greater than the third, and the fourth and fifth (if provided) must
|
|
be positive exact integers.
|
|
|
|
\index{source-file descriptors}%
|
|
Source-file descriptors are also values of a type distinct
|
|
from all other types and have two components: the file's path,
|
|
represented by a string, and a checksum, represented by a number.
|
|
The path might or might not be an absolute path depending on how
|
|
the file's path was specified when the source-file descriptor was
|
|
created.
|
|
The checksum is computed based on the file's length and contents
|
|
when the file is created and checked by tools that look for the
|
|
source file to make sure that the proper file has been found and
|
|
has not been modified.
|
|
Source-file descriptors can be created with
|
|
\index{\scheme{make-source-file-descriptor}}\scheme{make-source-file-descriptor},
|
|
which accepts two arguments: a string naming the path and a binary
|
|
input port, along with an optional third boolean argument, \var{reset?},
|
|
which defaults to false.
|
|
\scheme{make-source-file-descriptor} computes a checksum based on
|
|
the contents of the port, starting at its current position.
|
|
It resets the port, using \scheme{set-port-position!}, after computing
|
|
the checksum if \var{reset?} is true; otherwise, it leaves the
|
|
port at end-of-file.
|
|
|
|
The procedures that create, check for, and access annotations,
|
|
source objects, and source-file descriptors are summarized below
|
|
and described in more detail later in this section.
|
|
|
|
\schemedisplay
|
|
(make-annotation \var{obj} \var{source-object} \var{obj}) ;-> \var{annotation}
|
|
(annotation? \var{obj}) ;-> \var{boolean}
|
|
(annotation-expression \var{annotation}) ;-> \var{obj}
|
|
(annotation-source \var{annotation}) ;-> \var{source-object}
|
|
(annotation-stripped \var{annotation}) ;-> \var{obj}
|
|
|
|
(make-source-object \var{sfd} \var{uint} \var{uint}) ;-> \var{source-object}
|
|
(make-source-object \var{sfd} \var{uint} \var{uint} \var{uint} \var{uint}) ;-> \var{source-object}
|
|
(source-object? \var{obj}) ;-> \var{boolean}
|
|
(source-object-sfd \var{source-object}) ;-> \var{sfd}
|
|
(source-object-bfp \var{source-object}) ;-> \var{uint}
|
|
(source-object-efp \var{source-object}) ;-> \var{uint}
|
|
(source-object-line \var{source-object}) ;-> \var{uint} or #f
|
|
(source-object-column \var{source-object}) ;-> \var{uint} or #f
|
|
|
|
(make-source-file-descriptor \var{string} \var{binary-input-port}) ;-> \var{sfd}
|
|
(make-source-file-descriptor \var{string} \var{binary-input-port} \var{reset?}) ;-> \var{sfd}
|
|
(source-file-descriptor? \var{obj}) ;-> \var{boolean}
|
|
(source-file-descriptor-checksum \var{sfd}) ;-> \var{obj}
|
|
(source-file-descriptor-path \var{sfd}) ;-> \var{obj}
|
|
\endschemedisplay
|
|
|
|
A program might open a source file with
|
|
\scheme{open-file-input-port}, create an sfd using
|
|
\index{\scheme{make-source-file-descriptor}}\scheme{make-source-file-descriptor},
|
|
create a textual port from the binary port using transcoded-port, and
|
|
create source objects and annotations for each of the objects it reads
|
|
from the file.
|
|
If a custom reader is not required, the Scheme
|
|
reader can be used to read annotations via the
|
|
\index{\scheme{get-datum/annotations}}\scheme{get-datum/annotations}
|
|
procedure:
|
|
|
|
\schemedisplay
|
|
(get-datum/annotations \var{textual-input-port} \var{sfd} \var{uint}) ;-> \var{obj}, \var{uint}
|
|
\endschemedisplay
|
|
|
|
\scheme{get-datum/annotations} is like \scheme{get-datum} but instead of returning
|
|
a plain datum, it returns an annotation encapsulating a datum (possibly with nested
|
|
annotations), a source object, and the plain (stripped) datum.
|
|
It also returns a second value, the position of the first character beyond the
|
|
object in the file.
|
|
Character positions are accepted and returned by
|
|
\scheme{get-datum/annotations} so that the textual port need not support
|
|
\scheme{port-position} and need not report positions in characters
|
|
if it does support \scheme{port-position}.
|
|
(Positions are usually reported in bytes.)
|
|
The bfp and efp positions recorded in the annotations returned by
|
|
\scheme{get-datum/annotations} are correct only if the positions supplied
|
|
to it are correct.
|
|
|
|
Once read, an annotation can be passed to the expander, interpreter, or
|
|
compiler.
|
|
The procedures \scheme{eval}, \scheme{expand}, \scheme{interpret},
|
|
and \scheme{compile} all accept annotated or unannotated input.
|
|
|
|
Two additional procedures complete the set of annotation-related primitives:
|
|
|
|
\schemedisplay
|
|
(open-source-file \var{sfd}) ;-> #f or \var{port}
|
|
(syntax->annotation \var{obj}) ;-> #f or \var{annotation}
|
|
\endschemedisplay
|
|
|
|
\index{\scheme{open-source-file}}\scheme{open-source-file} attempts to
|
|
locate and open the source file identified by \var{sfd}.
|
|
It returns a textual input port, positioned at the beginning of the file,
|
|
if successful, and \scheme{#f} otherwise.
|
|
|
|
\index{\scheme{syntax->annotation}}\scheme{syntax->annotation} accepts
|
|
a syntax object.
|
|
If the syntax object's expression is annotated, it returns the
|
|
annotation; otherwise, it returns \scheme{#f}.
|
|
It can be used by a macro to extract source information, when
|
|
available, from an input form.
|
|
|
|
The procedure \scheme{datum->syntax} accepts either an
|
|
annotated or unannotated input datum.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{make-annotation}{\categoryprocedure}{(make-annotation \var{obj} \var{source-object} \var{stripped-obj})}
|
|
\formdef{make-annotation}{\categoryprocedure}{(make-annotation \var{obj} \var{source-object} \var{stripped-obj} \var{options})}
|
|
\returns an annotation
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
The annotation is formed with \var{obj} as its expression component,
|
|
\var{source-object} as its source-object component, and \var{stripped-obj}
|
|
as its stripped component.
|
|
\var{obj} should represent an expression, possibly with embedded
|
|
annotations.
|
|
\var{stripped-obj} should be a stripped version of \var{obj}, i.e.,
|
|
equivalent to \var{obj} with each annotation replaced by its
|
|
expression component.
|
|
\var{options}, if present must be an enumeration set over
|
|
the symbols \scheme{debug} and \scheme{profile}, and defaults to an
|
|
enumeration set containing both \scheme{debug} and \scheme{profile}.
|
|
Annotations marked \scheme{debug} are used for compile-time error
|
|
reporting and run-time error reporting and inspection; annotations
|
|
marked \scheme{profile} are used for profiling.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{annotation?}{\categoryprocedure}{(annotation? \var{obj})}
|
|
\returns \scheme{#t} if \var{obj} is an annotation, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{annotation-expression}{\categoryprocedure}{(annotation-expression \var{annotation})}
|
|
\returns the expression component of \var{annotation}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{annotation-source}{\categoryprocedure}{(annotation-source \var{annotation})}
|
|
\returns the source-object component of \var{annotation}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{annotation-stripped}{\categoryprocedure}{(annotation-stripped \var{annotation})}
|
|
\returns the stripped component of \var{annotation}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{annotation-options}{\categoryprocedure}{(annotation-options \var{annotation})}
|
|
\returns the options enumeration set of \var{annotation}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{make-source-object}{\categoryprocedure}{(make-source-object \var{sfd} \var{bfp} \var{efp})}
|
|
\formdef{make-source-object}{\categoryprocedure}{(make-source-object \var{sfd} \var{bfp} \var{efp} \var{line} \var{column})}
|
|
\returns a source object
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{sfd} must be a source-file descriptor.
|
|
\var{bfp} and \var{efp} must be exact nonnegative integers, and \var{bfp}
|
|
should not be greater than \var{efp}.
|
|
\var{line} and \var{column} must be exact positive integers.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-object?}{\categoryprocedure}{(source-object? \var{obj})}
|
|
\returns \scheme{#t} if \var{obj} is a source object, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-object-sfd}{\categoryprocedure}{(source-object-sfd \var{source-object})}
|
|
\returns the sfd component of \var{source-object}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-object-bfp}{\categoryprocedure}{(source-object-bfp \var{source-object})}
|
|
\returns the bfp component of \var{source-object}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-object-efp}{\categoryprocedure}{(source-object-efp \var{source-object})}
|
|
\returns the efp component of \var{source-object}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-object-line}{\categoryprocedure}{(source-object-line \var{source-object})}
|
|
\returns the line component of \var{source-object} if present, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-object-column}{\categoryprocedure}{(source-object-column \var{source-object})}
|
|
\returns the column component of \var{source-object} if present, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-make-source-object}{\categorythreadparameter}{current-make-source-object}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{current-make-source-object} is used by the reader to construct
|
|
a source object for an annotation. \scheme{current-make-source-object}
|
|
is initially bound to \scheme{make-source-object}, and the reader always
|
|
calls the function bound to the paramater with three arguments.
|
|
|
|
Adjust this parameter to, for example, eagerly convert a position integer
|
|
to a file-position object, instead of delaying the conversion to
|
|
\scheme{locate-source}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{make-source-file-descriptor}{\categoryprocedure}{(make-source-file-descriptor \var{string} \var{binary-input-port})}
|
|
\formdef{make-source-file-descriptor}{\categoryprocedure}{(make-source-file-descriptor \var{string} \var{binary-input-port} \var{reset?})}
|
|
\returns a source-file descriptor
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
To compute the checksum encapsulated in the source-file descriptor,
|
|
this procedure must read all of the data from
|
|
\var{binary-input-port}.
|
|
If \var{reset?} is present and \scheme{#t}, the port is reset to its
|
|
original position, as if via \scheme{port-position}.
|
|
Otherwise, it is left pointing at end-of-file.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-file-descriptor?}{\categoryprocedure}{(source-file-descriptor? \var{obj})}
|
|
\returns \scheme{#t} if \var{obj} is a source-file descriptor, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-file-descriptor-checksum}{\categoryprocedure}{(source-file-descriptor-checksum \var{sfd})}
|
|
\returns the checksum component of \var{sfd}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-file-descriptor-path}{\categoryprocedure}{(source-file-descriptor-path \var{sfd})}
|
|
\returns the path component of \var{sfd}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{sfd} must be a source-file descriptor.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-file-descriptor}{\categoryprocedure}{(source-file-descriptor \var{path} \var{checksum})}
|
|
\returns a new source-file-descriptor
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string, and \var{checksum} must be an exact nonnegative integer.
|
|
This procedure can be used to construct custom source-file descriptors or to reconstitute
|
|
source-file descriptors from the \var{path} and \var{checksum} components.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{annotation-option-set}{\categorysyntax}{(annotation-option-set \var{symbol} \dots)}
|
|
\returns an annotation-options enumeration set
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
Annotation-options enumeration sets may be passed to \scheme{make-annotation} to
|
|
control whether the annotation is used for debugging, profiling, both, or neither.
|
|
Accordingly, each \var{symbol} must be either \var{debug} or \scheme{profile}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{syntax->annotation}{\categoryprocedure}{(syntax->annotation \var{obj})}
|
|
\returns an annotation or \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
If \var{obj} is an annotation or syntax-object encapsulating an annotation,
|
|
the annotation is returned.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-datum/annotations}{\categoryprocedure}{(get-datum/annotations \var{textual-input-port} \var{sfd} \var{bfp})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{sfd} must be a source-file descriptor.
|
|
\var{bfp} must be an exact nonnegative integer and should be the
|
|
character position of the next character to be read from
|
|
\var{textual-input-port}.
|
|
|
|
This procedure returns two values: an annotated object and an ending
|
|
file position.
|
|
In most cases, \var{bfp} should be 0 for the first call
|
|
to \scheme{get-datum/annotation} at the start of a file,
|
|
and it should be the second return value of the preceding
|
|
call to \scheme{get-datum/annotation} for each subsequent
|
|
call.
|
|
This protocol is necessary to handle files containing multiple-byte
|
|
characters, since file positions do not necessarily correspond
|
|
to character positions.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-source-file}{\categoryprocedure}{(open-source-file \var{sfd})}
|
|
\returns a port or \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{sfd} must be a source-file descriptor.
|
|
This procedure attempts to locate and open the source file identified
|
|
by \var{sfd}.
|
|
It returns a textual input port, positioned at the beginning of the file,
|
|
if successful, and \scheme{#f} otherwise.
|
|
It can fail even if a file with the correct name exists in one of
|
|
the source directories when the file's checksum does not match the
|
|
checksum recorded in \var{sfd}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{locate-source}{\categoryprocedure}{(locate-source \var{sfd} \var{pos})}
|
|
\formdef{locate-source}{\categoryprocedure}{(locate-source \var{sfd} \var{pos} \var{use-cache?})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{sfd} must be a source-file descriptor, and \var{pos} must be an
|
|
exact nonnegative integer.
|
|
|
|
This procedure either uses cached information from a previous
|
|
request for \var{sfd} (only when \var{use-cache?} is provided as true)
|
|
or attempts to locate and open the source file identified
|
|
by \var{sfd}.
|
|
If successful, it returns three values: a string \var{path}, an exact
|
|
nonnegative integer \var{line}, and an exact nonnegative integer \var{char}
|
|
representing the absolute pathname, line, and character position within
|
|
the line represented by the specified source-file descriptor and file
|
|
position.
|
|
If unsuccessful, it returns zero values.
|
|
It can fail even if a file with the correct name exists in one of
|
|
the source directories when the file's checksum does not match the
|
|
checksum recorded in \var{sfd}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{locate-source-object-source}{\categoryprocedure}{(locate-source-object-source \var{source-object} \var{get-start?} \var{use-cache?})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
This procedure is similar to \scheme{locate-source}, but instead of
|
|
taking an sfd and a position, it takes a source object plus a request
|
|
for either the start or end location.
|
|
|
|
If \var{get-start?} is true and \var{source-object} has a line and column,
|
|
this procedure returns the path in
|
|
\var{source-objects}'s sfd, \var{source-object}'s line, and
|
|
\var{source-objects}'s column.
|
|
|
|
If \var{source-object} has no line and column, then
|
|
this procedure calls \scheme{locate-source} on
|
|
\var{source-object}'s sfd, either \var{source-object}'s bfp or efp
|
|
depending on \var{get-start?}, and \var{use-cache?}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-locate-source-object-source}{\categorythreadparameter}{current-locate-source-object-source}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
|
|
\scheme{current-locate-source-object-source} determines the
|
|
source-location lookup function that is used by the system to report
|
|
errors based on source objects. This parameter is initially bound to
|
|
\scheme{locate-source-object-object}.
|
|
|
|
Adjust this parameter to control the way that source locations are
|
|
extracted from source objects, possibly using recorded information,
|
|
caches, and the filesystem in a way different from
|
|
\scheme{locate-source-object-object}.
|
|
|
|
|
|
\section{Source Tables\label{SECTSYNTAXSOURCETABLES}}
|
|
|
|
Source tables provide an efficient way to associate information
|
|
with source objects both in memory and on disk, such as the coverage information
|
|
saved to \scheme{.covin} files when
|
|
\index{\scheme{generate-covin-files}}\scheme{generate-covin-files} is
|
|
set to \scheme{#t}
|
|
and the profile counts associated with source objects by
|
|
\index{\scheme{with-profile-tracker}}\scheme{with-profile-tracker}
|
|
(Section~\ref{SECTMISCPROFILE}).
|
|
|
|
Source tables are manipulated via hashtable-like accessors and setters
|
|
(Section~\ref{SECTMISCHASHTABLES}, {\TSPLFOUR} Section~\ref{TSPL:SECTHASHTABLES}), e.g.,
|
|
\index{\scheme{source-table-ref}}\scheme{source-table-ref} and \index{\scheme{source-table-set!}}\scheme{source-table-set!}.
|
|
They can be saved to files via
|
|
\index{\scheme{put-source-table}}\scheme{put-source-table}
|
|
and restored via
|
|
\index{\scheme{get-source-table!}}\scheme{get-source-table!}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{make-source-table}{\categoryprocedure}{(make-source-table)}
|
|
\returns a source table
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
A source table contains associations between source objects and arbitrary
|
|
values. For purposes of the source-table operations described below, two
|
|
source objects are the same if they have the same source-file descriptor,
|
|
equal beginning file positions and equal ending file positions.
|
|
Two source-file descriptors are the same if they have the same path and
|
|
checksum.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table?}{\categoryprocedure}{(source-table? \var{obj})}
|
|
\returns \scheme{#t} if \var{obj} is a source-table; \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table-set!}{\categoryprocedure}{(source-table-set! \var{source-table} \var{source-object} \var{obj})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{source-table-set!} associates \var{source-object}
|
|
with \var{obj} in \var{source-table}, replacing the
|
|
existing association, if any.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table-ref}{\categoryprocedure}{(source-table-ref \var{source-table} \var{source-object} \var{default})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{default} may be any Scheme value.
|
|
|
|
\scheme{source-table-ref} returns the value
|
|
associated with \var{source-object} in \var{source-table}.
|
|
If no value is associated with \var{source-object} in \var{source-table},
|
|
\scheme{source-table-ref} returns \var{default}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table-contains?}{\categoryprocedure}{(source-table-contains? \var{source-table} \var{source-object})}
|
|
\returns \scheme{#t} if an association for \var{source-object} exists in \var{source-table}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table-cell}{\categoryprocedure}{(source-table-cell \var{source-table} \var{source-object} \var{default})}
|
|
\returns a pair (see below)
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{default} may be any Scheme value.
|
|
|
|
If no value is associated with \var{source-object} in \var{source-table},
|
|
\scheme{source-table-cell} modifies \var{source-table} to associate \var{source-object} with
|
|
\var{default}.
|
|
Regardless, it returns a pair whose car is \var{source-object} and whose cdr is
|
|
the associated value.
|
|
Changing the cdr of this pair effectively updates the table to
|
|
associate \var{source-object} with a new value.
|
|
The car field of the pair should not be modified.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table-delete!}{\categoryprocedure}{(source-table-delete! \var{source-table} \var{source-object})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{source-table-delete!} drops the association
|
|
for \var{source-object} from \var{source-table}, if
|
|
one exists.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{source-table-size}{\categoryprocedure}{(source-table-size \var{source-table})}
|
|
\returns the number of entries in \var{source-table}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{put-source-table}{\categoryprocedure}{(put-source-table \var{textual-output-port} \var{source-table})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
This procedure writes a representation of the information stored in \var{source-table} to the port.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-source-table!}{\categoryprocedure}{(get-source-table! \var{textual-input-port} \var{source-table})}
|
|
\formdef{get-source-table!}{\categoryprocedure}{(get-source-table! \var{textual-input-port} \var{source-table} \var{combine})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
The port must be positioned at a representation of source-table
|
|
information written by some previous call to \scheme{put-source-table},
|
|
which reads the information and merges it into \scheme{source-table}.
|
|
|
|
If present and non-false, \var{combine} must be a procedure and
|
|
should accept two arguments.
|
|
It is called whenever associations for the same source object are
|
|
present both in \var{source-table} and in the information read from
|
|
the port.
|
|
In this case, \var{combine} is passed two arguments: the associated
|
|
value from \var{source-table} and the associated value from the
|
|
port (in that order) and must return one value, which is recorded
|
|
as the new associated value for the source object in \var{source-table}.
|
|
|
|
If \var{combine} is not present, \var{combine} is \scheme{#f}, or
|
|
no association for a source object read from the port already exists
|
|
in \var{source-table}, the value read from the port is recorded as
|
|
the associated value of the source object in \var{source-table}.
|
|
|
|
\schemedisplay
|
|
(define st (make-source-table))
|
|
(call-with-port (open-input-file "profile.out1")
|
|
(lambda (ip) (get-source-table! ip st)))
|
|
(call-with-port (open-input-file "profile.out2")
|
|
(lambda (ip) (get-source-table! ip st +)))
|
|
\endschemedisplay
|