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

doc work (start on module guide)

Browse Source 
svn: r6730
This commit is contained in:
Matthew Flatt 2007-06-25 06:37:25 +00:00
parent dc8d09997c
commit f7bf029234
13 changed files with 281 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
collects/scribble/html-render.ss
View File

@ -326,7 +326,7 @@
fns)))
(define/override (part-whole-page? d)
(= 2 (collecting-sub)))
((collecting-sub) . <= . 2))
(define/private (toc-part? d)
(and (styled-part? d)

2
collects/scribble/latex-render.ss
View File

@ -50,6 +50,7 @@
(define-color "schemeresult" "ResultColor")
(define-color "schemestdout" "OutputColor")
(define-color "schememeta" "IdentifierColor")
(define-color "schememod" "black")
(define-color "schemevariablecol" "IdentifierColor")
(printf "\\newcommand{\\schemevariable}[1]{{\\schemevariablecol{\\textsl{#1}}}}\n")
(define-color "schemeerrorcol" "red")
@ -232,6 +233,7 @@
[(ldquo) "``"]
[(rdquo) "''"]
[(rsquo) "'"]
[(prime) "$'$"]
[(rarr) "$\\rightarrow$"]))]
[else (display-protected (format "~s" i))])
null)

19
collects/scribble/manual.ss
View File

@ -94,7 +94,7 @@
(provide onscreen menuitem defterm
schemefont schemevalfont schemeresultfont schemeidfont
schemeparenfont schemekeywordfont schememetafont
schemeparenfont schemekeywordfont schememetafont schememodfont
file exec
link procedure
idefterm)
@ -120,6 +120,8 @@
(make-element "schemeparen" (decode-content str)))
(define (schememetafont . str)
(make-element "schememeta" (decode-content str)))
(define (schememodfont . str)
(make-element "schememod" (decode-content str)))
(define (schemekeywordfont . str)
(make-element "schemekeyword" (decode-content str)))
(define (file . str)
@ -808,12 +810,15 @@
(let loop ([i i])
(cond
[(string? i)
(let ([m (regexp-match #rx"^(.*)([()])(.*)$" i)])
(if m
(append (loop (cadr m))
(list (caddr m))
(loop (cadddr m)))
(list (make-element 'italic (list i)))))]
(cond
[(regexp-match #rx"^(.*)([()])(.*)$" i)
=> (lambda (m)
(append (loop (cadr m))
(list (caddr m))
(loop (cadddr m))))]
[else
(list (make-element 'italic (list i)))])]
[(eq? i 'rsquo) (list 'prime)]
[else (list i)])))
c)))))

54
collects/scribble/scheme.ss
View File

@ -49,6 +49,8 @@
(define-struct (sized-element element) (length))
(define-struct spaces (pre cnt post))
(define (typeset c multi-line? prefix1 prefix suffix color?)
(let* ([c (syntax-ize c 0)]
[content null]
@ -78,26 +80,35 @@
[(and (element? v)
(= 1 (length (element-content v))))
(sz-loop (car (element-content v)))]
[(spaces? v)
(+ (sz-loop (spaces-pre v))
(spaces-cnt v)
(sz-loop (spaces-post v)))]
[else 1])))]
[(v cls len)
(unless (equal? v "")
(if (equal? v "\n")
(if multi-line?
(begin
(finish-line!)
(out prefix cls))
(out " " cls))
(begin
(set! content (cons ((if highlight?
(lambda (c)
(make-element "highlighted" (list c)))
values)
(if color?
(make-element cls (list v))
(make-element #f (list v))))
content))
(set! dest-col (+ dest-col len)))))]))
(define advance
(cond
[(spaces? v)
(out (spaces-pre v) cls 0)
(out (make-element 'hspace (list (make-string (spaces-cnt v) #\space))) #f 0)
(out (spaces-post v) cls len)]
[(equal? v "\n")
(if multi-line?
(begin
(finish-line!)
(out prefix cls))
(out " " cls))]
[else
(set! content (cons ((if highlight?
(lambda (c)
(make-element "highlighted" (list c)))
values)
(if color?
(make-element cls (list v))
(make-element #f (list v))))
content))
(set! dest-col (+ dest-col len))]))]))
(define advance
(case-lambda
[(c init-line! delta)
(let ([c (+ delta (syntax-column c))]
@ -168,12 +179,9 @@
(define (literalize-spaces i)
(let ([m (regexp-match-positions #rx" +" i)])
(if m
(make-element
#f
(list (literalize-spaces (substring i 0 (caar m)))
(make-element 'hspace
(list (substring i (caar m) (cdar m))))
(literalize-spaces (substring i (cdar m)))))
(make-spaces (literalize-spaces (substring i 0 (caar m)))
(- (cdar m) (caar m))
(literalize-spaces (substring i (cdar m))))
i)))
(define (loop init-line! quote-depth)
(lambda (c)

7
collects/scribble/scribble.css
View File

@ -41,7 +41,7 @@
width: 10em;
margin-right: 2em;
text-align: left;
background-color: #ddffdd;
background-color: #F5F5DC;
}
.tocviewtitle {
@ -237,6 +237,11 @@
font-family: Courier; font-size: 80%;
}
.schememod {
color: black;
font-family: Courier; font-size: 80%;
}
.schemeopt {
color: black;
}

52
collects/scribblings/guide/define-struct.scrbl
View File

@ -6,23 +6,28 @@
@title[#:tag "guide:define-struct"]{Programmer-Defined Datatypes}
This section introduces the @scheme[define-struct] form for creating
your own datatypes. The class-based object system offers an alternate
mechanism for creating new datatypes; the resulting objects are
nevertheless implemented as structures, and we defer discussion of
objects to @secref["classes"].
@refalso["mz:structures"]{structure types}
New datatypes are normally created with the @scheme[define-struct]
form, which is the topic of this chapter. The class-based object
system, which we defer to @secref["classes"], offers an alternate
mechanism for creating new datatypes, but even classes and objects are
implemented in terms of structure types.
@; ------------------------------------------------------------
@section{Simple Structure Types: @scheme[define-struct]}
@refalso["mz:define-struct"]{@scheme[define-struct]}
To a first approximation, the syntax of @scheme[define-struct] is
@specform[
(define-struct struct-id (field-id ...))
]{}
Such a definition binds @scheme[_struct-id], but only to static
information about the structure type that cannot be used directly:
A @scheme[define-struct] declaration binds @scheme[_struct-id], but
only to static information about the structure type that cannot be
used directly:
@def+int[
(define-struct posn (x y))
@ -30,11 +35,11 @@ posn
]
We explain one use of the @scheme[_struct-id] binding in the next
section.
section, @secref["guide:struct-subtypes"].
In addition to defining @scheme[_struct-id], however,
@scheme[define-struct] also defines a number of functions whose names
are built from @scheme[_struct-id] and the @scheme[_field-id]s:
Meanwhile, in addition to defining @scheme[_struct-id],
@scheme[define-struct] also defines a number of identifiers that are
built from @scheme[_struct-id] and the @scheme[_field-id]s:
@itemize{
@ -71,8 +76,9 @@ are built from @scheme[_struct-id] and the @scheme[_field-id]s:
@item{@schemeidfont{struct:}@scheme[_struct-id] : a
@deftech{structure type descriptor}, which is a value that
represents the structure type (as opposed to a single instance)
for certain reflective operations.}
represents the structure type as a first-class value (with
@scheme[#:super], as discussed later in
@secref["guide:struct-options"]).}
}
@ -86,9 +92,9 @@ as requiring them to be numbers, is normally the job of a contract, as
discussed later in @secref["guide:contracts"].
@; ------------------------------------------------------------
@section{Structure Subtypes}
@section[#:tag "guide:struct-subtypes"]{Structure Subtypes}
An extended form of @scheme[defin-struct] can be used to define a
An extended form of @scheme[define-struct] can be used to define a
@defterm{structure subtype}, which is a structure type that extends an
existing structure type:
@ -97,8 +103,8 @@ existing structure type:
]
The @scheme[_super-id] must be a structure type name bound by
@scheme[define-struct] (i.e., the name bound by @scheme[define-struct]
that cannot be used directly as an expression).
@scheme[define-struct] (i.e., the name that cannot be used directly as
an expression).
@as-examples[@schemeblock+eval[
(define-struct posn (x y))
@ -146,7 +152,7 @@ field-name sequence:
An instance of a transparent structure type prints like a vector, and
it shows the content of the structure's fields. A transparent
structure type also allows reflective operations, like
structure type also allows reflective operations, such as
@scheme[struct?] and @scheme[struct-info], to be used on its instances
(see @secref["reflection"]). Different values for @scheme[#:inspector]
support more controlled access to reflective operations.
@ -158,7 +164,7 @@ library cannot manipulate the data in the structure except as allowed
by the library.
@; ------------------------------------------------------------
@section{More Structure Type Options}
@section[#:tag "guide:struct-options"]{More Structure Type Options}
The full syntax of @scheme[define-struct] supports many options, both
at the structure-type level and at the level of individual fields:
@ -199,8 +205,8 @@ A @scheme[_struct-option] always starts with a keyword:
Specifies a value to be used for all automatic fields in the
structure type, where an automatic field is indicated by the
@scheme[#:auto] @scheme[_field-option]. The structure type's
constructor omits arguments for automatic fields.
@scheme[#:auto] field option. The constructor procedure does not
accept arguments for automatic fields.
@defexamples[
(define-struct posn (x y [z #:auto])
@ -302,7 +308,7 @@ times.
@defexamples[
(define (add-bigger-fish lst)
(define-struct fish (size) #:inspector #f)
(define-struct fish (size) #:inspector #f) (code:comment #,(t "new every time"))
(cond
[(null? lst) (list (make-fish 1))]
[else (cons (make-fish (* 2 (fish-size (car lst))))
@ -320,3 +326,5 @@ times.
lst)]))]
(add-bigger-fish (add-bigger-fish null))
]
@refdetails["mz:structures"]{structure types}

4
collects/scribblings/guide/guide.scrbl
View File

@ -31,7 +31,7 @@ precise details to @|MzScheme| and other reference manuals.
@include-section["define-struct.scrbl"]
@include-section["module-basics.scrbl"]
@include-section["modules.scrbl"]
@; ----------------------------------------------------------------------
@section[#:tag "guide:contracts"]{Contracts}
@ -80,7 +80,7 @@ of an expression to the values for the clause:
@section[#:tag "threads"]{Threads}
@; ----------------------------------------------------------------------
@section[#:tag "guide:macros"]{Syntactic Extension@aux-elem{ (Modules and Macros)}}
@section[#:tag "guide:macros"]{Syntactic Extension@aux-elem{ (Macros)}}
@; ----------------------------------------------------------------------

71
collects/scribblings/guide/module-basics.scrbl
View File

@ -3,19 +3,12 @@
@require[(lib "eval.ss" "scribble")]
@require["guide-utils.ss"]
@title{Modules}
@title[#:tag "guide:module-basics"]{Module Basics}
Scheme definitions and expressions are normally written inside of a
module. Although a REPL evaluates definitions and expressions outide
of a module, and although @scheme[load] can evaluate definitions and
expressions from a file as if they appeared in a REPL interaction,
code that is meant to last for more than a few seconds belongs in a
module.
The space of modules is distinct from the space of normal Scheme
definitions. Since modules typically reside in files, the space of
module names is explicitly tied to the filesystem at run time. For
example, if the file @file{/home/molly/cake.ss} contains
The space of module names is distinct from the space of normal Scheme
definitions. Indeed, since modules typically reside in files, the
space of module names is explicitly tied to the filesystem at run
time. For example, if the file @file{/home/molly/cake.ss} contains
@schememod[
big
@ -31,10 +24,14 @@ big
]
then it can be used as the source of a module whose full name is based
on the path @file{/home/molly/cake.ss}. Instead of using the full
path, however, the module is likely to be referenced by a releative
path. For example, a file @file{/home/molly/random-cake.ss} could use
the module like this:
on the path @file{/home/molly/cake.ss}. The @scheme[provide] line
exports the definition @scheme[print-cake] so that it can be used
outside the module.
Instead of using its full path, a module is more likely to be
referenced by a relative path. For example, a file
@file{/home/molly/random-cake.ss} could use the @file{cake.ss} module
like this:
@schememod[
big
@ -44,10 +41,40 @@ big
(print-cake (random 30))
]
The relative reference @scheme[(require "cake.ss")] works because the
@file{cake.ss} module source is in the same directory as the
@file{random-cake.ss} file.
The relative reference @scheme["cake.ss"] in the import
@scheme[(require "cake.ss")] works because the @file{cake.ss} module
source is in the same directory as the @file{random-cake.ss}
file. (Unix-style relative paths are used for relative module
references on all platforms, much like relative URLs.)
As you see in the above examples, @scheme[provide] and
@scheme[require] are module-level declarations that export and import
bindings between modules.
Library modules that are distributed with PLT Scheme are referenced
through a @scheme[lib] path. A @scheme[lib] path is like a relative
path, but it is relative (roughly) to the library installation
directory.
@schememod[
big
(require (lib "mzlib/date.ss"))
(printf "Today is ~s\n"
(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.

87
collects/scribblings/guide/module-syntax.scrbl Normal file
View File

@ -0,0 +1,87 @@
#reader(lib "docreader.ss" "scribble")
@require[(lib "manual.ss" "scribble")]
@require[(lib "eval.ss" "scribble")]
@require["guide-utils.ss"]
@title{Module Syntax}
The @litchar{#module} at the start of a module file begins a shorthand
for a @scheme[module] form, much like @litchar{'} is a shorthand for a
@scheme[quote] form. Unlike @litchar{'}, the @litchar{#module}
shorthand does not work well in a REPL, in part because it must be
terminated by an end-of-file, but also because the longhand expansion
of @litchar{#module} depends on the name of the enclosing file.
@;------------------------------------------------------------------------
@section{The @scheme[module] Form}
The longhand form of a module declaration, which works in a REPL as
well as a file, is
@specform[
(module name-id initial-module-path
decl ...)
]
where the @scheme[_name-id] is a name for the module,
@scheme[_initial-module-path] is an initial import, and each
@scheme[_decl] is an import, export, definition, or expression. In
the case of a file, @scheme[_name-id] must match the name of the
containing file, minus its directory path or file extension.
The @scheme[_initial-module-path] is needed because even the
@scheme[require] form must be imported for further use in the module
body. In other words, the @scheme[_initial-module-path] import
bootstraps the syntax available in the body. The most commonly used
@scheme[_initial-module-path] is @scheme[(lib "big/lang.ss")], which
supplies most of the bindings described in this guide, including
@scheme[require], @scheme[define], and @scheme[provide].
For example, the @file{cake.ss} example of the
@seclink["guide:module-basics"]{previous section} could be written as
@schemeblock[
(module cake (lib "big/lang.ss")
(provide print-cake)
(define (print-cake n)
(printf " ~a \n" (make-string n #\.))
(printf " .-~a-.\n" (make-string n #\|))
(printf " | ~a |\n" (make-string n #\space))
(printf "---~a---\n" (make-string n #\-))))
]
Furthermore, this @scheme[module] form can be evaluated in a REPL to
declare a @scheme[cake] module that is not associated with any file.
@;------------------------------------------------------------------------
@section{The @schememodfont{#module} Shorthand}
Unlike @litchar{'}, there is no fixed syntax for the body of a
@litchar{#module} shorthand. In general, the syntax is determined by
the language name that follows @litchar{#module}.
In the case of @schememodfont{#module} @schememodname[big], the syntax
is
@schememod[
big
_decl ...]
which reads the same as
@schemeblock[
(module _name (lib "big/lang.ss")
_decl ...)
]
where @scheme[_name] is derived from the name of the file that
contains the @schememodfont{#module} form.
The @schememodfont{#module} @scheme[little] form has the same syntax
as @schememodfont{#module} @schememodname[big], except that the
longhand expansion uses @scheme[(lib "little/lang.ss")] instead of
@scheme[(lib "big/lang.ss")]. The @schememodfont{#module}
@scheme[honu] form, in contrast, has a completely different syntax
that doesn't even look like Scheme, and which we do not attempt to
describe in this guide.

18
collects/scribblings/guide/modules.scrbl Normal file
View File

@ -0,0 +1,18 @@
#reader(lib "docreader.ss" "scribble")
@require[(lib "manual.ss" "scribble")]
@require[(lib "eval.ss" "scribble")]
@require["guide-utils.ss"]
@title[#:tag "guide:modules" #:style 'toc]{Modules}
Scheme definitions and expressions are normally written inside of a
module. Although a REPL evaluates definitions and expressions outside
of a module for exploration and debugging purposes, and although
@scheme[load] can evaluate definitions and expressions from a file as
if they appeared in a REPL interaction, code that is meant to last for
more than a few seconds belongs in a module.
@local-table-of-contents[]
@include-section["module-basics.scrbl"]
@include-section["module-syntax.scrbl"]

26
collects/scribblings/reference/define-struct.scrbl
View File

@ -22,38 +22,42 @@
[field-option #:immutable
#:auto])]{
Creates a new structure type, and binds transformers and
variables related to the new structure type. A
@moreref["mz:structures"]{structures}
Creates a new @techlink{structure type}, and binds transformers and
variables related to the new @tech{structure type}. A
@scheme[define-struct] form with @math{n} @scheme[field]s defines
up to @math{4+2n} names:
@itemize{
@item{@schemeidfont{struct:}@scheme[id], a @tech{structure type descriptor}
value that represents the new datatype.}
@item{@schemeidfont{struct:}@scheme[id], a @deftech{structure type
descriptor} value that represents the new @tech{structure
type}.}
@item{@schemeidfont{make-}@scheme[id], a @deftech{constructor}
procedure that takes @math{m} arguments and returns a new
instance of the structure type, where @math{m} is the number of
@scheme[field]s that do not include an @scheme[#:auto] option.}
instance of the @tech{structure type}, where @math{m} is the
number of @scheme[field]s that do not include an
@scheme[#:auto] option.}
@item{@scheme[id]@schemeidfont{?}, a @deftech{predicate} procedure
that returns @scheme[#t] for instances of the structure type
(constructed by @schemeidfont{make-}@scheme[id] or the
that returns @scheme[#t] for instances of the @tech{structure
type} (constructed by @schemeidfont{make-}@scheme[id] or the
@tech{constructor} for a subtype) and @scheme[#f] for any other
value.}
@item{@scheme[id]@schemeidfont{-}@scheme[field-id], for each
@scheme[field]; an @deftech{accessor} procedure that takes an
instance of the structure type and extracts the value for the
corresponding field.}
instance of the @tech{structure type} and extracts the value
for the corresponding field.}
@item{@schemeidfont{set-}@scheme[id]@schemeidfont{-}@scheme[field-id]@schemeidfont{!},
for each @scheme[field] that does not include a
@scheme[#:immutable] option, and only when the
@scheme[#:immutable] option is not specified as a
@scheme[struct-option]; a @deftech{mutator} procedure that
takes an instance of the structure type and a new field
takes an instance of the @tech{structure type} and a new field
value. The structure is destructively updated with the new
value, and @|void-const| is returned.}

17
collects/scribblings/reference/mz.ss
View File

@ -19,7 +19,19 @@
[(_ s) (scheme s)]))
(provide exnraise Exn)
(provide Guide guideintro)
(provide refalso moreref Guide guideintro)
(define/kw (refalso tag #:body s)
(apply margin-note
(decode-content (append (list magnify (secref tag) " also provides information on ")
s
(list ".")))))
(define/kw (moreref tag #:body s)
(apply margin-note
(decode-content (append (list magnify (secref tag) " provides more information on ")
s
(list ".")))))
(define Guide
(italic (link "../guide/index.html" "A Guide to PLT Scheme")))
@ -27,5 +39,6 @@
(define/kw (guideintro tag #:body s)
(apply margin-note
(decode-content (append (list finger (secref tag) " in " Guide " introduces ")
s)))))
s
(list "."))))))

18
collects/scribblings/reference/struct.scrbl
View File

@ -3,7 +3,9 @@
@title[#:tag "mz:structures"]{Structures}
A @pidefterm{structure type} is a record datatype composing a number
@guideintro["guide:define-struct"]{structure types via @scheme[define-struct]}
A @deftech{structure type} is a record datatype composing a number
of @idefterm{fields}. A @pidefterm{structure}, an instance of a
structure type, is a first-class value that contains a value for each
field of the structure type. A structure instance is created with a
@ -13,6 +15,8 @@ accessed and changed with type-specific @tech{accessor} and
@tech{predicate} procedure that answers @scheme[#t] for instances of
the structure type and @scheme[#f] for any other value.
@refalso["mz:define-struct"]{structure types via @scheme[define-struct]}
A structure type's fields are essentially unnamed, though names are
supported for error-reporting purposes. The constructor procedure
takes one value for each field of the structure type, except that some
@ -83,13 +87,13 @@ Creates a new structure type. The @scheme[name] argument is used as
the type name. If @scheme[super-type] is not @scheme[#f], the new type
is a subtype of the corresponding structure type.
The new structure type has @scheme[(+ init-field-cnt auto-field-cnt)]
The new structure type has @math{@scheme[init-field-cnt]+@scheme[auto-field-cnt]}
fields (in addition to any fields from @scheme[super-type]), but only
@scheme[init-field-cnt] constructor arguments (in addition to any
constructor arguments from @scheme[super-type]). The remaining
fields are initialized with @scheme[auto-v].
The @scheme{props} argument is a list of pairs, where the @scheme[car]
The @scheme[props] argument is a list of pairs, where the @scheme[car]
of each pair is a structure type property descriptor, and the
@scheme[cdr] is an arbitrary value. See @secref["mz:structprops"] for
more information about properties.
@ -131,7 +135,7 @@ subtype's guard procedure become the first @math{n} arguments to
@scheme[guard].
The result of @scheme[make-struct-type] is five values:
%
@itemize{
@item{a @tech{structure type descriptor},}
@ -158,7 +162,9 @@ The result of @scheme[make-struct-type] is five values:
(a-ref an-a 2)
(define a-first (make-struct-field-accessor a-ref 0))
(a-first an-a)
]
@interaction[
(define-values (struct:b make-b b? b-ref b-set!)
(make-struct-type 'b struct:a 1 2 'b-uninitialized))
(define a-b (make-b 'x 'y 'z))
@ -167,7 +173,9 @@ The result of @scheme[make-struct-type] is five values:
(b-ref a-b 0)
(b-ref a-b 1)
(b-ref a-b 2)
]
@interaction[
(define-values (struct:c make-c c? c-ref c-set!)
(make-struct-type
'c struct:b 0 0 #f null (make-inspector) #f null
@ -235,7 +243,7 @@ A @index['("structure type properties")]{@defterm{structure type
@itemize{
@item{a @deftech{structure property type descriptor}, for use with
@item{a @deftech{structure type property descriptor}, for use with
@scheme[make-struct-type] and @scheme[define-struct];}
@item{a @deftech{property predicate} procedure, which takes an