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

fix docs for `multi-in'

Browse Source 
because the previous documentation didn't actually define the form;
 the examples were good, but epecting a reader to infer meaning
 from examples wasn't good enough. The use of a `module-path?' contract
 in the old docs wasn't appropriate; contracts apply to values, while
 grammar productions should be used to document syntax constraints.
 Also, `module-path?' was too permissive (only literal strings and
 identifiers are actually allowed), while the actual syntax allows
 either a single path or a sequence.
This commit is contained in:
Matthew Flatt 2011-05-30 08:43:03 -06:00
parent 84415dd4a9
commit a7ae3b807e
2 changed files with 48 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
collects/racket/require.rkt
View File

@ -126,9 +126,9 @@
(provide multi-in)
(define-require-syntax (multi-in stx)
(syntax-case stx ()
[(_ elem ...)
[(_ elem0 elem ...)
(quasisyntax/loc stx
(combine-in #,@(datum->syntax stx (multi (syntax->datum #'(elem ...)))
(combine-in #,@(datum->syntax stx (multi (syntax->datum #'(elem0 elem ...)))
stx stx stx)))]))

72
collects/scribblings/reference/syntax.scrbl
View File

@ -1,6 +1,7 @@
#lang scribble/doc
@(require "mz.ss"
scribble/bnf
scribble/core
(for-label (only-in racket/require-transform
make-require-transformer)
racket/require-syntax
@ -25,6 +26,25 @@
@(define unquote-id (racket unquote))
@(define unquote-splicing-id (racket unquote-splicing))
@(define-syntax-rule (equiv-to-block b)
(tabular #:style (make-style #f (list (make-table-columns
(list (make-style #f '(baseline))
(make-style #f '(baseline))))))
(list (list (para (hspace 2) " is equivalent to" (hspace 1))
(racketblock0 b)))))
@(define-syntax-rule (subeqivs [a0 b0] [a b] ...)
(tabular (map
list
(apply
append
(list (list (racketblock a0)
(equiv-to-block b0))
(list (para 'nbsp)
(racketblock a)
(equiv-to-block b))
...)))))
@title[#:tag "syntax" #:style 'toc]{Syntactic Forms}
This section describes the core syntax forms that appear in a fully
@ -1161,35 +1181,35 @@ but then sub-directories that are called
@filepath{utils} override the one in the project's root.
In other words, the previous method requires only a single unique name.}
@defform[(multi-in (dir ...) ...)
#:contracts ([dir module-path?])]{
@defform/subs[(multi-in subs ...+)
([subs sub-path
(sub-path ...)]
[sub-path rel-string
id])]{
Specifies multiple files to be required from a hierarchy of
directories or collects.
directories or collections. The set of required module paths is computed
as the cartesian product of the @racket[subs] groups, where each
@racket[sub-path] is combined with other @racket[sub-path]s in order
using a @litchar{/} separator. A @racket[sub-path] as a @racket[subs]
is equivalent to @racket[(sub-path)]. All @racket[sub-path]s in a given
@racket[multi-in] form must be either strings or identifiers.
For example:
@racketblock[(require (multi-in racket (list dict)))]
is equivalent to:
@racketblock[(require racket/list racket/dict)]
Similarly:
@racketblock[(require (multi-in "utils" ("math.rkt" "matrix.rkt")))]
is equivalent to:
@racketblock[(require "utils/math.rkt" "utils/matrix.rkt")]
Examples:
It is also possible to require to require files with identical names
located in different directories:
@racketblock[(require (multi-in ("math" "matrix") "utils.rkt"))]
which is equivalent to:
@racketblock[(require "math/utils.rkt" "matrix/utils.rkt")]
or even:
@racketblock[(require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt")))]
which is equivalent to:
@racketblock[(require "math/utils.rkt" "math/helpers.rkt" "matrix/utils.rkt" "matrix/helpers.rkt")]
Deeper nesting is also possible:
@racketblock[(require (multi-in "math" "matrix" "utils.rkt"))]
is equivalent to:
@racketblock[(require "math/matrix/utils.rkt")]
}
@subeqivs[
[(require (multi-in racket (dict @#,schemeidfont{list})))
(require racket/dict racket/list)]
[(require (multi-in "math" "matrix" "utils.rkt"))
(require "math/matrix/utils.rkt")]
[(require (multi-in "utils" ("math.rkt" "matrix.rkt")))
(require "utils/math.rkt" "utils/matrix.rkt")]
[(require (multi-in ("math" "matrix") "utils.rkt"))
(require "math/utils.rkt" "matrix/utils.rkt")]
[(require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt")))
(require "math/utils.rkt" "math/helpers.rkt"
"matrix/utils.rkt" "matrix/helpers.rkt")]
]}
@; --------------------