diff options
Diffstat (limited to 'slib_4.html')
| -rw-r--r-- | slib_4.html | 5157 |
1 files changed, 5157 insertions, 0 deletions
diff --git a/slib_4.html b/slib_4.html new file mode 100644 index 0000000..4aa89a0 --- /dev/null +++ b/slib_4.html @@ -0,0 +1,5157 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html40/loose.dtd"> +<HTML> +<!-- Created on January, 10 2005 by texi2html 1.66 --> +<!-- +Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) + Karl Berry <karl@freefriends.org> + Olaf Bachmann <obachman@mathematik.uni-kl.de> + and many others. +Maintained by: Many creative people <dev@texi2html.cvshome.org> +Send bugs and suggestions to <users@texi2html.cvshome.org> + +--> +<HEAD> +<TITLE>SLIB: Textual Conversion Packages</TITLE> + +<META NAME="description" CONTENT="SLIB: Textual Conversion Packages"> +<META NAME="keywords" CONTENT="SLIB: Textual Conversion Packages"> +<META NAME="resource-type" CONTENT="document"> +<META NAME="distribution" CONTENT="global"> +<META NAME="Generator" CONTENT="texi2html 1.66"> + +</HEAD> + +<BODY LANG="en" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"> + +<A NAME="SEC45"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_3.html#SEC44"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_3.html#SEC21"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H1> 4. Textual Conversion Packages </H1> +<!--docid::SEC45::--> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC46">4.1 Precedence Parsing</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC53">4.2 Format (version 3.0)</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Common-Lisp Format</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC54">4.3 Standard Formatted I/O</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Posix printf and scanf</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC61">4.4 Program and Arguments</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC69">4.5 HTML</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Generating</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC71">4.7 HTML Tables</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Databases meet HTML</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC74">4.8 HTTP and CGI</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Serve WWW sites</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC75">4.9 Parsing HTML</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'html-for-each</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC76">4.10 URI</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Uniform Resource Identifier</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC78">4.11 Printing Scheme</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Nicely</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC82">4.12 Time and Date</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC86">4.13 NCBI-DNA</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">DNA and protein sequences</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC87">4.14 Schmooz</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Documentation markup for Scheme programs</TD></TR> +</TABLE> +<P> + +<A NAME="Precedence Parsing"></A> +<HR SIZE="6"> +<A NAME="SEC46"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC47"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.1 Precedence Parsing </H2> +<!--docid::SEC46::--> +<P> + +<CODE>(require 'precedence-parse)</CODE> or <CODE>(require 'parse)</CODE> +<A NAME="IDX170"></A> +<A NAME="IDX171"></A> +</P> +<P> + +This package implements: +</P> +<P> + +<UL> +<LI> +a Pratt style precedence parser; +<LI> +a <EM>tokenizer</EM> which congeals tokens according to assigned classes of +constituent characters; +<LI> +procedures giving direct control of parser rulesets; +<LI> +procedures for higher level specification of rulesets. +</UL> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC47">4.1.1 Precedence Parsing Overview</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC48">4.1.2 Rule Types</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC49">4.1.3 Ruleset Definition and Use</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC50">4.1.4 Token definition</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC51">4.1.5 Nud and Led Definition</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC52">4.1.6 Grammar Rule Definition</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +</TABLE> +<P> + +<A NAME="Precedence Parsing Overview"></A> +<HR SIZE="6"> +<A NAME="SEC47"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC48"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.1.1 Precedence Parsing Overview </H3> +<!--docid::SEC47::--> +<P> + +This package offers improvements over previous parsers. +</P> +<P> + +<UL> +<LI> +Common computer language constructs are concisely specified. +<LI> +Grammars can be changed dynamically. Operators can be assigned +different meanings within a lexical context. +<LI> +Rulesets don't need compilation. Grammars can be changed incrementally. +<LI> +Operator precedence is specified by integers. +<LI> +All possibilities of bad input are handled <A NAME="DOCF3" HREF="slib_fot.html#FOOT3">(3)</A> and return as much structure as was +parsed when the error occured; The symbol <CODE>?</CODE> is substituted for +missing input. +</UL> +<P> + +<A NAME="IDX172"></A> +The notion of <EM>binding power</EM> may be unfamiliar to those +accustomed to BNF grammars. +</P> +<P> + +When two consecutive objects are parsed, the first might be the prefix +to the second, or the second might be a suffix of the first. +Comparing the left and right binding powers of the two objects decides +which way to interpret them. +</P> +<P> + +Objects at each level of syntactic grouping have binding powers. +</P> +<P> + +<A NAME="IDX173"></A> +A syntax tree is not built unless the rules explicitly do so. The +call graph of grammar rules effectively instantiate the sytnax tree. +</P> +<P> + +The JACAL symbolic math system +(<A HREF="http://swissnet.ai.mit.edu/~jaffer/JACAL.html">http://swissnet.ai.mit.edu/~jaffer/JACAL.html</A>) uses +<TT>precedence-parse</TT>. Its grammar definitions in the file +`<TT>jacal/English.scm</TT>' can serve as examples of use. +</P> +<P> + +<A NAME="Rule Types"></A> +<HR SIZE="6"> +<A NAME="SEC48"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC47"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC49"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.1.2 Rule Types </H3> +<!--docid::SEC48::--> +<P> + +Here are the higher-level syntax types and an example of each. +Precedence considerations are omitted for clarity. See <A HREF="slib_4.html#SEC52">4.1.6 Grammar Rule Definition</A> for full details. +<A NAME="IDX174"></A> +</P> +<DL> +<DT><U>Grammar:</U> <B>nofix</B> <I>bye exit</I> +<DD><TABLE><tr><td> </td><td class=example><pre>bye +</pre></td></tr></table>calls the function <CODE>exit</CODE> with no arguments. +</DL> +<A NAME="IDX175"></A> +<DL> +<DT><U>Grammar:</U> <B>prefix</B> <I>- negate</I> +<DD><TABLE><tr><td> </td><td class=example><pre>- 42 +</pre></td></tr></table>Calls the function <CODE>negate</CODE> with the argument <CODE>42</CODE>. +</DL> +<A NAME="IDX176"></A> +<DL> +<DT><U>Grammar:</U> <B>infix</B> <I>- difference</I> +<DD><TABLE><tr><td> </td><td class=example><pre>x - y +</pre></td></tr></table>Calls the function <CODE>difference</CODE> with arguments <CODE>x</CODE> and <CODE>y</CODE>. +</DL> +<A NAME="IDX177"></A> +<DL> +<DT><U>Grammar:</U> <B>nary</B> <I>+ sum</I> +<DD><TABLE><tr><td> </td><td class=example><pre>x + y + z +</pre></td></tr></table>Calls the function <CODE>sum</CODE> with arguments <CODE>x</CODE>, <CODE>y</CODE>, and +<CODE>y</CODE>. +</DL> +<A NAME="IDX178"></A> +<DL> +<DT><U>Grammar:</U> <B>postfix</B> <I>! factorial</I> +<DD><TABLE><tr><td> </td><td class=example><pre>5 ! +</pre></td></tr></table>Calls the function <CODE>factorial</CODE> with the argument <CODE>5</CODE>. +</DL> +<A NAME="IDX179"></A> +<DL> +<DT><U>Grammar:</U> <B>prestfix</B> <I>set set!</I> +<DD><TABLE><tr><td> </td><td class=example><pre>set foo bar +</pre></td></tr></table>Calls the function <CODE>set!</CODE> with the arguments <CODE>foo</CODE> and +<CODE>bar</CODE>. +</DL> +<A NAME="IDX180"></A> +<DL> +<DT><U>Grammar:</U> <B>commentfix</B> <I>/* */</I> +<DD><TABLE><tr><td> </td><td class=example><pre>/* almost any text here */ +</pre></td></tr></table>Ignores the comment delimited by <CODE>/*</CODE> and <CODE>*/</CODE>. +</DL> +<A NAME="IDX181"></A> +<DL> +<DT><U>Grammar:</U> <B>matchfix</B> <I>{ list }</I> +<DD><TABLE><tr><td> </td><td class=example><pre>{0, 1, 2} +</pre></td></tr></table>Calls the function <CODE>list</CODE> with the arguments <CODE>0</CODE>, <CODE>1</CODE>, +and <CODE>2</CODE>. +</DL> +<A NAME="IDX182"></A> +<DL> +<DT><U>Grammar:</U> <B>inmatchfix</B> <I>( funcall )</I> +<DD><TABLE><tr><td> </td><td class=example><pre>f(x, y) +</pre></td></tr></table>Calls the function <CODE>funcall</CODE> with the arguments <CODE>f</CODE>, <CODE>x</CODE>, +and <CODE>y</CODE>. +</DL> +<A NAME="IDX183"></A> +<DL> +<DT><U>Grammar:</U> <B>delim</B> <I>;</I> +<DD><TABLE><tr><td> </td><td class=example><pre>set foo bar; +</pre></td></tr></table>delimits the extent of the restfix operator <CODE>set</CODE>. +</DL> +<P> + +<A NAME="Ruleset Definition and Use"></A> +<HR SIZE="6"> +<A NAME="SEC49"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC48"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC50"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.1.3 Ruleset Definition and Use </H3> +<!--docid::SEC49::--> +<P> + +<A NAME="IDX184"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*syn-defs*</B> +<DD>A grammar is built by one or more calls to <CODE>prec:define-grammar</CODE>. +The rules are appended to <VAR>*syn-defs*</VAR>. The value of +<VAR>*syn-defs*</VAR> is the grammar suitable for passing as an argument to +<CODE>prec:parse</CODE>. +</DL> +<P> + +<A NAME="IDX185"></A> +</P> +<DL> +<DT><U>Constant:</U> <B>*syn-ignore-whitespace*</B> +<DD>Is a nearly empty grammar with whitespace characters set to group 0, +which means they will not be made into tokens. Most rulesets will want +to start with <CODE>*syn-ignore-whitespace*</CODE> +</DL> +<P> + +In order to start defining a grammar, either +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(set! *syn-defs* '()) +</pre></td></tr></table>or +<P> + +<TABLE><tr><td> </td><td class=example><pre>(set! *syn-defs* *syn-ignore-whitespace*) +</pre></td></tr></table><P> + +<A NAME="IDX186"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:define-grammar</B> <I>rule1 <small>...</small></I> +<DD>Appends <VAR>rule1</VAR> <small>...</small> to <VAR>*syn-defs*</VAR>. +<CODE>prec:define-grammar</CODE> is used to define both the character classes +and rules for tokens. +</DL> +<P> + +Once your grammar is defined, save the value of <CODE>*syn-defs*</CODE> in a +variable (for use when calling <CODE>prec:parse</CODE>). +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(define my-ruleset *syn-defs*) +</pre></td></tr></table><P> + +<A NAME="IDX187"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:parse</B> <I>ruleset delim</I> +<DD><A NAME="IDX188"></A> +<DT><U>Function:</U> <B>prec:parse</B> <I>ruleset delim port</I> +<DD>The <VAR>ruleset</VAR> argument must be a list of rules as constructed by +<CODE>prec:define-grammar</CODE> and extracted from <VAR>*syn-defs*</VAR>. +<P> + +The token <VAR>delim</VAR> may be a character, symbol, or string. A +character <VAR>delim</VAR> argument will match only a character token; i.e. a +character for which no token-group is assigned. A symbols or string +will match only a token string; i.e. a token resulting from a token +group. +</P> +<P> + +<CODE>prec:parse</CODE> reads a <VAR>ruleset</VAR> grammar expression delimited +by <VAR>delim</VAR> from the given input <VAR>port</VAR>. <CODE>prec:parse</CODE> +returns the next object parsable from the given input <VAR>port</VAR>, +updating <VAR>port</VAR> to point to the first character past the end of the +external representation of the object. +</P> +<P> + +If an end of file is encountered in the input before any characters are +found that can begin an object, then an end of file object is returned. +If a delimiter (such as <VAR>delim</VAR>) is found before any characters are +found that can begin an object, then <CODE>#f</CODE> is returned. +</P> +<P> + +The <VAR>port</VAR> argument may be omitted, in which case it defaults to the +value returned by <CODE>current-input-port</CODE>. It is an error to parse +from a closed port. +<A NAME="IDX189"></A> +</P> +</DL> +<P> + +<A NAME="Token definition"></A> +<HR SIZE="6"> +<A NAME="SEC50"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC49"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC51"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.1.4 Token definition </H3> +<!--docid::SEC50::--> +<P> + +<A NAME="IDX190"></A> +</P> +<DL> +<DT><U>Function:</U> <B>tok:char-group</B> <I>group chars chars-proc</I> +<DD>The argument <VAR>chars</VAR> may be a single character, a list of +characters, or a string. Each character in <VAR>chars</VAR> is treated as +though <CODE>tok:char-group</CODE> was called with that character alone. +<P> + +The argument <VAR>chars-proc</VAR> must be a procedure of one argument, a +list of characters. After <CODE>tokenize</CODE> has finished +accumulating the characters for a token, it calls <VAR>chars-proc</VAR> with +the list of characters. The value returned is the token which +<CODE>tokenize</CODE> returns. +</P> +<P> + +The argument <VAR>group</VAR> may be an exact integer or a procedure of one +character argument. The following discussion concerns the treatment +which the tokenizing routine, <CODE>tokenize</CODE>, will accord to characters +on the basis of their groups. +</P> +<P> + +When <VAR>group</VAR> is a non-zero integer, characters whose group number is +equal to or exactly one less than <VAR>group</VAR> will continue to +accumulate. Any other character causes the accumulation to stop (until +a new token is to be read). +</P> +<P> + +The <VAR>group</VAR> of zero is special. These characters are ignored when +parsed pending a token, and stop the accumulation of token characters +when the accumulation has already begun. Whitespace characters are +usually put in group 0. +</P> +<P> + +If <VAR>group</VAR> is a procedure, then, when triggerd by the occurence of +an initial (no accumulation) <VAR>chars</VAR> character, this procedure will +be repeatedly called with each successive character from the input +stream until the <VAR>group</VAR> procedure returns a non-false value. +</P> +</DL> +<P> + +The following convenient constants are provided for use with +<CODE>tok:char-group</CODE>. +</P> +<P> + +<A NAME="IDX191"></A> +</P> +<DL> +<DT><U>Constant:</U> <B>tok:decimal-digits</B> +<DD>Is the string <CODE>"0123456789"</CODE>. +</DL> +<A NAME="IDX192"></A> +<DL> +<DT><U>Constant:</U> <B>tok:upper-case</B> +<DD>Is the string consisting of all upper-case letters +("ABCDEFGHIJKLMNOPQRSTUVWXYZ"). +</DL> +<A NAME="IDX193"></A> +<DL> +<DT><U>Constant:</U> <B>tok:lower-case</B> +<DD>Is the string consisting of all lower-case letters +("abcdefghijklmnopqrstuvwxyz"). +</DL> +<A NAME="IDX194"></A> +<DL> +<DT><U>Constant:</U> <B>tok:whitespaces</B> +<DD>Is the string consisting of all characters between 0 and 255 for which +<CODE>char-whitespace?</CODE> returns true. +</DL> +<P> + +For the purpose of reporting problems in error messages, this package +keeps track of the <EM>current column</EM>. When the column does not +simply track input characters, <CODE>tok:bump-column</CODE> can be used to +adjust the current-column. +</P> +<P> + +<A NAME="IDX195"></A> +</P> +<DL> +<DT><U>Function:</U> <B>tok:bump-column</B> <I>pos port</I> +<DD>Adds <VAR>pos</VAR> to the current-column for input-port <VAR>port</VAR>. +</DL> +<P> + +<A NAME="Nud and Led Definition"></A> +<HR SIZE="6"> +<A NAME="SEC51"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC50"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC52"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.1.5 Nud and Led Definition </H3> +<!--docid::SEC51::--> +<P> + +This section describes advanced features. You can skip this section on +first reading. +</P> +<P> + +The <EM>Null Denotation</EM> (or <EM>nud</EM>) +<A NAME="IDX196"></A> +of a token is the procedure and arguments applying for that token when +<EM>Left</EM>, an unclaimed parsed expression is not extant. +</P> +<P> + +The <EM>Left Denotation</EM> (or <EM>led</EM>) +<A NAME="IDX197"></A> +of a token is the procedure, arguments, and lbp applying for that token +when there is a <EM>Left</EM>, an unclaimed parsed expression. +</P> +<P> + +In his paper, +</P> +<P> + +<BLOCKQUOTE> +Pratt, V. R. +Top Down Operator Precendence. +<CITE>SIGACT/SIGPLAN Symposium on Principles of Programming Languages</CITE>, +Boston, 1973, pages 41-51 +</BLOCKQUOTE> +<P> + +the <EM>left binding power</EM> (or <EM>lbp</EM>) was an independent property +of tokens. I think this was done in order to allow tokens with NUDs but +not LEDs to also be used as delimiters, which was a problem for +statically defined syntaxes. It turns out that <EM>dynamically +binding</EM> NUDs and LEDs allows them independence. +</P> +<P> + +For the rule-defining procedures that follow, the variable <VAR>tk</VAR> may +be a character, string, or symbol, or a list composed of characters, +strings, and symbols. Each element of <VAR>tk</VAR> is treated as though the +procedure were called for each element. +</P> +<P> + +Character <VAR>tk</VAR> arguments will match only character tokens; +i.e. characters for which no token-group is assigned. Symbols and +strings will both match token strings; i.e. tokens resulting from token +groups. +</P> +<P> + +<A NAME="IDX198"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:make-nud</B> <I>tk sop arg1 <small>...</small></I> +<DD>Returns a rule specifying that <VAR>sop</VAR> be called when <VAR>tk</VAR> is +parsed. If <VAR>sop</VAR> is a procedure, it is called with <VAR>tk</VAR> and +<VAR>arg1</VAR> <small>...</small> as its arguments; the resulting value is incorporated +into the expression being built. Otherwise, <CODE>(list <VAR>sop</VAR> +<VAR>arg1</VAR> <small>...</small>)</CODE> is incorporated. +</DL> +<P> + +If no NUD has been defined for a token; then if that token is a string, +it is converted to a symbol and returned; if not a string, the token is +returned. +</P> +<P> + +<A NAME="IDX199"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:make-led</B> <I>tk sop arg1 <small>...</small></I> +<DD>Returns a rule specifying that <VAR>sop</VAR> be called when <VAR>tk</VAR> is +parsed and <VAR>left</VAR> has an unclaimed parsed expression. If <VAR>sop</VAR> +is a procedure, it is called with <VAR>left</VAR>, <VAR>tk</VAR>, and <VAR>arg1</VAR> +<small>...</small> as its arguments; the resulting value is incorporated into the +expression being built. Otherwise, <VAR>left</VAR> is incorporated. +</DL> +<P> + +If no LED has been defined for a token, and <VAR>left</VAR> is set, the +parser issues a warning. +</P> +<P> + +<A NAME="Grammar Rule Definition"></A> +<HR SIZE="6"> +<A NAME="SEC52"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC51"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC53"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC46"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.1.6 Grammar Rule Definition </H3> +<!--docid::SEC52::--> +<P> + +Here are procedures for defining rules for the syntax types introduced +in <A HREF="slib_4.html#SEC47">4.1.1 Precedence Parsing Overview</A>. +</P> +<P> + +For the rule-defining procedures that follow, the variable <VAR>tk</VAR> may +be a character, string, or symbol, or a list composed of characters, +strings, and symbols. Each element of <VAR>tk</VAR> is treated as though the +procedure were called for each element. +</P> +<P> + +For procedures prec:delim, <small>...</small>, prec:prestfix, if the <VAR>sop</VAR> +argument is <CODE>#f</CODE>, then the token which triggered this rule is +converted to a symbol and returned. A false <VAR>sop</VAR> argument to the +procedures prec:commentfix, prec:matchfix, or prec:inmatchfix has a +different meaning. +</P> +<P> + +Character <VAR>tk</VAR> arguments will match only character tokens; +i.e. characters for which no token-group is assigned. Symbols and +strings will both match token strings; i.e. tokens resulting from token +groups. +</P> +<P> + +<A NAME="IDX200"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:delim</B> <I>tk</I> +<DD>Returns a rule specifying that <VAR>tk</VAR> should not be returned from +parsing; i.e. <VAR>tk</VAR>'s function is purely syntactic. The end-of-file +is always treated as a delimiter. +</DL> +<P> + +<A NAME="IDX201"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:nofix</B> <I>tk sop</I> +<DD>Returns a rule specifying the following actions take place when <VAR>tk</VAR> +is parsed: +<UL> +<LI> +If <VAR>sop</VAR> is a procedure, it is called with no arguments; the +resulting value is incorporated into the expression being built. +Otherwise, the list of <VAR>sop</VAR> is incorporated. +</UL> +</DL> +<P> + +<A NAME="IDX202"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:prefix</B> <I>tk sop bp rule1 <small>...</small></I> +<DD>Returns a rule specifying the following actions take place when <VAR>tk</VAR> +is parsed: +<UL> +<LI> +The rules <VAR>rule1</VAR> <small>...</small> augment and, in case of conflict, override +rules currently in effect. +<LI> +<CODE>prec:parse1</CODE> is called with binding-power <VAR>bp</VAR>. +<LI> +If <VAR>sop</VAR> is a procedure, it is called with the expression returned +from <CODE>prec:parse1</CODE>; the resulting value is incorporated into the +expression being built. Otherwise, the list of <VAR>sop</VAR> and the +expression returned from <CODE>prec:parse1</CODE> is incorporated. +<LI> +The ruleset in effect before <VAR>tk</VAR> was parsed is restored; +<VAR>rule1</VAR> <small>...</small> are forgotten. +</UL> +</DL> +<P> + +<A NAME="IDX203"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:infix</B> <I>tk sop lbp bp rule1 <small>...</small></I> +<DD>Returns a rule declaring the left-binding-precedence of the token +<VAR>tk</VAR> is <VAR>lbp</VAR> and specifying the following actions take place +when <VAR>tk</VAR> is parsed: +<UL> +<LI> +The rules <VAR>rule1</VAR> <small>...</small> augment and, in case of conflict, override +rules currently in effect. +<LI> +One expression is parsed with binding-power <VAR>lbp</VAR>. If instead a +delimiter is encountered, a warning is issued. +<LI> +If <VAR>sop</VAR> is a procedure, it is applied to the list of <VAR>left</VAR> and +the parsed expression; the resulting value is incorporated into the +expression being built. Otherwise, the list of <VAR>sop</VAR>, the +<VAR>left</VAR> expression, and the parsed expression is incorporated. +<LI> +The ruleset in effect before <VAR>tk</VAR> was parsed is restored; +<VAR>rule1</VAR> <small>...</small> are forgotten. +</UL> +</DL> +<P> + +<A NAME="IDX204"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:nary</B> <I>tk sop bp</I> +<DD>Returns a rule declaring the left-binding-precedence of the token +<VAR>tk</VAR> is <VAR>bp</VAR> and specifying the following actions take place +when <VAR>tk</VAR> is parsed: +<UL> +<LI> +Expressions are parsed with binding-power <VAR>bp</VAR> as far as they are +interleaved with the token <VAR>tk</VAR>. +<LI> +If <VAR>sop</VAR> is a procedure, it is applied to the list of <VAR>left</VAR> and +the parsed expressions; the resulting value is incorporated into the +expression being built. Otherwise, the list of <VAR>sop</VAR>, the +<VAR>left</VAR> expression, and the parsed expressions is incorporated. +</UL> +</DL> +<P> + +<A NAME="IDX205"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:postfix</B> <I>tk sop lbp</I> +<DD>Returns a rule declaring the left-binding-precedence of the token +<VAR>tk</VAR> is <VAR>lbp</VAR> and specifying the following actions take place +when <VAR>tk</VAR> is parsed: +<UL> +<LI> +If <VAR>sop</VAR> is a procedure, it is called with the <VAR>left</VAR> expression; +the resulting value is incorporated into the expression being built. +Otherwise, the list of <VAR>sop</VAR> and the <VAR>left</VAR> expression is +incorporated. +</UL> +</DL> +<P> + +<A NAME="IDX206"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:prestfix</B> <I>tk sop bp rule1 <small>...</small></I> +<DD>Returns a rule specifying the following actions take place when <VAR>tk</VAR> +is parsed: +<UL> +<LI> +The rules <VAR>rule1</VAR> <small>...</small> augment and, in case of conflict, override +rules currently in effect. +<LI> +Expressions are parsed with binding-power <VAR>bp</VAR> until a delimiter is +reached. +<LI> +If <VAR>sop</VAR> is a procedure, it is applied to the list of parsed +expressions; the resulting value is incorporated into the expression +being built. Otherwise, the list of <VAR>sop</VAR> and the parsed +expressions is incorporated. +<LI> +The ruleset in effect before <VAR>tk</VAR> was parsed is restored; +<VAR>rule1</VAR> <small>...</small> are forgotten. +</UL> +</DL> +<P> + +<A NAME="IDX207"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:commentfix</B> <I>tk stp match rule1 <small>...</small></I> +<DD>Returns rules specifying the following actions take place when <VAR>tk</VAR> +is parsed: +<UL> +<LI> +The rules <VAR>rule1</VAR> <small>...</small> augment and, in case of conflict, override +rules currently in effect. +<LI> +Characters are read until and end-of-file or a sequence of characters +is read which matches the <EM>string</EM> <VAR>match</VAR>. +<LI> +If <VAR>stp</VAR> is a procedure, it is called with the string of all that +was read between the <VAR>tk</VAR> and <VAR>match</VAR> (exclusive). +<LI> +The ruleset in effect before <VAR>tk</VAR> was parsed is restored; +<VAR>rule1</VAR> <small>...</small> are forgotten. +</UL> +<P> + +Parsing of commentfix syntax differs from the others in several ways. +It reads directly from input without tokenizing; It calls <VAR>stp</VAR> but +does not return its value; nay any value. I added the <VAR>stp</VAR> +argument so that comment text could be echoed. +</P> +</DL> +<P> + +<A NAME="IDX208"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:matchfix</B> <I>tk sop sep match rule1 <small>...</small></I> +<DD>Returns a rule specifying the following actions take place when <VAR>tk</VAR> +is parsed: +<UL> +<LI> +The rules <VAR>rule1</VAR> <small>...</small> augment and, in case of conflict, override +rules currently in effect. +<LI> +A rule declaring the token <VAR>match</VAR> a delimiter takes effect. +<LI> +Expressions are parsed with binding-power <CODE>0</CODE> until the token +<VAR>match</VAR> is reached. If the token <VAR>sep</VAR> does not appear between +each pair of expressions parsed, a warning is issued. +<LI> +If <VAR>sop</VAR> is a procedure, it is applied to the list of parsed +expressions; the resulting value is incorporated into the expression +being built. Otherwise, the list of <VAR>sop</VAR> and the parsed +expressions is incorporated. +<LI> +The ruleset in effect before <VAR>tk</VAR> was parsed is restored; +<VAR>rule1</VAR> <small>...</small> are forgotten. +</UL> +</DL> +<P> + +<A NAME="IDX209"></A> +</P> +<DL> +<DT><U>Function:</U> <B>prec:inmatchfix</B> <I>tk sop sep match lbp rule1 <small>...</small></I> +<DD>Returns a rule declaring the left-binding-precedence of the token +<VAR>tk</VAR> is <VAR>lbp</VAR> and specifying the following actions take place +when <VAR>tk</VAR> is parsed: +<UL> +<LI> +The rules <VAR>rule1</VAR> <small>...</small> augment and, in case of conflict, override +rules currently in effect. +<LI> +A rule declaring the token <VAR>match</VAR> a delimiter takes effect. +<LI> +Expressions are parsed with binding-power <CODE>0</CODE> until the token +<VAR>match</VAR> is reached. If the token <VAR>sep</VAR> does not appear between +each pair of expressions parsed, a warning is issued. +<LI> +If <VAR>sop</VAR> is a procedure, it is applied to the list of <VAR>left</VAR> and +the parsed expressions; the resulting value is incorporated into the +expression being built. Otherwise, the list of <VAR>sop</VAR>, the +<VAR>left</VAR> expression, and the parsed expressions is incorporated. +<LI> +The ruleset in effect before <VAR>tk</VAR> was parsed is restored; +<VAR>rule1</VAR> <small>...</small> are forgotten. +</UL> +</DL> +<P> + +<A NAME="Format"></A> +<HR SIZE="6"> +<A NAME="SEC53"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC52"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.2 Format (version 3.0) </H2> +<!--docid::SEC53::--> +<P> + +<A NAME="format"></A> +<A NAME="IDX210"></A> +</P> +<P> + +The `<TT>format.scm</TT>' package was removed because it was not +reentrant. <A HREF="http://swissnet.ai.mit.edu/~jaffer/SLIB.FAQ">http://swissnet.ai.mit.edu/~jaffer/SLIB.FAQ</A> explains +more about FORMAT's woes. +</P> +<P> + +<A NAME="Standard Formatted I/O"></A> +<HR SIZE="6"> +<A NAME="SEC54"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC53"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC55"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.3 Standard Formatted I/O </H2> +<!--docid::SEC54::--> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC56">4.3.2 Standard Formatted Output</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'printf</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC60">4.3.3 Standard Formatted Input</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'scanf</TD></TR> +</TABLE> +<P> + +<HR SIZE="6"> +<A NAME="SEC55"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC56"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.3.1 stdio </H3> +<!--docid::SEC55::--> +<P> + +<CODE>(require 'stdio)</CODE> +<A NAME="IDX211"></A> +</P> +<P> + +<CODE>require</CODE>s <CODE>printf</CODE> and <CODE>scanf</CODE> and additionally defines +the symbols: +</P> +<P> + +<A NAME="IDX212"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>stdin</B> +<DD>Defined to be <CODE>(current-input-port)</CODE>. +</DL> +<A NAME="IDX213"></A> +<DL> +<DT><U>Variable:</U> <B>stdout</B> +<DD>Defined to be <CODE>(current-output-port)</CODE>. +</DL> +<A NAME="IDX214"></A> +<DL> +<DT><U>Variable:</U> <B>stderr</B> +<DD>Defined to be <CODE>(current-error-port)</CODE>. +</DL> +<P> + +<A NAME="Standard Formatted Output"></A> +<HR SIZE="6"> +<A NAME="SEC56"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC55"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC57"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.3.2 Standard Formatted Output </H3> +<!--docid::SEC56::--> +<P> + +<A NAME="printf"></A> +<CODE>(require 'printf)</CODE> +<A NAME="IDX215"></A> +</P> +<P> + +<A NAME="IDX216"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>printf</B> <I>format arg1 <small>...</small></I> +<DD><A NAME="IDX217"></A> +<DT><U>Procedure:</U> <B>fprintf</B> <I>port format arg1 <small>...</small></I> +<DD><A NAME="IDX218"></A> +<DT><U>Procedure:</U> <B>sprintf</B> <I>str format arg1 <small>...</small></I> +<DD><A NAME="IDX219"></A> +<DT><U>Procedure:</U> <B>sprintf</B> <I>#f format arg1 <small>...</small></I> +<DD><A NAME="IDX220"></A> +<DT><U>Procedure:</U> <B>sprintf</B> <I>k format arg1 <small>...</small></I> +<DD><P> + +Each function converts, formats, and outputs its <VAR>arg1</VAR> <small>...</small> +arguments according to the control string <VAR>format</VAR> argument and +returns the number of characters output. +</P> +<P> + +<CODE>printf</CODE> sends its output to the port <CODE>(current-output-port)</CODE>. +<CODE>fprintf</CODE> sends its output to the port <VAR>port</VAR>. <CODE>sprintf</CODE> +<CODE>string-set!</CODE>s locations of the non-constant string argument +<VAR>str</VAR> to the output characters. +</P> +<P> + +Two extensions of <CODE>sprintf</CODE> return new strings. If the first +argument is <CODE>#f</CODE>, then the returned string's length is as many +characters as specified by the <VAR>format</VAR> and data; if the first +argument is a non-negative integer <VAR>k</VAR>, then the length of the +returned string is also bounded by <VAR>k</VAR>. +</P> +<P> + +The string <VAR>format</VAR> contains plain characters which are copied to +the output stream, and conversion specifications, each of which results +in fetching zero or more of the arguments <VAR>arg1</VAR> <small>...</small>. The +results are undefined if there are an insufficient number of arguments +for the format. If <VAR>format</VAR> is exhausted while some of the +<VAR>arg1</VAR> <small>...</small> arguments remain unused, the excess <VAR>arg1</VAR> +<small>...</small> arguments are ignored. +</P> +<P> + +The conversion specifications in a format string have the form: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>% [ <VAR>flags</VAR> ] [ <VAR>width</VAR> ] [ . <VAR>precision</VAR> ] [ <VAR>type</VAR> ] <VAR>conversion</VAR> +</pre></td></tr></table><P> + +An output conversion specifications consist of an initial `<SAMP>%</SAMP>' +character followed in sequence by: +</P> +<P> + +<UL> +<LI> +Zero or more <EM>flag characters</EM> that modify the normal behavior of +the conversion specification. +<P> + +</P> +<DL COMPACT> +<DT>`<SAMP>-</SAMP>' +<DD>Left-justify the result in the field. Normally the result is +right-justified. +<P> + +</P> +<DT>`<SAMP>+</SAMP>' +<DD>For the signed `<SAMP>%d</SAMP>' and `<SAMP>%i</SAMP>' conversions and all inexact +conversions, prefix a plus sign if the value is positive. +<P> + +</P> +<DT>`<SAMP> </SAMP>' +<DD>For the signed `<SAMP>%d</SAMP>' and `<SAMP>%i</SAMP>' conversions, if the result +doesn't start with a plus or minus sign, prefix it with a space +character instead. Since the `<SAMP>+</SAMP>' flag ensures that the result +includes a sign, this flag is ignored if both are specified. +<P> + +</P> +<DT>`<SAMP>#</SAMP>' +<DD>For inexact conversions, `<SAMP>#</SAMP>' specifies that the result should +always include a decimal point, even if no digits follow it. For the +`<SAMP>%g</SAMP>' and `<SAMP>%G</SAMP>' conversions, this also forces trailing zeros +after the decimal point to be printed where they would otherwise be +elided. +<P> + +For the `<SAMP>%o</SAMP>' conversion, force the leading digit to be `<SAMP>0</SAMP>', as +if by increasing the precision. For `<SAMP>%x</SAMP>' or `<SAMP>%X</SAMP>', prefix a +leading `<SAMP>0x</SAMP>' or `<SAMP>0X</SAMP>' (respectively) to the result. This +doesn't do anything useful for the `<SAMP>%d</SAMP>', `<SAMP>%i</SAMP>', or `<SAMP>%u</SAMP>' +conversions. Using this flag produces output which can be parsed by the +<CODE>scanf</CODE> functions with the `<SAMP>%i</SAMP>' conversion (see section <A HREF="slib_4.html#SEC60">4.3.3 Standard Formatted Input</A>). +</P> +<P> + +</P> +<DT>`<SAMP>0</SAMP>' +<DD>Pad the field with zeros instead of spaces. The zeros are placed after +any indication of sign or base. This flag is ignored if the `<SAMP>-</SAMP>' +flag is also specified, or if a precision is specified for an exact +converson. +</DL> +<P> + +</P> +<LI> +An optional decimal integer specifying the <EM>minimum field width</EM>. +If the normal conversion produces fewer characters than this, the field +is padded (with spaces or zeros per the `<SAMP>0</SAMP>' flag) to the specified +width. This is a <EM>minimum</EM> width; if the normal conversion +produces more characters than this, the field is <EM>not</EM> truncated. +<A NAME="IDX221"></A> +<P> + +Alternatively, if the field width is `<SAMP>*</SAMP>', the next argument in the +argument list (before the actual value to be printed) is used as the +field width. The width value must be an integer. If the value is +negative it is as though the `<SAMP>-</SAMP>' flag is set (see above) and the +absolute value is used as the field width. +</P> +<P> + +</P> +<LI> +An optional <EM>precision</EM> to specify the number of digits to be +written for numeric conversions and the maximum field width for string +conversions. The precision is specified by a period (`<SAMP>.</SAMP>') followed +optionally by a decimal integer (which defaults to zero if omitted). +<A NAME="IDX222"></A> +<P> + +Alternatively, if the precision is `<SAMP>.*</SAMP>', the next argument in the +argument list (before the actual value to be printed) is used as the +precision. The value must be an integer, and is ignored if negative. +If you specify `<SAMP>*</SAMP>' for both the field width and precision, the +field width argument precedes the precision argument. The `<SAMP>.*</SAMP>' +precision is an enhancement. C library versions may not accept this +syntax. +</P> +<P> + +For the `<SAMP>%f</SAMP>', `<SAMP>%e</SAMP>', and `<SAMP>%E</SAMP>' conversions, the precision +specifies how many digits follow the decimal-point character. The +default precision is <CODE>6</CODE>. If the precision is explicitly <CODE>0</CODE>, +the decimal point character is suppressed. +</P> +<P> + +For the `<SAMP>%g</SAMP>' and `<SAMP>%G</SAMP>' conversions, the precision specifies how +many significant digits to print. Significant digits are the first +digit before the decimal point, and all the digits after it. If the +precision is <CODE>0</CODE> or not specified for `<SAMP>%g</SAMP>' or `<SAMP>%G</SAMP>', it is +treated like a value of <CODE>1</CODE>. If the value being printed cannot be +expressed accurately in the specified number of digits, the value is +rounded to the nearest number that fits. +</P> +<P> + +For exact conversions, if a precision is supplied it specifies the +minimum number of digits to appear; leading zeros are produced if +necessary. If a precision is not supplied, the number is printed with +as many digits as necessary. Converting an exact `<SAMP>0</SAMP>' with an +explicit precision of zero produces no characters. +</P> +<P> + +</P> +<LI> +An optional one of `<SAMP>l</SAMP>', `<SAMP>h</SAMP>' or `<SAMP>L</SAMP>', which is ignored for +numeric conversions. It is an error to specify these modifiers for +non-numeric conversions. +<P> + +</P> +<LI> +A character that specifies the conversion to be applied. +</UL> +<P> + +<HR SIZE="6"> +<A NAME="SEC57"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC56"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC58"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H4> 4.3.2.1 Exact Conversions </H4> +<!--docid::SEC57::--> +<P> + +</P> +<DL COMPACT> +<DT>`<SAMP>b</SAMP>', `<SAMP>B</SAMP>' +<DD>Print an integer as an unsigned binary number. +<P> + +<EM>Note:</EM> `<SAMP>%b</SAMP>' and `<SAMP>%B</SAMP>' are SLIB extensions. +</P> +<P> + +</P> +<DT>`<SAMP>d</SAMP>', `<SAMP>i</SAMP>' +<DD>Print an integer as a signed decimal number. `<SAMP>%d</SAMP>' and `<SAMP>%i</SAMP>' +are synonymous for output, but are different when used with <CODE>scanf</CODE> +for input (see section <A HREF="slib_4.html#SEC60">4.3.3 Standard Formatted Input</A>). +<P> + +</P> +<DT>`<SAMP>o</SAMP>' +<DD>Print an integer as an unsigned octal number. +<P> + +</P> +<DT>`<SAMP>u</SAMP>' +<DD>Print an integer as an unsigned decimal number. +<P> + +</P> +<DT>`<SAMP>x</SAMP>', `<SAMP>X</SAMP>' +<DD>Print an integer as an unsigned hexadecimal number. `<SAMP>%x</SAMP>' prints +using the digits `<SAMP>0123456789abcdef</SAMP>'. `<SAMP>%X</SAMP>' prints using the +digits `<SAMP>0123456789ABCDEF</SAMP>'. +</DL> +<P> + +<HR SIZE="6"> +<A NAME="SEC58"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC57"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC59"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H4> 4.3.2.2 Inexact Conversions </H4> +<!--docid::SEC58::--> +<P> + +</P> +<DL COMPACT> +<DT>`<SAMP>f</SAMP>' +<DD>Print a floating-point number in fixed-point notation. +<P> + +</P> +<DT>`<SAMP>e</SAMP>', `<SAMP>E</SAMP>' +<DD>Print a floating-point number in exponential notation. `<SAMP>%e</SAMP>' prints +`<SAMP>e</SAMP>' between mantissa and exponont. `<SAMP>%E</SAMP>' prints `<SAMP>E</SAMP>' +between mantissa and exponont. +<P> + +</P> +<DT>`<SAMP>g</SAMP>', `<SAMP>G</SAMP>' +<DD>Print a floating-point number in either fixed or exponential notation, +whichever is more appropriate for its magnitude. Unless an `<SAMP>#</SAMP>' +flag has been supplied, trailing zeros after a decimal point will be +stripped off. `<SAMP>%g</SAMP>' prints `<SAMP>e</SAMP>' between mantissa and exponont. +`<SAMP>%G</SAMP>' prints `<SAMP>E</SAMP>' between mantissa and exponent. +<P> + +</P> +<DT>`<SAMP>k</SAMP>', `<SAMP>K</SAMP>' +<DD>Print a number like `<SAMP>%g</SAMP>', except that an SI prefix is output after +the number, which is scaled accordingly. `<SAMP>%K</SAMP>' outputs a space +between number and prefix, `<SAMP>%k</SAMP>' does not. +<P> + +</DL> +<P> + +<HR SIZE="6"> +<A NAME="SEC59"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC58"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC60"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H4> 4.3.2.3 Other Conversions </H4> +<!--docid::SEC59::--> +<DL COMPACT> +<DT>`<SAMP>c</SAMP>' +<DD>Print a single character. The `<SAMP>-</SAMP>' flag is the only one which can +be specified. It is an error to specify a precision. +<P> + +</P> +<DT>`<SAMP>s</SAMP>' +<DD>Print a string. The `<SAMP>-</SAMP>' flag is the only one which can be +specified. A precision specifies the maximum number of characters to +output; otherwise all characters in the string are output. +<P> + +</P> +<DT>`<SAMP>a</SAMP>', `<SAMP>A</SAMP>' +<DD>Print a scheme expression. The `<SAMP>-</SAMP>' flag left-justifies the output. +The `<SAMP>#</SAMP>' flag specifies that strings and characters should be quoted +as by <CODE>write</CODE> (which can be read using <CODE>read</CODE>); otherwise, +output is as <CODE>display</CODE> prints. A precision specifies the maximum +number of characters to output; otherwise as many characters as needed +are output. +<P> + +<EM>Note:</EM> `<SAMP>%a</SAMP>' and `<SAMP>%A</SAMP>' are SLIB extensions. +</P> +<P> + +</P> +<DT>`<SAMP>%</SAMP>' +<DD>Print a literal `<SAMP>%</SAMP>' character. No argument is consumed. It is an +error to specify flags, field width, precision, or type modifiers with +`<SAMP>%%</SAMP>'. +</DL> +</DL> +<P> + +<A NAME="Standard Formatted Input"></A> +<HR SIZE="6"> +<A NAME="SEC60"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC59"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC54"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.3.3 Standard Formatted Input </H3> +<!--docid::SEC60::--> +<P> + +<CODE>(require 'scanf)</CODE> +<A NAME="IDX223"></A> +</P> +<P> + +<A NAME="IDX224"></A> +</P> +<DL> +<DT><U>Function:</U> <B>scanf-read-list</B> <I>format</I> +<DD><A NAME="IDX225"></A> +<DT><U>Function:</U> <B>scanf-read-list</B> <I>format port</I> +<DD><A NAME="IDX226"></A> +<DT><U>Function:</U> <B>scanf-read-list</B> <I>format string</I> +<DD></DL> +<P> + +<A NAME="IDX227"></A> +</P> +<DL> +<DT><U>Macro:</U> <B>scanf</B> <I>format arg1 <small>...</small></I> +<DD><A NAME="IDX228"></A> +<DT><U>Macro:</U> <B>fscanf</B> <I>port format arg1 <small>...</small></I> +<DD><A NAME="IDX229"></A> +<DT><U>Macro:</U> <B>sscanf</B> <I>str format arg1 <small>...</small></I> +<DD><P> + +Each function reads characters, interpreting them according to the +control string <VAR>format</VAR> argument. +</P> +<P> + +<CODE>scanf-read-list</CODE> returns a list of the items specified as far as +the input matches <VAR>format</VAR>. <CODE>scanf</CODE>, <CODE>fscanf</CODE>, and +<CODE>sscanf</CODE> return the number of items successfully matched and +stored. <CODE>scanf</CODE>, <CODE>fscanf</CODE>, and <CODE>sscanf</CODE> also set the +location corresponding to <VAR>arg1</VAR> <small>...</small> using the methods: +</P> +<P> + +</P> +<DL COMPACT> +<DT>symbol +<DD><CODE>set!</CODE> +<DT>car expression +<DD><CODE>set-car!</CODE> +<DT>cdr expression +<DD><CODE>set-cdr!</CODE> +<DT>vector-ref expression +<DD><CODE>vector-set!</CODE> +<DT>substring expression +<DD><CODE>substring-move-left!</CODE> +</DL> +<P> + +The argument to a <CODE>substring</CODE> expression in <VAR>arg1</VAR> <small>...</small> must +be a non-constant string. Characters will be stored starting at the +position specified by the second argument to <CODE>substring</CODE>. The +number of characters stored will be limited by either the position +specified by the third argument to <CODE>substring</CODE> or the length of the +matched string, whichever is less. +</P> +<P> + +The control string, <VAR>format</VAR>, contains conversion specifications and +other characters used to direct interpretation of input sequences. The +control string contains: +</P> +<P> + +<UL> +<LI>White-space characters (blanks, tabs, newlines, or formfeeds) +that cause input to be read (and discarded) up to the next +non-white-space character. +<P> + +</P> +<LI>An ordinary character (not `<SAMP>%</SAMP>') that must match the next +character of the input stream. +<P> + +</P> +<LI>Conversion specifications, consisting of the character `<SAMP>%</SAMP>', an +optional assignment suppressing character `<SAMP>*</SAMP>', an optional +numerical maximum-field width, an optional `<SAMP>l</SAMP>', `<SAMP>h</SAMP>' or +`<SAMP>L</SAMP>' which is ignored, and a conversion code. +<P> + +</UL> +<P> + +Unless the specification contains the `<SAMP>n</SAMP>' conversion character +(described below), a conversion specification directs the conversion of +the next input field. The result of a conversion specification is +returned in the position of the corresponding argument points, unless +`<SAMP>*</SAMP>' indicates assignment suppression. Assignment suppression +provides a way to describe an input field to be skipped. An input field +is defined as a string of characters; it extends to the next +inappropriate character or until the field width, if specified, is +exhausted. +</P> +<P> + +<BLOCKQUOTE> +<EM>Note:</EM> This specification of format strings differs from the +<CITE>ANSI C</CITE> and <CITE>POSIX</CITE> specifications. In SLIB, white space +before an input field is not skipped unless white space appears before +the conversion specification in the format string. In order to write +format strings which work identically with <CITE>ANSI C</CITE> and SLIB, +prepend whitespace to all conversion specifications except `<SAMP>[</SAMP>' and +`<SAMP>c</SAMP>'. +</BLOCKQUOTE> +<P> + +The conversion code indicates the interpretation of the input field; For +a suppressed field, no value is returned. The following conversion +codes are legal: +</P> +<P> + +</P> +<DL COMPACT> + +<DT>`<SAMP>%</SAMP>' +<DD>A single % is expected in the input at this point; no value is returned. +<P> + +</P> +<DT>`<SAMP>d</SAMP>', `<SAMP>D</SAMP>' +<DD>A decimal integer is expected. +<P> + +</P> +<DT>`<SAMP>u</SAMP>', `<SAMP>U</SAMP>' +<DD>An unsigned decimal integer is expected. +<P> + +</P> +<DT>`<SAMP>o</SAMP>', `<SAMP>O</SAMP>' +<DD>An octal integer is expected. +<P> + +</P> +<DT>`<SAMP>x</SAMP>', `<SAMP>X</SAMP>' +<DD>A hexadecimal integer is expected. +<P> + +</P> +<DT>`<SAMP>i</SAMP>' +<DD>An integer is expected. Returns the value of the next input item, +interpreted according to C conventions; a leading `<SAMP>0</SAMP>' implies +octal, a leading `<SAMP>0x</SAMP>' implies hexadecimal; otherwise, decimal is +assumed. +<P> + +</P> +<DT>`<SAMP>n</SAMP>' +<DD>Returns the total number of bytes (including white space) read by +<CODE>scanf</CODE>. No input is consumed by <CODE>%n</CODE>. +<P> + +</P> +<DT>`<SAMP>f</SAMP>', `<SAMP>F</SAMP>', `<SAMP>e</SAMP>', `<SAMP>E</SAMP>', `<SAMP>g</SAMP>', `<SAMP>G</SAMP>' +<DD>A floating-point number is expected. The input format for +floating-point numbers is an optionally signed string of digits, +possibly containing a radix character `<SAMP>.</SAMP>', followed by an optional +exponent field consisting of an `<SAMP>E</SAMP>' or an `<SAMP>e</SAMP>', followed by an +optional `<SAMP>+</SAMP>', `<SAMP>-</SAMP>', or space, followed by an integer. +<P> + +</P> +<DT>`<SAMP>c</SAMP>', `<SAMP>C</SAMP>' +<DD><VAR>Width</VAR> characters are expected. The normal skip-over-white-space +is suppressed in this case; to read the next non-space character, use +`<SAMP>%1s</SAMP>'. If a field width is given, a string is returned; up to the +indicated number of characters is read. +<P> + +</P> +<DT>`<SAMP>s</SAMP>', `<SAMP>S</SAMP>' +<DD>A character string is expected The input field is terminated by a +white-space character. <CODE>scanf</CODE> cannot read a null string. +<P> + +</P> +<DT>`<SAMP>[</SAMP>' +<DD>Indicates string data and the normal skip-over-leading-white-space is +suppressed. The left bracket is followed by a set of characters, called +the scanset, and a right bracket; the input field is the maximal +sequence of input characters consisting entirely of characters in the +scanset. `<SAMP>^</SAMP>', when it appears as the first character in the +scanset, serves as a complement operator and redefines the scanset as +the set of all characters not contained in the remainder of the scanset +string. Construction of the scanset follows certain conventions. A +range of characters may be represented by the construct first-last, +enabling `<SAMP>[0123456789]</SAMP>' to be expressed `<SAMP>[0-9]</SAMP>'. Using this +convention, first must be lexically less than or equal to last; +otherwise, the dash stands for itself. The dash also stands for itself +when it is the first or the last character in the scanset. To include +the right square bracket as an element of the scanset, it must appear as +the first character (possibly preceded by a `<SAMP>^</SAMP>') of the scanset, in +which case it will not be interpreted syntactically as the closing +bracket. At least one character must match for this conversion to +succeed. +</DL> +<P> + +The <CODE>scanf</CODE> functions terminate their conversions at end-of-file, +at the end of the control string, or when an input character conflicts +with the control string. In the latter case, the offending character is +left unread in the input stream. +</P> +</DL> +<P> + +<A NAME="Programs and Arguments"></A> +<HR SIZE="6"> +<A NAME="SEC61"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC60"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC62"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.4 Program and Arguments </H2> +<!--docid::SEC61::--> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC62">4.4.1 Getopt</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Command Line option parsing</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC64">4.4.3 Command Line</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">A command line reader for Scheme shells</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC65">4.4.4 Parameter lists</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'parameters</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC66">4.4.5 Getopt Parameter lists</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'getopt-parameters</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC67">4.4.6 Filenames</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'glob or 'filename</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC68">4.4.7 Batch</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'batch</TD></TR> +</TABLE> +<P> + +<A NAME="Getopt"></A> +<HR SIZE="6"> +<A NAME="SEC62"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC63"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.1 Getopt </H3> +<!--docid::SEC62::--> +<P> + +<CODE>(require 'getopt)</CODE> +<A NAME="IDX230"></A> +</P> +<P> + +This routine implements Posix command line argument parsing. Notice +that returning values through global variables means that <CODE>getopt</CODE> +is <EM>not</EM> reentrant. +</P> +<P> + +Obedience to Posix format for the <CODE>getopt</CODE> calls sows confusion. +Passing <VAR>argc</VAR> and <VAR>argv</VAR> as arguments while referencing +<VAR>optind</VAR> as a global variable leads to strange behavior, +especially when the calls to <CODE>getopt</CODE> are buried in other +procedures. +</P> +<P> + +Even in C, <VAR>argc</VAR> can be derived from <VAR>argv</VAR>; what purpose +does it serve beyond providing an opportunity for +<VAR>argv</VAR>/<VAR>argc</VAR> mismatch? Just such a mismatch existed for +years in a SLIB <CODE>getopt--</CODE> example. +</P> +<P> + +I have removed the <VAR>argc</VAR> and <VAR>argv</VAR> arguments to getopt +procedures; and replaced them with a global variable: +</P> +<P> + +<A NAME="IDX231"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*argv*</B> +<DD>Define <VAR>*argv*</VAR> with a list of arguments before calling getopt +procedures. If you don't want the first (0th) element to be ignored, +set <VAR>*optind*</VAR> to 0 (after requiring getopt). +</DL> +<P> + +<A NAME="IDX232"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*optind*</B> +<DD>Is the index of the current element of the command line. It is +initially one. In order to parse a new command line or reparse an old +one, <VAR>*optind*</VAR> must be reset. +</DL> +<P> + +<A NAME="IDX233"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*optarg*</B> +<DD>Is set by getopt to the (string) option-argument of the current option. +</DL> +<P> + +<A NAME="IDX234"></A> +</P> +<DL> +<DT><U>Function:</U> <B>getopt</B> <I>optstring</I> +<DD>Returns the next option letter in <VAR>*argv*</VAR> (starting from +<CODE>(vector-ref argv *optind*)</CODE>) that matches a letter in +<VAR>optstring</VAR>. <VAR>*argv*</VAR> is a vector or list of strings, the 0th +of which getopt usually ignores. <VAR>optstring</VAR> is a string of +recognized option characters; if a character is followed by a colon, +the option takes an argument which may be immediately following it in +the string or in the next element of <VAR>*argv*</VAR>. +<P> + +<VAR>*optind*</VAR> is the index of the next element of the <VAR>*argv*</VAR> vector +to be processed. It is initialized to 1 by `<TT>getopt.scm</TT>', and +<CODE>getopt</CODE> updates it when it finishes with each element of +<VAR>*argv*</VAR>. +</P> +<P> + +<CODE>getopt</CODE> returns the next option character from <VAR>*argv*</VAR> that +matches a character in <VAR>optstring</VAR>, if there is one that matches. +If the option takes an argument, <CODE>getopt</CODE> sets the variable +<VAR>*optarg*</VAR> to the option-argument as follows: +</P> +<P> + +<UL> +<LI> +If the option was the last character in the string pointed to by an +element of <VAR>*argv*</VAR>, then <VAR>*optarg*</VAR> contains the next element +of <VAR>*argv*</VAR>, and <VAR>*optind*</VAR> is incremented by 2. If the +resulting value of <VAR>*optind*</VAR> is greater than or equal to +<CODE>(length <VAR>*argv*</VAR>)</CODE>, this indicates a missing option +argument, and <CODE>getopt</CODE> returns an error indication. +<P> + +</P> +<LI> +Otherwise, <VAR>*optarg*</VAR> is set to the string following the option +character in that element of <VAR>*argv*</VAR>, and <VAR>*optind*</VAR> is +incremented by 1. +</UL> +<P> + +If, when <CODE>getopt</CODE> is called, the string <CODE>(vector-ref argv +*optind*)</CODE> either does not begin with the character <CODE>#\-</CODE> or is +just <CODE>"-"</CODE>, <CODE>getopt</CODE> returns <CODE>#f</CODE> without changing +<VAR>*optind*</VAR>. If <CODE>(vector-ref argv *optind*)</CODE> is the string +<CODE>"--"</CODE>, <CODE>getopt</CODE> returns <CODE>#f</CODE> after incrementing +<VAR>*optind*</VAR>. +</P> +<P> + +If <CODE>getopt</CODE> encounters an option character that is not contained in +<VAR>optstring</VAR>, it returns the question-mark <CODE>#\?</CODE> character. If +it detects a missing option argument, it returns the colon character +<CODE>#\:</CODE> if the first character of <VAR>optstring</VAR> was a colon, or a +question-mark character otherwise. In either case, <CODE>getopt</CODE> sets +the variable <VAR>getopt:opt</VAR> to the option character that caused the +error. +</P> +<P> + +The special option <CODE>"--"</CODE> can be used to delimit the end of the +options; <CODE>#f</CODE> is returned, and <CODE>"--"</CODE> is skipped. +</P> +<P> + +RETURN VALUE +</P> +<P> + +<CODE>getopt</CODE> returns the next option character specified on the command +line. A colon <CODE>#\:</CODE> is returned if <CODE>getopt</CODE> detects a missing +argument and the first character of <VAR>optstring</VAR> was a colon +<CODE>#\:</CODE>. +</P> +<P> + +A question-mark <CODE>#\?</CODE> is returned if <CODE>getopt</CODE> encounters an +option character not in <VAR>optstring</VAR> or detects a missing argument +and the first character of <VAR>optstring</VAR> was not a colon <CODE>#\:</CODE>. +</P> +<P> + +Otherwise, <CODE>getopt</CODE> returns <CODE>#f</CODE> when all command line options +have been parsed. +</P> +<P> + +Example: +<TABLE><tr><td> </td><td class=example><pre>#! /usr/local/bin/scm +;;;This code is SCM specific. +(define argv (program-arguments)) +(require 'getopt) +<A NAME="IDX235"></A> +(define opts ":a:b:cd") +(let loop ((opt (getopt (length argv) argv opts))) + (case opt + ((#\a) (print "option a: " *optarg*)) + ((#\b) (print "option b: " *optarg*)) + ((#\c) (print "option c")) + ((#\d) (print "option d")) + ((#\?) (print "error" getopt:opt)) + ((#\:) (print "missing arg" getopt:opt)) + ((#f) (if (< *optind* (length argv)) + (print "argv[" *optind* "]=" + (list-ref argv *optind*))) + (set! *optind* (+ *optind* 1)))) + (if (< *optind* (length argv)) + (loop (getopt (length argv) argv opts)))) + +(slib:exit) +</pre></td></tr></table></DL> +<P> + +<HR SIZE="6"> +<A NAME="SEC63"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC62"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC64"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.2 Getopt--- </H3> +<!--docid::SEC63::--> +<P> + +<A NAME="IDX236"></A> +</P> +<DL> +<DT><U>Function:</U> <B><CODE>getopt--</CODE></B> <I>optstring</I> +<DD>The procedure <CODE>getopt--</CODE> is an extended version of <CODE>getopt</CODE> +which parses <EM>long option names</EM> of the form +`<SAMP>--hold-the-onions</SAMP>' and `<SAMP>--verbosity-level=extreme</SAMP>'. +<CODE>Getopt--</CODE> behaves as <CODE>getopt</CODE> except for non-empty +options beginning with `<SAMP>--</SAMP>'. +<P> + +Options beginning with `<SAMP>--</SAMP>' are returned as strings rather than +characters. If a value is assigned (using `<SAMP>=</SAMP>') to a long option, +<CODE>*optarg*</CODE> is set to the value. The `<SAMP>=</SAMP>' and value are +not returned as part of the option string. +</P> +<P> + +No information is passed to <CODE>getopt--</CODE> concerning which long +options should be accepted or whether such options can take arguments. +If a long option did not have an argument, <CODE>*optarg*</CODE> will be set +to <CODE>#f</CODE>. The caller is responsible for detecting and reporting +errors. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(define opts ":-:b:") +(define *argv* '("foo" "-b9" "--f1" "--2=" "--g3=35234.342" "--")) +(define *optind* 1) +(define *optarg* #f) +(require 'qp) +<A NAME="IDX237"></A>(do ((i 5 (+ -1 i))) + ((zero? i)) + (let ((opt (getopt-- opts))) + (print *optind* opt *optarg*))) +-| +2 #\b "9" +3 "f1" #f +4 "2" "" +5 "g3" "35234.342" +5 #f "35234.342" +</pre></td></tr></table></DL> +<P> + +<A NAME="Command Line"></A> +<HR SIZE="6"> +<A NAME="SEC64"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC63"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC65"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.3 Command Line </H3> +<!--docid::SEC64::--> +<P> + +<CODE>(require 'read-command)</CODE> +<A NAME="IDX238"></A> +</P> +<P> + +<A NAME="IDX239"></A> +</P> +<DL> +<DT><U>Function:</U> <B>read-command</B> <I>port</I> +<DD><P> + +<A NAME="IDX240"></A> +<DT><U>Function:</U> <B>read-command</B> +<DD><CODE>read-command</CODE> converts a <EM>command line</EM> into a list of strings +<A NAME="IDX241"></A> +<A NAME="IDX242"></A> +suitable for parsing by <CODE>getopt</CODE>. The syntax of command lines +supported resembles that of popular <EM>shell</EM>s. <CODE>read-command</CODE> +<A NAME="IDX243"></A> +updates <VAR>port</VAR> to point to the first character past the command +delimiter. +</P> +<P> + +If an end of file is encountered in the input before any characters are +found that can begin an object or comment, then an end of file object is +returned. +</P> +<P> + +The <VAR>port</VAR> argument may be omitted, in which case it defaults to the +value returned by <CODE>current-input-port</CODE>. +</P> +<P> + +The fields into which the command line is split are delimited by +whitespace as defined by <CODE>char-whitespace?</CODE>. The end of a command +is delimited by end-of-file or unescaped semicolon (<KBD>;</KBD>) or +<KBD>newline</KBD>. Any character can be literally included in a field by +escaping it with a backslach (<KBD>\</KBD>). +</P> +<P> + +The initial character and types of fields recognized are: +</P> +<DL COMPACT> +<DT>`<SAMP>\</SAMP>' +<DD>The next character has is taken literally and not interpreted as a field +delimiter. If <KBD>\</KBD> is the last character before a <KBD>newline</KBD>, +that <KBD>newline</KBD> is just ignored. Processing continues from the +characters after the <KBD>newline</KBD> as though the backslash and +<KBD>newline</KBD> were not there. +<DT>`<SAMP>"</SAMP>' +<DD>The characters up to the next unescaped <KBD>"</KBD> are taken literally, +according to [R4RS] rules for literal strings (see section `Strings' in <CITE>Revised(4) Scheme</CITE>). +<DT>`<SAMP>(</SAMP>', `<SAMP>%'</SAMP>' +<DD>One scheme expression is <CODE>read</CODE> starting with this character. The +<CODE>read</CODE> expression is evaluated, converted to a string +(using <CODE>display</CODE>), and replaces the expression in the returned +field. +<DT>`<SAMP>;</SAMP>' +<DD>Semicolon delimits a command. Using semicolons more than one command +can appear on a line. Escaped semicolons and semicolons inside strings +do not delimit commands. +</DL> +<P> + +The comment field differs from the previous fields in that it must be +the first character of a command or appear after whitespace in order to +be recognized. <KBD>#</KBD> can be part of fields if these conditions are +not met. For instance, <CODE>ab#c</CODE> is just the field ab#c. +</P> +<P> + +</P> +<DL COMPACT> +<DT>`<SAMP>#</SAMP>' +<DD>Introduces a comment. The comment continues to the end of the line on +which the semicolon appears. Comments are treated as whitespace by +<CODE>read-dommand-line</CODE> and backslashes before <KBD>newline</KBD>s in +comments are also ignored. +</DL> +</DL> +<P> + +<A NAME="IDX244"></A> +</P> +<DL> +<DT><U>Function:</U> <B>read-options-file</B> <I>filename</I> +<DD><P> + +<CODE>read-options-file</CODE> converts an <EM>options file</EM> into a list of +<A NAME="IDX245"></A> +<A NAME="IDX246"></A> +strings suitable for parsing by <CODE>getopt</CODE>. The syntax of options +files is the same as the syntax for command +lines, except that <KBD>newline</KBD>s do not terminate reading (only <KBD>;</KBD> +or end of file). +</P> +<P> + +If an end of file is encountered before any characters are found that +can begin an object or comment, then an end of file object is returned. +</P> +</DL> +<P> + +<A NAME="Parameter lists"></A> +<HR SIZE="6"> +<A NAME="SEC65"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC64"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC66"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.4 Parameter lists </H3> +<!--docid::SEC65::--> +<P> + +<CODE>(require 'parameters)</CODE> +<A NAME="IDX247"></A> +</P> +<P> + +Arguments to procedures in scheme are distinguished from each other by +their position in the procedure call. This can be confusing when a +procedure takes many arguments, many of which are not often used. +</P> +<P> + +A <EM>parameter-list</EM> is a way of passing named information to a +procedure. Procedures are also defined to set unused parameters to +default values, check parameters, and combine parameter lists. +</P> +<P> + +A <VAR>parameter</VAR> has the form <CODE>(parameter-name value1 +<small>...</small>)</CODE>. This format allows for more than one value per +parameter-name. +</P> +<P> + +A <VAR>parameter-list</VAR> is a list of <VAR>parameter</VAR>s, each with a +different <VAR>parameter-name</VAR>. +</P> +<P> + +<A NAME="IDX248"></A> +</P> +<DL> +<DT><U>Function:</U> <B>make-parameter-list</B> <I>parameter-names</I> +<DD>Returns an empty parameter-list with slots for <VAR>parameter-names</VAR>. +</DL> +<P> + +<A NAME="IDX249"></A> +</P> +<DL> +<DT><U>Function:</U> <B>parameter-list-ref</B> <I>parameter-list parameter-name</I> +<DD><VAR>parameter-name</VAR> must name a valid slot of <VAR>parameter-list</VAR>. +<CODE>parameter-list-ref</CODE> returns the value of parameter +<VAR>parameter-name</VAR> of <VAR>parameter-list</VAR>. +</DL> +<P> + +<A NAME="IDX250"></A> +</P> +<DL> +<DT><U>Function:</U> <B>remove-parameter</B> <I>parameter-name parameter-list</I> +<DD>Removes the parameter <VAR>parameter-name</VAR> from <VAR>parameter-list</VAR>. +<CODE>remove-parameter</CODE> does not alter the argument +<VAR>parameter-list</VAR>. +<P> + +If there are more than one <VAR>parameter-name</VAR> parameters, an error is +signaled. +</P> +</DL> +<P> + +<A NAME="IDX251"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>adjoin-parameters!</B> <I>parameter-list parameter1 <small>...</small></I> +<DD>Returns <VAR>parameter-list</VAR> with <VAR>parameter1</VAR> <small>...</small> merged in. +</DL> +<P> + +<A NAME="IDX252"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>parameter-list-expand</B> <I>expanders parameter-list</I> +<DD><VAR>expanders</VAR> is a list of procedures whose order matches the order of +the <VAR>parameter-name</VAR>s in the call to <CODE>make-parameter-list</CODE> +which created <VAR>parameter-list</VAR>. For each non-false element of +<VAR>expanders</VAR> that procedure is mapped over the corresponding +parameter value and the returned parameter lists are merged into +<VAR>parameter-list</VAR>. +<P> + +This process is repeated until <VAR>parameter-list</VAR> stops growing. The +value returned from <CODE>parameter-list-expand</CODE> is unspecified. +</P> +</DL> +<P> + +<A NAME="IDX253"></A> +</P> +<DL> +<DT><U>Function:</U> <B>fill-empty-parameters</B> <I>defaulters parameter-list</I> +<DD><VAR>defaulters</VAR> is a list of procedures whose order matches the order +of the <VAR>parameter-name</VAR>s in the call to <CODE>make-parameter-list</CODE> +which created <VAR>parameter-list</VAR>. <CODE>fill-empty-parameters</CODE> +returns a new parameter-list with each empty parameter replaced with the +list returned by calling the corresponding <VAR>defaulter</VAR> with +<VAR>parameter-list</VAR> as its argument. +</DL> +<P> + +<A NAME="IDX254"></A> +</P> +<DL> +<DT><U>Function:</U> <B>check-parameters</B> <I>checks parameter-list</I> +<DD><VAR>checks</VAR> is a list of procedures whose order matches the order of +the <VAR>parameter-name</VAR>s in the call to <CODE>make-parameter-list</CODE> +which created <VAR>parameter-list</VAR>. +<P> + +<CODE>check-parameters</CODE> returns <VAR>parameter-list</VAR> if each <VAR>check</VAR> +of the corresponding <VAR>parameter-list</VAR> returns non-false. If some +<VAR>check</VAR> returns <CODE>#f</CODE> a warning is signaled. +</P> +</DL> +<P> + +In the following procedures <VAR>arities</VAR> is a list of symbols. The +elements of <CODE>arities</CODE> can be: +</P> +<P> + +</P> +<DL COMPACT> +<DT><CODE>single</CODE> +<DD>Requires a single parameter. +<DT><CODE>optional</CODE> +<DD>A single parameter or no parameter is acceptable. +<DT><CODE>boolean</CODE> +<DD>A single boolean parameter or zero parameters is acceptable. +<DT><CODE>nary</CODE> +<DD>Any number of parameters are acceptable. +<DT><CODE>nary1</CODE> +<DD>One or more of parameters are acceptable. +</DL> +<P> + +<A NAME="IDX255"></A> +</P> +<DL> +<DT><U>Function:</U> <B>parameter-list->arglist</B> <I>positions arities parameter-list</I> +<DD>Returns <VAR>parameter-list</VAR> converted to an argument list. Parameters +of <VAR>arity</VAR> type <CODE>single</CODE> and <CODE>boolean</CODE> are converted to +the single value associated with them. The other <VAR>arity</VAR> types are +converted to lists of the value(s). +<P> + +<VAR>positions</VAR> is a list of positive integers whose order matches the +order of the <VAR>parameter-name</VAR>s in the call to +<CODE>make-parameter-list</CODE> which created <VAR>parameter-list</VAR>. The +integers specify in which argument position the corresponding parameter +should appear. +</P> +</DL> +<P> + +<A NAME="Getopt Parameter lists"></A> +<HR SIZE="6"> +<A NAME="SEC66"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC65"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC67"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.5 Getopt Parameter lists </H3> +<!--docid::SEC66::--> +<P> + +<CODE>(require 'getopt-parameters)</CODE> +<A NAME="IDX256"></A> +</P> +<P> + +<A NAME="IDX257"></A> +</P> +<DL> +<DT><U>Function:</U> <B>getopt->parameter-list</B> <I>optnames arities types aliases desc <small>...</small></I> +<DD><P> + +Returns <VAR>*argv*</VAR> converted to a parameter-list. <VAR>optnames</VAR> are +the parameter-names. <VAR>arities</VAR> and <VAR>types</VAR> are lists of symbols +corresponding to <VAR>optnames</VAR>. +</P> +<P> + +<VAR>aliases</VAR> is a list of lists of strings or integers paired with +elements of <VAR>optnames</VAR>. Each one-character string will be treated +as a single `<SAMP>-</SAMP>' option by <CODE>getopt</CODE>. Longer strings will be +treated as long-named options (see section <A HREF="slib_4.html#SEC62">getopt--</A>). +</P> +<P> + +If the <VAR>aliases</VAR> association list has only strings as its +<CODE>car</CODE>s, then all the option-arguments after an option (and before +the next option) are adjoined to that option. +</P> +<P> + +If the <VAR>aliases</VAR> association list has integers, then each (string) +option will take at most one option-argument. Unoptioned arguments are +collected in a list. A `<SAMP>-1</SAMP>' alias will take the last argument in +this list; `<SAMP>+1</SAMP>' will take the first argument in the list. The +aliases -2 then +2; -3 then +3; <small>...</small> are tried so long as a positive +or negative consecutive alias is found and arguments remain in the list. +Finally a `<SAMP>0</SAMP>' alias, if found, absorbs any remaining arguments. +</P> +<P> + +In all cases, if unclaimed arguments remain after processing, a warning +is signaled and #f is returned. +</P> +</DL> +<P> + +<A NAME="IDX258"></A> +</P> +<DL> +<DT><U>Function:</U> <B>getopt->arglist</B> <I>optnames positions arities types defaulters checks aliases desc <small>...</small></I> +<DD><P> + +Like <CODE>getopt->parameter-list</CODE>, but converts <VAR>*argv*</VAR> to an +argument-list as specified by <VAR>optnames</VAR>, <VAR>positions</VAR>, +<VAR>arities</VAR>, <VAR>types</VAR>, <VAR>defaulters</VAR>, <VAR>checks</VAR>, and +<VAR>aliases</VAR>. If the options supplied violate the <VAR>arities</VAR> or +<VAR>checks</VAR> constraints, then a warning is signaled and #f is returned. +</P> +</DL> +These <CODE>getopt</CODE> functions can be used with SLIB relational +databases. For an example, See section <A HREF="slib_6.html#SEC142">make-command-server</A>. +<P> + +If errors are encountered while processing options, directions for using +the options (and argument strings <VAR>desc</VAR> <small>...</small>) are printed to +<CODE>current-error-port</CODE>. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(begin + (set! *optind* 1) + (set! *argv* '("cmd" "-?") + (getopt->parameter-list + '(flag number symbols symbols string flag2 flag3 num2 num3) + '(boolean optional nary1 nary single boolean boolean nary nary) + '(boolean integer symbol symbol string boolean boolean integer integer) + '(("flag" flag) + ("f" flag) + ("Flag" flag2) + ("B" flag3) + ("optional" number) + ("o" number) + ("nary1" symbols) + ("N" symbols) + ("nary" symbols) + ("n" symbols) + ("single" string) + ("s" string) + ("a" num2) + ("Abs" num3)))) +-| +Usage: cmd [OPTION ARGUMENT ...] ... + + -f, --flag + -o, --optional=<number> + -n, --nary=<symbols> ... + -N, --nary1=<symbols> ... + -s, --single=<string> + --Flag + -B + -a <num2> ... + --Abs=<num3> ... + +ERROR: getopt->parameter-list "unrecognized option" "-?" +</pre></td></tr></table><P> + +<A NAME="Filenames"></A> +<HR SIZE="6"> +<A NAME="SEC67"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC66"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC68"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.6 Filenames </H3> +<!--docid::SEC67::--> +<P> + +<CODE>(require 'filename)</CODE> or <CODE>(require 'glob)</CODE> +<A NAME="IDX259"></A> +<A NAME="IDX260"></A> +</P> +<P> + +<A NAME="IDX261"></A> +</P> +<DL> +<DT><U>Function:</U> <B>filename:match??</B> <I>pattern</I> +<DD><A NAME="IDX262"></A> +<DT><U>Function:</U> <B>filename:match-ci??</B> <I>pattern</I> +<DD><P> + +Returns a predicate which returns a non-false value if its string argument +matches (the string) <VAR>pattern</VAR>, false otherwise. Filename matching +is like +<A NAME="IDX263"></A> +<EM>glob</EM> expansion described the bash manpage, except that names +<A NAME="IDX264"></A> +beginning with `<SAMP>.</SAMP>' are matched and `<SAMP>/</SAMP>' characters are not +treated specially. +</P> +<P> + +These functions interpret the following characters specially in +<VAR>pattern</VAR> strings: +</P> +<DL COMPACT> +<DT>`<SAMP>*</SAMP>' +<DD>Matches any string, including the null string. +<DT>`<SAMP>?</SAMP>' +<DD>Matches any single character. +<DT>`<SAMP>[<small>...</small>]</SAMP>' +<DD>Matches any one of the enclosed characters. A pair of characters +separated by a minus sign (-) denotes a range; any character lexically +between those two characters, inclusive, is matched. If the first +character following the `<SAMP>[</SAMP>' is a `<SAMP>!</SAMP>' or a `<SAMP>^</SAMP>' then any +character not enclosed is matched. A `<SAMP>-</SAMP>' or `<SAMP>]</SAMP>' may be +matched by including it as the first or last character in the set. +</DL> +</DL> +<P> + +<A NAME="IDX265"></A> +</P> +<DL> +<DT><U>Function:</U> <B>filename:substitute??</B> <I>pattern template</I> +<DD><A NAME="IDX266"></A> +<DT><U>Function:</U> <B>filename:substitute-ci??</B> <I>pattern template</I> +<DD><P> + +Returns a function transforming a single string argument according to +glob patterns <VAR>pattern</VAR> and <VAR>template</VAR>. <VAR>pattern</VAR> and +<VAR>template</VAR> must have the same number of wildcard specifications, +which need not be identical. <VAR>pattern</VAR> and <VAR>template</VAR> may have +a different number of literal sections. If an argument to the function +matches <VAR>pattern</VAR> in the sense of <CODE>filename:match??</CODE> then it +returns a copy of <VAR>template</VAR> in which each wildcard specification is +replaced by the part of the argument matched by the corresponding +wildcard specification in <VAR>pattern</VAR>. A <CODE>*</CODE> wildcard matches +the longest leftmost string possible. If the argument does not match +<VAR>pattern</VAR> then false is returned. +</P> +<P> + +<VAR>template</VAR> may be a function accepting the same number of string +arguments as there are wildcard specifications in <VAR>pattern</VAR>. In +the case of a match the result of applying <VAR>template</VAR> to a list +of the substrings matched by wildcard specifications will be returned, +otherwise <VAR>template</VAR> will not be called and <CODE>#f</CODE> will be returned. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>((filename:substitute?? "scm_[0-9]*.html" "scm5c4_??.htm") + "scm_10.html") +=> "scm5c4_10.htm" +((filename:substitute?? "??" "beg?mid?end") "AZ") +=> "begAmidZend" +((filename:substitute?? "*na*" "?NA?") "banana") +=> "banaNA" +((filename:substitute?? "?*?" (lambda (s1 s2 s3) (string-append s3 s1))) + "ABZ") +=> "ZA" +</pre></td></tr></table><P> + +<A NAME="IDX267"></A> +</P> +<DL> +<DT><U>Function:</U> <B>replace-suffix</B> <I>str old new</I> +<DD><P> + +<VAR>str</VAR> can be a string or a list of strings. Returns a new string +(or strings) similar to <CODE>str</CODE> but with the suffix string <VAR>old</VAR> +removed and the suffix string <VAR>new</VAR> appended. If the end of +<VAR>str</VAR> does not match <VAR>old</VAR>, an error is signaled. +</P> +</DL> +<TABLE><tr><td> </td><td class=example><pre>(replace-suffix "/usr/local/lib/slib/batch.scm" ".scm" ".c") +=> "/usr/local/lib/slib/batch.c" +</pre></td></tr></table><P> + +<A NAME="IDX268"></A> +</P> +<DL> +<DT><U>Function:</U> <B>call-with-tmpnam</B> <I>proc k</I> +<DD><P> + +<A NAME="IDX269"></A> +<DT><U>Function:</U> <B>call-with-tmpnam</B> <I>proc</I> +<DD>Calls <VAR>proc</VAR> with <VAR>k</VAR> arguments, strings returned by successive calls to +<CODE>tmpnam</CODE>. +If <VAR>proc</VAR> returns, then any files named by the arguments to <VAR>proc</VAR> are +deleted automatically and the value(s) yielded by the <VAR>proc</VAR> is(are) +returned. <VAR>k</VAR> may be ommited, in which case it defaults to <CODE>1</CODE>. +</P> +<P> + +<A NAME="IDX270"></A> +<DT><U>Function:</U> <B>call-with-tmpnam</B> <I>proc suffix1 <small>...</small></I> +<DD>Calls <VAR>proc</VAR> with strings returned by successive calls to <CODE>tmpnam</CODE>, +each with the corresponding <VAR>suffix</VAR> string appended. +If <VAR>proc</VAR> returns, then any files named by the arguments to <VAR>proc</VAR> are +deleted automatically and the value(s) yielded by the <VAR>proc</VAR> is(are) +returned. +</P> +</DL> +<P> + +<A NAME="Batch"></A> +<HR SIZE="6"> +<A NAME="SEC68"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC67"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC69"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC61"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.4.7 Batch </H3> +<!--docid::SEC68::--> +<P> + +<CODE>(require 'batch)</CODE> +<A NAME="IDX271"></A> +</P> +<P> + +The batch procedures provide a way to write and execute portable scripts +for a variety of operating systems. Each <CODE>batch:</CODE> procedure takes +as its first argument a parameter-list (see section <A HREF="slib_4.html#SEC65">4.4.4 Parameter lists</A>). This +parameter-list argument <VAR>parms</VAR> contains named associations. Batch +currently uses 2 of these: +</P> +<P> + +</P> +<DL COMPACT> +<DT><CODE>batch-port</CODE> +<DD>The port on which to write lines of the batch file. +<DT><CODE>batch-dialect</CODE> +<DD>The syntax of batch file to generate. Currently supported are: +<UL> +<LI> +unix +<LI> +dos +<LI> +vms +<LI> +amigaos +<LI> +system +<LI> +*unknown* +</UL> +</DL> +<P> + +`<TT>batch.scm</TT>' uses 2 enhanced relational tables +(see section <A HREF="slib_6.html#SEC142">6.1.1 Using Databases</A>) to store information linking the names of +<CODE>operating-system</CODE>s to <CODE>batch-dialect</CODE>es. +</P> +<P> + +<A NAME="IDX272"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:initialize!</B> <I>database</I> +<DD>Defines <CODE>operating-system</CODE> and <CODE>batch-dialect</CODE> tables and adds +the domain <CODE>operating-system</CODE> to the enhanced relational database +<VAR>database</VAR>. +</DL> +<P> + +<A NAME="IDX273"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*operating-system*</B> +<DD>Is batch's best guess as to which operating-system it is running under. +<CODE>*operating-system*</CODE> is set to <CODE>(software-type)</CODE> +(see section <A HREF="slib_2.html#SEC15">2.2 Configuration</A>) unless <CODE>(software-type)</CODE> is <CODE>unix</CODE>, +in which case finer distinctions are made. +</DL> +<P> + +<A NAME="IDX274"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:call-with-output-script</B> <I>parms file proc</I> +<DD><VAR>proc</VAR> should be a procedure of one argument. If <VAR>file</VAR> is an +output-port, <CODE>batch:call-with-output-script</CODE> writes an appropriate +header to <VAR>file</VAR> and then calls <VAR>proc</VAR> with <VAR>file</VAR> as the +only argument. If <VAR>file</VAR> is a string, +<CODE>batch:call-with-output-script</CODE> opens a output-file of name +<VAR>file</VAR>, writes an appropriate header to <VAR>file</VAR>, and then calls +<VAR>proc</VAR> with the newly opened port as the only argument. Otherwise, +<CODE>batch:call-with-output-script</CODE> acts as if it was called with the +result of <CODE>(current-output-port)</CODE> as its third argument. +</DL> +<P> + +The rest of the <CODE>batch:</CODE> procedures write (or execute if +<CODE>batch-dialect</CODE> is <CODE>system</CODE>) commands to the batch port which +has been added to <VAR>parms</VAR> or <CODE>(copy-tree <VAR>parms</VAR>)</CODE> by the +code: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(adjoin-parameters! <VAR>parms</VAR> (list 'batch-port <VAR>port</VAR>)) +</pre></td></tr></table><P> + +<A NAME="IDX275"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:command</B> <I>parms string1 string2 <small>...</small></I> +<DD>Calls <CODE>batch:try-command</CODE> (below) with arguments, but signals an +error if <CODE>batch:try-command</CODE> returns <CODE>#f</CODE>. +</DL> +<P> + +These functions return a non-false value if the command was successfully +translated into the batch dialect and <CODE>#f</CODE> if not. In the case of +the <CODE>system</CODE> dialect, the value is non-false if the operation +suceeded. +</P> +<P> + +<A NAME="IDX276"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:try-command</B> <I>parms string1 string2 <small>...</small></I> +<DD>Writes a command to the <CODE>batch-port</CODE> in <VAR>parms</VAR> which executes +the program named <VAR>string1</VAR> with arguments <VAR>string2</VAR> <small>...</small>. +</DL> +<P> + +<A NAME="IDX277"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:try-chopped-command</B> <I>parms arg1 arg2 <small>...</small> list</I> +<DD>breaks the last argument <VAR>list</VAR> into chunks small enough so that the +command: +<P> + +<TABLE><tr><td> </td><td class=example><pre><VAR>arg1</VAR> <VAR>arg2</VAR> <small>...</small> <VAR>chunk</VAR> +</pre></td></tr></table><P> + +fits withing the platform's maximum command-line length. +</P> +<P> + +<CODE>batch:try-chopped-command</CODE> calls <CODE>batch:try-command</CODE> with the +command and returns non-false only if the commands all fit and +<CODE>batch:try-command</CODE> of each command line returned non-false. +</P> +</DL> +<P> + +<A NAME="IDX278"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:run-script</B> <I>parms string1 string2 <small>...</small></I> +<DD>Writes a command to the <CODE>batch-port</CODE> in <VAR>parms</VAR> which executes +the batch script named <VAR>string1</VAR> with arguments <VAR>string2</VAR> +<small>...</small>. +<P> + +<EM>Note:</EM> <CODE>batch:run-script</CODE> and <CODE>batch:try-command</CODE> are not the +same for some operating systems (VMS). +</P> +</DL> +<P> + +<A NAME="IDX279"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:comment</B> <I>parms line1 <small>...</small></I> +<DD>Writes comment lines <VAR>line1</VAR> <small>...</small> to the <CODE>batch-port</CODE> in +<VAR>parms</VAR>. +</DL> +<P> + +<A NAME="IDX280"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:lines->file</B> <I>parms file line1 <small>...</small></I> +<DD>Writes commands to the <CODE>batch-port</CODE> in <VAR>parms</VAR> which create a +file named <VAR>file</VAR> with contents <VAR>line1</VAR> <small>...</small>. +</DL> +<P> + +<A NAME="IDX281"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:delete-file</B> <I>parms file</I> +<DD>Writes a command to the <CODE>batch-port</CODE> in <VAR>parms</VAR> which deletes +the file named <VAR>file</VAR>. +</DL> +<P> + +<A NAME="IDX282"></A> +</P> +<DL> +<DT><U>Function:</U> <B>batch:rename-file</B> <I>parms old-name new-name</I> +<DD>Writes a command to the <CODE>batch-port</CODE> in <VAR>parms</VAR> which renames +the file <VAR>old-name</VAR> to <VAR>new-name</VAR>. +</DL> +<P> + +In addition, batch provides some small utilities very useful for writing +scripts: +</P> +<P> + +<A NAME="IDX283"></A> +</P> +<DL> +<DT><U>Function:</U> <B>truncate-up-to</B> <I>path char</I> +<DD><A NAME="IDX284"></A> +<DT><U>Function:</U> <B>truncate-up-to</B> <I>path string</I> +<DD><A NAME="IDX285"></A> +<DT><U>Function:</U> <B>truncate-up-to</B> <I>path charlist</I> +<DD><VAR>path</VAR> can be a string or a list of strings. Returns <VAR>path</VAR> +sans any prefixes ending with a character of the second argument. This +can be used to derive a filename moved locally from elsewhere. +<P> + +<TABLE><tr><td> </td><td class=example><pre>(truncate-up-to "/usr/local/lib/slib/batch.scm" "/") +=> "batch.scm" +</pre></td></tr></table></DL> +<P> + +<A NAME="IDX286"></A> +</P> +<DL> +<DT><U>Function:</U> <B>string-join</B> <I>joiner string1 <small>...</small></I> +<DD>Returns a new string consisting of all the strings <VAR>string1</VAR> <small>...</small> +in order appended together with the string <VAR>joiner</VAR> between each +adjacent pair. +</DL> +<P> + +<A NAME="IDX287"></A> +</P> +<DL> +<DT><U>Function:</U> <B>must-be-first</B> <I>list1 list2</I> +<DD>Returns a new list consisting of the elements of <VAR>list2</VAR> ordered so +that if some elements of <VAR>list1</VAR> are <CODE>equal?</CODE> to elements of +<VAR>list2</VAR>, then those elements will appear first and in the order of +<VAR>list1</VAR>. +</DL> +<P> + +<A NAME="IDX288"></A> +</P> +<DL> +<DT><U>Function:</U> <B>must-be-last</B> <I>list1 list2</I> +<DD>Returns a new list consisting of the elements of <VAR>list1</VAR> ordered so +that if some elements of <VAR>list2</VAR> are <CODE>equal?</CODE> to elements of +<VAR>list1</VAR>, then those elements will appear last and in the order of +<VAR>list2</VAR>. +</DL> +<P> + +<A NAME="IDX289"></A> +</P> +<DL> +<DT><U>Function:</U> <B>os->batch-dialect</B> <I>osname</I> +<DD>Returns its best guess for the <CODE>batch-dialect</CODE> to be used for the +operating-system named <VAR>osname</VAR>. <CODE>os->batch-dialect</CODE> uses the +tables added to <VAR>database</VAR> by <CODE>batch:initialize!</CODE>. +</DL> +<P> + +Here is an example of the use of most of batch's procedures: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require 'databases) +<A NAME="IDX290"></A>(require 'parameters) +<A NAME="IDX291"></A>(require 'batch) +<A NAME="IDX292"></A>(require 'glob) +<A NAME="IDX293"></A> +(define batch (create-database #f 'alist-table)) +(batch:initialize! batch) + +(define my-parameters + (list (list 'batch-dialect (os->batch-dialect *operating-system*)) + (list 'operating-system *operating-system*) + (list 'batch-port (current-output-port)))) ;gets filled in later + +(batch:call-with-output-script + my-parameters + "my-batch" + (lambda (batch-port) + (adjoin-parameters! my-parameters (list 'batch-port batch-port)) + (and + (batch:comment my-parameters + "================ Write file with C program.") + (batch:rename-file my-parameters "hello.c" "hello.c~") + (batch:lines->file my-parameters "hello.c" + "#include <stdio.h>" + "int main(int argc, char **argv)" + "{" + " printf(\"hello world\\n\");" + " return 0;" + "}" ) + (batch:command my-parameters "cc" "-c" "hello.c") + (batch:command my-parameters "cc" "-o" "hello" + (replace-suffix "hello.c" ".c" ".o")) + (batch:command my-parameters "hello") + (batch:delete-file my-parameters "hello") + (batch:delete-file my-parameters "hello.c") + (batch:delete-file my-parameters "hello.o") + (batch:delete-file my-parameters "my-batch") + ))) +</pre></td></tr></table><P> + +Produces the file `<TT>my-batch</TT>': +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>#! /bin/sh +# "my-batch" script created by SLIB/batch Sun Oct 31 18:24:10 1999 +# ================ Write file with C program. +mv -f hello.c hello.c~ +rm -f hello.c +echo '#include <stdio.h>'>>hello.c +echo 'int main(int argc, char **argv)'>>hello.c +echo '{'>>hello.c +echo ' printf("hello world\n");'>>hello.c +echo ' return 0;'>>hello.c +echo '}'>>hello.c +cc -c hello.c +cc -o hello hello.o +hello +rm -f hello +rm -f hello.c +rm -f hello.o +rm -f my-batch +</pre></td></tr></table><P> + +When run, `<TT>my-batch</TT>' prints: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>bash$ my-batch +mv: hello.c: No such file or directory +hello world +</pre></td></tr></table><P> + +<A NAME="HTML"></A> +<HR SIZE="6"> +<A NAME="SEC69"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC68"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC70"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.5 HTML </H2> +<!--docid::SEC69::--> +<P> + +<CODE>(require 'html-form)</CODE> +<A NAME="IDX294"></A> +</P> +<P> + +<A NAME="IDX295"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:atval</B> <I>txt</I> +<DD>Returns a string with character substitutions appropriate to +send <VAR>txt</VAR> as an <EM>attribute-value</EM>. +<A NAME="IDX296"></A> +</DL> +<P> + +<A NAME="IDX297"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:plain</B> <I>txt</I> +<DD>Returns a string with character substitutions appropriate to +send <VAR>txt</VAR> as an <EM>plain-text</EM>. +<A NAME="IDX298"></A> +</DL> +<P> + +<A NAME="IDX299"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:meta</B> <I>name content</I> +<DD>Returns a tag of meta-information suitable for passing as the +third argument to <CODE>html:head</CODE>. The tag produced is `<SAMP><META +NAME="<VAR>name</VAR>" CONTENT="<VAR>content</VAR>"></SAMP>'. The string or symbol <VAR>name</VAR> can be +`<SAMP>author</SAMP>', `<SAMP>copyright</SAMP>', `<SAMP>keywords</SAMP>', `<SAMP>description</SAMP>', +`<SAMP>date</SAMP>', `<SAMP>robots</SAMP>', <small>...</small>. +</DL> +<P> + +<A NAME="IDX300"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:http-equiv</B> <I>name content</I> +<DD>Returns a tag of HTTP information suitable for passing as the +third argument to <CODE>html:head</CODE>. The tag produced is `<SAMP><META +HTTP-EQUIV="<VAR>name</VAR>" CONTENT="<VAR>content</VAR>"></SAMP>'. The string or symbol <VAR>name</VAR> can be +`<SAMP>Expires</SAMP>', `<SAMP>PICS-Label</SAMP>', `<SAMP>Content-Type</SAMP>', +`<SAMP>Refresh</SAMP>', <small>...</small>. +</DL> +<P> + +<A NAME="IDX301"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:meta-refresh</B> <I>delay uri</I> +<DD><P> + +<A NAME="IDX302"></A> +<DT><U>Function:</U> <B>html:meta-refresh</B> <I>delay</I> +<DD></P> +<P> + +Returns a tag suitable for passing as the third argument to +<CODE>html:head</CODE>. If <VAR>uri</VAR> argument is supplied, then <VAR>delay</VAR> seconds after +displaying the page with this tag, Netscape or IE browsers will fetch +and display <VAR>uri</VAR>. Otherwise, <VAR>delay</VAR> seconds after displaying the page with +this tag, Netscape or IE browsers will fetch and redisplay this page. +</P> +</DL> +<P> + +<A NAME="IDX303"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:head</B> <I>title backlink tags <small>...</small></I> +<DD><P> + +<A NAME="IDX304"></A> +<DT><U>Function:</U> <B>html:head</B> <I>title backlink</I> +<DD></P> +<P> + +<A NAME="IDX305"></A> +<DT><U>Function:</U> <B>html:head</B> <I>title</I> +<DD></P> +<P> + +Returns header string for an HTML page named <VAR>title</VAR>. If <VAR>backlink</VAR> is a string, +it is used verbatim between the `<SAMP>H1</SAMP>' tags; otherwise <VAR>title</VAR> is +used. If string arguments <VAR>tags</VAR> ... are supplied, then they are +included verbatim within the <TT><HEAD></TT> section. +</P> +</DL> +<P> + +<A NAME="IDX306"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:body</B> <I>body <small>...</small></I> +<DD>Returns HTML string to end a page. +</DL> +<P> + +<A NAME="IDX307"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:pre</B> <I>line1 line <small>...</small></I> +<DD>Returns the strings <VAR>line1</VAR>, <VAR>lines</VAR> as <EM>PRE</EM>formmated plain text +<A NAME="IDX308"></A> +(rendered in fixed-width font). Newlines are inserted between <VAR>line1</VAR>, +<VAR>lines</VAR>. HTML tags (`<SAMP><tag></SAMP>') within <VAR>lines</VAR> will be visible verbatim. +</DL> +<P> + +<A NAME="IDX309"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:comment</B> <I>line1 line <small>...</small></I> +<DD>Returns the strings <VAR>line1</VAR> as HTML comments. +</DL> +<HR SIZE="6"> +<A NAME="SEC70"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC69"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC71"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.6 HTML Forms </H2> +<!--docid::SEC70::--> +<P> + +<A NAME="IDX310"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:form</B> <I>method action body <small>...</small></I> +<DD>The symbol <VAR>method</VAR> is either <CODE>get</CODE>, <CODE>head</CODE>, <CODE>post</CODE>, +<CODE>put</CODE>, or <CODE>delete</CODE>. The strings <VAR>body</VAR> form the body of the +form. <CODE>html:form</CODE> returns the HTML <EM>form</EM>. +<A NAME="IDX311"></A> +</DL> +<P> + +<A NAME="IDX312"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:hidden</B> <I>name value</I> +<DD>Returns HTML string which will cause <VAR>name</VAR>=<VAR>value</VAR> in form. +</DL> +<P> + +<A NAME="IDX313"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:checkbox</B> <I>pname default</I> +<DD>Returns HTML string for check box. +</DL> +<P> + +<A NAME="IDX314"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:text</B> <I>pname default size <small>...</small></I> +<DD>Returns HTML string for one-line text box. +</DL> +<P> + +<A NAME="IDX315"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:text-area</B> <I>pname default-list</I> +<DD>Returns HTML string for multi-line text box. +</DL> +<P> + +<A NAME="IDX316"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:select</B> <I>pname arity default-list foreign-values</I> +<DD>Returns HTML string for pull-down menu selector. +</DL> +<P> + +<A NAME="IDX317"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:buttons</B> <I>pname arity default-list foreign-values</I> +<DD>Returns HTML string for any-of selector. +</DL> +<P> + +<A NAME="IDX318"></A> +</P> +<DL> +<DT><U>Function:</U> <B>form:submit</B> <I>submit-label command</I> +<DD><P> + +<A NAME="IDX319"></A> +<DT><U>Function:</U> <B>form:submit</B> <I>submit-label</I> +<DD></P> +<P> + +The string or symbol <VAR>submit-label</VAR> appears on the button which submits the form. +If the optional second argument <VAR>command</VAR> is given, then <CODE>*command*=<VAR>command</VAR></CODE> +and <CODE>*button*=<VAR>submit-label</VAR></CODE> are set in the query. Otherwise, +<CODE>*command*=<VAR>submit-label</VAR></CODE> is set in the query. +</P> +</DL> +<P> + +<A NAME="IDX320"></A> +</P> +<DL> +<DT><U>Function:</U> <B>form:image</B> <I>submit-label image-src</I> +<DD>The <VAR>image-src</VAR> appears on the button which submits the form. +</DL> +<P> + +<A NAME="IDX321"></A> +</P> +<DL> +<DT><U>Function:</U> <B>form:reset</B> +<DD>Returns a string which generates a <EM>reset</EM> button. +<A NAME="IDX322"></A> +</DL> +<P> + +<A NAME="IDX323"></A> +</P> +<DL> +<DT><U>Function:</U> <B>form:element</B> <I>pname arity default-list foreign-values</I> +<DD>Returns a string which generates an INPUT element for the field +named <VAR>pname</VAR>. The element appears in the created form with its +representation determined by its <VAR>arity</VAR> and domain. For domains which +are foreign-keys: +<P> + +</P> +<DL COMPACT> +<DT><CODE>single</CODE> +<DD>select menu +<DT><CODE>optional</CODE> +<DD>select menu +<DT><CODE>nary</CODE> +<DD>check boxes +<DT><CODE>nary1</CODE> +<DD>check boxes +</DL> +<P> + +If the foreign-key table has a field named `<SAMP>visible-name</SAMP>', then +the contents of that field are the names visible to the user for +those choices. Otherwise, the foreign-key itself is visible. +</P> +<P> + +For other types of domains: +</P> +<P> + +</P> +<DL COMPACT> +<DT><CODE>single</CODE> +<DD>text area +<DT><CODE>optional</CODE> +<DD>text area +<DT><CODE>boolean</CODE> +<DD>check box +<DT><CODE>nary</CODE> +<DD>text area +<DT><CODE>nary1</CODE> +<DD>text area +</DL> +</DL> +<P> + +<A NAME="IDX324"></A> +</P> +<DL> +<DT><U>Function:</U> <B>form:delimited</B> <I>pname doc aliat arity default-list foreign-values</I> +<DD><P> + +Returns a HTML string for a form element embedded in a line of a +delimited list. Apply map <CODE>form:delimited</CODE> to the list returned by +<CODE>command->p-specs</CODE>. +</P> +</DL> +<P> + +<A NAME="IDX325"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:delimited-list</B> <I>row <small>...</small></I> +<DD>Wraps its arguments with delimited-list (`<SAMP>DL</SAMP>' command. +</DL> +<P> + +<A NAME="IDX326"></A> +</P> +<DL> +<DT><U>Function:</U> <B>get-foreign-choices</B> <I>tab</I> +<DD>Returns a list of the `<SAMP>visible-name</SAMP>' or first fields of +table <VAR>tab</VAR>. +</DL> +<P> + +<A NAME="IDX327"></A> +</P> +<DL> +<DT><U>Function:</U> <B>command->p-specs</B> <I>rdb command-table command</I> +<DD><P> + +The symbol <VAR>command-table</VAR> names a command table in the <VAR>rdb</VAR> relational database. +The symbol <VAR>command</VAR> names a key in <VAR>command-table</VAR>. +</P> +<P> + +<CODE>command->p-specs</CODE> returns a list of lists of <VAR>pname</VAR>, <VAR>doc</VAR>, <VAR>aliat</VAR>, +<VAR>arity</VAR>, <VAR>default-list</VAR>, and <VAR>foreign-values</VAR>. The +returned list has one element for each parameter of command <VAR>command</VAR>. +</P> +<P> + +This example demonstrates how to create a HTML-form for the `<SAMP>build</SAMP>' +command. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require (in-vicinity (implementation-vicinity) "build.scm")) +(call-with-output-file "buildscm.html" + (lambda (port) + (display + (string-append + (html:head 'commands) + (html:body + (sprintf #f "<H2>%s:</H2><BLOCKQUOTE>%s</BLOCKQUOTE>\\n" + (html:plain 'build) + (html:plain ((comtab 'get 'documentation) 'build))) + (html:form + 'post + (or "http://localhost:8081/buildscm" "/cgi-bin/build.cgi") + (apply html:delimited-list + (apply map form:delimited + (command->p-specs build '*commands* 'build))) + (form:submit 'build) + (form:reset)))) + port))) +</pre></td></tr></table></DL> +<P> + +<A NAME="HTML Tables"></A> +<HR SIZE="6"> +<A NAME="SEC71"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC70"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC72"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.7 HTML Tables </H2> +<!--docid::SEC71::--> +<P> + +<CODE>(require 'db->html)</CODE> +<A NAME="IDX328"></A> +</P> +<P> + +<A NAME="IDX329"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:table</B> <I>options row <small>...</small></I> +<DD><P> + +</P> +</DL> +<P> + +<A NAME="IDX330"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:caption</B> <I>caption align</I> +<DD><P> + +<A NAME="IDX331"></A> +<DT><U>Function:</U> <B>html:caption</B> <I>caption</I> +<DD><VAR>align</VAR> can be `<SAMP>top</SAMP>' or `<SAMP>bottom</SAMP>'. +</P> +</DL> +<P> + +<A NAME="IDX332"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:heading</B> <I>columns</I> +<DD>Outputs a heading row for the currently-started table. +</DL> +<P> + +<A NAME="IDX333"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:href-heading</B> <I>columns uris</I> +<DD>Outputs a heading row with column-names <VAR>columns</VAR> linked to URIs <VAR>uris</VAR>. +</DL> +<P> + +<A NAME="IDX334"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:linked-row-converter</B> <I>k foreigns</I> +<DD><P> + +The positive integer <VAR>k</VAR> is the primary-key-limit (number of +primary-keys) of the table. <VAR>foreigns</VAR> is a list of the filenames of +foreign-key field pages and #f for non foreign-key fields. +</P> +<P> + +<CODE>html:linked-row-converter</CODE> returns a procedure taking a row for its single argument. This +returned procedure returns the html string for that table row. +</P> +</DL> +<P> + +<A NAME="IDX335"></A> +</P> +<DL> +<DT><U>Function:</U> <B>table-name->filename</B> <I>table-name</I> +<DD><P> + +Returns the symbol <VAR>table-name</VAR> converted to a filename. +</P> +</DL> +<P> + +<A NAME="IDX336"></A> +</P> +<DL> +<DT><U>Function:</U> <B>table->linked-html</B> <I>caption db table-name match-key1 <small>...</small></I> +<DD><P> + +Returns HTML string for <VAR>db</VAR> table <VAR>table-name</VAR>. Every foreign-key value is +linked to the page (of the table) defining that key. +</P> +<P> + +The optional <VAR>match-key1</VAR> <small>...</small> arguments restrict actions to a subset of +the table. See section <A HREF="slib_6.html#SEC147">match-key</A>. +</P> +</DL> +<P> + +<A NAME="IDX337"></A> +</P> +<DL> +<DT><U>Function:</U> <B>table->linked-page</B> <I>db table-name index-filename arg <small>...</small></I> +<DD><P> + +Returns a complete HTML page. The string <VAR>index-filename</VAR> names the page which +refers to this one. +</P> +<P> + +The optional <VAR>args</VAR> <small>...</small> arguments restrict actions to a subset of +the table. See section <A HREF="slib_6.html#SEC147">match-key</A>. +</P> +</DL> +<P> + +<A NAME="IDX338"></A> +</P> +<DL> +<DT><U>Function:</U> <B>catalog->html</B> <I>db caption arg <small>...</small></I> +<DD><P> + +Returns HTML string for the catalog table of <VAR>db</VAR>. +</P> +</DL> +<HR SIZE="6"> +<A NAME="SEC72"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC71"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC73"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.7.1 HTML editing tables </H3> +<!--docid::SEC72::--> +<P> + +A client can modify one row of an editable table at a time. +For any change submitted, these routines check if that row has been +modified during the time the user has been editing the form. If so, +an error page results. +</P> +<P> + +The behavior of edited rows is: +</P> +<P> + +<UL> +<LI> +If no fields are changed, then no change is made to the table. +<LI> +If the primary keys equal null-keys (parameter defaults), and no other +user has modified that row, then that row is deleted. +<LI> +If only primary keys are changed, there are non-key fields, and no +row with the new keys is in the table, then the old row is +deleted and one with the new keys is inserted. +<LI> +If only non-key fields are changed, and that row has not been +modified by another user, then the row is changed to reflect the +fields. +<LI> +If both keys and non-key fields are changed, and no row with the +new keys is in the table, then a row is created with the new +keys and fields. +<LI> +If fields are changed, all fields are primary keys, and no row with +the new keys is in the table, then a row is created with the new +keys. +</UL> +<P> + +After any change to the table, a <CODE>sync-database</CODE> of the +database is performed. +</P> +<P> + +<A NAME="IDX339"></A> +</P> +<DL> +<DT><U>Function:</U> <B>command:modify-table</B> <I>table-name null-keys update delete retrieve</I> +<DD><P> + +<A NAME="IDX340"></A> +<DT><U>Function:</U> <B>command:modify-table</B> <I>table-name null-keys update delete</I> +<DD></P> +<P> + +<A NAME="IDX341"></A> +<DT><U>Function:</U> <B>command:modify-table</B> <I>table-name null-keys update</I> +<DD></P> +<P> + +<A NAME="IDX342"></A> +<DT><U>Function:</U> <B>command:modify-table</B> <I>table-name null-keys</I> +<DD></P> +<P> + +Returns procedure (of <VAR>db</VAR>) which returns procedure to modify +row of <VAR>table-name</VAR>. <VAR>null-keys</VAR> is the list of <EM>null</EM> keys indicating the row is +<A NAME="IDX343"></A> +to be deleted when any matches its corresponding primary key. +Optional arguments <VAR>update</VAR>, <VAR>delete</VAR>, and <VAR>retrieve</VAR> default to the <CODE>row:update</CODE>, +<CODE>row:delete</CODE>, and <CODE>row:retrieve</CODE> of <VAR>table-name</VAR> in <VAR>db</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX344"></A> +</P> +<DL> +<DT><U>Function:</U> <B>command:make-editable-table</B> <I>rdb table-name arg <small>...</small></I> +<DD>Given <VAR>table-name</VAR> in <VAR>rdb</VAR>, creates parameter and <CODE>*command*</CODE> tables +for editing one row of <VAR>table-name</VAR> at a time. <CODE>command:make-editable-table</CODE> returns a procedure taking a +row argument which returns the HTML string for editing that row. +<P> + +Optional <VAR>args</VAR> are expressions (lists) added to the call to +<CODE>command:modify-table</CODE>. +</P> +<P> + +The domain name of a column determines the expected arity of the data +stored in that column. Domain names ending in: +</P> +<P> + +</P> +<DL COMPACT> +<DT>`<SAMP>*</SAMP>' +<DD>have arity `<SAMP>nary</SAMP>'; +<DT>`<SAMP>+</SAMP>' +<DD>have arity `<SAMP>nary1</SAMP>'. +</DL> +</DL> +<P> + +<A NAME="IDX345"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:editable-row-converter</B> <I>k names edit-point edit-converter</I> +<DD><P> + +The positive integer <VAR>k</VAR> is the primary-key-limit (number of +primary-keys) of the table. <VAR>names</VAR> is a list of the field-names. <VAR>edit-point</VAR> is +the list of primary-keys denoting the row to edit (or #f). <VAR>edit-converter</VAR> is the +procedure called with <VAR>k</VAR>, <VAR>names</VAR>, and the row to edit. +</P> +<P> + +<CODE>html:editable-row-converter</CODE> returns a procedure taking a row for its single argument. This +returned procedure returns the html string for that table row. +</P> +<P> + +Each HTML table constructed using <CODE>html:editable-row-converter</CODE> has first <VAR>k</VAR> fields (typically +the primary key fields) of each row linked to a text encoding of these +fields (the result of calling <CODE>row->anchor</CODE>). The page so +referenced typically allows the user to edit fields of that row. +</P> +</DL> +<HR SIZE="6"> +<A NAME="SEC73"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC72"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC74"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.7.2 HTML databases </H3> +<!--docid::SEC73::--> +<P> + +<A NAME="IDX346"></A> +</P> +<DL> +<DT><U>Function:</U> <B>db->html-files</B> <I>db dir index-filename caption</I> +<DD><VAR>db</VAR> must be a relational database. <VAR>dir</VAR> must be #f or a +non-empty string naming an existing sub-directory of the current +directory. +<P> + +<CODE>db->html-files</CODE> creates an html page for each table in the database <VAR>db</VAR> in the +sub-directory named <VAR>dir</VAR>, or the current directory if <VAR>dir</VAR> is #f. The +top level page with the catalog of tables (captioned <VAR>caption</VAR>) is written +to a file named <VAR>index-filename</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX347"></A> +</P> +<DL> +<DT><U>Function:</U> <B>db->html-directory</B> <I>db dir index-filename</I> +<DD><P> + +<A NAME="IDX348"></A> +<DT><U>Function:</U> <B>db->html-directory</B> <I>db dir</I> +<DD><VAR>db</VAR> must be a relational database. <VAR>dir</VAR> must be a non-empty +string naming an existing sub-directory of the current directory or +one to be created. The optional string <VAR>index-filename</VAR> names the filename of the +top page, which defaults to `<TT>index.html</TT>'. +</P> +<P> + +<CODE>db->html-directory</CODE> creates sub-directory <VAR>dir</VAR> if neccessary, and calls +<CODE>(db->html-files <VAR>db</VAR> <VAR>dir</VAR> <VAR>index-filename</VAR> <VAR>dir</VAR>)</CODE>. The `<SAMP>file:</SAMP>' URI of <VAR>index-filename</VAR> is +returned. +</P> +</DL> +<P> + +<A NAME="IDX349"></A> +</P> +<DL> +<DT><U>Function:</U> <B>db->netscape</B> <I>db dir index-filename</I> +<DD><P> + +<A NAME="IDX350"></A> +<DT><U>Function:</U> <B>db->netscape</B> <I>db dir</I> +<DD><CODE>db->netscape</CODE> is just like <CODE>db->html-directory</CODE>, but calls +<CODE>browse-url</CODE> with the uri for the top page after the +pages are created. +</P> +</DL> +<P> + +<A NAME="HTTP and CGI"></A> +<HR SIZE="6"> +<A NAME="SEC74"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC73"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC75"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.8 HTTP and CGI </H2> +<!--docid::SEC74::--> +<P> + +<CODE>(require 'http)</CODE> or <CODE>(require 'cgi)</CODE> +<A NAME="IDX351"></A> +<A NAME="IDX352"></A> +</P> +<P> + +<A NAME="IDX353"></A> +</P> +<DL> +<DT><U>Function:</U> <B>http:header</B> <I>alist</I> +<DD>Returns a string containing lines for each element of <VAR>alist</VAR>; the +<CODE>car</CODE> of which is followed by `<SAMP>: </SAMP>', then the <CODE>cdr</CODE>. +</DL> +<P> + +<A NAME="IDX354"></A> +</P> +<DL> +<DT><U>Function:</U> <B>http:content</B> <I>alist body <small>...</small></I> +<DD>Returns the concatenation of strings <VAR>body</VAR> with the +<CODE>(http:header <VAR>alist</VAR>)</CODE> and the `<SAMP>Content-Length</SAMP>' prepended. +</DL> +<P> + +<A NAME="IDX355"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*http:byline*</B> +<DD>String appearing at the bottom of error pages. +</DL> +<P> + +<A NAME="IDX356"></A> +</P> +<DL> +<DT><U>Function:</U> <B>http:error-page</B> <I>status-code reason-phrase html-string <small>...</small></I> +<DD><VAR>status-code</VAR> and <VAR>reason-phrase</VAR> should be an integer and string as specified in +<CITE>RFC 2068</CITE>. The returned page (string) will show the <VAR>status-code</VAR> and <VAR>reason-phrase</VAR> +and any additional <VAR>html-strings</VAR> <small>...</small>; with <VAR>*http:byline*</VAR> or SLIB's +default at the bottom. +</DL> +<P> + +<A NAME="IDX357"></A> +</P> +<DL> +<DT><U>Function:</U> <B>http:forwarding-page</B> <I>title delay uri html-string <small>...</small></I> +<DD>The string or symbol <VAR>title</VAR> is the page title. <VAR>delay</VAR> is a non-negative +integer. The <VAR>html-strings</VAR> <small>...</small> are typically used to explain to the user why +this page is being forwarded. +<P> + +<CODE>http:forwarding-page</CODE> returns an HTML string for a page which automatically forwards to +<VAR>uri</VAR> after <VAR>delay</VAR> seconds. The returned page (string) contains any <VAR>html-strings</VAR> +<small>...</small> followed by a manual link to <VAR>uri</VAR>, in case the browser does not +forward automatically. +</P> +</DL> +<P> + +<A NAME="IDX358"></A> +</P> +<DL> +<DT><U>Function:</U> <B>http:serve-query</B> <I>serve-proc input-port output-port</I> +<DD>reads the <EM>URI</EM> and <EM>query-string</EM> from <VAR>input-port</VAR>. If the +<A NAME="IDX359"></A> +<A NAME="IDX360"></A> +query is a valid `<SAMP>"POST"</SAMP>' or `<SAMP>"GET"</SAMP>' query, then <CODE>http:serve-query</CODE> calls +<VAR>serve-proc</VAR> with three arguments, the <VAR>request-line</VAR>, <VAR>query-string</VAR>, +and <VAR>header-alist</VAR>. Otherwise, <CODE>http:serve-query</CODE> calls <VAR>serve-proc</VAR> with the +<VAR>request-line</VAR>, #f, and <VAR>header-alist</VAR>. +<P> + +If <VAR>serve-proc</VAR> returns a string, it is sent to <VAR>output-port</VAR>. If <VAR>serve-proc</VAR> returns a list, +then an error page with number 525 and strings from the list. If <VAR>serve-proc</VAR> +returns #f, then a `<SAMP>Bad Request</SAMP>' (400) page is sent to <VAR>output-port</VAR>. +</P> +<P> + +Otherwise, <CODE>http:serve-query</CODE> replies (to <VAR>output-port</VAR>) with appropriate HTML describing the +problem. +</P> +</DL> +<P> + +This example services HTTP queries from <VAR>port-number</VAR>: +<TABLE><tr><td> </td><td class=example><pre> +(define socket (make-stream-socket AF_INET 0)) +(and (socket:bind socket port-number) ; AF_INET INADDR_ANY + (socket:listen socket 10) ; Queue up to 10 requests. + (dynamic-wind + (lambda () #f) + (lambda () + (do ((port (socket:accept socket) (socket:accept socket))) + (#f) + (let ((iport (duplicate-port port "r")) + (oport (duplicate-port port "w"))) + (http:serve-query build:serve iport oport) + (close-port iport) + (close-port oport)) + (close-port port))) + (lambda () (close-port socket)))) +</pre></td></tr></table><P> + +<A NAME="IDX361"></A> +</P> +<DL> +<DT><U>Function:</U> <B>cgi:serve-query</B> <I>serve-proc</I> +<DD>reads the <EM>URI</EM> and <EM>query-string</EM> from +<A NAME="IDX362"></A> +<A NAME="IDX363"></A> +<CODE>(current-input-port)</CODE>. If the query is a valid `<SAMP>"POST"</SAMP>' +or `<SAMP>"GET"</SAMP>' query, then <CODE>cgi:serve-query</CODE> calls <VAR>serve-proc</VAR> with three arguments, the +<VAR>request-line</VAR>, <VAR>query-string</VAR>, and <VAR>header-alist</VAR>. +Otherwise, <CODE>cgi:serve-query</CODE> calls <VAR>serve-proc</VAR> with the <VAR>request-line</VAR>, #f, and +<VAR>header-alist</VAR>. +<P> + +If <VAR>serve-proc</VAR> returns a string, it is sent to <CODE>(current-input-port)</CODE>. +If <VAR>serve-proc</VAR> returns a list, then an error page with number 525 and strings +from the list. If <VAR>serve-proc</VAR> returns #f, then a `<SAMP>Bad Request</SAMP>' (400) +page is sent to <CODE>(current-input-port)</CODE>. +</P> +<P> + +Otherwise, <CODE>cgi:serve-query</CODE> replies (to <CODE>(current-input-port)</CODE>) with +appropriate HTML describing the problem. +</P> +</DL> +<P> + +<A NAME="IDX364"></A> +</P> +<DL> +<DT><U>Function:</U> <B>make-query-alist-command-server</B> <I>rdb command-table</I> +<DD><P> + +<A NAME="IDX365"></A> +<DT><U>Function:</U> <B>make-query-alist-command-server</B> <I>rdb command-table #t</I> +<DD></P> +<P> + +Returns a procedure of one argument. When that procedure is called +with a <VAR>query-alist</VAR> (as returned by <CODE>uri:decode-query</CODE>, the +value of the `<SAMP>*command*</SAMP>' association will be the command invoked +in <VAR>command-table</VAR>. If `<SAMP>*command*</SAMP>' is not in the <VAR>query-alist</VAR> then the +value of `<SAMP>*suggest*</SAMP>' is tried. If neither name is in the +<VAR>query-alist</VAR>, then the literal value `<SAMP>*default*</SAMP>' is tried in +<VAR>command-table</VAR>. +</P> +<P> + +If optional third argument is non-false, then the command is called +with just the parameter-list; otherwise, command is called with the +arguments described in its table. +</P> +</DL> +<P> + +<A NAME="Parsing HTML"></A> +<HR SIZE="6"> +<A NAME="SEC75"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC74"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC76"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.9 Parsing HTML </H2> +<!--docid::SEC75::--> +<P> + +<CODE>(require 'html-for-each)</CODE> +<A NAME="IDX366"></A> +</P> +<P> + +<A NAME="IDX367"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html-for-each</B> <I>file word-proc markup-proc white-proc newline-proc</I> +<DD><P> + +<VAR>file</VAR> is an input port or a string naming an existing file containing +HTML text. +<VAR>word-proc</VAR> is a procedure of one argument or #f. +<VAR>markup-proc</VAR> is a procedure of one argument or #f. +<VAR>white-proc</VAR> is a procedure of one argument or #f. +<VAR>newline-proc</VAR> is a procedure of no arguments or #f. +</P> +<P> + +<CODE>html-for-each</CODE> opens and reads characters from port <VAR>file</VAR> or the file named by +string <VAR>file</VAR>. Sequential groups of characters are assembled into +strings which are either +</P> +<P> + +<UL> +<LI> +enclosed by `<SAMP><</SAMP>' and `<SAMP>></SAMP>' (hypertext markups or comments); +<LI> +end-of-line; +<LI> +whitespace; or +<LI> +none of the above (words). +</UL> +<P> + +Procedures are called according to these distinctions in order of +the string's occurrence in <VAR>file</VAR>. +</P> +<P> + +<VAR>newline-proc</VAR> is called with no arguments for end-of-line <EM>not within a +markup or comment</EM>. +</P> +<P> + +<VAR>white-proc</VAR> is called with strings of non-newline whitespace. +</P> +<P> + +<VAR>markup-proc</VAR> is called with hypertext markup strings (including `<SAMP><</SAMP>' and +`<SAMP>></SAMP>'). +</P> +<P> + +<VAR>word-proc</VAR> is called with the remaining strings. +</P> +<P> + +<CODE>html-for-each</CODE> returns an unspecified value. +</P> +</DL> +<P> + +<A NAME="IDX368"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:read-title</B> <I>file limit</I> +<DD><P> + +<A NAME="IDX369"></A> +<DT><U>Function:</U> <B>html:read-title</B> <I>file</I> +<DD><VAR>file</VAR> is an input port or a string naming an existing file containing +HTML text. If supplied, <VAR>limit</VAR> must be an integer. <VAR>limit</VAR> defaults to +1000. +</P> +<P> + +<CODE>html:read-title</CODE> opens and reads HTML from port <VAR>file</VAR> or the file named by string <VAR>file</VAR>, +until reaching the (mandatory) `<SAMP>TITLE</SAMP>' field. <CODE>html:read-title</CODE> returns the +title string with adjacent whitespaces collapsed to one space. <CODE>html:read-title</CODE> +returns #f if the title field is empty, absent, if the first +character read from <VAR>file</VAR> is not `<SAMP>#\<</SAMP>', or if the end of title is +not found within the first (approximately) <VAR>limit</VAR> words. +</P> +</DL> +<P> + +<A NAME="IDX370"></A> +</P> +<DL> +<DT><U>Function:</U> <B>htm-fields</B> <I>htm</I> +<DD><P> + +<VAR>htm</VAR> is a hypertext markup string. +</P> +<P> + +If <VAR>htm</VAR> is a (hypertext) comment, then <CODE>htm-fields</CODE> returns #f. +Otherwise <CODE>htm-fields</CODE> returns the hypertext element symbol (created by +<CODE>string-ci->symbol</CODE>) consed onto an association list of the +attribute name-symbols and values. Each value is a number or +string; or #t if the name had no value assigned within the markup. +</P> +</DL> +<P> + +<A NAME="URI"></A> +<HR SIZE="6"> +<A NAME="SEC76"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC75"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC78"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.10 URI </H2> +<!--docid::SEC76::--> +<P> + +<CODE>(require 'uri)</CODE> +<A NAME="IDX371"></A> +</P> +<P> + +Implements <EM>Uniform Resource Identifiers</EM> (URI) as +<A NAME="IDX372"></A> +described in RFC 2396. +</P> +<P> + +<A NAME="IDX373"></A> +</P> +<DL> +<DT><U>Function:</U> <B>make-uri</B> +<DD><P> + +<A NAME="IDX374"></A> +<DT><U>Function:</U> <B>make-uri</B> <I>fragment</I> +<DD></P> +<P> + +<A NAME="IDX375"></A> +<DT><U>Function:</U> <B>make-uri</B> <I>query fragment</I> +<DD></P> +<P> + +<A NAME="IDX376"></A> +<DT><U>Function:</U> <B>make-uri</B> <I>path query fragment</I> +<DD></P> +<P> + +<A NAME="IDX377"></A> +<DT><U>Function:</U> <B>make-uri</B> <I>authority path query fragment</I> +<DD></P> +<P> + +<A NAME="IDX378"></A> +<DT><U>Function:</U> <B>make-uri</B> <I>scheme authority path query fragment</I> +<DD></P> +<P> + +Returns a Uniform Resource Identifier string from component arguments. +</P> +</DL> +<P> + +<A NAME="IDX379"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uri:make-path</B> <I>path</I> +<DD><P> + +Returns a URI string combining the components of list <VAR>path</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX380"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:anchor</B> <I>name</I> +<DD>Returns a string which defines this location in the (HTML) file +as <VAR>name</VAR>. The hypertext `<SAMP><A HREF="#<VAR>name</VAR>"></SAMP>' will link to this point. +<P> + +<TABLE><tr><td> </td><td class=example><pre>(html:anchor "(section 7)") +=> +"<A NAME=\"(section%207)\"></A>" +</pre></td></tr></table></DL> +<P> + +<A NAME="IDX381"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:link</B> <I>uri highlighted</I> +<DD>Returns a string which links the <VAR>highlighted</VAR> text to <VAR>uri</VAR>. +<P> + +<TABLE><tr><td> </td><td class=example><pre>(html:link (make-uri "(section 7)") "section 7") +=> +"<A HREF=\"#(section%207)\">section 7</A>" +</pre></td></tr></table></DL> +<P> + +<A NAME="IDX382"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:base</B> <I>uri</I> +<DD>Returns a string specifying the <EM>base</EM> <VAR>uri</VAR> of a document, for +<A NAME="IDX383"></A> +inclusion in the HEAD of the document (see section <A HREF="slib_4.html#SEC69">head</A>). +</DL> +<P> + +<A NAME="IDX384"></A> +</P> +<DL> +<DT><U>Function:</U> <B>html:isindex</B> <I>prompt</I> +<DD>Returns a string specifying the search <VAR>prompt</VAR> of a document, for +inclusion in the HEAD of the document (see section <A HREF="slib_4.html#SEC69">head</A>). +</DL> +<P> + +<A NAME="IDX385"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uri->tree</B> <I>uri-reference base-tree</I> +<DD><P> + +<A NAME="IDX386"></A> +<DT><U>Function:</U> <B>uri->tree</B> <I>uri-reference</I> +<DD></P> +<P> + +Returns a list of 5 elements corresponding to the parts +(<VAR>scheme</VAR> <VAR>authority</VAR> <VAR>path</VAR> <VAR>query</VAR> <VAR>fragment</VAR>) +of string <VAR>uri-reference</VAR>. Elements corresponding to absent parts are #f. +</P> +<P> + +The <VAR>path</VAR> is a list of strings. If the first string is empty, +then the path is absolute; otherwise relative. The optional <VAR>base-tree</VAR> is a +tree as returned by <CODE>uri->tree</CODE>; and is used as the base address for relative +URIs. +</P> +<P> + +If the <VAR>authority</VAR> component is a +<EM>Server-based Naming Authority</EM>, then it is a list of the +<A NAME="IDX387"></A> +<VAR>userinfo</VAR>, <VAR>host</VAR>, and <VAR>port</VAR> strings (or #f). For other +types of <VAR>authority</VAR> components the <VAR>authority</VAR> will be a +string. +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(uri->tree "http://www.ics.uci.edu/pub/ietf/uri/#Related") +=> +(http "www.ics.uci.edu" ("" "pub" "ietf" "uri" "") #f "Related") +</pre></td></tr></table></DL> +<P> + +<A NAME="IDX388"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uri:split-fields</B> <I>txt chr</I> +<DD><P> + +Returns a list of <VAR>txt</VAR> split at each occurrence of <VAR>chr</VAR>. <VAR>chr</VAR> does not +appear in the returned list of strings. +</P> +</DL> +<P> + +<A NAME="IDX389"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uri:decode-query</B> <I>query-string</I> +<DD>Converts a <EM>URI</EM> encoded <VAR>query-string</VAR> to a query-alist. +<A NAME="IDX390"></A> +</DL> +<P> + +<CODE>uric:</CODE> prefixes indicate procedures dealing with +URI-components. +</P> +<P> + +<A NAME="IDX391"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uric:encode</B> <I>uri-component allows</I> +<DD>Returns a copy of the string <VAR>uri-component</VAR> in which all <EM>unsafe</EM> octets +<A NAME="IDX392"></A> +(as defined in RFC 2396) have been `<SAMP>%</SAMP>' <EM>escaped</EM>. +<A NAME="IDX393"></A> +<CODE>uric:decode</CODE> decodes strings encoded by <CODE>uric:encode</CODE>. +</DL> +<P> + +<A NAME="IDX394"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uric:decode</B> <I>uri-component</I> +<DD>Returns a copy of the string <VAR>uri-component</VAR> in which each `<SAMP>%</SAMP>' escaped +characters in <VAR>uri-component</VAR> is replaced with the character it encodes. This +routine is useful for showing URI contents on error pages. +</DL> +<P> + +<A NAME="IDX395"></A> +</P> +<DL> +<DT><U>Function:</U> <B>uri:path->keys</B> <I>path-list ptypes</I> +<DD><VAR>path-list</VAR> is a path-list as returned by <CODE>uri:split-fields</CODE>. <CODE>uri:path->keys</CODE> +returns a list of items returned by <CODE>uri:decode-path</CODE>, coerced +to types <VAR>ptypes</VAR>. +</DL> +<A NAME="SEC77"></A> +<H3> File-system Locators and Predicates </H3> +<!--docid::SEC77::--> +<P> + +<A NAME="IDX396"></A> +</P> +<DL> +<DT><U>Function:</U> <B>path->uri</B> <I>path</I> +<DD>Returns a URI-string for <VAR>path</VAR> on the local host. +</DL> +<P> + +<A NAME="IDX397"></A> +</P> +<DL> +<DT><U>Function:</U> <B>absolute-uri?</B> <I>str</I> +<DD>Returns #t if <VAR>str</VAR> is an absolute-URI as indicated by a +syntactically valid (per RFC 2396) <EM>scheme</EM>; otherwise returns +<A NAME="IDX398"></A> +#f. +</DL> +<P> + +<A NAME="IDX399"></A> +</P> +<DL> +<DT><U>Function:</U> <B>absolute-path?</B> <I>file-name</I> +<DD>Returns #t if <VAR>file-name</VAR> is a fully specified pathname (does not +depend on the current working directory); otherwise returns #f. +</DL> +<P> + +<A NAME="IDX400"></A> +</P> +<DL> +<DT><U>Function:</U> <B>null-directory?</B> <I>str</I> +<DD>Returns #t if changing directory to <VAR>str</VAR> would leave the current +directory unchanged; otherwise returns #f. +</DL> +<P> + +<A NAME="IDX401"></A> +</P> +<DL> +<DT><U>Function:</U> <B>glob-pattern?</B> <I>str</I> +<DD>Returns #t if the string <VAR>str</VAR> contains characters used for +specifying glob patterns, namely `<SAMP>*</SAMP>', `<SAMP>?</SAMP>', or `<SAMP>[</SAMP>'. +</DL> +Before RFC 2396, the <EM>File Transfer Protocol</EM> (FTP) served a +<A NAME="IDX402"></A> +similar purpose. +<P> + +<A NAME="IDX403"></A> +</P> +<DL> +<DT><U>Function:</U> <B>parse-ftp-address</B> <I>uri</I> +<DD><P> + +Returns a list of the decoded FTP <VAR>uri</VAR>; or #f if indecipherable. FTP +<EM>Uniform Resource Locator</EM>, <EM>ange-ftp</EM>, and <EM>getit</EM> +<A NAME="IDX404"></A> +<A NAME="IDX405"></A> +<A NAME="IDX406"></A> +formats are handled. The returned list has four elements which are +strings or #f: +</P> +<P> + +<OL> +<LI> +username +<LI> +password +<LI> +remote-site +<LI> +remote-directory +</OL> +</DL> +<P> + +<A NAME="Printing Scheme"></A> +<HR SIZE="6"> +<A NAME="SEC78"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC76"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC79"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.11 Printing Scheme </H2> +<!--docid::SEC78::--> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC79">4.11.1 Generic-Write</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'generic-write</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC80">4.11.2 Object-To-String</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'object->string</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC81">4.11.3 Pretty-Print</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'pretty-print, 'pprint-file</TD></TR> +</TABLE> +<P> + +<A NAME="Generic-Write"></A> +<HR SIZE="6"> +<A NAME="SEC79"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC78"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC80"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC78"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.11.1 Generic-Write </H3> +<!--docid::SEC79::--> +<P> + +<CODE>(require 'generic-write)</CODE> +<A NAME="IDX407"></A> +</P> +<P> + +<CODE>generic-write</CODE> is a procedure that transforms a Scheme data value +(or Scheme program expression) into its textual representation and +prints it. The interface to the procedure is sufficiently general to +easily implement other useful formatting procedures such as pretty +printing, output to a string and truncated output. +</P> +<P> + +<A NAME="IDX408"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>generic-write</B> <I>obj display? width output</I> +<DD><DL COMPACT> +<DT><VAR>obj</VAR> +<DD>Scheme data value to transform. +<DT><VAR>display?</VAR> +<DD>Boolean, controls whether characters and strings are quoted. +<DT><VAR>width</VAR> +<DD>Extended boolean, selects format: +<DL COMPACT> +<DT>#f +<DD>single line format +<DT>integer > 0 +<DD>pretty-print (value = max nb of chars per line) +</DL> +<DT><VAR>output</VAR> +<DD>Procedure of 1 argument of string type, called repeatedly with +successive substrings of the textual representation. This procedure can +return <CODE>#f</CODE> to stop the transformation. +</DL> +<P> + +The value returned by <CODE>generic-write</CODE> is undefined. +</P> +<P> + +Examples: +<TABLE><tr><td> </td><td class=example><pre>(write obj) == (generic-write obj #f #f <VAR>display-string</VAR>) +(display obj) == (generic-write obj #t #f <VAR>display-string</VAR>) +</pre></td></tr></table>where +<TABLE><tr><td> </td><td class=example><pre><VAR>display-string</VAR> == +(lambda (s) (for-each write-char (string->list s)) #t) +</pre></td></tr></table></DL> +<P> + +<A NAME="Object-To-String"></A> +<HR SIZE="6"> +<A NAME="SEC80"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC79"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC81"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC78"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.11.2 Object-To-String </H3> +<!--docid::SEC80::--> +<P> + +<CODE>(require 'object->string)</CODE> +<A NAME="IDX409"></A> +</P> +<P> + +<A NAME="IDX410"></A> +</P> +<DL> +<DT><U>Function:</U> <B>object->string</B> <I>obj</I> +<DD>Returns the textual representation of <VAR>obj</VAR> as a string. +</DL> +<P> + +<A NAME="IDX411"></A> +</P> +<DL> +<DT><U>Function:</U> <B>object->limited-string</B> <I>obj limit</I> +<DD>Returns the textual representation of <VAR>obj</VAR> as a string of length +at most <VAR>limit</VAR>. +</DL> +<P> + +<A NAME="Pretty-Print"></A> +<HR SIZE="6"> +<A NAME="SEC81"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC80"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC82"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC78"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.11.3 Pretty-Print </H3> +<!--docid::SEC81::--> +<P> + +<CODE>(require 'pretty-print)</CODE> +<A NAME="IDX412"></A> +</P> +<P> + +<A NAME="IDX413"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>pretty-print</B> <I>obj</I> +<DD><A NAME="IDX414"></A> +<DT><U>Procedure:</U> <B>pretty-print</B> <I>obj port</I> +<DD><P> + +<CODE>pretty-print</CODE>s <VAR>obj</VAR> on <VAR>port</VAR>. If <VAR>port</VAR> is not +specified, <CODE>current-output-port</CODE> is used. +</P> +<P> + +Example: +<TABLE><tr><td> </td><td class=example><pre>(pretty-print '((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))) + -| ((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)) +</pre></td></tr></table></DL> +<P> + +<A NAME="IDX415"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>pretty-print->string</B> <I>obj</I> +<DD><A NAME="IDX416"></A> +<DT><U>Procedure:</U> <B>pretty-print->string</B> <I>obj width</I> +<DD><P> + +Returns the string of <VAR>obj</VAR> <CODE>pretty-print</CODE>ed in <VAR>width</VAR> +columns. If <VAR>width</VAR> is not specified, <CODE>(output-port-width)</CODE> is +used. +</P> +<P> + +Example: +<TABLE><tr><td> </td><td class=example><pre>(pretty-print->string '((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))) +=> +"((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)) +" +(pretty-print->string '((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)) + 16) +=> +"((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)) +" +</pre></td></tr></table></DL> +<P> + +<CODE>(require 'pprint-file)</CODE> +<A NAME="IDX417"></A> +</P> +<P> + +<A NAME="IDX418"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>pprint-file</B> <I>infile</I> +<DD><A NAME="IDX419"></A> +<DT><U>Procedure:</U> <B>pprint-file</B> <I>infile outfile</I> +<DD>Pretty-prints all the code in <VAR>infile</VAR>. If <VAR>outfile</VAR> is +specified, the output goes to <VAR>outfile</VAR>, otherwise it goes to +<CODE>(current-output-port)</CODE>. +</DL> +<P> + +<A NAME="IDX420"></A> +</P> +<DL> +<DT><U>Function:</U> <B>pprint-filter-file</B> <I>infile proc outfile</I> +<DD><A NAME="IDX421"></A> +<DT><U>Function:</U> <B>pprint-filter-file</B> <I>infile proc</I> +<DD><VAR>infile</VAR> is a port or a string naming an existing file. Scheme +source code expressions and definitions are read from the port (or file) +and <VAR>proc</VAR> is applied to them sequentially. +<P> + +<VAR>outfile</VAR> is a port or a string. If no <VAR>outfile</VAR> is specified +then <CODE>current-output-port</CODE> is assumed. These expanded expressions +are then <CODE>pretty-print</CODE>ed to this port. +</P> +<P> + +Whitepsace and comments (introduced by <CODE>;</CODE>) which are not part of +scheme expressions are reproduced in the output. This procedure does +not affect the values returned by <CODE>current-input-port</CODE> and +<CODE>current-output-port</CODE>. +</P> +</DL> +<P> + +<CODE>pprint-filter-file</CODE> can be used to pre-compile macro-expansion and +thus can reduce loading time. The following will write into +`<TT>exp-code.scm</TT>' the result of expanding all defmacros in +`<TT>code.scm</TT>'. +<TABLE><tr><td> </td><td class=example><pre>(require 'pprint-file) +<A NAME="IDX422"></A>(require 'defmacroexpand) +<A NAME="IDX423"></A>(defmacro:load "my-macros.scm") +(pprint-filter-file "code.scm" defmacro:expand* "exp-code.scm") +</pre></td></tr></table><P> + +<A NAME="Time and Date"></A> +<HR SIZE="6"> +<A NAME="SEC82"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC81"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC83"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.12 Time and Date </H2> +<!--docid::SEC82::--> +<P> + +<TABLE BORDER="0" CELLSPACING="0"> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC83">4.12.1 Time Zone</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC84">4.12.2 Posix Time</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'posix-time</TD></TR> +<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="slib_4.html#SEC85">4.12.3 Common-Lisp Time</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">'common-lisp-time</TD></TR> +</TABLE> +<P> + +If <CODE>(provided? 'current-time)</CODE>: +</P> +<P> + +The procedures <CODE>current-time</CODE>, <CODE>difftime</CODE>, and +<CODE>offset-time</CODE> deal with a <EM>calendar time</EM> datatype +<A NAME="IDX424"></A> +<A NAME="IDX425"></A> +which may or may not be disjoint from other Scheme datatypes. +</P> +<P> + +<A NAME="IDX426"></A> +</P> +<DL> +<DT><U>Function:</U> <B>current-time</B> +<DD>Returns the time since 00:00:00 GMT, January 1, 1970, measured in +seconds. Note that the reference time is different from the reference +time for <CODE>get-universal-time</CODE> in <A HREF="slib_4.html#SEC85">4.12.3 Common-Lisp Time</A>. +</DL> +<P> + +<A NAME="IDX427"></A> +</P> +<DL> +<DT><U>Function:</U> <B>difftime</B> <I>caltime1 caltime0</I> +<DD>Returns the difference (number of seconds) between twe calendar times: +<VAR>caltime1</VAR> - <VAR>caltime0</VAR>. <VAR>caltime0</VAR> may also be a number. +</DL> +<P> + +<A NAME="IDX428"></A> +</P> +<DL> +<DT><U>Function:</U> <B>offset-time</B> <I>caltime offset</I> +<DD>Returns the calendar time of <VAR>caltime</VAR> offset by <VAR>offset</VAR> number +of seconds <CODE>(+ caltime offset)</CODE>. +</DL> +<P> + +<A NAME="Time Zone"></A> +<HR SIZE="6"> +<A NAME="SEC83"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC82"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC84"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC82"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.12.1 Time Zone </H3> +<!--docid::SEC83::--> +<P> + +(require 'time-zone) +</P> +<P> + +<A NAME="IDX429"></A> +</P> +<DL> +<DT><U>Data Format:</U> <B>TZ-string</B> +<DD><P> + +POSIX standards specify several formats for encoding time-zone rules. +</P> +<P> + +</P> +<DL COMPACT> +<DT><TT>:<I><pathname></I></TT> +<DD>If the first character of <I><pathname></I> is `<SAMP>/</SAMP>', then +<I><pathname></I> specifies the absolute pathname of a tzfile(5) format +time-zone file. Otherwise, <I><pathname></I> is interpreted as a pathname +within <VAR>tzfile:vicinity</VAR> (/usr/lib/zoneinfo/) naming a tzfile(5) +format time-zone file. +<DT><TT><I><std></I><I><offset></I></TT> +<DD>The string <I><std></I> consists of 3 or more alphabetic characters. +<I><offset></I> specifies the time difference from GMT. The <I><offset></I> +is positive if the local time zone is west of the Prime Meridian and +negative if it is east. <I><offset></I> can be the number of hours or +hours and minutes (and optionally seconds) separated by `<SAMP>:</SAMP>'. For +example, <CODE>-4:30</CODE>. +<DT><TT><I><std></I><I><offset></I><I><dst></I></TT> +<DD><I><dst></I> is the at least 3 alphabetic characters naming the local +daylight-savings-time. +<DT><TT><I><std></I><I><offset></I><I><dst></I><I><doffset></I></TT> +<DD><I><doffset></I> specifies the offset from the Prime Meridian when +daylight-savings-time is in effect. +</DL> +<P> + +The non-tzfile formats can optionally be followed by transition times +specifying the day and time when a zone changes from standard to +daylight-savings and back again. +</P> +<P> + +</P> +<DL COMPACT> +<DT><TT>,<I><date></I>/<I><time></I>,<I><date></I>/<I><time></I></TT> +<DD>The <I><time></I>s are specified like the <I><offset></I>s above, except that +leading `<SAMP>+</SAMP>' and `<SAMP>-</SAMP>' are not allowed. +<P> + +Each <I><date></I> has one of the formats: +</P> +<P> + +</P> +<DL COMPACT> +<DT><TT>J<I><day></I></TT> +<DD>specifies the Julian day with <I><day></I> between 1 and 365. February 29 +is never counted and cannot be referenced. +<DT><TT><I><day></I></TT> +<DD>This specifies the Julian day with n between 0 and 365. February 29 is +counted in leap years and can be specified. +<DT><TT>M<I><month></I>.<I><week></I>.<I><day></I></TT> +<DD>This specifies day <I><day></I> (0 <= <I><day></I> <= 6) of week <I><week></I> (1 +<= <I><week></I> <= 5) of month <I><month></I> (1 <= <I><month></I> <= 12). Week +1 is the first week in which day d occurs and week 5 is the last week in +which day <I><day></I> occurs. Day 0 is a Sunday. +</DL> +</DL> +<P> + +</P> +</DL> +<P> + +<A NAME="IDX430"></A> +</P> +<DL> +<DT><U>Data Type:</U> <B>time-zone</B> +<DD>is a datatype encoding how many hours from Greenwich Mean Time the local +time is, and the <EM>Daylight Savings Time</EM> rules for changing it. +</DL> +<P> + +<A NAME="IDX431"></A> +</P> +<DL> +<DT><U>Function:</U> <B>time-zone</B> <I>TZ-string</I> +<DD>Creates and returns a time-zone object specified by the string +<VAR>TZ-string</VAR>. If <CODE>time-zone</CODE> cannot interpret <VAR>TZ-string</VAR>, +<CODE>#f</CODE> is returned. +</DL> +<P> + +<A NAME="IDX432"></A> +</P> +<DL> +<DT><U>Function:</U> <B>tz:params</B> <I>caltime tz</I> +<DD><VAR>tz</VAR> is a time-zone object. <CODE>tz:params</CODE> returns a list of +three items: +<OL> +<LI> +An integer. 0 if standard time is in effect for timezone <VAR>tz</VAR> at +<VAR>caltime</VAR>; 1 if daylight savings time is in effect for timezone +<VAR>tz</VAR> at <VAR>caltime</VAR>. +<LI> +The number of seconds west of the Prime Meridian timezone <VAR>tz</VAR> is at +<VAR>caltime</VAR>. +<LI> +The name for timezone <VAR>tz</VAR> at <VAR>caltime</VAR>. +</OL> +<P> + +<CODE>tz:params</CODE> is unaffected by the default timezone; inquiries can be +made of any timezone at any calendar time. +</P> +<P> + +</P> +</DL> +<P> + +<A NAME="IDX433"></A> +</P> +<DL> +<DT><U>Function:</U> <B>tz:std-offset</B> <I>tz</I> +<DD><VAR>tz</VAR> is a time-zone object. <CODE>tz:std-offset</CODE> returns the +number of seconds west of the Prime Meridian timezone <VAR>tz</VAR> is. +<P> + +</P> +</DL> +<P> + +The rest of these procedures and variables are provided for POSIX +compatability. Because of shared state they are not thread-safe. +</P> +<P> + +<A NAME="IDX434"></A> +</P> +<DL> +<DT><U>Function:</U> <B>tzset</B> +<DD>Returns the default time-zone. +<P> + +<A NAME="IDX435"></A> +<DT><U>Function:</U> <B>tzset</B> <I>tz</I> +<DD>Sets (and returns) the default time-zone to <VAR>tz</VAR>. +</P> +<P> + +<A NAME="IDX436"></A> +<DT><U>Function:</U> <B>tzset</B> <I>TZ-string</I> +<DD>Sets (and returns) the default time-zone to that specified by +<VAR>TZ-string</VAR>. +</P> +<P> + +<CODE>tzset</CODE> also sets the variables <VAR>*timezone*</VAR>, <VAR>daylight?</VAR>, +and <VAR>tzname</VAR>. This function is automatically called by the time +conversion procedures which depend on the time zone (see section <A HREF="slib_4.html#SEC82">4.12 Time and Date</A>). +</P> +</DL> +<P> + +<A NAME="IDX437"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>*timezone*</B> +<DD>Contains the difference, in seconds, between Greenwich Mean Time and +local standard time (for example, in the U.S. Eastern time zone (EST), +timezone is 5*60*60). <CODE>*timezone*</CODE> is initialized by <CODE>tzset</CODE>. +</DL> +<P> + +<A NAME="IDX438"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>daylight?</B> +<DD>is <CODE>#t</CODE> if the default timezone has rules for <EM>Daylight Savings +Time</EM>. <EM>Note:</EM> <VAR>daylight?</VAR> does not tell you when Daylight +Savings Time is in effect, just that the default zone sometimes has +Daylight Savings Time. +</DL> +<P> + +<A NAME="IDX439"></A> +</P> +<DL> +<DT><U>Variable:</U> <B>tzname</B> +<DD>is a vector of strings. Index 0 has the abbreviation for the standard +timezone; If <VAR>daylight?</VAR>, then index 1 has the abbreviation for the +Daylight Savings timezone. +</DL> +<P> + +<A NAME="Posix Time"></A> +<HR SIZE="6"> +<A NAME="SEC84"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC83"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC85"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC82"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.12.2 Posix Time </H3> +<!--docid::SEC84::--> +<P> + +<TABLE><tr><td> </td><td class=example><pre>(require 'posix-time) +<A NAME="IDX440"></A></pre></td></tr></table><P> + +<A NAME="IDX441"></A> +</P> +<DL> +<DT><U>Data Type:</U> <B>Calendar-Time</B> +<DD><A NAME="IDX442"></A> +<A NAME="IDX443"></A> +is a datatype encapsulating time. +</DL> +<P> + +<A NAME="IDX444"></A> +</P> +<DL> +<DT><U>Data Type:</U> <B>Coordinated Universal Time</B> +<DD><A NAME="IDX445"></A> +<A NAME="IDX446"></A> +(abbreviated <EM>UTC</EM>) is a vector of integers representing time: +<P> + +<OL> +<LI> + seconds (0 - 61) +<LI> + minutes (0 - 59) +<LI> + hours since midnight (0 - 23) +<LI> + day of month (1 - 31) +<LI> + month (0 - 11). Note difference from <CODE>decode-universal-time</CODE>. +<LI> + the number of years since 1900. Note difference from +<CODE>decode-universal-time</CODE>. +<LI> + day of week (0 - 6) +<LI> + day of year (0 - 365) +<LI> + 1 for daylight savings, 0 for regular time +</OL> +</DL> +<P> + +<A NAME="IDX447"></A> +</P> +<DL> +<DT><U>Function:</U> <B>gmtime</B> <I>caltime</I> +<DD>Converts the calendar time <VAR>caltime</VAR> to UTC and returns it. +<P> + +<A NAME="IDX448"></A> +<DT><U>Function:</U> <B>localtime</B> <I>caltime tz</I> +<DD>Returns <VAR>caltime</VAR> converted to UTC relative to timezone <VAR>tz</VAR>. +</P> +<P> + +<A NAME="IDX449"></A> +<DT><U>Function:</U> <B>localtime</B> <I>caltime</I> +<DD>converts the calendar time <VAR>caltime</VAR> to a vector of integers +expressed relative to the user's time zone. <CODE>localtime</CODE> sets the +variable <VAR>*timezone*</VAR> with the difference between Coordinated +Universal Time (UTC) and local standard time in seconds +(see section <A HREF="slib_4.html#SEC83">tzset</A>). +</P> +<P> + +</P> +</DL> +<P> + +<A NAME="IDX450"></A> +</P> +<DL> +<DT><U>Function:</U> <B>gmktime</B> <I>univtime</I> +<DD>Converts a vector of integers in GMT Coordinated Universal Time (UTC) +format to a calendar time. +<P> + +<A NAME="IDX451"></A> +<DT><U>Function:</U> <B>mktime</B> <I>univtime</I> +<DD>Converts a vector of integers in local Coordinated Universal Time (UTC) +format to a calendar time. +</P> +<P> + +<A NAME="IDX452"></A> +<DT><U>Function:</U> <B>mktime</B> <I>univtime tz</I> +<DD>Converts a vector of integers in Coordinated Universal Time (UTC) format +(relative to time-zone <VAR>tz</VAR>) +to calendar time. +</P> +</DL> +<P> + +<A NAME="IDX453"></A> +</P> +<DL> +<DT><U>Function:</U> <B>asctime</B> <I>univtime</I> +<DD>Converts the vector of integers <VAR>caltime</VAR> in Coordinated +Universal Time (UTC) format into a string of the form +<CODE>"Wed Jun 30 21:49:08 1993"</CODE>. +</DL> +<P> + +<A NAME="IDX454"></A> +</P> +<DL> +<DT><U>Function:</U> <B>gtime</B> <I>caltime</I> +<DD><A NAME="IDX455"></A> +<DT><U>Function:</U> <B>ctime</B> <I>caltime</I> +<DD><A NAME="IDX456"></A> +<DT><U>Function:</U> <B>ctime</B> <I>caltime tz</I> +<DD>Equivalent to <CODE>(asctime (gmtime <VAR>caltime</VAR>))</CODE>, +<CODE>(asctime (localtime <VAR>caltime</VAR>))</CODE>, and +<CODE>(asctime (localtime <VAR>caltime</VAR> <VAR>tz</VAR>))</CODE>, respectively. +</DL> +<P> + +<A NAME="Common-Lisp Time"></A> +<HR SIZE="6"> +<A NAME="SEC85"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC84"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC86"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC82"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H3> 4.12.3 Common-Lisp Time </H3> +<!--docid::SEC85::--> +<P> + +<A NAME="IDX457"></A> +</P> +<DL> +<DT><U>Function:</U> <B>get-decoded-time</B> +<DD>Equivalent to <CODE>(decode-universal-time (get-universal-time))</CODE>. +</DL> +<P> + +<A NAME="IDX458"></A> +</P> +<DL> +<DT><U>Function:</U> <B>get-universal-time</B> +<DD>Returns the current time as <EM>Universal Time</EM>, number of seconds +since 00:00:00 Jan 1, 1900 GMT. Note that the reference time is +different from <CODE>current-time</CODE>. +</DL> +<P> + +<A NAME="IDX459"></A> +</P> +<DL> +<DT><U>Function:</U> <B>decode-universal-time</B> <I>univtime</I> +<DD>Converts <VAR>univtime</VAR> to <EM>Decoded Time</EM> format. +Nine values are returned: +<OL> +<LI> + seconds (0 - 61) +<LI> + minutes (0 - 59) +<LI> + hours since midnight +<LI> + day of month +<LI> + month (1 - 12). Note difference from <CODE>gmtime</CODE> and <CODE>localtime</CODE>. +<LI> + year (A.D.). Note difference from <CODE>gmtime</CODE> and <CODE>localtime</CODE>. +<LI> + day of week (0 - 6) +<LI> + #t for daylight savings, #f otherwise +<LI> + hours west of GMT (-24 - +24) +</OL> +<P> + +Notice that the values returned by <CODE>decode-universal-time</CODE> do not +match the arguments to <CODE>encode-universal-time</CODE>. +</P> +</DL> +<P> + +<A NAME="IDX460"></A> +</P> +<DL> +<DT><U>Function:</U> <B>encode-universal-time</B> <I>second minute hour date month year</I> +<DD><A NAME="IDX461"></A> +<DT><U>Function:</U> <B>encode-universal-time</B> <I>second minute hour date month year time-zone</I> +<DD>Converts the arguments in Decoded Time format to Universal Time format. +If <VAR>time-zone</VAR> is not specified, the returned time is adjusted for +daylight saving time. Otherwise, no adjustment is performed. +<P> + +Notice that the values returned by <CODE>decode-universal-time</CODE> do not +match the arguments to <CODE>encode-universal-time</CODE>. +</P> +</DL> +<P> + +<A NAME="NCBI-DNA"></A> +<HR SIZE="6"> +<A NAME="SEC86"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC85"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC87"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.13 NCBI-DNA </H2> +<!--docid::SEC86::--> +<P> + +<A NAME="IDX462"></A> +</P> +<DL> +<DT><U>Function:</U> <B>ncbi:read-dna-sequence</B> <I>port</I> +<DD><P> + +Reads the NCBI-format DNA sequence following the word `<SAMP>ORIGIN</SAMP>' +from <VAR>port</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX463"></A> +</P> +<DL> +<DT><U>Function:</U> <B>ncbi:read-file</B> <I>file</I> +<DD><P> + +Reads the NCBI-format DNA sequence following the word `<SAMP>ORIGIN</SAMP>' +from <VAR>file</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX464"></A> +</P> +<DL> +<DT><U>Function:</U> <B>mrna<-cdna</B> <I>str</I> +<DD><P> + +Replaces `<SAMP>T</SAMP>' with `<SAMP>U</SAMP>' in <VAR>str</VAR> +</P> +</DL> +<P> + +<A NAME="IDX465"></A> +</P> +<DL> +<DT><U>Function:</U> <B>codons<-cdna</B> <I>cdna</I> +<DD><P> + +Returns a list of three-letter symbol codons comprising the protein +sequence encoded by <VAR>cdna</VAR> starting with its first occurence of +`<SAMP>atg</SAMP>'. +</P> +</DL> +<P> + +<A NAME="IDX466"></A> +</P> +<DL> +<DT><U>Function:</U> <B>protein<-cdna</B> <I>cdna</I> +<DD><P> + +Returns a list of three-letter symbols for the protein sequence +encoded by <VAR>cdna</VAR> starting with its first occurence of `<SAMP>atg</SAMP>'. +</P> +</DL> +<P> + +<A NAME="IDX467"></A> +</P> +<DL> +<DT><U>Function:</U> <B>p<-cdna</B> <I>cdna</I> +<DD><P> + +Returns a string of one-letter amino acid codes for the protein +sequence encoded by <VAR>cdna</VAR> starting with its first occurence of +`<SAMP>atg</SAMP>'. +</P> +</DL> +<P> + +These cDNA count routines provide a means to check the nucleotide +sequence with the `<SAMP>BASE COUNT</SAMP>' line preceding the sequence from +NCBI. +</P> +<P> + +<A NAME="IDX468"></A> +</P> +<DL> +<DT><U>Function:</U> <B>cdna:base-count</B> <I>cdna</I> +<DD><P> + +Returns a list of counts of `<SAMP>a</SAMP>', `<SAMP>c</SAMP>', `<SAMP>g</SAMP>', and +`<SAMP>t</SAMP>' occurrencing in <VAR>cdna</VAR>. +</P> +</DL> +<P> + +<A NAME="IDX469"></A> +</P> +<DL> +<DT><U>Function:</U> <B>cdna:report-base-count</B> <I>cdna</I> +<DD><P> + +Prints the counts of `<SAMP>a</SAMP>', `<SAMP>c</SAMP>', `<SAMP>g</SAMP>', and `<SAMP>t</SAMP>' +occurrencing in <VAR>cdna</VAR>. +</P> +</DL> +<P> + +<A NAME="Schmooz"></A> +<HR SIZE="6"> +<A NAME="SEC87"></A> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC86"> < </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> > </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> Up </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<H2> 4.14 Schmooz </H2> +<!--docid::SEC87::--> +<P> + +<A NAME="IDX470"></A> +<EM>Schmooz</EM> is a simple, lightweight markup language for interspersing +Texinfo documentation with Scheme source code. Schmooz does not create +the top level Texinfo file; it creates `<SAMP>txi</SAMP>' files which can be +imported into the documentation using the Texinfo command +`<SAMP>@include</SAMP>'. +</P> +<P> + +<A NAME="IDX471"></A> +<CODE>(require 'schmooz)</CODE> defines the function <CODE>schmooz</CODE>, which is +used to process files. Files containing schmooz documentation should +not contain <CODE>(require 'schmooz)</CODE>. +</P> +<P> + +<A NAME="IDX472"></A> +</P> +<DL> +<DT><U>Procedure:</U> <B>schmooz</B> <I>filename.scm <small>...</small></I> +<DD><VAR>Filename</VAR>.scm should be a string ending with `<SAMP>.scm</SAMP>' naming an +existing file containing Scheme source code. <CODE>schmooz</CODE> extracts +top-level comments containing schmooz commands from <VAR>filename</VAR>.scm +and writes the converted Texinfo source to a file named +<VAR>filename</VAR>.txi. +<P> + +<A NAME="IDX473"></A> +<DT><U>Procedure:</U> <B>schmooz</B> <I>filename.texi <small>...</small></I> +<DD><A NAME="IDX474"></A> +<DT><U>Procedure:</U> <B>schmooz</B> <I>filename.tex <small>...</small></I> +<DD><A NAME="IDX475"></A> +<DT><U>Procedure:</U> <B>schmooz</B> <I>filename.txi <small>...</small></I> +<DD><VAR>Filename</VAR> should be a string naming an existing file containing +Texinfo source code. For every occurrence of the string `<SAMP>@include +<VAR>filename</VAR>.txi</SAMP>' within that file, <CODE>schmooz</CODE> calls itself with +the argument `<SAMP><VAR>filename</VAR>.scm</SAMP>'. +</P> +</DL> +<P> + +Schmooz comments are distinguished (from non-schmooz comments) by their +first line, which must start with an at-sign (@) preceded by one or +more semicolons (<TT>;</TT>). A schmooz comment ends at the first subsequent +line which does <EM>not</EM> start with a semicolon. Currently schmooz +comments are recognized only at top level. +</P> +<P> + +Schmooz comments are copied to the Texinfo output file with the leading +contiguous semicolons removed. Certain character sequences starting +with at-sign are treated specially. Others are copied unchanged. +</P> +<P> + +A schmooz comment starting with `<SAMP>@body</SAMP>' must be followed by a +Scheme definition. All comments between the `<SAMP>@body</SAMP>' line and +the definition will be included in a Texinfo definition, either +a `<SAMP>@defun</SAMP>' or a `<SAMP>@defvar</SAMP>', depending on whether a procedure +or a variable is being defined. +</P> +<P> + +Within the text of that schmooz comment, at-sign +followed by `<SAMP>0</SAMP>' will be replaced by <CODE>@code{procedure-name}</CODE> +if the following definition is of a procedure; or +<CODE>@var{variable}</CODE> if defining a variable. +</P> +<P> + +An at-sign followed by a non-zero digit will expand to the variable +citation of that numbered argument: `<SAMP>@var{argument-name}</SAMP>'. +</P> +<P> + +If more than one definition follows a `<SAMP>@body</SAMP>' comment line +without an intervening blank or comment line, then those definitions +will be included in the same Texinfo definition using `<SAMP>@defvarx</SAMP>' +or `<SAMP>@defunx</SAMP>', depending on whether the first definition is of +a variable or of a procedure. +</P> +<P> + +Schmooz can figure out whether a definition is of a procedure if +it is of the form: +</P> +<P> + +`<SAMP>(define (<identifier> <arg> ...) <expression>)</SAMP>' +</P> +<P> + +or if the left hand side of the definition is some form ending in +a lambda expression. Obviously, it can be fooled. In order to +force recognition of a procedure definition, start the documentation +with `<SAMP>@args</SAMP>' instead of `<SAMP>@body</SAMP>'. `<SAMP>@args</SAMP>' should +be followed by the argument list of the function being defined, +which may be enclosed in parentheses and delimited by whitespace, +(as in Scheme), enclosed in braces and separated by commas, (as +in Texinfo), or consist of the remainder of the line, separated +by whitespace. +</P> +<P> + +For example: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>;;@args arg1 args ... +;;@0 takes argument @1 and any number of @2 +(define myfun (some-function-returning-magic)) +</pre></td></tr></table><P> + +Will result in: +</P> +<P> + +<TABLE><tr><td> </td><td class=example><pre>@defun myfun arg1 args @dots{} + +@code{myfun} takes argument @var{arg1} and any number of @var{args} +@end defun +</pre></td></tr></table><P> + +`<SAMP>@args</SAMP>' may also be useful for indicating optional arguments +by name. If `<SAMP>@args</SAMP>' occurs inside a schmooz comment section, +rather than at the beginning, then it will generate a `<SAMP>@defunx</SAMP>' +line with the arguments supplied. +</P> +<P> + +If the first at-sign in a schmooz comment is immediately followed by +whitespace, then the comment will be expanded to whatever follows that +whitespace. If the at-sign is followed by a non-whitespace character +then the at-sign will be included as the first character of the expansion. +This feature is intended to make it easy to include Texinfo directives +in schmooz comments. +</P> +<P> + +<A NAME="Mathematical Packages"></A> +<HR SIZE="6"> +<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> +<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_4.html#SEC45"> << </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_5.html#SEC88"> >> </A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib.html#SEC_Top">Top</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_toc.html#SEC_Contents">Contents</A>]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> +<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="slib_abt.html#SEC_About"> ? </A>]</TD> +</TR></TABLE> +<BR> +<FONT SIZE="-1"> +This document was generated +by <I>Steve Langasek</I> on <I>January, 10 2005</I> +using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A> +</FONT> + +</BODY> +</HTML> |