/usr/share/doc/racket/reference/notation.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | <!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"/><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"><span style="font-weight: bold">The Racket Reference</span></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="" 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</a></td></tr><tr><td align="right">18 </td><td><a href="running.html" class="tocviewlink" data-pltdoc="x">Running Racket</a></td></tr><tr><td align="right"></td><td><a href="doc-bibliography.html" class="tocviewlink" data-pltdoc="x">Bibliography</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>2 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Notation for Documentation</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">2.1 </td><td><a href="#%28part._.Notation_for_.Module_.Documentation%29" class="tocviewlink" data-pltdoc="x">Notation for Module Documentation</a></td></tr><tr><td align="right">2.2 </td><td><a href="#%28part._.Notation_for_.Syntactic_.Form_.Documentation%29" class="tocviewlink" data-pltdoc="x">Notation for Syntactic Form Documentation</a></td></tr><tr><td align="right">2.3 </td><td><a href="#%28part._.Notation_for_.Function_.Documentation%29" class="tocviewlink" data-pltdoc="x">Notation for Function Documentation</a></td></tr><tr><td align="right">2.4 </td><td><a href="#%28part._.Notation_for_.Structure_.Type_.Documentation%29" class="tocviewlink" data-pltdoc="x">Notation for Structure Type Documentation</a></td></tr><tr><td align="right">2.5 </td><td><a href="#%28part._.Notation_for_.Parameter_.Documentation%29" class="tocviewlink" data-pltdoc="x">Notation for Parameter Documentation</a></td></tr><tr><td align="right">2.6 </td><td><a href="#%28part._.Notation_for_.Other_.Documentation%29" class="tocviewlink" data-pltdoc="x">Notation for Other Documentation</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">2.1<tt> </tt></span><a href="#%28part._.Notation_for_.Module_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Notation for Module Documentation</a></td></tr><tr><td><span class="tocsublinknumber">2.2<tt> </tt></span><a href="#%28part._.Notation_for_.Syntactic_.Form_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Notation for Syntactic Form Documentation</a></td></tr><tr><td><span class="tocsublinknumber">2.3<tt> </tt></span><a href="#%28part._.Notation_for_.Function_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Notation for Function Documentation</a></td></tr><tr><td><span class="tocsublinknumber">2.4<tt> </tt></span><a href="#%28part._.Notation_for_.Structure_.Type_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Notation for Structure Type Documentation</a></td></tr><tr><td><span class="tocsublinknumber">2.5<tt> </tt></span><a href="#%28part._.Notation_for_.Parameter_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Notation for Parameter Documentation</a></td></tr><tr><td><span class="tocsublinknumber">2.6<tt> </tt></span><a href="#%28part._.Notation_for_.Other_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Notation for Other Documentation</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="printing.html" title="backward to "1.4 The Printer"" 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><h3 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-part-tag=""notation"">2<tt> </tt><a name="(part._notation)"></a>Notation for Documentation</h3><p>This chapter introduces essential terminology and notation that is
used throughout Racket documentation.</p><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" 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> <span class="stt">base</span></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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" 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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" 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> <span class="stt">base</span></span></td></tr></table></blockquote><p>Using <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" 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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" 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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" 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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=pkg&rel=Package_Concepts.html%23%2528tech._package%2529&version=6.1" 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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=pkg&rel=index.html&version=6.1" 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"><span style="font-weight: bold">The Racket Reference</span></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-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="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=syntax-notation.html&version=6.1" class="Sq" data-pltdoc="x">Notation</a> in <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=index.html&version=6.1" class="Sq" data-pltdoc="x"><span style="font-weight: bold">The Racket Guide</span></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 name="(tech._form)"></a><span style="font-style: italic">form</span> 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="#%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="#%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-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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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="RktVar">in</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><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><span class="hspace"> </span></td><td><span class="RktVar">lst</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="RktVar">less-than?</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span>[</td><td><span class="RktPn">#:key</span><span class="hspace"> </span><span class="RktVar">extract-key</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="RktPn">#:cache-keys?</span><span class="hspace"> </span><span class="RktVar">cache-keys?</span>]<span class="RktPn">)</span></td><td><span class="hspace"> </span></td><td>→</td><td><span class="hspace"> </span></td><td><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><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><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">x</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">cache-keys?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></blockquote><p>The brackets around the <span class="RktVar">extract-key</span> and
<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-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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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">alpha</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._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></table></blockquote></blockquote><p>The structure type is typeset as it were declared in
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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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%2Fprivate%2Fmisc..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-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%2Fprivate%2Fmisc..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-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" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="printing.html" title="backward to "1.4 The Printer"" 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>
|