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

doc for make, mzcom, and mysterx (started) collections; Sam's patches to syntax/module-reader docs

Browse Source 
svn: r9324
This commit is contained in:
Matthew Flatt 2008-04-15 20:25:56 +00:00
parent 68f35e8b25
commit 09b52486b4
18 changed files with 3694 additions and 1422 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
collects/dynext/dynext.scrbl
View File

@ -3,7 +3,13 @@
@(require
scribble/manual
(for-label scheme
dynext))
dynext
dynext/compile-unit
dynext/compile-sig
dynext/link-unit
dynext/link-sig
dynext/file-unit
dynext/file-sig))
@title{@bold{Dynext}: Running a C Compiler/Linker}
@ -160,6 +166,22 @@ inlined in the corresponding position in the output list. This
expansion enables occasional parametrization of flag lists, etc.,
depending on the current compile variant.}
@subsection[#:tag "compile-sig"]{Signature}
@defmodule[dynext/compile-sig]
@defsignature[dynext:compile^ ()]
Includes everything exported by the @schememodname[dynext/compile] module.
@subsection[#:tag "compile-unit"]{Unit}
@defmodule[dynext/compile-unit]
@defthing[dyntex:compile@ unit?]{
Imports nothing, exports @scheme[dynext:compile^].}
@; ----------------------------------------------------------------------
@section{Linking}
@ -283,6 +305,23 @@ particular known linker.}
The same as @scheme[expand-for-compile-variant].}
@subsection[#:tag "link-sig"]{Signature}
@defmodule[dynext/link-sig]
@defsignature[dynext:link^ ()]
Includes everything exported by the @schememodname[dynext/link] module.
@subsection[#:tag "link-unit"]{Unit}
@defmodule[dynext/link-unit]
@defthing[dyntex:link@ unit?]{
Imports nothing, exports @scheme[dynext:link^].}
@; ----------------------------------------------------------------------
@section{Filenames}
@ -348,3 +387,21 @@ files.}
@defproc[(extract-base-filename/ext (s path-string?) (program any/c #f)) (or/c path? false/c)]{
Same as @scheme[extract-base-filename/c], but for extension files.}
@subsection[#:tag "file-sig"]{Signature}
@defmodule[dynext/file-sig]
@defsignature[dynext:file^ ()]
Includes everything exported by the @schememodname[dynext/file] module.
@subsection[#:tag "file-unit"]{Unit}
@defmodule[dynext/file-unit]
@defthing[dyntex:file@ unit?]{
Imports nothing, exports @scheme[dynext:file^].}

460
collects/html/doc.txt
View File

@ -1,460 +0,0 @@
_HTML_ Library, _html.ss_
=========================
(require (lib "html.ss" "html")) will provide functions to read
html documents and structures to represent them.
Functions:
==========
> read-xhtml : [Input-port] -> Html
> read-html : [Input-port] -> Html
> read-html-as-xml : [Input-port] -> (listof Content)
See the XML library for the definition of Content
HTML Structures:
================
Pcdata, Entity, and Attribute are defined in the XML documentation.
> Html-content = Html-element | Pcdata | Entity
> Html-element = any of the structures below which all inherit from
(define-struct html-element (attributes)). Any html tag that may
include content also inherits from
(define-struct (html-full struct:html-element) (content))
without adding any additional fields.
A Html is
(make-html (listof Attribute) (listof Contents-of-html))
A Contents-of-html is either
- Body
- Head
A Div is
(make-div (listof Attribute) G2)
A Center is
(make-center (listof Attribute) G2)
A Blockquote is
(make-blockquote (listof Attribute) G2)
An Ins is
(make-ins (listof Attribute) G2)
A Del is
(make-del (listof Attribute) G2)
A Dd is
(make-dd (listof Attribute) G2)
A Li is
(make-li (listof Attribute) G2)
A Th is
(make-th (listof Attribute) G2)
A Td is
(make-td (listof Attribute) G2)
An Iframe is
(make-iframe (listof Attribute) G2)
A Noframes is
(make-noframes (listof Attribute) G2)
A Noscript is
(make-noscript (listof Attribute) G2)
A Style is
(make-style (listof Attribute) Cdata)
A Script is
(make-script (listof Attribute) Cdata)
A Basefont is
(make-basefont (listof Attribute))
A Br is
(make-br (listof Attribute))
An Area is
(make-area (listof Attribute))
A Link is
(make-link (listof Attribute))
An Img is
(make-img (listof Attribute))
A Param is
(make-param (listof Attribute))
A Hr is
(make-hr (listof Attribute))
An Input is
(make-input (listof Attribute))
A Col is
(make-col (listof Attribute))
An Isindex is
(make-isindex (listof Attribute))
A Base is
(make-base (listof Attribute))
A Meta is
(make-meta (listof Attribute))
An Option is
(make-option (listof Attribute) Pcdata)
A Textarea is
(make-textarea (listof Attribute) Pcdata)
A Title is
(make-title (listof Attribute) Pcdata)
A Head is
(make-head (listof Attribute) (listof Contents-of-head))
A Contents-of-head is either
- Base
- Isindex
- Link
- Meta
- Object
- Script
- Style
- Title
A Tr is
(make-tr (listof Attribute) (listof Contents-of-tr))
A Contents-of-tr is either
- Td
- Th
A Colgroup is
(make-colgroup (listof Attribute) Col)
A Thead is
(make-thead (listof Attribute) Tr)
A Tfoot is
(make-tfoot (listof Attribute) Tr)
A Tbody is
(make-tbody (listof Attribute) Tr)
A Tt is
(make-tt (listof Attribute) G5)
An I is
(make-i (listof Attribute) G5)
A B is
(make-b (listof Attribute) G5)
An U is
(make-u (listof Attribute) G5)
A S is
(make-s (listof Attribute) G5)
A Strike is
(make-strike (listof Attribute) G5)
A Big is
(make-big (listof Attribute) G5)
A Small is
(make-small (listof Attribute) G5)
An Em is
(make-em (listof Attribute) G5)
A Strong is
(make-strong (listof Attribute) G5)
A Dfn is
(make-dfn (listof Attribute) G5)
A Code is
(make-code (listof Attribute) G5)
A Samp is
(make-samp (listof Attribute) G5)
A Kbd is
(make-kbd (listof Attribute) G5)
A Var is
(make-var (listof Attribute) G5)
A Cite is
(make-cite (listof Attribute) G5)
An Abbr is
(make-abbr (listof Attribute) G5)
An Acronym is
(make-acronym (listof Attribute) G5)
A Sub is
(make-sub (listof Attribute) G5)
A Sup is
(make-sup (listof Attribute) G5)
A Span is
(make-span (listof Attribute) G5)
A Bdo is
(make-bdo (listof Attribute) G5)
A Font is
(make-font (listof Attribute) G5)
A P is
(make-p (listof Attribute) G5)
A H1 is
(make-h1 (listof Attribute) G5)
A H2 is
(make-h2 (listof Attribute) G5)
A H3 is
(make-h3 (listof Attribute) G5)
A H4 is
(make-h4 (listof Attribute) G5)
A H5 is
(make-h5 (listof Attribute) G5)
A H6 is
(make-h6 (listof Attribute) G5)
A Q is
(make-q (listof Attribute) G5)
A Dt is
(make-dt (listof Attribute) G5)
A Legend is
(make-legend (listof Attribute) G5)
A Caption is
(make-caption (listof Attribute) G5)
A Table is
(make-table (listof Attribute) (listof Contents-of-table))
A Contents-of-table is either
- Caption
- Col
- Colgroup
- Tbody
- Tfoot
- Thead
A Button is
(make-button (listof Attribute) G4)
A Fieldset is
(make-fieldset (listof Attribute) (listof Contents-of-fieldset))
A Contents-of-fieldset is either
- Legend
- G2
An Optgroup is
(make-optgroup (listof Attribute) Option)
A Select is
(make-select (listof Attribute) (listof Contents-of-select))
A Contents-of-select is either
- Optgroup
- Option
A Label is
(make-label (listof Attribute) G6)
A Form is
(make-form (listof Attribute) G3)
An Ol is
(make-ol (listof Attribute) Li)
An Ul is
(make-ul (listof Attribute) Li)
A Dir is
(make-dir (listof Attribute) Li)
A Menu is
(make-menu (listof Attribute) Li)
A Dl is
(make-dl (listof Attribute) (listof Contents-of-dl))
A Contents-of-dl is either
- Dd
- Dt
A Pre is
(make-pre (listof Attribute) (listof Contents-of-pre))
A Contents-of-pre is either
- G9
- G11
An Object is
(make-object (listof Attribute) (listof Contents-of-object-applet))
An Applet is
(make-applet (listof Attribute) (listof Contents-of-object-applet))
A Contents-of-object-applet is either
- Param
- G2
A Map is
(make-map (listof Attribute) (listof Contents-of-map))
A Contents-of-map is either
- Area
- Fieldset
- Form
- Isindex
- G10
An A is
(make-a (listof Attribute) (listof Contents-of-a))
A Contents-of-a is either
- Label
- G7
An Address is
(make-address (listof Attribute) (listof Contents-of-address))
A Contents-of-address is either
- P
- G5
A Body is
(make-body (listof Attribute) (listof Contents-of-body))
A Contents-of-body is either
- Del
- Ins
- G2
A G12 is either
- Button
- Iframe
- Input
- Select
- Textarea
A G11 is either
- A
- Label
- G12
A G10 is either
- Address
- Blockquote
- Center
- Dir
- Div
- Dl
- H1
- H2
- H3
- H4
- H5
- H6
- Hr
- Menu
- Noframes
- Noscript
- Ol
- P
- Pre
- Table
- Ul
A G9 is either
- Abbr
- Acronym
- B
- Bdo
- Br
- Cite
- Code
- Dfn
- Em
- I
- Kbd
- Map
- Pcdata
- Q
- S
- Samp
- Script
- Span
- Strike
- Strong
- Tt
- U
- Var
A G8 is either
- Applet
- Basefont
- Big
- Font
- Img
- Object
- Small
- Sub
- Sup
- G9
A G7 is either
- G8
- G12
A G6 is either
- A
- G7
A G5 is either
- Label
- G6
A G4 is either
- G8
- G10
A G3 is either
- Fieldset
- Isindex
- G4
- G11
A G2 is either
- Form
- G3

18
collects/html/html.scrbl
View File

@ -1,13 +1,13 @@
#lang scribble/doc
@(require scribble/manual
scribble/eval
(for-label html/html)
(for-label html)
(for-label xml))
@title{@bold{HTML}: Parsing Library}
@defmodule[html/html]{The @schememodname[html/html] library provides
@defmodule[html]{The @schememodname[html] library provides
functions to read html documents and structures to represent them.}
@ -23,10 +23,10 @@ Reads (X)HTML from a port, producing an @scheme[html] instance.}
@defproc[(read-html-as-xml [port input-port?])
(listof content)]{
(listof content?)]{
Reads HTML from a port, producing an xexpr compatible with the
@schememodname[xml] library (which defines @scheme[content]).}
@schememodname[xml] library (which defines @scheme[content?]).}
@ -34,10 +34,10 @@ Reads HTML from a port, producing an xexpr compatible with the
@def+int[
(module html-example scheme
(code:comment #, @t{Some of the symbols in html/html and xml conflict with})
(code:comment #, @t{Some of the symbols in @schememodname[html] and @schememodname[xml] conflict with})
(code:comment #, @t{each other and with scheme/base language, so we prefix})
(code:comment #, @t{to avoid namespace conflict.})
(require (prefix-in h: html/html)
(require (prefix-in h: html)
(prefix-in x: xml))
(define an-html
@ -198,9 +198,9 @@ An @scheme[area] is
@scheme[(make-area (listof attribute))]
}
@defstruct[(link html-element) ()]{
A @scheme[link] is
@scheme[(make-link (listof attribute))]
@defstruct[(alink html-element) ()]{
A @scheme[alink] is
@scheme[(make-alink (listof attribute))]
}
@defstruct[(img html-element) ()]{

30
collects/make/collection-unit.ss
View File

@ -14,9 +14,8 @@
(define-unit make:collection@
(import make^
dynext:file^
(prefix compiler:option: compiler:option^)
compiler^)
dynext:file^
compiler^)
(export make:collection^)
(define (make-collection
@ -25,40 +24,18 @@
argv)
(printf "building collection ~a: ~a~n" collection-name collection-files)
(let* ([zo-compiler #f]
[ext-compiler #f]
[dest-dir (build-path "compiled" "native" (system-library-subpath))]
[src-dir (current-directory)]
[sses (sort collection-files
(lambda (a b) (string-ci<? (path->string a) (path->string b))))]
[bases (map (lambda (src)
(extract-base-filename/ss src 'make-collection-extension))
sses)]
[cs (map
(lambda (base)
(build-path
"compiled"
"native"
(append-c-suffix base)))
bases)]
[zos (map
(lambda (base)
(build-path
"compiled"
(append-zo-suffix base)))
bases)]
[kps (map
(lambda (base)
(build-path
"compiled"
"native"
(append-constant-pool-suffix base)))
bases)]
[objs (map
(lambda (base)
(build-path
dest-dir
(append-object-suffix base)))
bases)]
[ss->zo-list
(map (lambda (ss zo)
`(,zo (,ss)
@ -68,9 +45,6 @@
(zo-compiler (list ss) "compiled"))))
sses zos)])
(unless (directory-exists? "compiled") (make-directory "compiled"))
(unless (or (equal? argv #("zo"))
(directory-exists? dest-dir))
(make-directory* dest-dir))
(make/proc
(append
`(("zo" ,zos))

289
collects/make/doc.txt
View File

@ -1,289 +0,0 @@
_Overview of make_
------------------
This library provides a Scheme version of the standard Unix
`make' utility. Its syntax is intended to simulate regular
Unix make in Scheme.
If you are already familiar with make, skip down the precise
details of the make collection. This section contains a
brief overview of make. The idea is to explain how to
generate some project you have from a collection of source
files that go through several stages of processing.
For example, lets say that you are writing some project that
has three input files (that you create and maintain) called
a.input, b.input, and c.input. Further, there are two stages
of processing -- first you run a particular tool
"make-output" that takes an input file and produces and
output file, and second you combine the input files into a
single file using "output". Using make, you might write
this:
a.output: a.input
make-output a.input a.output
b.output: b.input
make-output b.input b.output
c.output: c.input
make-output c.input c.output
total: a.output b.output c.output
combine a.output b.output c.output
Once you've put those above lines in a file called
"Makefile", you can issue the command:
make total
that builds your entire project. The Makefile consists of
several lines that tell `make' how to create each piece. The
first two lines say that a.output depends on a.input and the
command for making a.output from a.input is
make-output a.input a.output
The point of this exercise is that the `make' utility looks
at the file creation dates of the various files and only
re-builds what is necessary. Make is based on building
things with shell programs. If, on the other hand, you want
to build similar things with various Scheme programs, you
can use the make collection.
Here's the equivalent Scheme program:
(require make)
(define (make-output in out)
...)
(define (combine-total . args)
...)
(make
(("a.output" ("a.input") (make-output "a.output" "a.input"))
("b.output" ("b.input") (make-output "b.output" "b.input"))
("c.output" ("c.input") (make-output "c.output" "c.input"))
("total" ("a.output" "b.output" "c.output")
(combine-total "a.output" "b.output" "c.output")))
If you were to fill in the ellipses above with calls to
`system', you'd have the exact same thing as the original
Makefile. In addition, if you use `make/proc', you can
abstract over the various make lines (for example, the
a.output, b.output, and c.output lines are very similar and
it would be good to write a program to generate those
lines).
_make.ss_
---------
The make library in the `make' collection provides a
`make' macro and a `make/proc' procedure.
> (make ((target (depend ...) command ...) ...) argv)
expands to
(make/proc
(list (list target (list depend ...) (lambda () command ...)) ...)
argv)
> (make/proc spec argv) performs a make according to `spec'
and using `argv' as command-line arguments selecting one
or more targets. `argv' can either be a string or a
vector of strings.
`spec' is a MAKE-SPEC:
MAKE-SPEC = (list-of MAKE-LINE)
MAKE-LINE = (list TARGET (list-of DEPEND-STRING) COMMAND-THUNK)
TARGET = (union string (list-of string)) ; either a string or a list of strings
DEPEND-STRING = string
COMMAND-THUNK = (-> void)
To make a target, make/proc is first called on each of the
target's dependencies. If a target is not in the spec and it
exists, then the target is considered made. If a target is
older than any of its dependencies, the corresponding
COMMAND-THUNK is invoked. The COMMAND-THUNK is optional; a
MAKE-LINE without a COMMAND-THUNK is useful as a target for
making a number of other targets (the dependencies).
`make/proc' catches any exceptions raised by a COMMAND-THUNK
and wraps them in an exn:fail:make structure, and raises the
wrapped exn. exn:fail:make structures are defined with:
(define-struct (exn:fail:make exn:fail) (target orig-exn))
The `target' field is a string or a list of strings naming
the target(s), and the `orig-exn' field is the original
exception.
make also provides the following parameters:
> (make-print-checking [on?]) - If #f, make only prints when
it is making a target. Otherwise, it prints when it is
checking the dependencies of a target. Default: #t.
> (make-print-dep-no-line [on?]) - If #f, make only prints
"checking..." lines for dependencies that have a
corresponding make line. Default: #f.
> (make-print-reasons [on?]) If #t, make prints the reason
for each dependency that fires. Default: #t.
The make-sig.ss library provides `make^' signature that includes all
of the above.
The make-unit.ss library provides a `make@' unit with no imports and the
single export `make^'.
_collection.ss_
---------------
[index entry: _collections, compiling_]
The collection.ss library in the make collection provides a
`make-collection' procedure.
> (make-collection collection-name collection-files argv) constructs
and performs a make to compile a collection of Scheme files into a
multi-file extension. `collection-name' is used as a name that is
embedded into publicly visible names in the extension (choosing a
unique `collection-name' for each extension helps avoid conflicts
among different extensions for certain operating
systems). `collection-files' is a list of Scheme source files to be
compiled. `argv' is passed on to `make'.
The resulting extension "_loader" is compiled to the current
directory's "compiled/native/PLATFORM" subdirectory, where `PLATFORM'
is replaced by the system name of the current platform. Intermediate
.c and .kp files are placed into "compiled/native", and intermediate
object files are also placed into "compiled/native/PLATFORM". The .c
and .kp files are preserved so that they can be generated once for
compiling across multiple platforms with the same filesystem.
Make rules are also generated for compiling .zo files, placed in the
"compiled" directory. The make target "zo" makes all of the .zo
files. (In other words, pass #("zo") as `argv' to compile .zo files.)
The "compiled", "compiled/native", etc. directories are automatically
created if they do not already exist. Currently, `make-collection'
does not try to infer sophisticated file dependencies. Each .c/.kp/.zo
is dependent just on the .ss source file, each object file is depend
only on its .c file, and the extension is dependent only on the
object files.
_setup-extension.ss_
--------------------
[index entry: _Setup PLT compile extension_]
The "setup-extension.ss" library helps compile C code via Setup PLT's
"pre-install" phase (triggered by a `pre-installer' item in "info.ss";
see the "setup" collection for further information).
The `pre-install' function takes a number of arguments that describe
how the C code is compiled, mainly the libraries that it depends
on. It then drives a C compiler via the "dynext" collection functions.
Many issues can complicate C compilation, and the `pre-install'
function helps with a few:
* finding non-standard libraries and header files,
* taming to some degree the differing conventions of Unix and
Windows,
* setting up suitable dependencies on MzScheme headers, and
* using a pre-compiled binary when a "precompiled" directory
is present.
Many extension installers will have to sort out addition platform
issues manually, however. For example, an old "readline" installer
used to pick whether to link to "libcurses" or "libncurses"
heuristically by inspecting "/usr/lib". More generally, the "last
chance" argument to `pre-install' allows an installer to patch
compiler and linker options (see "dynext") before the C code is
compiled or linked.
> (pre-install plthome-dir
collection-dir
file.c
default-lib-dir
include-subdirs
find-unix-libs
find-windows-libs
unix-libs
windows-libs
extra-depends
last-chance-k
[3m-too? #f])
The arguments are as follows:
* plthome-dir --- the directory provided to a `pre-installer'
function.
* collection-dir --- a directory to use as the current directory
while building.
* file.c --- the name of the source file (relative to
`collection-dir'). The output file will be the same, except with a
".c" suffix replaced with ".so" or ".dll" (depending on the
platform) and the path changed to "compiled/native/<platform>".
If "precompiled/native/<platform>/file.{so,dll} exists", then
`file.c' is not used at all, and the file in the "precompiled"
directory is simply copied.
* default-lib-dir --- a default directory for finding supporting
libraries, often a subdirectory of `collection-dir'. The user
can supplement this path by setting the PLT_EXTENSION_LIB_PATHS
environment variable. [Index entry: _PLT_EXTENSION_LIB_PATHS_]
This one environment variable applies to all extensions manged
by `pre-install'.
* include-subdirs --- a list of relative paths in which include
files will be found; the path of the path will be determined
through a search, in case it's not in a standard place like
/usr/include.
For example, the list is '("openssl") for the "openssl"
collection, because the source uses "#include <openssl/ssl.h>" and
"#include <openssl/err.h>".
* find-unix-libs --- like `include-subdirs', but a list of library
bases. Leave off the "lib" prefix and any suffix (such as ".a" or
".zo"). For "openssl", the list is '("ssl" "crypto"). This name
will get a "-l" prefix on the link line.
* find-windows-libs --- like `find-unix-libs', but for Windows. The
library name will be suffixed with ".lib" and supplied directly to
the linker.
* unix-libs --- like `find-unix-libs', except that the installer
makes no attempt to find the libraries in a non-standard
place. For example, the "readline" installer supplies '("curses").
* windows-libs --- like `unix-libs', but for Windows. For example,
the "openssl" installer supplies '("wsock32").
* extra-depends --- a list of relative paths to treat as
dependencies for compiling `file.c'. Often this list will include
`file.c' with the ".c" suffix replaced by ".ss" or ".scm". For
example, the "openssl" installer supplies '("mzssl.ss") to ensure
that the stub module "mzssl.ss" is never used when the true
extension can be built.
* last-chance-k --- a procedure of one argument, which is a thunk.
this procedure should invoke the thunk to make the file, but may
add parameterizations before the final build. For example, the
"readline" installer adds an AIX-specific compile flag in this
step when under AIX.
* 3m-too?--- a boolean. If true, when the 3m variant is installed,
use the equivalent to mzc --xform to transform the source file and
then compile and link for 3m. Otherwise, the extension is built
only for CGC when the CGC variant is installed.

3
collects/make/info.ss Normal file
View File

@ -0,0 +1,3 @@
#lang setup/infotab
(define scribblings '(("make.scrbl" (multi-page))))

374
collects/make/make.scrbl Normal file
View File

@ -0,0 +1,374 @@
#lang scribble/doc
@(require scribble/manual
(for-label scheme/base
scheme/contract
scheme/unit
make
make/make-unit
make/make-sig
make/collection
make/collection-sig
make/collection-unit
dynext/file-sig
compiler/sig))
@(define mzc-manual @other-manual['(lib "scribblings/mzc/mzc.scrbl")])
@title{@bold{Make}: Dependency Manager}
The @schememodname[make] library provides a Scheme version of the
standard Unix @exec{make} utility. Its syntax is intended to imitate
regular Unix make, but in Scheme.
@table-of-contents[]
@; ----------------------------------------------------------------------
@section[#:tag "overview"]{Overview}
@margin-note{If you want to build Scheme modules with automatic
dependency tracking, just use @exec{mzc} as described in
@|mzc-manual|.}
If you are already familiar with @exec{make}, skip to the precise
details of the @schememodname[make] library in @secref["make"]. This
section contains a brief overview of @exec{make} for everyone
else. The idea is to explain how to generate some project you have
from a collection of source files that go through several stages of
processing.
For example, let's say that you are writing some project that has
three input files (that you create and maintain) called
@filepath{a.input}, @filepath{b.input}, and
@filepath{c.input}. Further, there are two stages of processing: first
you run a particular tool @exec{make-output} that takes an input file
and produces and output file, and second you combine the input files
into a single file using @filepath{output}. Using @exec{make}, you
might write this:
@verbatim[#:indent 2]{
a.output: a.input
make-output a.input a.output
b.output: b.input
make-output b.input b.output
c.output: c.input
make-output c.input c.output
total: a.output b.output c.output
combine a.output b.output c.output
}
Once you've put those above lines in a file called
@filepath{Makefile} you can issue the command:
@commandline{make total}
that builds your entire project. The @filepath{Makefile} consists of
several lines that tell @exec{make} how to create each piece. The
first two lines say that @filepath{a.output} depends on
@filepath{a.input} and the command for making @filepath{a.output} from
@filepath{a.input} is
@commandline{make-output a.input a.output}
The point of using @exec{make} is that it looks at the file creation
dates of the various files and only re-builds what is necessary.
The @exec{make} utility builds things with shell programs. If, on the
other hand, you want to build similar things with various Scheme
programs, you can use the @schememodname[make] library.
Here's the equivalent Scheme program:
@schemeblock[
(require make)
(define (make-output in out)
....)
(define (combine-total . args)
....)
(make
(("a.output" ("a.input") (make-output "a.output" "a.input"))
("b.output" ("b.input") (make-output "b.output" "b.input"))
("c.output" ("c.input") (make-output "c.output" "c.input"))
("total" ("a.output" "b.output" "c.output")
(combine-total "a.output" "b.output" "c.output"))))
]
If you were to fill in the ellipses above with calls to
@scheme[system], you'd have the exact same thing as the original
@filepath{Makefile}. In addition, if you use @scheme[make/proc]], you
can abstract over the various make lines (for example, the
@filepath{a.output}, @filepath{b.output}, and @filepath{c.output}
lines are similar, and it would be good to write a program to generate
those lines).
@; ----------------------------------------------------------------------
@section[#:tag "make"]{Make from Dependencies}
@defmodule[make]
@defform[(make ((target-expr (depend-expr ...)
command-expr ...)
...)
argv-expr)]{
Expands to
@schemeblock[
(make/proc
(list (list target-expr (list depend-expr ...)
(lambda () command-expr ...)) ...)
argv-expr)
]}
@defproc[(make/proc [spec (listof
(cons/c (or/c path-string? (listof path-string?))
(cons/c (listof path-string?)
(or/c null?
(list/c (-> any))))))]
[argv (or/c string? (vectorof string?))]) void?]
Performs a make according to @scheme[spec] and using @scheme[argv] as
command-line arguments selecting one or more targets.
Each element of the @scheme[spec] list is a target. A target element
that starts with a list of strings is the same as multiple elements,
one for each string. The second element of each target is a list of
dependencies, and the third element (if any) of a target is the
optional command thunk.
To make a target, @scheme[make/proc] is first called recursively on
each of the target's dependencies. If a target is not in @scheme[spec]
and it exists as a file, then the target is considered made. If a
target's modification date is older than any of its dependencies'
modification dates, the corresponding command thunk is called. If the
dependency has no command thunk then no action is taken; such a target
is useful for triggering the make of other targets (i.e., the
dependencies).
While running a command thunk, @scheme[make/proc] catches exceptions
and wraps them in an @scheme[exn:fail:make] structure, the raises the
resulting structure.}
@defstruct[(exn:fail:make exn:fail) ([target (or/c path-string? (listof path-string?))]
[orig-exn any/c])]{
The @scheme[target] field is a list of list of strings naming the
target(s), and the @scheme[orig-exn] field is the original raised
value.}
@defboolparam[make-print-checking on?]{
A parameter that controls whether @scheme[make/proc] prints a message
when making a target. The default is @scheme[#t].}
@defboolparam[make-print-dep-no-line on?]{
A parameter that controls whether @scheme[make/proc] prints
``checking...'' lines for dependencies that have no target in the
given k@scheme[_spec]. The default is @scheme[#f].}
@defboolparam[make-print-reasons on?]{
A parameter that controls whether @scheme[make/proc] prints the reason
that a command thunk is called. The default is @scheme[#t].}
@; ----------------------------------------
@subsection[#:tag "make-signature"]{Signature}
@defmodule[make/make-sig]
@defsignature[make^ ()]{
Includes all of the names provided by @schememodname[make].}
@; ----------------------------------------
@subsection[#:tag "make-unit"]{Unit}
@defmodule[make/make-unit]
@defthing[make@ unit?]{
A unit that imports nothing and exports @scheme[make^].}
@; ----------------------------------------------------------------------
@section[#:tag "setup-extension"]{Building Native-Code Extensions}
@defmodule[make/setup-extension]
The @schememodname[make/setup-extension] library helps compile C code
via Setup PLT's ``pre-install'' phase (triggered by a
@schemeidfont{pre-install-collection} item in @filepath{info.ss}; see
also @secref[#:doc '(lib "scribblings/setup-plt/setup-plt.scrbl")
"setup-info"]).
The @scheme[pre-install] function takes a number of arguments that
describe how the C code is compiled---mainly the libraries that it
depends on. It then drives a C compiler via the
@schememodname[dynext/compile] and @schememodname[dynext/link]
functions.
Many issues can complicate C compilation, and the @scheme[pre-install]
function helps with a few:
@itemize[
@item{finding non-standard libraries and header files,}
@item{taming to some degree the differing conventions of Unix and
Windows, }
@item{setting up suitable dependencies on PLT Scheme headers, and}
@item{using a pre-compiled binary when a @filepath{precompiled}
directory is present.}
]
Many extension installers will have to sort out addition platform
issues manually, however. For example, an old @filepath{readline}
installer used to pick whether to link to @filepath{libcurses} or
@filepath{libncurses} heuristically by inspecting
@filepath{/usr/lib}. More generally, the ``last chance'' argument to
@scheme[pre-install] allows an installer to patch compiler and linker
options (see @schememodname[dynext/compile] and
@schememodname[dynext/link]) before the C code is compiled or linked.
@defproc[(pre-install
[plthome-dir path-string?]
[collection-dir path-string?]
[c-file path-string?]
[default-lib-dir path-string?]
[include-subdirs (listof path-string?)]
[find-unix-libs (listof string?)]
[find-windows-libs (listof string?)]
[unix-libs (listof string?)]
[windows-libs (listof string?)]
[extra-depends (listof path-string?)]
[last-chance-k ((-> any) . > . any)]
[3m-too? any/c #f])
void?]{
The arguments are as follows:
@itemize[
@item{@scheme[plthome-dir] --- the directory provided to a `pre-installer'
function.}
@item{@scheme[collection-dir] --- a directory to use as the current directory
while building.}
@item{@scheme[c-file] --- the name of the source file (relative to
@scheme[collection-dir]). The output file will be the same, except
with a @filepath{.c} suffix replaced with @scheme[(system-type
'so-suffix)], and the path changed to @scheme[(build-path
"compiled" "native" (system-library-subpath))].
If @scheme[(build-path "precompiled" "native"
(system-library-subpath) (path-replace-suffix c-file (system-type
'so-suffix)))] exists, then @scheme[c-file] is not used at all,
and the file in the @filepath{precompiled} directory is simply
copied.}
@item{@scheme[default-lib-dir] --- a default directory for finding
supporting libraries, often a subdirectory of
@filepath{collection-dir}. The user can supplement this path by
setting the @indexed-envvar{PLT_EXTENSION_LIB_PATHS} environment
variable, which applies to all extensions manged by
@scheme[pre-install].}
@item{@scheme[include-subdirs] --- a list of relative paths in which
@tt{#include} files will be found; the path will be determined
through a search, in case it's not in a standard place like
@filepath{/usr/include}.
For example, the list used to be @scheme['("openssl")] for the
@filepath{openssl} collection, because the source uses
@tt{#include <openssl/ssl.h>} and @tt{#include <openssl/err.h>}.}
@item{@scheme[find-unix-libs] --- like @scheme[include-subdirs], but
a list of library bases. Leave off the @filepath{lib} prefix and
any suffix (such as @filepath{.a} or @filepath{.so}). For
@filepath{openssl}, the list used to be @scheme['("ssl"
"crypto")]. Each name will essentially get a @tt{-l} prefix for
the linker command line.}
@item{@scheme[find-windows-libs] --- like @scheme[find-unix-libs],
but for Windows. The library name will be suffixed with
@filepath{.lib} and supplied directly to the linker.}
@item{@scheme[unix-libs] --- like @scheme[find-unix-libs], except
that the installer makes no attempt to find the libraries in a
non-standard place. For example, the @filepath{readline} installer
used to supply @scheme['("curses")].}
@item{@scheme[windows-libs] --- like @scheme[unix-libs], but for
Windows. For example, the @filepath{openssl} installer used to
supply @scheme['("wsock32")].}
@item{@scheme[extra-depends] --- a list of relative paths to treat as
dependencies for compiling `file.c'. Often this list will include
`file.c' with the ".c" suffix replaced by ".ss" or ".scm". For
example, the "openssl" installer supplies '("mzssl.ss") to ensure
that the stub module "mzssl.ss" is never used when the true
extension can be built.}
@item{@scheme[last-chance-k] --- a procedure of one argument, which
is a thunk. This procedure should invoke the thunk to make the
file, but it may add parameterizations before the final build. For
example, the @filepath{readline} installer used to add an
AIX-specific compile flag in this step when compiling under AIX.}
@item{@scheme[3m-too?]--- a boolean. If true, when the 3m variant is
installed, use the equivalent to @exec{mzc --xform} to transform
the source file and then compile and link for 3m. Otherwise, the
extension is built only for CGC when the CGC variant is installed.}
]}
@; ----------------------------------------------------------------------
@section[#:tag "collection"]{Making Collections}
@defmodule[make/collection]
@defproc[(make-collection [collection-name any/c]
[collection-files (listof path-string?)]
[argv (or/c string? (vectorof string?))])
void?]{
Builds bytecode files for each file in @scheme[collection-files],
writing each to a @filepath{compiled} subdirectory and automatically
managing dependencies. Supply @scheme['#("zo")] as @scheme[argv] to
compile all files. The @scheme[collection-name] argument is used only
for printing status information.
Compilation is performed as with @exec{mzc --make} (see
@|mzc-manual|).}
@subsection{Signature}
@defmodule[make/collection-sig]
@defsignature[make:collection^ ()]{
Provides @schemeidfont{make-collection}.}
@subsection{Unit}
@defmodule[make/collection-unit]
@defthing[make:collection@ unit?]{
Imports @scheme[make^], @scheme[dynext:file^], and @scheme[compiler^],
and exports @scheme[make:collection^].}

2
collects/mysterx/info.ss
View File

@ -1,3 +1,5 @@
#lang setup/infotab
(define post-install-collection "installer.ss")
(define scribblings '(("mysterx.scrbl" (multi-page))))

3064
collects/mysterx/mysterx.scrbl Normal file
View File

File diff suppressed because it is too large Load Diff

189
collects/mzcom/doc.txt
View File

@ -1,189 +0,0 @@
_MzCOM_
=======
This directory contains the files for MzCOM, a COM
class wrapper for MzScheme.
The code is in the file mzcom.exe. During normal
installation of MzCOM from the file mzcom.plt, the
executable is registered automatically. You can
move the .exe to whatever location you like, but
you'll need to re-register it. From the command
line, run
mzcom.exe /RegServer
If you move mzcom.exe, you'll also need to set the Windows
environment variables PLTHOME or PLTCOLLECTS for
MzCOM to find collections.
The mzcom.exe executable also requires the dynamic
libraries libmzsch<version>.dll and libmzgc<version>.dll.
Those files must be in your PATH. If you have DrScheme
installed, those files are in the System32 subdirectory of the
main Windows directory, which is in the default Windows PATH.
Loading MzCOM
-------------
To load a COM object, COM hosts require a COM class
name or a ProgID. MzCOM has the class name
"MzObj Class" and the ProgID "MzCOM.MzObj.<version>",
where <version> is the version number, such as 200.
In the Visual BASIC 6 environment, from the menu
Project|References (VB6), check "MzCOM 1.0 Type Library".
In Visual BASIC .NET, choose Project|Add Reference,
and from the COM tab, select "MzCOM 1.0 Type Library".
In your code, declare a variable, then assign to it:
DIM schemeObject AS MzObj
SET schemeObject = NEW MzObj
From Visual C++:
#include "mzcom.h"
CLSID clsid;
IMzObj *pIMzObj;
CoInitialize(NULL);
CLSIDFromProgID(L"MzCOM.MzObj.<version>",&clsid);
CoCreateInstance(clsid,NULL,CLSCTX_SERVER,IID_IMzObj,
(void **)&pIMzObj);
where <version> is the version number. You'll need the
definition of IID_IMzObj (see GUID's, below). The header
file mzcom.h is in plt\src\worksp\mzcom\. This C/C++ code
is for illustration. Of course, your actual code should
check return values.
Using PLT's MysterX, available at
http://www.plt-scheme.org/software/mysterx/
you can load MzCOM with either
(cci/coclass "MzObj Class")
or
(cci/progid "MzCOM.MzObj.<version>")
Consult your documentation for loading MzCOM into other
COM environments. MzCOM is compiled as a "dual-mode"
class, meaning its methods may be called directly or by
using OLE Automation.
GUID's
------
When compiled, the directory
plt\src\worksp\mzcom\
contains the file MzCOM_i.c that contains GUID's for MzCOM.
Those GUID's are
const IID IID_IMzObj =
{0xA604CBA8,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};
const IID LIBID_MZCOMLib =
{0xA604CB9C,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};
const IID DIID__IMzObjEvents =
{0xA604CBA9,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};
const CLSID CLSID_MzObj =
{0xA3B0AF9E,0x2AB0,0x11D4,{0xB6,0xD2,0x00,0x60,0x08,0x90,0x02,0xFE}};
which represent the IMzObj interface, the MzCOM type library,
the IMzObjEvents interface, and the MzObj class, respectively.
Methods
-------
MzCOM has three methods.
> About :: void About(void)
About() takes no arguments and displays an informational
dialog.
> Eval :: BSTR Eval(BSTR input)
Eval() takes and returns BSTR's (BASIC strings). The
returned value is the result of evaluating the input
expression, formatted as a string. The input string
may contain several S-expressions. The embedded MzScheme
updates its environment with each evaluation. Therefore,
it is possible to define procedures in a call to
Eval(), and use the procedures in subsequent calls.
> Reset :: void Reset(void)
Reset() resets the Scheme environment to the
initial environment. Also, the custodian for the
primary Scheme thread is invoked, shutting
all its managed values.
Events
------
MzCOM has a single event.
> SchemeError()
The SchemeError() event is passed a BSTR (BASIC string)
that explains the error.
Errors
------
When an error occurs in MzCOM, it creates a COM
error object. C and C++ clients can use GetErrorInfo()
to retrieve error information. Clients implemented
in other languages typically have some equivalent means
to obtain COM error information.
Collections
-----------
If mzcom.exe is installed to its default location,
MzCOM is able to find other PLT collections.
When setting up the collection paths, MzCOM adds
the variable
> mzcom-exe
to the global environment. That variable is bound
to a string containing the full pathname for mzcom.exe.
If mzcom.exe is moved to another location, you should
set either the PLTHOME or PLTCOLLECTS environment
variables before loading MzCOM.
Evaluation thread
-----------------
The MzScheme evaluator runs in a Win32 thread created
when MzCOM is loaded. If an expression kills the
primary MzScheme thread, as in
(kill-thread (current-thread))
then the evaluator Win32 thread is also killed.
When that happens, subsequent calls to Eval() will fail.
Contact us
----------
If you need more information on using MzCOM, please
contact us at scheme@plt-scheme.org.
Acknowledgments
---------------
MzCOM was developed in response to a query by
Andre Van Meulebrouck. Andre also did extensive
testing with Visual BASIC.

2
collects/mzcom/info.ss
View File

@ -1,3 +1,5 @@
#lang setup/infotab
(define post-install-collection "installer.ss")
(define scribblings '(("mzcom.scrbl" ())))

170
collects/mzcom/mzcom.scrbl Normal file
View File

@ -0,0 +1,170 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
(for-label scheme/base
mysterx))
@(define (com-index name what . proto)
(index* (list (format "~a COM ~a" name what))
(list @elem{@(tt name) COM @|what|})
(apply tt proto)))
@title{@bold{MzCOM}: Scheme as a Windows COM Object}
@exec{MzCOM.exe} is a Windows COM (i.e., Component Object Model) class
wrapper for PLT Scheme.
During normal installation of MzCOM, the executable is registered as a
COM object automatically. If you move the PLT Scheme installation
folder, re-register @exec{MzCOM.exe} with
@commandline{mzcom.exe /RegServer}
The @exec{MzCOM.exe} executable find DLLs and PLT Scheme library
collections relative to its own path.
@; ----------------------------------------------------------------------
@section{Loading MzCOM}
To load a COM object, COM hosts require a COM class name or a ProgID.
MzCOM has the class name @tt{"MzObj Class"} and the ProgID
@tt{"MzCOM.MzObj.@nonterm{version}"}, where @nonterm{version} is
@(version).
In the Visual BASIC 6 environment, from the @menuitem["Project"
"References (VB6)"], check @onscreen{MzCOM 1.0 Type Library}. In
Visual BASIC .NET, choose @menuitem["Project" "Add Reference"], and
from the @onscreen{COM} tab, select @onscreen{MzCOM 1.0 Type Library}.
In your code, declare a variable, then assign to it:
@verbatim[#:indent 2]{
DIM schemeObject AS MzObj
SET schemeObject = NEW MzObj
}
From Visual C++:
@verbatim[#:indent 2]{
#include "mzcom.h"
CLSID clsid;
IMzObj *pIMzObj;
CoInitialize(NULL);
CLSIDFromProgID(L"MzCOM.MzObj.<version>",&clsid);
CoCreateInstance(clsid,NULL,CLSCTX_SERVER,IID_IMzObj, (void **)&pIMzObj);
}
where @tt{<version>} is the version number. You'll need the
definition of @tt{IID_IMzObj} (see @secref["guids"]). The header file
@filepath{mzcom.h} is generated as @filepath{src\worksp\mzcom\} when
building from the PLT Scheme source distribution. The above C/C++ code
is for illustration; your actual code should check return values, of
course.
Using @schememodname[mysterx] to manipulate COM objects within Scheme,
you can load MzCOM with either
@schemeblock[
(cci/coclass "MzObj Class")
]
or
@schemeblock[
(cci/progid "MzCOM.MzObj.<version>")
]
Consult your documentation for loading MzCOM into other COM
environments. MzCOM is compiled as a ``dual-mode'' class, meaning its
methods may be called directly or by using OLE Automation.
@section[#:tag "guids"]{GUIDs}
When compiled from the PLT Scheme source distibrution, the directory
@filepath{src\worksp\mzcom\} contains the file @filepath{MzCOM_i.c}
that contains GUIDs for MzCOM. Those GUIDs are as follows:
@verbatim[#:indent 2]{
const IID IID_IMzObj =
{0xA604CBA8,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};
const IID LIBID_MZCOMLib =
{0xA604CB9C,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};
const IID DIID__IMzObjEvents =
{0xA604CBA9,0x2AB5,0x11D4,{0xB6,0xD3,0x00,0x60,0x08,0x90,0x02,0xFE}};
const CLSID CLSID_MzObj =
{0xA3B0AF9E,0x2AB0,0x11D4,{0xB6,0xD2,0x00,0x60,0x08,0x90,0x02,0xFE}};
}
which represent the @tt{IMzObj} interface, the MzCOM type library, the
@tt{IMzObjEvents} interface, and the @tt{MzObj} class, respectively.
@section{Methods}
MzCOM support three COM methods:
@itemize[
@item{@com-index["About" "method"]{void About(void)}
Takes no arguments and displays an informational
dialog.}
@item{@com-index["Eval" "method"]{BSTR Eval(BSTR input)}
Takes and returns @tt{BSTR}s (BASIC strings). The returned
value is the result of evaluating the input expression,
formatted as a string. The input string may contain several
S-expressions. The embedded PLT Scheme updates its environment
with each evaluation. Therefore, it is possible to define
procedures in a call to @tt{Eval}, and use the procedures in
subsequent calls.}
@item{@com-index["Reset" "method"]{Reset :: void Reset(void)}
Resets the Scheme environment to the initial environment.
Also, the custodian for the primary Scheme thread is invoked,
shutting all its managed values.}
]
@section{Events}
MzCOM supports a single event.
@itemize[
@item{@com-index["SchemeError" "event"]{SchemeError()}
Passed a BSTR (BASIC string) that explains the error.}
]
@section{Errors}
When an error occurs in MzCOM, it creates a COM error object. C and
C++ clients can use @tt{GetErrorInfo} to retrieve error information.
Clients implemented in other languages typically have some equivalent
means to obtain COM error information.
@section{Evaluation thread}
The PLT Scheme evaluator runs in a Win32 thread created when MzCOM is
loaded. If an expression kills the primary MzScheme thread, as in
@schemeblock[
(kill-thread (current-thread))
]
then the evaluator Win32 thread is also killed.
When that happens, subsequent calls to Eval() will fail.
@section{Acknowledgments}
MzCOM was developed in response to a query by
Andre Van Meulebrouck. Andre also did extensive
testing with Visual BASIC.

32
collects/r5rs/doc.txt
View File

@ -1,32 +0,0 @@
_R5RS_
The "r5rs" collection implements the language defined by the
"Revised^5 Report on the Algorithmic Language Scheme" in the "lang.ss"
module. In addition, this module provides _#%provide_ (instead of
`provide'), _#%require_ (instead of `#%require'), `#%app', `%datum',
etc. The `letrec' of this language is defined exactly as in R5RS, and
not as in MzScheme.
You can use this collection in several ways:
* Use the "Standard (R5RS)" language in DrScheme.
* Write code in a module using the R5RS module (lib "lang.ss" "r5rs"),
as a base language:
(module foo (lib "lang.ss" "r5rs")
...)
in this case, you can `provide' bindings and `require' other modules
by using _#%require_ and _#%provide_.
* Start MzScheme using bindings from the R5RS language with
mzscheme -M r5rs
This will start MzScheme with only the R5RS bindings (with #%require
etc), and a reader that will reject use of square brackets and curly
braces.
(Note: do not use (lib "r5rs.ss" "r5rs") as a module -- it does some
side effects like changing the global namespace.)

2
collects/scribble/manual.ss
View File

@ -303,7 +303,7 @@
[s (element->string f)])
(index* (list (substring s 1 (sub1 (string-length s)))) (list f) f)))
(define (exec . str)
(make-element 'tt (decode-content str)))
(make-element 'tt str))
(define (Flag . str)
(make-element 'no-break (list (make-element 'tt (cons "-" (decode-content str))))))
(define (DFlag . str)

1
collects/syntax/module-reader.ss
View File

@ -30,7 +30,6 @@
(string->symbol
(path->string (path-replace-suffix name #""))))
'page)]
[id 'doc]
[tag-src (lambda (v)
(if (syntax? modpath)
(datum->syntax #f

11
collects/syntax/scribblings/module-reader.scrbl
View File

@ -49,12 +49,19 @@ For example, @scheme[scheme/base/lang/reader] is implemented as
@defproc[(wrap-read-all [mod-path module-path?]
[in input-port?]
[read (input-port . -> . any/c)])
[read (input-port . -> . any/c)]
[mod-path-stx syntax?]
[src (or/c syntax? #f)]
[line number?]
[col number?]
[pos number?])
any/c]{
Repeatedly calls @scheme[read] on @scheme[in] until an end of file,
collecting the results in order into @scheme[_lst], and derives a
@scheme[_name-id] from @scheme[(object-name in)]. The result is
@scheme[_name-id] from @scheme[(object-name in)]. The last five
arguments are used to construct the syntax object for the language
position of the module. The result is roughly
@schemeblock[
`(module ,_name-id ,mod-path ,@_lst)

55
collects/trace/doc.txt
View File

@ -1,55 +0,0 @@
[index entries: _debug_ _debugger_ _debugging_ ]
_Calltrace_ is a tool that displays all calls to user procedures. It
displays the arguments to the calls, and indents to show the depth of
the continuation.
Quick instructions
------------------
0) Throw away .zo versions of your source
1) Prefix your program with
(require (lib "calltrace.ss" "trace"))
2) Run your program
The calltrace module is odd; don't import it into another
module. Instead, the calltrace module is meant to be invoked from the
top-level, so that it can install an evaluation handler, exception
handler, etc.
To reuse parts of the code of errortrace, import
_calltrace-lib.ss_. It contains all of the names here but
does not set the eval-handler.
Exception Information
---------------------
Invoking the calltrace.ss module sets the eval handler to instrument
Scheme source code.
NOTE: errortrace has no effect on code loaded as compiled byte code
(i.e., from a .zo file) or native code (i.e., from a .dll or .so
file).
Errortrace's instrumentation can be explicitly disabled via the
`instrumenting-enabled' boolean parameter. Instrumentation is on by
default. The `instrumenting-enabled' parameter affects only the way
that source code is compiled, not the way that exception information
is reported.
> (instrumenting-enabled) - returns #t if error tracing instrumentation is
enabled, #f otherwise
> (instrumenting-enabled on?) - enables/disables error tracing
instrumentation
<slowdown information elided.>
Do not load calltrace before writing .zo files. Calltrace
instruments S-expressions with unprintable values; this works fine if
the instrumented S-expression is passed to the default eval handler,
but neither the S-expression nor its byte-code form can be marshalled
to a string.

355
collects/wxme/doc.txt
View File

@ -1,355 +0,0 @@
======================================================================
_wxme.ss_ --- reading PLT graphical format (WXME) files without MrEd
======================================================================
> (is-wxme-stream? input-port)
Peeks from `input-port' and returns #t if it starts with magic bytes
indicating a WXME-format stream, #f otherwise.
The magic bytes are "WXME01<n><m> ##" for digits <n> and <m>, followed
by either a space, carriage return, or newline, and optionally
prefixed with "#reader(\"read.ss\"\"wxme\")".
> (wxme-port->text-port input-port [close?])
Takes an import port whose stream starts with WXME-format data and
returns an input port that produces a text form of the WXME content,
like the result of opening a WXME file in DrScheme and saving it as
text.
If `close?' is true (the default), then closing the result port close
the original port.
See "Snip Class Mapping" (below) for information about the kinds of
non-text content that can be read.
> (wxme-port->port input-port [close? snip-filter-proc-or-false])
Takes an import port whose stream starts with WXME-format data and
returns an input port that produces text content converted to bytes,
and non-text content as "special" values.
These special values produced by the new import port are different
than the ones produced by reading a file into a MrEd `editor<%>'
object. Instead of instances of the MrEd `snip%' class, the special
values are typically simple extensions of `object%'. See "Snip Class
Mapping" (below) for information about the kinds of non-text content
that can be read.
If `close?' is true (the default), then closing the result port close
the original port.
The `snip-filter-proc' is applied to any special value generated for
the stream, and its result is used as an alternate special value. The
default `snip-filter-proc' is the identity function.
If a special value (possibly produced by the filter procedure) is an
object implementing the `readable<%>' interface provided by "wxme.ss",
then the object's `read-special' method is called to produce the
special value.
> (extract-used-classes input-port)
Returns two values: a list of snip-class names (as strings) used by
the given stream, and a list of data-class names (as strings) used by
the stream. If the stream is not a WXME stream, the result is two
empty lists. The given stream is not closed, and only data for a WXME
stream (if any) is consumed.
> (register-lib-mapping! string quoted-module-path)
Maps a snip-class name to a quoted module path that provides a reader%
implementation. The module path must have the form '(lib <str> ...),
where each <str> contains only alpha-numeric ASCII characters, ".",
"_", "-", and spaces.
> (string->lib-path string mred?)
Returns a quoted module path for `string' for either MrEd mode (when
`mred?' is #t) or "wxme.ss" mode (when `mred?' is #f). For the latter,
built-in mappings and mapping registered via `register-lib-mapping!'
are used. If `string' cannot be parsed as a library path, and if no
mapping is available (either because the class is built-in or not
known), the result is #f.
> unknown-extensions-skip-enabled
A parameter. When set to #f (the default), an exception is raised when
an unrecognized snip class is encountered in a WXME stream. When set to
a true value, instances of unrecognized snip classes are simply
omitted from the transformed stream.
> broken-wxme-big-endian?
A parameter. Some old and short-lived WXME formats depended on the
endian order of the machine where the file was saved. Set this
parameter to pick the endian order to use when reading the file; the
default is the current platform's endian order.
> (wxme-read port)
Like `read', but for a stream that starts with WXME-format data. If
multiple S-expressions are in the WXME data, they are all read and
combined with `begin'.
If MrEd is available (as determined by checking for `#%mred-kernel'),
then MrEd is used via `open-input-text-editor'. Otherwise,
`wxme-port->port' is used.
> (wxme-read-syntax source-v port)
Like `read-syntax', but for a WXME format input stream. If multiple
S-expressions are in the WXME data, they are all read and combined
with `begin'.
If MrEd is available (as determined by checking for `#%mred-kernel'),
then MrEd is used via `open-input-text-editor'. Otherwise,
`wxme-port->port' is used.
> snip-reader<%>
An interface to be implemented by a reader for a specific kind of data
in a WXME stream.
The interface has two methods:
> (read-header version-k stream-object)
> (read-snip text-only? version-k stream-object)
The first method is called at most once per WXME stream to initialize
the data type's stream-specific information. This method usually does
nothing.
The second method is called when an instance of the data type is
encountered in the stream. This method reads the data and returns
either bytes to be returned as part of the decoded stream or any other
kind of value to be returned as a "special" value from the decoded
stream.
> readable<%>
An interface to be implemented by values returned from a snip reader.
The only method is `read-special', which takes four arguments related
to source location: a value indicating the source, the line (positive
integer or #f), column (non-negative integer or #f), and position
(positive integer or #f).
When a value implements this interface, its `read-special' method is
called with source-location information to obtain the "special" result
from the WXME-decoding port.
------------------------------------------------------------
Snip Class Mapping
------------------------------------------------------------
When graphical data is marshaled to the WXME format, it is associated
with a snip-class name to be matched with an implementation at load
time.
Ideally, the snip-class name is generated as
(format "~s" (list '(lib <str> ...)
'(lib <str> ...)))
where each element of the list is a quoted module path. The <str>s
must contain only alpha-numeric ASCII characters, plus ".", "-", "_",
or space, and must not be "." or "..".
In that case, the first quoted module path is used by MrEd for loading
WXME files in graphical mode; the corresponding module must provide
`snip-class' object that implements MrEd's `snip-class%' class. The
second quoted module path is used by the "wxme.ss" library for
converting WXME streams without MrEd support; the corresponding module
must provide a `reader' object that implements `reader<%>' interface
described above. Of course, the `snip-class%' instance and `reader<%>'
instance are expected to parse the same format, but generate different
results suitable for the different contexts (graphical or not).
If a snip-class name is generated as
(format "~s" '(lib <str> ...))
then MrEd uses the sole module path, and the "wxme.ss" needs a
compatibility mapping. Install one with `register-lib-mapping!'.
If a snip-class name has neither of the above formats, then MrEd can
use the data only if a snip class is registered for the name, or if it
the name of one of the built-in classes: "wxtext", "wxtab", "wximage",
or "wxmedia" (for nested editors). The "wxme.ss" library needs a
compatibility mapping installed with `register-lib-mapping!' if it is
not one of the built-in classes.
Several compatibility mappings are installed automatically for the
"wxme.ss" library. They correspond to popular graphical elements
supported by various versions of DrScheme, including comment boxes,
fractions, XML boxes, Scheme boxes, text boxes, and images generated
by the "world.ss" and "image.ss" teachpacks (or, more generally, from
"cache-image-snip.ss" in "mrlib"), and test-case boxes.
For a port created by `wxme-port->port', nested editors are
represented by instances of the `editor%' class provided by the
"editor.ss" library of the "wxme" collection. This class provides a
single method, `get-content-port', which returns a port for the
editor's content. Images are represented as instances of the `image%'
class provided by the "image.ss" library (see below).
Comment boxes are represented as instances of a class that extends
`editor%' to implement `readable<%>' (see "comment.ss"); the read form
produces a special comment (created by `make-special-comment'), so
that the comment box disappears when `read' is used to read the
stream; the special-comment content is the readable instance. XML,
Scheme, and text boxes similarly produce instances of `editor%' and
`readable<%>' that expand in the usual way (see "xml.ss", "scheme.ss",
and "text.ss"). Images from the "world.ss" and "image.ss" teachpacks
are packaged as instances of `cache-image%' from the "cache-image.ss"
library (see below). Test-case boxes are packaged as instances of
`test-case%' from the "test-case.ss" library (see below).
======================================================================
_editor.ss_ --- MrEd nested editors
======================================================================
Provides
> editor%
that is instantiated for plain nested editors in a WXME stream.
The class has one method:
> (get-content-port)
which returns a port (like the one from `wxme-port->port') for the
editor's content.
======================================================================
_image.ss_ --- MrEd images
======================================================================
Provides
> image%
that is instantiated for MrEd images in a WXME stream. The class
provides several methods:
> (get-filename) - returns a filename as bytes, or #f if
data is available instead
> (get-data) - returns bytes for a PNG, XBM,or XPM file for the
image
> (get-w) - returns the display width of the image, which may
differ from the width of the actual image secified
as data or by a filename; -1 means that the image
data's width should be used
> (get-h) - returns the display height of the image, which may
differ from the width of the actual image secified
as data or by a filename; -1 means that the image
data's width should be used
> (get-dx) - returns an offset into the actual image to be used
as the left of the display image
> (get-dy) - returns an offset into the actual image to be used
as the top of the display image
======================================================================
_comment.ss_ --- DrScheme comment boxes
======================================================================
In addition to `reader', an instance of `snip-reader<%>', this library
provides
> comment-editor%
which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for Drscheme comment boxes in a WXME stream. The
class includes a `get-data' method that always returns #f.
======================================================================
_xml.ss_ --- DrScheme XML boxes
======================================================================
In addition to `reader', an instance of `snip-reader<%>', this library
provides
> xml-editor%
which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for Drscheme XML boxes in a WXME stream. The
class includes a `get-data' method that returns #t if whitespace is
elimited from the contained XML literal, #f otherwise.
======================================================================
_scheme.ss_ --- DrScheme Scheme boxes
======================================================================
In addition to `reader', an instance of `snip-reader<%>', this library
provides
> scheme-editor%
which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for Drscheme Scheme boxes in a WXME stream. The
class includes a `get-data' method that returns #t if the box
corresponds to a spliciing unquote, #f for a non-splicing unquote.
======================================================================
_text.ss_ --- DrScheme text boxes
======================================================================
In addition to `reader', an instance of `snip-reader<%>', this library
provides
> text-editor%
which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for DrScheme text boxes in a WXME stream. The
class includes a `get-data' method that always returns #f.
======================================================================
_number.ss_ --- DrScheme fractions
======================================================================
This library provides just `reader', which an instance of
`snip-reader<%>' that converts DrScheme fractions in a WXME stream to
exact numbers.
======================================================================
_cache-image.ss_ --- DrScheme teachpack images
======================================================================
In addition to `reader', an instance of `snip-reader<%>', this library
provides
> cache-image%
which is instantiated for images in a WXME stream generated by the
"image.ss" and "world.ss" teachpacks (or, more generally, by
"cache-image-snip.ss" of "mrlib". The class provides several methods:
> (get-argb) - returns a vector of integersin [0,255] representing
the content of the image
> (get-width) - returns the width of the image
> (get-height) - returns the height of the image
> (get-pin-x) - returns an offset into the image for the pinhole
> (get-pin-y) - returns an offset into the image for the pinhole
======================================================================
_test-case.ss_ --- DrScheme test-case boxes
======================================================================
In addition to `reader', an instance of `snip-reader<%>', this library
provides
> test-case%
which is instantiated for DrScheme test-case boxes in a WXME stream.
The class provides several methods:
> (get-comment) - returns a port or #f for the comment field (if any)
> (get-test) - returns a port for the "test" field
> (get-expected) - returns a port for the "expected" field
> (get-should-raise) - returns a port/#f for the "should raise" field
> (get-error-message) - returns a port/#f for the "error msg" field
> (get-enabled?) - returns #t if the test is enabled
> (get-collapsed?) - returns #t if the test is collapsed
> (get-error-box?) - return #t if the test is for an exception