113 lines
63 KiB
HTML
113 lines
63 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>2 Notation for Documentation</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="extras.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="icons.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">The Racket Reference</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="model.html" class="tocviewlink" data-pltdoc="x">Language Model</a></td></tr><tr><td align="right">2 </td><td><a href="notation.html" class="tocviewselflink" data-pltdoc="x">Notation for Documentation</a></td></tr><tr><td align="right">3 </td><td><a href="syntax.html" class="tocviewlink" data-pltdoc="x">Syntactic Forms</a></td></tr><tr><td align="right">4 </td><td><a href="data.html" class="tocviewlink" data-pltdoc="x">Datatypes</a></td></tr><tr><td align="right">5 </td><td><a href="structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">6 </td><td><a href="mzlib_class.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">7 </td><td><a href="mzlib_unit.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">8 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">9 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Control Flow</a></td></tr><tr><td align="right">11 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr><tr><td align="right">12 </td><td><a href="Macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">13 </td><td><a href="input-and-output.html" class="tocviewlink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">14 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Reflection and Security</a></td></tr><tr><td align="right">15 </td><td><a href="os.html" class="tocviewlink" data-pltdoc="x">Operating System</a></td></tr><tr><td align="right">16 </td><td><a href="memory.html" class="tocviewlink" data-pltdoc="x">Memory Management</a></td></tr><tr><td align="right">17 </td><td><a href="unsafe.html" class="tocviewlink" data-pltdoc="x">Unsafe Operations</
|
||
|
|
used throughout Racket documentation.</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Notation_for_Module_Documentation"">2.1<tt> </tt><a name="(part._.Notation_for_.Module_.Documentation)"></a>Notation for Module Documentation</h4><p>Since Racket programs are organized into <a href="eval-model.html#%28tech._module%29" class="techoutside" data-pltdoc="x"><span class="techinside">module</span></a>s, documentation
|
||
|
|
reflects that organization with an annotation at the beginning of a
|
||
|
|
section or subsection that describes the bindings that a particular
|
||
|
|
module provides.</p><p>For example, the section that describes the functionality provided by
|
||
|
|
<a href="pairs.html#%28mod-path._racket%2Flist%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/list</span></a> starts</p><blockquote><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="pairs.html#%28mod-path._racket%2Flist%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/list</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <a href="https://pkgs.racket-lang.org/package/base" title="Install this package using `raco pkg install base`"><span class="stt">base</span></a></span></td></tr></table></blockquote><p>Instead of <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span>, some modules are introduced with
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a>:</p><blockquote><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <a href="https://pkgs.racket-lang.org/package/base" title="Install this package using `raco pkg install base`"><span class="stt">base</span></a></span></td></tr></table></blockquote><p>Using <a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a> means that the module is normally used as the
|
||
|
|
language of a whole module—<wbr></wbr>that is, by a module that starts
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a> followed by the language—<wbr></wbr>instead of imported with
|
||
|
|
<span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span>. Unless otherwise specified, however, a module name
|
||
|
|
documented with <a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a> can also be used with <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span> to
|
||
|
|
obtain the language’s bindings.</p><p>The module annotation also shows the
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=pkg&rel=Package_Concepts.html%23%2528tech._package%2529&version=8.6" class="techoutside Sq" data-pltdoc="x"><span class="techinside">package</span></a>
|
||
|
|
that the module belongs to on the right-hand side. For more details
|
||
|
|
about packages, see
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=pkg&rel=index.html&version=8.6" class="Sq" data-pltdoc="x">Package Management in Racket</a>.</p><p>Sometimes, a module specification appears at the beginning of a
|
||
|
|
document or at the start of a section that contains many subsections.
|
||
|
|
The document’s section or section’s subsections are meant to
|
||
|
|
“inherit” the module declaration of the enclosing document or
|
||
|
|
section. Thus, bindings documented in <a href="index.html" data-pltdoc="x">The Racket Reference</a> are available from
|
||
|
|
<a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a> and <span class="RktSym">racket/base</span> unless otherwise
|
||
|
|
specified in a section or subsection.</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Notation_for_Syntactic_Form_Documentation"">2.2<tt> </tt><a name="(part._.Notation_for_.Syntactic_.Form_.Documentation)"></a>Notation for Syntactic Form Documentation</h4><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p><span class="imageleft"><img src="finger.png" alt="+" width="24" height="24"/></span><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=syntax-notation.html&version=8.6" class="Sq" data-pltdoc="x">Notation</a> in <a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=index.html&version=8.6" class="Sq" data-pltdoc="x">The Racket Guide</a> introduces this notation for syntactic forms.</p></blockquote></blockquote></blockquote><p>Syntactic forms are specified with a grammar. Typically, the grammar
|
||
|
|
starts with an open parenthesis followed by the syntactic form’s name,
|
||
|
|
as in the grammar for <span class="RktSym"><a href="if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29" class="RktStxLink" data-pltdoc="x">if</a></span>:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">if</a></span><span class="hspace"> </span><span class="RktVar">test-expr</span><span class="hspace"> </span><span class="RktVar">then-expr</span><span class="hspace"> </span><span class="RktVar">else-expr</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></blockquote><p>Since every <a href="syntax-model.html#%28tech._form%29" class="techoutside" data-pltdoc="x"><span class="techinside">form</span></a> is expressed in terms of <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax
|
||
|
|
objects</span></a>, parentheses in a grammar specification indicate a <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax
|
||
|
|
object</span></a> wrapping a list, and the leading <span class="RktSym"><a href="if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29" class="RktStxLink" data-pltdoc="x">if</a></span> is an identifier
|
||
|
|
that starts the list whose <a href="syntax-model.html#%28tech._binding%29" class="techoutside" data-pltdoc="x"><span class="techinside">binding</span></a> is the <span class="RktSym"><a href="if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29" class="RktStxLink" data-pltdoc="x">if</a></span> binding
|
||
|
|
of the module being documented—<wbr></wbr>in this case,
|
||
|
|
<a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a>. Square brackets in the grammar indicate
|
||
|
|
a <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax-object</span></a> list in the same way as parentheses, but in
|
||
|
|
places square brackets are normally used by convention in a program’s
|
||
|
|
source.</p><p>Italic <a href="syntax-model.html#%28tech._identifier%29" class="techoutside" data-pltdoc="x"><span class="techinside">identifiers</span></a> in the grammar are <a name="(tech._metavariable)"></a><span style="font-style: italic">metavariables</span>
|
||
|
|
that correspond to other grammar productions. Certain metavariable
|
||
|
|
names have implicit grammar productions:</p><ul><li><p>A metavariable that ends in <span class="RktVar">id</span> stands for an
|
||
|
|
<a href="syntax-model.html#%28tech._identifier%29" class="techoutside" data-pltdoc="x"><span class="techinside">identifier</span></a>.</p></li><li><p>A metavariable that ends in <span class="RktVar">keyword</span> stands
|
||
|
|
for a <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax-object</span></a> <a href="keywords.html#%28tech._keyword%29" class="techoutside" data-pltdoc="x"><span class="techinside">keyword</span></a>.</p></li><li><p>A metavariable that ends with <span class="RktVar">expr</span> stands for any
|
||
|
|
form, and the form will be parsed as an expression.</p></li><li><p>A metavariable that ends with <span class="RktVar">body</span> stands for any
|
||
|
|
<a href="syntax-model.html#%28tech._form%29" class="techoutside" data-pltdoc="x"><span class="techinside">form</span></a>; the form will be parsed as either a local definition or
|
||
|
|
an expression. A <span class="RktVar">body</span> can parse as a definition only
|
||
|
|
if it is not preceded by any expression, and the last
|
||
|
|
<span class="RktVar">body</span> must be an expression; see also
|
||
|
|
<a href="syntax-model.html#%28part._intdef-body%29" data-pltdoc="x">Internal Definitions</a>.</p></li><li><p>A metavariable that ends with <span class="RktVar">datum</span> stands for any
|
||
|
|
<a href="syntax-model.html#%28tech._form%29" class="techoutside" data-pltdoc="x"><span class="techinside">form</span></a>, and the form is normally uninterpreted (e.g.,
|
||
|
|
<span class="RktSym"><a href="quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">quote</a></span>d).</p></li><li><p>A metavariable that ends with <span class="RktVar">number</span> or
|
||
|
|
<span class="RktVar">boolean</span> stands for any <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax-object</span></a> (i.e.,
|
||
|
|
literal) <a href="numbers.html#%28tech._number%29" class="techoutside" data-pltdoc="x"><span class="techinside">number</span></a> or <a href="booleans.html#%28tech._boolean%29" class="techoutside" data-pltdoc="x"><span class="techinside">boolean</span></a>, respectively.</p></li></ul><p>In a grammar, <span class="RktVar">form</span><span class="stt"> </span><span class="RktSym"><a href="stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29" class="RktStxLink" data-pltdoc="x">...</a></span> stands for any number of forms
|
||
|
|
(possibly zero) matching <span class="RktVar">form</span>, while <span class="RktVar">form</span><span class="stt"> </span><span class="RktSym">...+</span>
|
||
|
|
stands for one or more forms matching <span class="RktVar">form</span>.</p><p>Metavariables without an implicit grammar are defined by productions
|
||
|
|
alongside the syntactic form’s overall grammar. For example, in</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktVar">formals</span><span class="hspace"> </span><span class="RktVar">body</span><span class="hspace"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="stt"> </span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="specgrammar"><tr><td align="right" valign="baseline"><span class="RktVar">formals</span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">=</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktVar">id</span></td></tr><tr><td align="right" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">|</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktPn">(</span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="RktPn">)</span></td></tr><tr><td align="right" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">|</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktPn">(</span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktMeta">...+</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktVar">rest-id</span><span class="RktPn">)</span></td></tr></table></td></tr></table></blockquote></blockquote><p>the <span class="RktVar">formals</span> metavariable stands for either an
|
||
|
|
<a href="syntax-model.html#%28tech._identifier%29" class="techoutside" data-pltdoc="x"><span class="techinside">identifier</span></a>, zero or more <a href="syntax-model.html#%28tech._identifier%29" class="techoutside" data-pltdoc="x"><span class="techinside">identifiers</span></a> in a
|
||
|
|
<a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax-object</span></a> list, or a <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax object</span></a> corresponding to
|
||
|
|
a chain of one or more pairs where the chain ends in an
|
||
|
|
<a href="syntax-model.html#%28tech._identifier%29" class="techoutside" data-pltdoc="x"><span class="techinside">identifier</span></a> instead of an empty list.</p><p>Some syntactic forms have multiple top-level grammars, in which case
|
||
|
|
the documentation of the syntactic forms shows multiple grammars. For
|
||
|
|
example,</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="createclass.html#%28form._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._init-rest%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">init-rest</a></span><span class="hspace"> </span><span class="RktVar">id</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="createclass.html#%28form._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._init-rest%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">init-rest</a></span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote><p>indicates that <span class="RktSym"><a href="createclass.html#%28form._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._init-rest%29%29" class="RktStxLink" data-pltdoc="x">init-rest</a></span> can either be alone in its
|
||
|
|
<a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax-object</span></a> list or followed by a single <a href="syntax-model.html#%28tech._identifier%29" class="techoutside" data-pltdoc="x"><span class="techinside">identifier</span></a>.</p><p>Finally, a grammar specification that includes <span class="RktVar">expr</span>
|
||
|
|
metavariables may be augmented with run-time <a href="contracts.html#%28tech._contract%29" class="techoutside" data-pltdoc="x"><span class="techinside">contract</span></a>s on some
|
||
|
|
of the metavariables, which indicate a predicate that the result of
|
||
|
|
the expression must satisfy at run time. For example,</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><table cellspacing="0" cellpadding="0" class="RktBlk RForeground"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="parameters.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">parameterize</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktVar">parameter-expr</span><span class="hspace"> </span><span class="RktVar">value-expr</span><span class="RktPn">]</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">body</span><span class="hspace"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span></td></tr></table></blockquote></td></tr><tr><td><span class="stt"> </span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="argcontract"><tr><td><span class="hspace"> </span></td><td><span class="RktVar">parameter-expr</span></td><td><span class="hspace"> </span></td><td>:</td><td><span class="hspace"> </span></td><td><span class="RktSym"><a href="parameters.html#%28def._%28%28quote._~23~25kernel%29._parameter~3f%29%29" class="RktValLink" data-pltdoc="x">parameter?</a></span></td></tr></table></td></tr></table></blockquote></blockquote><p>indicates that the result of each <span class="RktVar">parameter-expr</span> must be a
|
||
|
|
value <span class="RktVar">v</span> for which <span class="RktPn">(</span><span class="RktSym"><a href="parameters.html#%28def._%28%28quote._~23~25kernel%29._parameter~3f%29%29" class="RktValLink" data-pltdoc="x">parameter?</a></span><span class="stt"> </span><span class="RktVar">v</span><span class="RktPn">)</span> returns true.</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Notation_for_Function_Documentation"">2.3<tt> </tt><a name="(part._.Notation_for_.Function_.Documentation)"></a>Notation for Function Documentation</h4><p>Procedures and other values are described using a notation based on
|
||
|
|
<a href="contracts.html#%28tech._contract%29" class="techoutside" data-pltdoc="x"><span class="techinside">contract</span></a>s. In essence, these contracts describe the interfaces of
|
||
|
|
the documented library using Racket predicates and expressions.</p><p>For example, the following is the header of the definition of a
|
||
|
|
typical procedure:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="characters.html#%28def._%28%28quote._~23~25kernel%29._char-~3einteger%29%29" class="RktValDef RktValLink" data-pltdoc="x">char->integer</a></span><span class="hspace"> </span><span class="RktVar">char</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-integer?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">char</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="characters.html#%28def._%28%28quote._~23~25kernel%29._char~3f%29%29" class="RktValLink" data-pltdoc="x">char?</a></span></td></tr></table></blockquote></blockquote><p>The function being defined, <span class="RktSym"><a href="characters.html#%28def._%28%28quote._~23~25kernel%29._char-~3einteger%29%29" class="RktValLink" data-pltdoc="x">char->integer</a></span>, 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.</p><p>Each metavariable is described with a contract. In the preceding
|
||
|
|
example, the metavariable <span class="RktVar">char</span> has the contract
|
||
|
|
<span class="RktSym"><a href="characters.html#%28def._%28%28quote._~23~25kernel%29._char~3f%29%29" class="RktValLink" data-pltdoc="x">char?</a></span>. This contract specifies that any argument
|
||
|
|
<span class="RktVar">char</span> that answers true to the <span class="RktSym"><a href="characters.html#%28def._%28%28quote._~23~25kernel%29._char~3f%29%29" class="RktValLink" data-pltdoc="x">char?</a></span> predicate is
|
||
|
|
valid. The documented function may or may not actually check this
|
||
|
|
property, but the contract signals the intent of the implementer.</p><p>The contract on the right of the arrow, <span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-integer?</a></span> in this case,
|
||
|
|
specifies the expected result that is produced by the function.</p><p>Contract specifications can be more expressive than just names of
|
||
|
|
predicates. Consider the following header for <span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Flist..rkt%29._argmax%29%29" class="RktValLink" data-pltdoc="x">argmax</a></span>:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Flist..rkt%29._argmax%29%29" class="RktValDef RktValLink" data-pltdoc="x">argmax</a></span><span class="hspace"> </span><span class="RktVar">proc</span><span class="hspace"> </span><span class="RktVar">lst</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">proc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._real~3f%29%29" class="RktValLink" data-pltdoc="x">real?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">lst</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._pair~3f%29%29" class="RktValLink" data-pltdoc="x">pair?</a></span><span class="hspace"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote><p>The contract <span class="RktPn">(</span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="stt"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="stt"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._real~3f%29%29" class="RktValLink" data-pltdoc="x">real?</a></span><span class="RktPn">)</span> denotes a function contract specifying
|
||
|
|
that <span class="RktSym">proc</span>’s argument can be any single value and the result should be
|
||
|
|
a real number. The contract <span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="stt"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._pair~3f%29%29" class="RktValLink" data-pltdoc="x">pair?</a></span><span class="stt"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span><span class="RktPn">)</span> for <span class="RktVar">lst</span>
|
||
|
|
specifies that <span class="RktVar">lst</span> should pass both <span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._pair~3f%29%29" class="RktValLink" data-pltdoc="x">pair?</a></span> and <span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span>
|
||
|
|
(i.e., that it is a non-empty list).</p><p>Both <span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span> and <span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span> are examples of <a href="contracts.html#%28tech._contract._combinator%29" class="techoutside" data-pltdoc="x"><span class="techinside">contract combinator</span></a>s.
|
||
|
|
Contract combinators such as <span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span>, <span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._cons%2Fc%29%29" class="RktValLink" data-pltdoc="x">cons/c</a></span>, <span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span>,
|
||
|
|
and others are used throughout the documentation. Clicking on the hyperlinked
|
||
|
|
combinator name will provide more information on its meaning.</p><p>A Racket function may be documented as having one or more optional arguments.
|
||
|
|
The <span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValLink" data-pltdoc="x">read</a></span> function is an example of such a function:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValDef RktValLink" data-pltdoc="x">read</a></span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">in</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">in</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._input-port~3f%29%29" class="RktValLink" data-pltdoc="x">input-port?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29" class="RktValLink" data-pltdoc="x">current-input-port</a></span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote><p>The brackets surrounding the <span class="RktVar">in</span> argument in the application
|
||
|
|
syntax indicates that it is an optional argument.</p><p>The header for <span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValLink" data-pltdoc="x">read</a></span> specifies a contract for the parameter
|
||
|
|
<span class="RktVar">in</span> as usual. To the right of the contract, it also specifies
|
||
|
|
a default value <span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29" class="RktValLink" data-pltdoc="x">current-input-port</a></span><span class="RktPn">)</span> that is used if
|
||
|
|
<span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValLink" data-pltdoc="x">read</a></span> is called with no arguments.</p><p>Functions may also be documented as accepting mandatory or optional
|
||
|
|
keyword-based arguments. For example, the <span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Fprivate%2Flist..rkt%29._sort%29%29" class="RktValLink" data-pltdoc="x">sort</a></span> function has
|
||
|
|
two optional, keyword-based arguments:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Fprivate%2Flist..rkt%29._sort%29%29" class="RktValDef RktValLink" data-pltdoc="x">sort</a></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">lst</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">less-than?</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:key</span><span class="hspace"> </span><span class="RktVar">extract-key</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:cache-keys?</span><span class="hspace"> </span><span class="RktVar">cache-keys?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">lst</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">less-than?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">extract-key</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">
|
||
|
|
<span class="RktVar">cache-keys?</span> 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.</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Notation_for_Structure_Type_Documentation"">2.4<tt> </tt><a name="(part._.Notation_for_.Structure_.Type_.Documentation)"></a>Notation for Structure Type Documentation</h4><p>A <a href="structures.html#%28tech._structure._type%29" class="techoutside" data-pltdoc="x"><span class="techinside">structure type</span></a> is also documented using contract notation:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>struct</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29" class="RktStxLink" data-pltdoc="x">struct</a></span><span class="stt"> </span><span class="RktSym"><span class="RktSymDef RktSym">color</span></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym">red</span><span class="stt"> </span><span class="RktSym">green</span><span class="stt"> </span><span class="RktSym">blue</span><span class="stt"> </span><span class="RktSym">alpha</span><span class="RktPn">)</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktSym">red</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._natural-number%2Fc%29%29" class="RktValLink" data-pltdoc="x">natural-number/c</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._~3c~3d%2Fc%29%29" class="RktValLink" data-pltdoc="x"><=/c</a></span><span class="hspace"> </span><span class="RktVal">255</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym">green</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._natural-number%2Fc%29%29" class="RktValLink" data-pltdoc="x">natural-number/c</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._~3c~3d%2Fc%29%29" class="RktValLink" data-pltdoc="x"><=/c</a></span><span class="hspace"> </span><span class="RktVal">255</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym">blue</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._natural-number%2Fc%29%29" class="RktValLink" data-pltdoc="x">natural-number/c</a></span><span class="hspace"> </span><span class="RktPn">(</span><span clas
|
||
|
|
the source code of a program using the <span class="RktSym"><a href="define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29" class="RktStxLink" data-pltdoc="x">struct</a></span> form.
|
||
|
|
Each field of the structure is documented with a corresponding
|
||
|
|
contract that specifies the values that are accepted for that field.</p><p>In the example above, the structure type <span class="RktVar">color</span> has
|
||
|
|
four fields: <span class="RktVar">red</span>, <span class="RktVar">green</span>, <span class="RktVar">blue</span>,
|
||
|
|
and <span class="RktVar">alpha</span>. The constructor for the structure type
|
||
|
|
accepts field values that satisfy
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="stt"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._natural-number%2Fc%29%29" class="RktValLink" data-pltdoc="x">natural-number/c</a></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._~3c~3d%2Fc%29%29" class="RktValLink" data-pltdoc="x"><=/c</a></span><span class="stt"> </span><span class="RktVal">255</span><span class="RktPn">)</span><span class="RktPn">)</span>, i.e., non-negative
|
||
|
|
exact integers up to 255.</p><p>Additional keywords may appear after the field names in the
|
||
|
|
documentation for a structure type:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>struct</p></div></div><table cellspacing="0" cellpadding="0" class="RForeground"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29" class="RktStxLink" data-pltdoc="x">struct</a></span></td><td><span class="hspace"> </span></td><td><span class="RktSym"><span class="RktSymDef RktSym">data-source</span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">connector</span><span class="stt"> </span><span class="RktSym">args</span><span class="stt"> </span><span class="RktSym">extensions</span><span class="RktPn">)</span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">#:mutable</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym">connector</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">postgresql</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">mysql</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">sqlite3</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">odbc</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym">args</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list~3f%29%29" class="RktValLink" data-pltdoc="x">list?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktSym">extensions</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._list%2Fc%29%29" class="RktValLink" data-pltdoc="x">list/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="symbols.html#%28def._%28%28quote._~23~25kernel%29._symbol~3f%29%29" class="RktValLink" data-pltdoc="x">symbol?</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote><p>Here, the <span class="RktPn">#:mutable</span> keyword indicates that the fields of
|
||
|
|
instances of the <span class="RktVar">data-source</span> structure type can be
|
||
|
|
mutated with their respective setter functions.</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Notation_for_Parameter_Documentation"">2.5<tt> </tt><a name="(part._.Notation_for_.Parameter_.Documentation)"></a>Notation for Parameter Documentation</h4><p>A <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> is documented the same way as a function:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-command-line-arguments</a></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fvector..rkt%29._vectorof%29%29" class="RktValLink" data-pltdoc="x">vectorof</a></span><span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-command-line-arguments</a></span><span class="hspace"> </span><span class="RktVar">argv</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">argv</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fvector..rkt%29._vectorof%29%29" class="RktValLink" data-pltdoc="x">vectorof</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._immutable~3f%29%29" class="RktValLink" data-pltdoc="x">immutable?</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote><p>Since <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameters</span></a> can be referenced or set, there are two entries in the
|
||
|
|
header above. Calling <span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29" class="RktValLink" data-pltdoc="x">current-command-line-arguments</a></span> with no
|
||
|
|
arguments accesses the parameter’s value, which must be a vector whose elements
|
||
|
|
pass both <span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span> and <span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._immutable~3f%29%29" class="RktValLink" data-pltdoc="x">immutable?</a></span>. Calling
|
||
|
|
<span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29" class="RktValLink" data-pltdoc="x">current-command-line-arguments</a></span> with a single argument
|
||
|
|
sets the parameter’s value, where the value must be a vector whose
|
||
|
|
elements pass <span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span> (and a guard on the <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a>
|
||
|
|
coerces the strings to immutable form, if necessary).</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Notation_for_Other_Documentation"">2.6<tt> </tt><a name="(part._.Notation_for_.Other_.Documentation)"></a>Notation for Other Documentation</h4><p>Some libraries provide bindings to constant values. These values are
|
||
|
|
documented with a separate header:</p><blockquote><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><span class="RktSym"><a href="createclass.html#%28def._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._object~25%29%29" class="RktValDef RktValLink" data-pltdoc="x">object%</a></span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="objectutils.html#%28def._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._class~3f%29%29" class="RktValLink" data-pltdoc="x">class?</a></span></p></blockquote></td></tr></table></blockquote></blockquote><p>The <a href="mzlib_class.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/class</span></a> library provides the <span class="RktSym"><a href="createclass.html#%28def._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._object~25%29%29" class="RktValLink" data-pltdoc="x">object%</a></span>
|
||
|
|
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 <span class="RktSym"><a href="objectutils.html#%28def._%28%28lib._racket%2Fprivate%2Fclass-internal..rkt%29._class~3f%29%29" class="RktValLink" data-pltdoc="x">class?</a></span>.</p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" id="searchbox" type="text" tabindex="1" placeholder="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "8.6", "../");"/></form> <a href="https://docs.racket-lang.org/index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("8.6");">top</a><span class="tocsettoggle"> <a href="javascript:void(0);" title="show/hide table of contents" onclick="TocsetToggle();">contents</a></span></span><span class="navright"> <a href="implementations.html" title="backward to "1.5 Implementations"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "The Racket Reference"" data-pltdoc="x">up</a> <a href="syntax.html" title="forward to "3 Syntactic Forms"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|