147 lines
5.8 KiB
Racket
147 lines
5.8 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/struct scribble/racket "mz.rkt")
|
|
|
|
@title[#:tag "intro"]{Introduction}
|
|
|
|
This chapter introduces essential terminology and notation that is
|
|
used throughout the rest of the document and other Racket reference
|
|
manuals.
|
|
|
|
@section{Notation}
|
|
|
|
The following sections explain how to read the notation used in Racket
|
|
manuals to describe syntactic forms and values that are provided by
|
|
the base language and by additional libraries.
|
|
|
|
Syntactic forms, whether provided from the base language or via
|
|
syntactic extensions, are specified using the same format that is
|
|
described in the @guidesecref{syntax-notation} chapter of @|Guide|.
|
|
|
|
@section{How to Read Module Declarations}
|
|
|
|
Racket programs are usually organized into @tech{module}s. The Reference
|
|
reflects this organization with a notation for module declarations.
|
|
A module declaration often prefaces the beginning of a Reference section
|
|
or subsection:
|
|
|
|
@; TODO: change `defmodule` to support this
|
|
@(make-table "defmodule"
|
|
(list
|
|
(list
|
|
(make-flow
|
|
(list
|
|
(make-omitable-paragraph
|
|
(list (hspace 1) (racket (require racket/list)))))))))
|
|
|
|
The preceding @racket[require] statement indicates that the bindings that would be
|
|
documented below are available in the @racketmodname[racket/list] module. When
|
|
a module name is not explicitly mentioned, it usually indicates that the
|
|
documented bindings are contained in @racketmodname[racket/base].
|
|
|
|
|
|
@section{How to Read Contracts for Functions}
|
|
|
|
Procedures and other values are described using a notation based on
|
|
@tech{contract}s. In essence, these contracts describe the interfaces of
|
|
the documented library using Racket predicates and expressions.
|
|
|
|
For example, the following is the header of the definition of a
|
|
typical procedure:
|
|
|
|
@defproc[#:link-target? #f
|
|
(char->integer [char char?]) exact-integer?]{}
|
|
|
|
The function being defined, @racket[char->integer], is typeset as if it
|
|
were being applied. The metavariables that come after the function name
|
|
stand in for arguments. The white text in the corner identifies the
|
|
kind of value that is being documented.
|
|
|
|
Each metavariable is described with a contract. In the preceding
|
|
example, the metavariable @racket[_char] has the contract
|
|
@racket[char?]. This contract specifies that any argument
|
|
@racket[_char] that answers true to the @racket[char?] predicate is
|
|
valid. The documented function may or may not actually check this
|
|
property, but the contract signals the intent of the implementer.
|
|
|
|
The contract on the right of the arrow, @racket[exact-integer?] in this case,
|
|
specifies the expected result that is produced by the function.
|
|
|
|
Contract specifications can be more expressive than just names of
|
|
predicates. Consider the following header for @racket[argmax]:
|
|
|
|
@defproc[#:link-target? #f
|
|
(argmax [proc (-> any/c real?)]
|
|
[lst (and/c pair? list?)])
|
|
any]{}
|
|
|
|
The contract @racket[(-> any/c real?)] denotes a function contract specifying
|
|
that @racket[proc]'s argument can be any single value and the result should be
|
|
a real number. The contract @racket[(and/c pair? list?)] for @racket[_lst]
|
|
specifies that @racket[_lst] should pass both @racket[pair?] and @racket[list?]
|
|
(i.e., that it is a non-empty list).
|
|
|
|
Both @racket[->] and @racket[and/c] are examples of @tech{contract combinator}s.
|
|
Contract combinators such as @racket[or/c], @racket[cons/c], @racket[listof],
|
|
and others are used throughout the documentation. Clicking on the hyperlinked
|
|
combinator name will provide more information on its meaning.
|
|
|
|
A Racket function may be documented as having one or more optional arguments.
|
|
The @racket[read] function is an example of such a function:
|
|
|
|
@defproc[#:link-target? #f
|
|
(read [in input-port? (current-input-port)])
|
|
any]{}
|
|
|
|
The brackets surrounding the @racket[_in] argument in the application
|
|
syntax indicates that it is an optional argument.
|
|
|
|
The header for @racket[read] specifies a contract for the parameter
|
|
@racket[_in] as usual. To the right of the contract, it also specifies
|
|
a default value @racket[(current-input-port)] that is used if
|
|
@racket[read] is called with no arguments.
|
|
|
|
Functions may also be documented as accepting mandatory or optional
|
|
keyword-based arguments. For example, the @racket[sort] function has
|
|
two optional, keyword-based arguments:
|
|
|
|
@defproc[#:link-target? #f
|
|
(sort [lst list?] [less-than? (any/c any/c . -> . any/c)]
|
|
[#:key extract-key (any/c . -> . any/c) (lambda (x) x)]
|
|
[#:cache-keys? cache-keys? boolean? #f]) list?]{}
|
|
|
|
The brackets around the @racket[_extract-key] and
|
|
@racket[_cache-keys?] arguments indicate that they are optional as
|
|
before. The contract section of the header shows the default values
|
|
that are provided for these keyword arguments.
|
|
|
|
@section{How to Read Parameter Contracts}
|
|
|
|
Parameters are used in Racket for dynamically customizable arguments
|
|
to code. They are documented with a notation similar to function
|
|
contracts:
|
|
|
|
@defparam[#:link-target? #f
|
|
current-command-line-arguments
|
|
argv
|
|
(vectorof (and/c string? immutable?))]{}
|
|
|
|
Since parameters can be read or written, there are two entries in the
|
|
header above. Calling @racket[current-command-line-arguments] with no
|
|
arguments is documented to return a vector that contains objects that
|
|
pass both @racket[string?] and @racket[immutable?]. Similarly, the
|
|
single argument case takes a vector with the same specification and
|
|
returns an object satisfying @racket[void?].
|
|
|
|
@section{How to Read Contracts on Other Values}
|
|
|
|
Some libraries provide bindings to constant values. These values are
|
|
documented with a separate header:
|
|
|
|
@defthing[#:link-target? #f object% class?]{}
|
|
|
|
The @racketmodname[racket/class] library provides the @racket[object%]
|
|
value, which is the root of the class hierarchy in Racket. Its
|
|
documentation header just indicates that it is a value that satisfies
|
|
the predicate @racket[class?].
|
|
|