From 0cc6eac6db7f4714ae8622cfbe40827316655d36 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 23 Nov 2007 14:53:20 +0000 Subject: [PATCH] doc require/provide transformers and pretty-print svn: r7820 --- collects/scheme/provide-transform.ss | 2 +- collects/scheme/require-transform.ss | 4 +- collects/scribblings/reference/data.scrbl | 2 +- .../scribblings/reference/file-ports.scrbl | 8 +- .../scribblings/reference/filesystem.scrbl | 12 +- collects/scribblings/reference/io.scrbl | 1 + .../reference/module-reflect.scrbl | 4 + collects/scribblings/reference/mz.ss | 14 +- collects/scribblings/reference/numbers.scrbl | 51 ++- .../{pairs-scrbl.scrbl => pairs.scrbl} | 0 collects/scribblings/reference/paths.scrbl | 4 +- .../scribblings/reference/pretty-print.scrbl | 370 ++++++++++++++++++ .../scribblings/reference/stx-trans.scrbl | 189 ++++++++- collects/scribblings/reference/syntax.scrbl | 6 + .../scribblings/reference/unix-paths.scrbl | 2 +- 15 files changed, 646 insertions(+), 23 deletions(-) rename collects/scribblings/reference/{pairs-scrbl.scrbl => pairs.scrbl} (100%) create mode 100644 collects/scribblings/reference/pretty-print.scrbl diff --git a/collects/scheme/provide-transform.ss b/collects/scheme/provide-transform.ss index 026d87fd1d..b4bf94cb71 100644 --- a/collects/scheme/provide-transform.ss +++ b/collects/scheme/provide-transform.ss @@ -10,7 +10,7 @@ (#%provide expand-export make-provide-transformer prop:provide-transformer provide-transformer? ;; the export struct type: - export make-export export? + export struct:export make-export export? export-local-id export-out-sym export-orig-stx export-protect? export-mode) (define-struct* export (local-id out-sym mode protect? orig-stx) diff --git a/collects/scheme/require-transform.ss b/collects/scheme/require-transform.ss index 8b18879f7c..3b1c00b567 100644 --- a/collects/scheme/require-transform.ss +++ b/collects/scheme/require-transform.ss @@ -11,10 +11,10 @@ (#%provide expand-import make-require-transformer prop:require-transformer require-transformer? ;; the import struct type: - import make-import import? + import struct:import make-import import? import-local-id import-src-sym import-src-mod-path import-orig-stx import-mode import-req-mode ;; the import-source struct type: - import-source make-import-source import-source? + import-source struct:import-source make-import-source import-source? import-source-mod-path-stx import-source-mode) (define-struct* import (local-id src-sym src-mod-path mode req-mode orig-stx) diff --git a/collects/scribblings/reference/data.scrbl b/collects/scribblings/reference/data.scrbl index f425104fd5..cac5131e96 100644 --- a/collects/scribblings/reference/data.scrbl +++ b/collects/scribblings/reference/data.scrbl @@ -171,7 +171,7 @@ for each pair of keywords is the same as using @scheme[keyword->string] and @scheme[stringdirectory-path]; expansion and simplification raise -an exception if the path is ill-formed. Thus, the current value of -@scheme[current-directory] is always an expanded, simplified, -complete, directory path. +the path argument is @tech{cleanse}d using @scheme[cleanse-path], +simplified using @scheme[simplify-path], and then converted to a +directory path with @scheme[path->directory-path]; cleansing and +simplification raise an exception if the path is ill-formed. Thus, the +current value of @scheme[current-directory] is always a cleansed, +simplified, complete, directory path. The path is not checked for existence when the parameter is set.} diff --git a/collects/scribblings/reference/io.scrbl b/collects/scribblings/reference/io.scrbl index aa888ea222..25f3379a7e 100644 --- a/collects/scribblings/reference/io.scrbl +++ b/collects/scribblings/reference/io.scrbl @@ -12,5 +12,6 @@ @include-section["write.scrbl"] @include-section["reader.scrbl"] @include-section["printer.scrbl"] +@include-section["pretty-print.scrbl"] @include-section["readtables.scrbl"] @include-section["custom-write.scrbl"] diff --git a/collects/scribblings/reference/module-reflect.scrbl b/collects/scribblings/reference/module-reflect.scrbl index 87b749095c..a567ab74a9 100644 --- a/collects/scribblings/reference/module-reflect.scrbl +++ b/collects/scribblings/reference/module-reflect.scrbl @@ -14,6 +14,10 @@ evaluation (e.g., @scheme[eval]). A filesystem path normally refers to a module declaration that was loaded on demand via @scheme[require] or other forms. +A @deftech{module path} is a datum that matches the grammar for +@scheme[_module-path] for @scheme[require]. A module path is relative +to another module. + @defproc[(resolved-module-path? [v any/c]) boolean?]{ Returns @scheme[#f] if @scheme[v] is a @tech{resolved module path}, diff --git a/collects/scribblings/reference/mz.ss b/collects/scribblings/reference/mz.ss index 41ff3a1523..cc9dcf0913 100644 --- a/collects/scribblings/reference/mz.ss +++ b/collects/scribblings/reference/mz.ss @@ -21,10 +21,18 @@ (provide note-lib) (define-syntax-rule (note-lib lib) (t "The bindings documented in this section are provided by the " - (schemeidfont "scheme/list") + (schememodname lib) " and " - (schemeidfont "scheme") - " libraries, but not " (schemeidfont "scheme/base") + (schememodname scheme) + " libraries, but not " (schememodname scheme/base) + ".")) + + (provide note-lib-only) + (define-syntax-rule (note-lib-only lib) + (t "The bindings documented in this section are provided by the " + (schememodname lib) + " library, not " (schememodname scheme/base) + " or " (schememodname scheme) ".")) (define (*exnraise s) diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index 829dbcd593..30e037c2a9 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -1,6 +1,6 @@ #lang scribble/doc -@require["mz.ss"] -@require[(only-in scheme pi)] +@require["mz.ss" + scheme/math] @title[#:tag "numbers"]{Numbers} @@ -755,3 +755,50 @@ If @scheme[dest-bstr] is provided and it is not of length Returns @scheme[#t] if the native encoding of numbers is big-endian for the machine running Scheme, @scheme[#f] if the native encoding is little-endian.} + +@; ------------------------------------------------------------------------ +@section{Extra Constants and Functions} + +@declare-exporting[scheme/math scheme] +@note-lib[scheme/math] + +@defthing[euler real?]{ + +An approximation to Euler's constant: @number->string[euler].} + +@defthing[pi real]{ + +An approximation to the ratio of a circle's circumference to its +diameter: @number->string[pi].} + +@defproc[(sqr [z number?]) number?]{ + +Returns @scheme[(* z z)].} + +@defproc[(sgn [x real?]) (one-of/c 1 0 -1 1.0 0.0 -1.0)]{ + +Returns the sign of @scheme[x] as either @math{-1}, @math{0}, or +@math{1}. + +@examples[ +(sgn 10) +(sgn -10.0) +(sgn 0) +]} + +@defproc[(conjugate [z number?]) number?]{ + +Returns the complex conjugate of @scheme[z]. + +@examples[ +(conjugate 1) +(conjugate 3+4i) +]} + +@defproc[(sinh [z number?]) number?]{ + +Returns the hyperbolic sine of @scheme[z].} + +@defproc[(cosh [z number?]) number?]{ + +Returns the hyperbolic cosine of @scheme[z].} diff --git a/collects/scribblings/reference/pairs-scrbl.scrbl b/collects/scribblings/reference/pairs.scrbl similarity index 100% rename from collects/scribblings/reference/pairs-scrbl.scrbl rename to collects/scribblings/reference/pairs.scrbl diff --git a/collects/scribblings/reference/paths.scrbl b/collects/scribblings/reference/paths.scrbl index 5c0732ed06..09591508ae 100644 --- a/collects/scribblings/reference/paths.scrbl +++ b/collects/scribblings/reference/paths.scrbl @@ -330,8 +330,8 @@ This procedure does not access the filesystem.} @defproc[(resolve-path [path path-string?]) path?]{ -@tech{Path-expands} @scheme[path] and returns a path that references -the same file or directory as @scheme[path]. Under @|AllUnix|, if +@tech{Cleanse}s @scheme[path] and returns a path that references the +same file or directory as @scheme[path]. Under @|AllUnix|, if @scheme[path] is a soft link to another path, then the referenced path is returned (this may be a relative path with respect to the directory owning @scheme[path]), otherwise @scheme[path] is returned (after diff --git a/collects/scribblings/reference/pretty-print.scrbl b/collects/scribblings/reference/pretty-print.scrbl new file mode 100644 index 0000000000..f73558c1f7 --- /dev/null +++ b/collects/scribblings/reference/pretty-print.scrbl @@ -0,0 +1,370 @@ +#lang scribble/doc +@require["mz.ss" + scribble/bnf] + +@title[#:tag "pretty-print"]{Pretty Printing} + +@declare-exporting[scheme/pretty scheme] +@note-lib[scheme/pretty] + +@defproc[(pretty-print [v any/c] [port output-port? (current-output-port)]) + void?]{ + +Pretty-prints the value @scheme[v] using the same printed form as +@scheme[write], but with newlines and whitespace inserted to avoid +lines longer than @scheme[(pretty-print-columns)], as controlled by +@scheme[(pretty-print-current-style-table)]. The printed form ends in +a newline, unless the @scheme[pretty-print-columns] parameter is set +to @scheme['infinity]. + +In addition to the parameters defined in this section, +@scheme[pretty-print] conforms to the @scheme[print-graph], +@scheme[print-struct], @scheme[print-hash-table], +@scheme[print-vector-length], and @scheme[print-box] parameters. + +The pretty printer also detects structures that have the +@scheme[prop:custom-write] property and it calls the corresponding +custom-write procedure. The custom-write procedure can check the +parameter @scheme[pretty-printing] to cooperate with the +pretty-printer. Recursive printing to the port automatically uses +pretty printing, but if the structure has multiple recursively printed +sub-expressions, a custom-write procedure may need to cooperate more +to insert explicit newlines. Use @scheme[port-next-location] to +determine the current output column, use @scheme[pretty-print-columns] +to determine the target printing width, and use +@scheme[pretty-print-newline] to insert a newline (so that the +function in the @scheme[pretty-print-print-line] parameter can be +called appropriately). Use +@scheme[make-tentative-pretty-print-output-port] to obtain a port for +tentative recursive prints (e.g., to check the length of the output).} + + +@defproc[(pretty-display [v any/c][port output-port? (current-output-port)]) + void?]{ + +Same as @scheme[pretty-print], but @scheme[v] is printed like +@scheme[display] instead of like @scheme[write].} + + +@defproc[(pretty-format [v any/c][columns nonnegative-exact-integer? (pretty-print-columns)]) + string?]{ + +Like @scheme[pretty-print], except that it returns a string containing +the pretty-printed value, rather than sending the output to a port. + +The optional argument @scheme[columns] argument is used to +parameterize @scheme[pretty-print-columns].} + + +@defproc[(pretty-print-handler [v any/c]) void?]{ + +Pretty-prints @scheme[v] if @scheme[v] is not @|void-const|, or prints +nothing if @scheme[v] is @|void-const|. Pass this procedure to +@scheme[current-print] to install the pretty printer into the REPL run +by @scheme[read-eval-print-loop].} + + +@; ---------------------------------------------------------------------- + +@section{Basic Pretty-Print Options} + +@defparam[pretty-print-columns width (or/c positive-exact-integer? (one-of/c 'infinity))]{ + +A parameter that determines the default width for pretty printing. + +If the display width is @scheme['infinity], then pretty-printed output +is never broken into lines, and a newline is not added to the end of +the output.} + + +@defparam[pretty-print-depth depth (or/c nonnegative-exact-integer? false/c)]{ + +Parameter that controls the default depth for recursive pretty +printing. Printing to @scheme[depth] means that elements nested more +deeply than @scheme[depth] are replaced with ``...''; in particular, a +depth of 0 indicates that only simple values are printed. A depth of +@scheme[#f] (the default) allows printing to arbitrary +depths.} + + +@defboolparam[pretty-print-exact-as-decimal as-decimal?]{ + +A parameter that determines how exact non-integers are printed. If +the parameter's value is @scheme[#t], then an exact non-integer with a +decimal representation is printed as a decimal number instead of a +fraction. The initial value is @scheme[#f].} + +@defboolparam[pretty-print-.-symbol-without-bars on?]{ + +A parameter that controls the printing of the symbol whose print name +is just a period. If set to a true value, then such a symbol is +printed as only the period. If set to a false value, it is printed as +a period with vertical bars surrounding it.} + + +@defboolparam[pretty-print-show-inexactness show?]{ + +A parameter that determines how inexact numbers are printed. If the +parameter's value is @scheme[#t], then inexact numbers are always +printed with a leading @litchar{#i}. The initial value is @scheme[#f].} + +@; ---------------------------------------------------------------------- + +@section{Per-Symbol Special Printing} + + +@defboolparam[pretty-print-abbreviate-read-macros abbrev?]{ + +A parameter that controls whether or not @schemeidfont{quote}, +@schemeidfont{unquote}, @schemeidfont{unquote-splicing}, @|etc| are +abbreviated with @litchar{'}, @litchar{,}, @litchar[",@"], etc. +By default, the abbreviations are enabled.} + + +@defproc[(pretty-print-style-table? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is a style table for use with +@scheme[pretty-print-current-style-table], @scheme[#f] otherwise.} + + +@defparam[pretty-print-current-style-table style-table pretty-print-style-table?]{ + +A parameter that holds a table of style mappings. See +@scheme[pretty-print-extend-style-table].} + + +@defproc[(pretty-print-extend-style-table [style-table pretty-print-style-table?] + [symbol-list (listof symbol?)] + [like-symbol-list (listof symbol?)]) + pretty-print-style-table?]{ + +Creates a new style table by extending an existing +@scheme[style-table], so that the style mapping for each symbol of +@scheme[like-symbol-list] in the original table is used for the +corresponding symbol of @scheme[symbol-list] in the new table. The +@scheme[symbol-list] and @scheme[like-symbol-list] lists must have the +same length. The @scheme[style-table] argument can be @scheme[#f], in +which case with default mappings are used for the original table (see +below). + +The style mapping for a symbol controls the way that whitespace is +inserted when printing a list that starts with the symbol. In the +absence of any mapping, when a list is broken across multiple lines, +each element of the list is printed on its own line, each with the +same indentation. + +The default style mapping includes mappings for the following symbols, +so that the output follows popular code-formatting rules: + +@schemeblock[ +'lambda 'case-lambda +'define 'define-macro 'define-syntax +'let letrec 'let* +'let-syntax 'letrec-syntax +'let-values 'letrec-values 'let*-values +'let-syntaxes 'letrec-syntaxes +'begin 'begin0 'do +'if 'set! 'set!-values +'unless 'when +'cond 'case 'and 'or +'module +'syntax-rules 'syntax-case 'letrec-syntaxes+values +'import 'export 'link +'require 'require-for-syntax 'require-for-template 'provide +'public 'private 'override 'rename 'inherit 'field 'init +'shared 'send 'class 'instantiate 'make-object +]} + + +@defparam[pretty-print-remap-stylable + proc + (any/c . -> . (or/c symbol? false/c))]{ + +A parameter that controls remapping for styles. This procedure is +called with each subexpression that appears as the first element in a +sequence. If it returns a symbol, the style table is used, as if that +symbol were at the head of the sequence. If it returns @scheme[#f], +the style table is treated normally.} + + +@; ---------------------------------------------------------------------- + +@section{Line-Output Hook} + +@defproc[(pretty-print-newline [port out-port?][width nonnegative-exact-integer?]) void?]{ + +Calls the procedure associated with the +@scheme[pretty-print-print-line] parameter to print a newline to +@scheme[port], if @scheme[port] is the output port that is redirected +to the original output port for printing, otherwise a plain newline is +printed to @scheme[port]. The @scheme[width] argument should be the +target column width, typically obtained from +@scheme[pretty-print-columns].} + + +@defparam[pretty-print-print-line proc + ((or/c nonnegative-exact-integer? false/c) + output-port? + nonnegative-exact-integer? + (or/c nonnegative-exact-integer? (one-of/c 'infinity)) + . -> . + nonnegative-exact-integer?)]{ + +A parameter that determines a procedure for printing the newline +separator between lines of a pretty-printed value. The procedure is +called with four arguments: a new line number, an output port, the old +line's length, and the number of destination columns. The return value +from @scheme[proc] is the number of extra characters it printed at the +beginning of the new line. + +The @scheme[proc] procedure is called before any characters are +printed with @scheme[0] as the line number and @scheme[0] as the old +line length; @scheme[proc] is called after the last character for a +value is printed with @scheme[#f] as the line number and with the +length of the last line. Whenever the pretty-printer starts a new +line, @scheme[proc] is called with the new line's number (where the +first new line is numbered @scheme[1]) and the just-finished line's +length. The destination-columns argument to @scheme[proc] is always +the total width of the destination printing area, or +@scheme['infinity] if pretty-printed values are not broken into lines. + +The default @scheme[proc] procedure prints a newline whenever the line +number is not @scheme[0] and the column count is not +@scheme['infinity], always returning @scheme[0]. A custom +@scheme[proc] procedure can be used to print extra text before each +line of pretty-printed output; the number of characters printed before +each line should be returned by @scheme[proc] so that the next line +break can be chosen correctly. + +The destination port supplied to @scheme[proc] is generally not the +port supplied to @scheme[pretty-print] or @scheme[pretty-display] (or +the current output port), but output to this port is ultimately +redirected to the port supplied to @scheme[pretty-print] or +@scheme[pretty-display].} + + +@; ---------------------------------------------------------------------- + +@section{Value Output Hook} + + +@defparam[pretty-print-size-hook proc + (any/c boolean? output-port . -> . (or/c false/c nonnegative-exact-integer?))]{ + +A parameter that determines a sizing hook for pretty-printing. + +The sizing hook is applied to each value to be printed. If the hook +returns @scheme[#f], then printing is handled internally by the +pretty-printer. Otherwise, the value should be an integer specifying +the length of the printed value in characters; the print hook will be +called to actually print the value (see +@scheme[pretty-print-print-hook]). + +The sizing hook receives three arguments. The first argument is the +value to print. The second argument is a Boolean: @scheme[#t] for +printing like @scheme[display] and @scheme[#f] for printing like +@scheme[write]. The third argument is the destination port; the port +is the one supplied to @scheme[pretty-print] or +@scheme[pretty-display] (or the current output port). The sizing hook +may be applied to a single value multiple times during +pretty-printing.} + + +@defparam[pretty-print-print-hook proc + (any/c boolean? output-port . -> . void?)]{ + +A parameter that determines a print hook for pretty-printing. The +print-hook procedure is applied to a value for printing when the +sizing hook (see @scheme[pretty-print-size-hook]) returns an integer +size for the value. + +The print hook receives three arguments. The first argument is the +value to print. The second argument is a boolean: @scheme[#t] for +printing like @scheme[display] and @scheme[#f] for printing like +@scheme[write]. The third argument is the destination port; this port +is generally not the port supplied to @scheme[pretty-print] or +@scheme[pretty-display] (or the current output port), but output to +this port is ultimately redirected to the port supplied to +@scheme[pretty-print] or @scheme[pretty-display].} + + +@defparam[pretty-print-pre-print-hook proc + (any/c output-port? . -> . void)]{ + +A parameter that determines a hook procedure to be called just before +an object is printed. The hook receives two arguments: the object and +the output port. The port is the one supplied to @scheme[pretty-print] +or @scheme[pretty-display] (or the current output port).} + + +@defparam[pretty-print-post-print-hook proc + (any/c output-port? . -> . void)]{ + +A parameter that determines a hook procedure to be called just after +an object is printed. The hook receives two arguments: the object and +the output port. The port is the one supplied to @scheme[pretty-print] +or @scheme[pretty-display] (or the current output port).} + +@; ---------------------------------------------------------------------- + +@section{Additional Custom-Output Support} + +@defboolparam[pretty-printing on?]{ + +A parameter that is set to @scheme[#t] when the pretty printer calls a +custom-write procedure (see @scheme[prop:custom-write]) for output. +When pretty printer calls a custom-write procedure merely to detect +cycles, it sets this parameter to @scheme[#f].} + + +@defproc[(make-tentative-pretty-print-output-port + [out output-port?] + [width nonnegative-exact-integer?] + [overflow-thunk (-> any)]) + output-port?]{ + +Produces an output port that is suitable for recursive pretty printing +without actually producing output. Use such a port to tentatively +print when proper output depends on the size of recursive +prints. Determine the size of the tentative print using +@scheme[port-count-lines]. + +The @scheme[out] argument should be a pretty-printing port, such as +the one supplied to a custom-write procedure when +@scheme[pretty-printing] is set to true, or another tentative output +port. The @scheme[width] argument should be a target column width, +usually obtained from @scheme[pretty-print-column-count], possibly +decremented to leave room for a terminator. The +@scheme[overflow-thunk] procedure is called if more than +@scheme[width] items are printed to the port; it can escape from the +recursive print through a continuation as a short cut, but +@scheme[overflow-thunk] can also return, in which case it is called +every time afterward that additional output is written to the port. + +After tentative printing, either accept the result with +@scheme[tentative-pretty-print-port-transfer] or reject it with +@scheme[tentative-pretty-print-port-cancel]. Failure to accept or +cancel properly interferes with graph-structure printing, calls to +hook procedures, etc. Explicitly cancel the tentative print even when +@scheme[overflow-thunk] escapes from a recursive print.} + + +@defproc[(tentative-pretty-print-port-transfer + [tentative-out output-port?][orig-out output-port?]) + void?]{ + +Causes the data written to @scheme[tentative-out] to be transferred as +if written to @scheme[orig-out]. The @scheme[tentative-out] argument +should be a port produced by +@scheme[make-tentative-pretty-print-output-port], and +@scheme[orig-out] should be either a pretty-printing port (provided to +a custom-write procedure) or another tentative output port.} + + +@defproc[(tentative-pretty-print-port-cancel [tentative-out output-port?]) void?]{ + +Cancels the content of @scheme[tentative-out], which was produced by +@scheme[make-tentative-pretty-print-output-port]. The main effect of +canceling is that graph-reference definitions are undone, so that a +future print of a graph-referenced object includes the defining +@litchar{#}@nonterm{n}@litchar{=}.} diff --git a/collects/scribblings/reference/stx-trans.scrbl b/collects/scribblings/reference/stx-trans.scrbl index 43e84cb27e..31da529363 100644 --- a/collects/scribblings/reference/stx-trans.scrbl +++ b/collects/scribblings/reference/stx-trans.scrbl @@ -1,5 +1,8 @@ #lang scribble/doc -@require["mz.ss"] +@require[(except-in "mz.ss" import export) + (for-syntax scheme/base) + (for-label scheme/require-transform + scheme/provide-transform)] @define[(transform-time) @t{This procedure must be called during the dynamic extent of a @tech{syntax transformer} application by the @@ -409,3 +412,187 @@ mark}. Multiple applications of the same @scheme[make-syntax-introducer] result procedure use the same mark, and different result procedures use distinct marks.} +@; ---------------------------------------------------------------------- + +@section[#:tag "require-trans"]{@scheme[require] Transformers} + +@declare-exporting[scheme/require-transform] +@note-lib-only[scheme/require-transform] + +A @tech{transformer binding} whose value is a structure with the +@scheme[prop:require-transformer] property implements a derived +@scheme[_require-spec] for @scheme[require]. + +The transformer is called with the syntax object representing its use +as a @scheme[_require-spec] within a @scheme[require] form, and the +result must be two lists: a list of @scheme[import]s and a list of +@scheme[import-source]s. + +If the derived form contains a sub-form that is a +@scheme[_require-spec], then it can call @scheme[expand-import] to +transform the sub-@scheme[_require-spec] to lists of imports and +import sources. + + +@defproc[(expand-import [stx syntax?]) + (values (listof import?) + (listof import-source?))]{ + +Expands the given @scheme[_require-spec] to lists of imports and +import sources.} + + +@defproc[(make-require-transformer [proc (syntax? . ->* . ((listof import?) (listof import-source?)))]) + require-transformer?]{ + +Creates a require transformer (i.e., a structure with the +@scheme[prop:require-transformer] property) using the given procedure +as the transformer.} + + +@defthing[prop:require-transformer struct-type-property?]{ + +A property to identify @scheme[require] transformers. The property +value must be a procedure that takes a syntax object and returns +import and import-source lists.} + + +@defproc[(require-transformer? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] has the +@scheme[prop:require-transformer] property, @scheme[#f] otherwise.} + + +@defstruct[import ([local-id identifier?] + [src-sym symbol?] + [src-mod-path module-path?] + [orig-stx syntax?] + [mode (one-of/c 'run 'syntax 'template 'label)] + [req-mode (one-of/c 'run 'syntax 'template 'label)])]{ + +A structure representing a single imported identifier: + +@itemize{ + + @item{@scheme[local-id] --- the identifier to be bound within the + importing module.} + + @item{@scheme[src-sym] --- the external name of the binding as + exported from its source module.} + + @item{@scheme[src-mod-path] --- a @tech{module path} (relative to the + importing module) for the source of the imported binding.} + + @item{@scheme[orig-stx] --- a @tech{syntax object} for the source of + the import, used for error reporting.} + + @item{@scheme[mode] --- the @tech{phase level} of the binding in the + importing module.} + + @item{@scheme[req-mode] --- the @tech{phase level} shift of the + import relative to the exporting module. Since the underlying + module system currently allows only for-run @scheme[require]s + to import into other @tech{phase levels}, if this value is not + @scheme['run], then it must match the @scheme[mode] field's + value.} + +}} + +@defstruct[import-source ([mod-path-stx (and/c syntax? + (lambda (x) + (module-path? (syntax->datum x))))] + [mode (one-of/c 'run 'syntax 'template 'label)])]{ + +A structure representing an imported module, which must be +instantiated or visited even if no binding is imported into a module. + +@itemize{ + + @item{@scheme[mod-path-stx] --- a @tech{module path} (relative + to the importing module) for the source of the imported binding.} + + @item{@scheme[mode] --- the @tech{phase level} shift the import.} + +}} + + +@; ---------------------------------------------------------------------- + +@section[#:tag "provide-trans"]{@scheme[provide] Transformers} + +@declare-exporting[scheme/provide-transform] +@note-lib-only[scheme/provide-transform] + +A @tech{transformer binding} whose value is a structure with the +@scheme[prop:provide-transformer] property implements a derived +@scheme[_provide-spec] for @scheme[provide]. + +The transformer is called with the syntax object representing its use +as a @scheme[_provide-spec] within a @scheme[provide] form and a list +of symbols representing the export modes specified by enclosing +@scheme[_provide-spec]s. The result must be a list of +@scheme[export]s. + +If the derived form contains a sub-form that is a +@scheme[_provide-spec], then it can call @scheme[expand-export] to +transform the sub-@scheme[_provide-spec] to a lists of exports. + + +@defproc[(expand-export [stx syntax?] [modes (listof (one-of/c 'run 'syntax 'label))]) + (listof export?)]{ + +Expands the given @scheme[_provide-spec] to a list of exports. The +@scheme[modes] list controls the expansion of +sub-@scheme[_provide-specs]; for example, an identifier refers to a +@tech{phase level} 0 binding unless the @scheme[modes] list specifies +otherwise. Normally, @scheme[modes] is either empty or contains a +single symbol.} + + +@defproc[(make-provide-transformer [proc (syntax? (listof (one-of/c 'run 'syntax 'label)) + . -> . (listof export?))]) + provide-transformer?]{ + +Creates a provide transformer (i.e., a structure with the +@scheme[prop:provide-transformer] property) using the given procedure +as the transformer.} + + +@defthing[prop:provide-transformer struct-type-property?]{ + +A property to identify @scheme[provide] transformers. The property +value must be a procedure that takes a syntax object and mode list and +returns an export list.} + + +@defproc[(provide-transformer? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] has the +@scheme[prop:provide-transformer] property, @scheme[#f] otherwise.} + + +@defstruct[export ([local-id identifier?] + [out-sym symbol?] + [orig-stx syntax?] + [protect? any/c] + [mode (one-of/c 'run 'syntax 'label)])]{ + +A structure representing a single imported identifier: + +@itemize{ + + @item{@scheme[local-id] --- the identifier that is bound within the + exporting module.} + + @item{@scheme[out-sym] --- the external name of the binding.} + + @item{@scheme[orig-stx] --- a @tech{syntax object} for the source of + the export, used for error reporting.} + + @item{@scheme[protect?] --- indicates whether the identifier should + be protected (see @secref["modprotect"]).} + + @item{@scheme[mode] --- the @tech{phase level} of the binding in the + exporting module.} + +}} diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 264f544f1c..6e36caedb0 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -1279,6 +1279,9 @@ pre-defined forms are as follows. @scheme[for-syntax-spec], but shifts bindings to the @tech{label phase level}.} + @specsubform[derived-require-spec]{See @secref["require-trans"] for + information on expanding the set of @scheme[require-spec] forms.} + A @scheme[module-path] identifies a module, either through a concrete name in the form of an identifier, or through an indirect name that can trigger automatic loading of the module declaration. Except for @@ -1452,6 +1455,9 @@ pre-defined forms are as follows. @scheme[for-syntax], adjusting each @scheme[provide-spec] to the @tech{label phase level}.} + @specsubform[derived-provide-spec]{See @secref["provide-trans"] for + information on expanding the set of @scheme[provide-spec] forms.} + Each export specified within a module must have a distinct symbolic export name, though the same binding can be specified with the multiple symbolic names.} diff --git a/collects/scribblings/reference/unix-paths.scrbl b/collects/scribblings/reference/unix-paths.scrbl index 9f4bb33b0d..9ff0e4b60b 100644 --- a/collects/scribblings/reference/unix-paths.scrbl +++ b/collects/scribblings/reference/unix-paths.scrbl @@ -9,7 +9,7 @@ In @|AllUnix| paths, a @litchar{/} separates elements of the path, preceding path, and @litchar{..} as a path element always means the parent of the directory indicated by the preceding path. A leading @litchar{~} in a path is not treated specially, but -@scheme[expand-path] can be used to convert a leading @litchar{~} +@scheme[expand-user-path] can be used to convert a leading @litchar{~} element to a user-specific directory. No other character or byte has a special meaning within a path. Multiple adjacent @litchar{/} are equivalent to a single @litchar{/} (i.e., they act as a single path