#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?].