From efb592bd15892791a8bff3b9d203e905bcc40d6e Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 25 Jun 2007 08:47:02 +0000 Subject: [PATCH] doc work on modules, new big collection svn: r6732 --- .../new-struct.ss => big/define-struct.ss} | 2 +- collects/big/info.ss | 3 + collects/big/lang.ss | 16 +++ collects/{scribblings => big}/new-lambda.ss | 14 +-- collects/mzlib/big/lang.ss | 5 + collects/scribble/basic.ss | 2 +- collects/scribble/doclang.ss | 4 +- collects/scribble/eval.ss | 12 +- collects/scribble/manual.ss | 16 ++- collects/scribblings/guide/guide-utils.ss | 2 +- .../scribblings/guide/module-basics.scrbl | 19 +--- collects/scribblings/guide/module-paths.scrbl | 105 ++++++++++++++++++ .../scribblings/guide/module-provide.scrbl | 7 ++ .../scribblings/guide/module-require.scrbl | 7 ++ collects/scribblings/guide/modules.scrbl | 3 + .../scribblings/reference/reader-example.ss | 2 +- collects/scribblings/reference/syntax.scrbl | 14 ++- 17 files changed, 196 insertions(+), 37 deletions(-) rename collects/{scribblings/new-struct.ss => big/define-struct.ss} (99%) create mode 100644 collects/big/info.ss create mode 100644 collects/big/lang.ss rename collects/{scribblings => big}/new-lambda.ss (98%) create mode 100644 collects/mzlib/big/lang.ss create mode 100644 collects/scribblings/guide/module-paths.scrbl create mode 100644 collects/scribblings/guide/module-provide.scrbl create mode 100644 collects/scribblings/guide/module-require.scrbl diff --git a/collects/scribblings/new-struct.ss b/collects/big/define-struct.ss similarity index 99% rename from collects/scribblings/new-struct.ss rename to collects/big/define-struct.ss index 0f8dac8b77..83c65f3715 100644 --- a/collects/scribblings/new-struct.ss +++ b/collects/big/define-struct.ss @@ -4,7 +4,7 @@ ;; though, strangely and embarassingly, Matthew didn't know that until ;; after he had mostly re-implemented it. -(module new-struct mzscheme +(module define-struct mzscheme (require (lib "stxparam.ss")) (provide define-struct* diff --git a/collects/big/info.ss b/collects/big/info.ss new file mode 100644 index 0000000000..147bfc8ad6 --- /dev/null +++ b/collects/big/info.ss @@ -0,0 +1,3 @@ +(module info (lib "infotab.ss" "setup") + (define name "Big Scheme")) + diff --git a/collects/big/lang.ss b/collects/big/lang.ss new file mode 100644 index 0000000000..a0c7bf130b --- /dev/null +++ b/collects/big/lang.ss @@ -0,0 +1,16 @@ +(module lang mzscheme + (require "define-struct.ss" + "new-lambda.ss") + + (provide (all-from-except mzscheme #%datum lambda define #%app define-struct) + (rename new-datum #%datum) + (rename new-lambda lambda) + (rename new-define define) + (rename new-app #%app) + make-keyword-procedure + keyword-apply + procedure-keywords + (rename define-struct* define-struct) + struct-field-index)) + + diff --git a/collects/scribblings/new-lambda.ss b/collects/big/new-lambda.ss similarity index 98% rename from collects/scribblings/new-lambda.ss rename to collects/big/new-lambda.ss index 9b6bcaa17e..2f07d7524e 100644 --- a/collects/scribblings/new-lambda.ss +++ b/collects/big/new-lambda.ss @@ -1,18 +1,14 @@ (module new-lambda mzscheme (require-for-syntax (lib "name.ss" "syntax") (lib "define.ss" "syntax")) - (require "new-struct.ss") - (provide (all-from-except mzscheme #%datum lambda define #%app define-struct) - (rename new-datum #%datum) - (rename new-lambda lambda) - (rename new-define define) - (rename new-app #%app) + (provide new-datum + new-lambda + new-define + new-app (rename *make-keyword-procedure make-keyword-procedure) keyword-apply - procedure-keywords - (rename define-struct* define-struct) - struct-field-index) + procedure-keywords) ;; ---------------------------------------- diff --git a/collects/mzlib/big/lang.ss b/collects/mzlib/big/lang.ss new file mode 100644 index 0000000000..7edbd1482a --- /dev/null +++ b/collects/mzlib/big/lang.ss @@ -0,0 +1,5 @@ + +;; Temporary hack for building "scribblings" doc examples. + +(module lang (lib "lang.ss" "big") + (provide (all-from (lib "lang.ss" "big")))) diff --git a/collects/scribble/basic.ss b/collects/scribble/basic.ss index d43b716def..c9b9775d62 100644 --- a/collects/scribble/basic.ss +++ b/collects/scribble/basic.ss @@ -1,5 +1,5 @@ -(module basic (lib "new-lambda.ss" "scribblings") +(module basic (lib "lang.ss" "big") (require "decode.ss" "struct.ss" "config.ss" diff --git a/collects/scribble/doclang.ss b/collects/scribble/doclang.ss index 0d6199fc65..31eb64b04b 100644 --- a/collects/scribble/doclang.ss +++ b/collects/scribble/doclang.ss @@ -1,11 +1,11 @@ -(module doclang (lib "new-lambda.ss" "scribblings") ; <--- temporary +(module doclang (lib "lang.ss" "big") (require "struct.ss" "decode.ss" (lib "kw.ss")) (require-for-syntax (lib "kerncase.ss" "syntax")) - (provide (all-from-except (lib "new-lambda.ss" "scribblings") #%module-begin) + (provide (all-from-except (lib "lang.ss" "big") #%module-begin) (rename *module-begin #%module-begin)) ;; Module wrapper ---------------------------------------- diff --git a/collects/scribble/eval.ss b/collects/scribble/eval.ss index 01a05770ce..92d9502489 100644 --- a/collects/scribble/eval.ss +++ b/collects/scribble/eval.ss @@ -1,5 +1,5 @@ -(module eval (lib "new-lambda.ss" "scribblings") +(module eval (lib "lang.ss" "big") (require "manual.ss" "struct.ss" "scheme.ss" @@ -171,7 +171,15 @@ (define (do-plain-eval s catching-exns?) (parameterize ([current-namespace (current-int-namespace)]) - (call-with-values (lambda () ((scribble-eval-handler) catching-exns? (strip-comments s))) list))) + (call-with-values (lambda () + ((scribble-eval-handler) + catching-exns? + (let ([s (strip-comments s)]) + (syntax-case s (module) + [(module . _rest) + (syntax-object->datum s)] + [_else s])))) + list))) (define-syntax interaction-eval (syntax-rules () diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 2204a6383b..5db07c202c 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -1,5 +1,5 @@ -(module manual (lib "new-lambda.ss" "scribblings") +(module manual (lib "lang.ss" "big") (require "decode.ss" "struct.ss" "scheme.ss" @@ -182,7 +182,7 @@ (provide defproc defproc* defstruct defthing defform defform* defform/subs defform*/subs defform/none specform specform/subs - specsubform specspecsubform specsubform/inline + specsubform specsubform/subs specspecsubform specsubform/inline schemegrammar schemegrammar* var svar void-const undefined-const) @@ -294,6 +294,18 @@ (*specsubform 'spec #f '(lit ...) (lambda () (schemeblock0 spec)) null null (lambda () (list desc ...)))] [(_ spec desc ...) (*specsubform 'spec #f null (lambda () (schemeblock0 spec)) null null (lambda () (list desc ...)))])) + (define-syntax specsubform/subs + (syntax-rules () + [(_ #:literals (lit ...) spec ([non-term-id non-term-form ...] ...) desc ...) + (*specsubform 'spec #f '(lit ...) (lambda () (schemeblock0 spec)) + '((non-term-id non-term-form ...) ...) + (list (list (lambda () (scheme non-term-id)) + (lambda () (schemeblock0 non-term-form)) + ...) + ...) + (lambda () (list desc ...)))] + [(_ spec subs desc ...) + (specsubform/subs #:literals () spec subs desc ...)])) (define-syntax specspecsubform (syntax-rules () [(_ spec desc ...) diff --git a/collects/scribblings/guide/guide-utils.ss b/collects/scribblings/guide/guide-utils.ss index af1227350a..6519f12fe9 100644 --- a/collects/scribblings/guide/guide-utils.ss +++ b/collects/scribblings/guide/guide-utils.ss @@ -1,4 +1,4 @@ -(module guide-utils (lib "new-lambda.ss" "scribblings") +(module guide-utils (lib "lang.ss" "big") (require (lib "manual.ss" "scribble") (lib "struct.ss" "scribble") (lib "decode.ss" "scribble") diff --git a/collects/scribblings/guide/module-basics.scrbl b/collects/scribblings/guide/module-basics.scrbl index cf438e0526..e1dde38c90 100644 --- a/collects/scribblings/guide/module-basics.scrbl +++ b/collects/scribblings/guide/module-basics.scrbl @@ -61,20 +61,5 @@ big (date->string (seconds->date (current-seconds)))) ] -Additional third-party libraries that are distributed through -@|PLaneT| can be imported using a @scheme[planet] form: - -@schememod[ -big - -(require "cake.ss" - (planet "random.ss" ("schematics" "random.plt" 1 0))) - -(print-cake (inexact->exact - (round (* 30 (random-gaussian))))) -] - -A @|PLaneT| reference starts like a @scheme[lib] reference, with a -relative path, but the path is followed by information about the -producer, archive, and version of the library. The specified archive -is downloaded and installed on demand. +We discuss more forms of module reference later in +@secref["guide:module-paths"]. diff --git a/collects/scribblings/guide/module-paths.scrbl b/collects/scribblings/guide/module-paths.scrbl new file mode 100644 index 0000000000..20cad9be0f --- /dev/null +++ b/collects/scribblings/guide/module-paths.scrbl @@ -0,0 +1,105 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "manual.ss" "scribble")] +@require[(lib "eval.ss" "scribble")] +@require["guide-utils.ss"] + +@title[#:tag "guide:module-paths"]{Module Paths} + +A @deftech{module path} is a reference to a module, as used with +@scheme[require] or as the @scheme[_initial-module-path] in a +@scheme[module] form. It can be any of several forms: + +@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@specsubform[id]{ + +A @tech{module path} that is just an identifier refers to a +@scheme[module] declaration using the identifier. This form of module +reference makes the most sense in a REPL, where a module can be +declared independent of any file. + +@examples[ +(module m (lib "big/lang.ss") + (provide color) + (define color "blue")) +(module n (lib "big/lang.ss") + (require m) + (printf "my favorite color is ~a\n" color)) +(require n) +]} + +@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@specsubform[rel-string]{ + +A string @tech{module path} is a relative path using Unix-style +conventions: @litchar{/} is the path separator, @litchar{..} refers to +the parent directory, and @litchar{.} refers to the same +directory. The @scheme[rel-string] must not start or end with a path +separator. + +The path is relative to the enclosing file, if any, or it is relative +to the current directory. (More precisely, it is relative to the value +of @scheme[(current-load-relative-directory)], which is set while +loading a file.) + +@secref["guide:module-basics"] shows examples using relative paths. +} + +@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@specsubform[#:literals (lib) + (lib rel-string)]{ + +Like a plain-string @scheme[rel-path], but the elements of +@scheme[rel-path] refer to @tech{collection}s and +sub-@tech{collections}, instead of directories and sub-directories. A +collection is represented by a directory in one of several +installation-specific locations. + +The common initial import @scheme[(lib "big/lang.ss")] uses this form; +it refers to the module whose source is the @file{lang.ss} file in the +@file{big} collection, which is installed as part of PLT Scheme. + +@examples[ +(module m (lib "big/lang.ss") + (require (lib "mzlib/date.ss")) + + (printf "Today is ~s\n" + (date->string (seconds->date (current-seconds))))) +(require m) +]} + +@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@specsubform/subs[#:literals (planet) + (planet rel-string (user-string pkg-string vers ...)) + ([vers nat + (nat nat) + (= nat) + (+ nat) + (- nat)])]{ + +Accesses a third-party library that is distributed through the +@|PLaneT| server. The specified package is downloaded and installed on +demand. A @|PLaneT| reference starts like a @scheme[lib] reference, +with a relative path, but the path is followed by information about +the producer, package, and version of the library. + +The version is expressed as a constraint on the acceptable version, +where a version number is a sequence of non-negative integers, and the +constraints determine the allowable values for each element in the +sequence. If no constraint is provided for a particular component, +then any version is allowed; in particular, omitting all +@scheme[vers]es means that any version is acceptable. Specifying at +least one @scheme[vers] is strongly recommended. + +For a version constraint, a plain @scheme[nat] is the same as +@scheme[(+ nat)], which matches @scheme[nat] or higher for the +corresponding component of the version number. A @scheme[(_start-nat +_end-nat)] matches any number in the range @scheme[_start-nat] to +@scheme[_end-nat] inclusive. A @scheme[(= nat)] matches only exactly +@scheme[nat]. A @scheme[(- nat)] matches @scheme[nat] or lower. + +@examples[ +(module m (lib "big/lang.ss") + (require (planet "random.ss" ("schematics" "random.plt" 1 0))) + (display (random-gaussian))) +] +} diff --git a/collects/scribblings/guide/module-provide.scrbl b/collects/scribblings/guide/module-provide.scrbl new file mode 100644 index 0000000000..ab4978e187 --- /dev/null +++ b/collects/scribblings/guide/module-provide.scrbl @@ -0,0 +1,7 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "manual.ss" "scribble")] +@require[(lib "eval.ss" "scribble")] +@require["guide-utils.ss"] + +@title[#:tag "guide:module-provide"]{Module Exports: @scheme[provide]} + diff --git a/collects/scribblings/guide/module-require.scrbl b/collects/scribblings/guide/module-require.scrbl new file mode 100644 index 0000000000..a8c7d091e1 --- /dev/null +++ b/collects/scribblings/guide/module-require.scrbl @@ -0,0 +1,7 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "manual.ss" "scribble")] +@require[(lib "eval.ss" "scribble")] +@require["guide-utils.ss"] + +@title[#:tag "guide:module-require"]{Module Imports: @scheme[require]} + diff --git a/collects/scribblings/guide/modules.scrbl b/collects/scribblings/guide/modules.scrbl index 88cbddb82c..9b2392f923 100644 --- a/collects/scribblings/guide/modules.scrbl +++ b/collects/scribblings/guide/modules.scrbl @@ -16,3 +16,6 @@ more than a few seconds belongs in a module. @include-section["module-basics.scrbl"] @include-section["module-syntax.scrbl"] +@include-section["module-paths.scrbl"] +@include-section["module-require.scrbl"] +@include-section["module-provide.scrbl"] diff --git a/collects/scribblings/reference/reader-example.ss b/collects/scribblings/reference/reader-example.ss index a64598ccd2..a2554cfab7 100644 --- a/collects/scribblings/reference/reader-example.ss +++ b/collects/scribblings/reference/reader-example.ss @@ -1,5 +1,5 @@ -(module reader-example (lib "new-lambda.ss" "scribblings") +(module reader-example (lib "lang.ss" "big") (require (lib "struct.ss" "scribble") (lib "decode.ss" "scribble") (lib "manual.ss" "scribble") diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 7759969686..0f30d477c3 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -661,6 +661,18 @@ information} and source-location information attached to ] } +@;------------------------------------------------------------------------ +@section[#:tag "mz:module"]{Modules: @scheme[module]} + +@defform[(module id require-spec form ...)]{ + +Declares a module named by @scheme[id]. The @scheme[require-spec] must +be as for @scheme[require] (see @secref["mz:require"]), and it +supplies the initial bindings for the body @scheme[form]s. Each +@scheme[form] is expanded in a @tech{module context}. + +} + @;------------------------------------------------------------------------ @section[#:tag "mz:require"]{Importing: @scheme[require], @scheme[require-for-syntax], @scheme[require-for-template]} @@ -739,7 +751,7 @@ can trigger automatic loading of the module declaration: @scheme[rel-string] is always parsed as a Unix-format relative path: @litchar{/} is the path delimiter (multiple adjacent @litchar{/}s are treated as a single delimiter), @litchar{..} accesses the parent - directory, and @litchar{.} accesses the current directory. The path + directory, and @litchar{.} accesses the current directory. The path cannot be empty or contain a leading or trailing slash.} @specsubform[#:literals (lib) (lib rel-string)]{Like the plain