% This file is part of Oaklisp.
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% The GNU GPL is available at http://www.gnu.org/licenses/gpl.html
% or from the Free Software Foundation, 59 Temple Place - Suite 330,
% Boston, MA 02111-1307, USA


\chapter{Input and Output}

\section{Streams and Files}

Streams are the tokens through which interaction with the outside
world occurs.  Although streams are primarily used for reading and
writing to files, they have found a number of internal uses.

\ty{stream}
\doc{The supertype of all streams.}

\ty{input-stream}
\doc{This is an abstract type.  Instantiable subtypes must define
methods for the \df{really-read-char} operation.}

\op{read-char}{input-stream}
\doc{Return a character, or \df{the-eof-token} if we've already read
the last character in the stream.}

\op{unread-char}{input-stream character}
\doc{Puts \emph{character} back into \emph{input-stream}.  One can only
put one character back, and it must be the last character read.}

\op{peek-char}{input-stream}
\doc{Equivalent to \texttt{(let ((c (read-char \emph{input-stream})))
(unread-char \emph{input-stream} c) c)}.}

\ob{the-eof-token}
\doc{This distinguished object is returned to indicate that one has
read past the end of the file.}


\ty{output-stream}
\doc{This is an abstract type.  Instantiable subtypes must define
methods for the \df{write-char} operation.}

\op{write-char}{output-stream character}

\op{newline}{output-stream}
\doc{Outputs a carriage return to \emph{output-stream}.}
\op{freshline}{output-stream}
\doc{Ensures that \emph{output-stream} is at the beginning of a line.}

\op{flush}{output-stream}
\doc{Flushes any buffered output.}

\op{interactive?}{stream}
\doc{Returns true if and only if \emph{stream} is connected to the
user.  This is used to check if an end of file condition on the
control stream is really an end of file or if the user just typed
control-D.}

\so{position}{stream}
\doc{Returns the position we are at within \emph{stream}.  By setting
this, one can get back to a previous position.}

\op{write-string}{string output-stream}
\doc{Writes the characters of \emph{string} to \emph{stream}.}

\mc{with-open-file}{\lpar variable filename \dt options\rpar \dt body}
\doc{Binds \emph{variable} to a stream which is connected to the file
with the name \emph{filename}.  \emph{Options} is not evaluated, and
describes how \emph{filename} should be opened.  Possible symbols
include \df{in} for input, \df{out} for output, and \df{append} for
output with position set to the end of the file.  The \df{ugly} option
can be added to either \df{out} or \df{append} if the user doesn't
mind poor formating, as in files meant to be read only by other
programs.  The opened stream will be closed when the
\df{with-open-file} is exited, even upon abnormal exit.  \textbf{Note:}
the stream is not reopened upon abnormal entry, but this may be
changed in future versions of the system.}

\mc{with-input-from-string}{\lpar variable sequence\rpar \dt body}
\doc{Binds \emph{variable} to an input stream whose contents are the
characters of \emph{sequence}.  Although \emph{sequence} is usually a
string, this will work correctly for any sequence type.}

\makin{string-output-stream}{}
\doc{These save all their output and return it as a string in response
to the \dfcoer{string} operation.}



\section{Reading}

Oaklisp has an industrial strength reader, replete with nonterminating
macro characters and descriptive error messages.  List syntax is not
described below; read some other lisp manual.  Our reader is modeled
after the Common Lisp reader, so we emphasize differences with the
Common Lisp reader below.

\op{read}{input-stream}
\doc{Returns a lisp object read from \emph{stream}.  This is sensitive
to a large number of factors detailed below.}

\ob{standard-read-table}
\doc{This holds the read table for usual lisp syntax.  The \df{nth}
operation can be used to get and set elements of read tables, which
are indexed by characters.  Potential entries are \df{whitespace},
\df{constituent}, \df{single-escape}, \df{illegal},
\emph{\lpar\df{terminating-macro} \dt operation\rpar}, and
\emph{\lpar\df{nonterminating-macro} \dt operation\rpar}.}

\op{skip-whitespace}{input-stream}
\doc{Reads characters from \emph{input-stream} until the next character
is not whitespace.}

The reader is not sensitive to the case of macro characters.

\op{define-macro-char}{character operation}
\doc{Defines \emph{character} to be a reader macro in
\df{standard-read-table}.  When \emph{character} is encountered by the
reader, \emph{operation} is called with two arguments, the stream and
the character that was read.}

\op{define-nonterminating-macro-char}{character operation}
\doc{Just like \df{define-macro-char} except that the macro is not
triggered if \emph{character} is read inside a token.}

There are a number of ``quotelike'' macro characters present for the
convenience of the user.

\begin{center}
\begin{tabular}{cl}
\emph{macro character} & \emph{symbol} \\\hline
\texttt{'} & \df{quote} \\
\texttt{`} & \df{quasiquote} \\
\texttt{control-v} & \df{fluid} \\
\texttt{control-y} & \df{coercer} \\
\texttt{,@} & \df{unquote-splicing} \\
\texttt{,} & \df{unquote}
\end{tabular}
\end{center}

\op{define-quotelike-macro-char}{character object}
\begin{docenv}
Makes \emph{character} a terminating macro which returns a list of
\emph{object} and the next thing read.  This also arranges for the printer
to print using analogous syntax.  For instance, the quote syntax is
defined with the line \texttt{(define-quotelike-macro-char
\texttt{\#'} 'quote)} in the system internals.
\end{docenv}

\ob{the-unread-object}
\doc{When a reader macro returns this, the reader takes it to mean
that nothing at all was read.  For instance, the reader macro for
\texttt{;} reads the remainder of the line and returns this.}

The character \texttt{[} is used to read lists in the same way that
\texttt{(} is, except that \texttt{[} must be matched by a \texttt{]}.
This is mostly for compatiblity with code written at the University of
Indiana.

Since there are no packages in Oaklisp, the \texttt{:} character is
treated like any other constituent.

Most of the Common Lisp hash reader macros are supported.  For
instance, the character object representing \texttt{a} is read
\texttt{\#$\backslash$a}.  Many special characters have long names, such as
\texttt{\#$\backslash$space}.

\op{define-hash-macro-char}{character operation}
\doc{Defines \emph{character} to be a hash reader macro character.
\emph{Operation} should take three arguments: a stream, the character,
and the numeric argument that was between the hash and the character,
\df{\#f} if none was passed.}

There are many hash reader macro characters, including \df{\#o},
\df{\#x}, \df{\#d}, \df{\#b} and \df{\#c} for octal, hexidecimal,
decimal, binary and complex numbers, respectively.  The syntax
\texttt{\#\emph{n}r\emph{xxx}} is used to read \emph{xxx} in base \emph{n}.
\texttt{\#(\ldots)} is used for reading vectors.  The \texttt{\#|} macro
comments out text until a matching \texttt{|\#}, with proper nesting.
\texttt{\#;\emph{e}} comments out the s-expression \emph{e}. As
described in Section~\ref{sec:truths}, \df{\#t} and \df{\#f} are read
as the canonical true and false values, respectively.

The \texttt{\#[symbol "\ldots"]} syntax can be used to read arbitrary
characters, although the \texttt{|$\ldots$|} construction is prefered.
Analogous constructors can be added with the settable operation
\df{hash-bracket-option}.

\fv{input-base}
\doc{The radix in which numbers will be read.}

\fv{features}
\doc{A list of ``features'' present in the current implementation,
used by the \df{\#+} and \df{\#-} reader macros.  Testable and
settable with the \df{feature?} settable operation.  It is guaranteed
that the \df{oaklisp} and \df{scheme} features will be present in any
implementation of Oaklisp.}

\fv{current-locale}
\doc{The \df{\#.} macro evaluates its argument in this locale.}

\fv{read-suppress}
\doc{This is true when what is being read will just be ignored, and
indicates to the reader that it shouldn't go to the trouble of
interpreting the meaning of complex tokens or anything like that.}



\section{Printing}

The printer is pretty heavy duty, but has no facilities for printing
circular objects.

\op{format}{stream control-string \dt args}
\doc{This is very similar to the Common Lisp \df{format} function, and
is the usual way for users to print things.

\emph{Stream} is permitted to be \df{\#t} to indicate that output
should be sent to the standard output, and \df{\#f} to indicate that
the output should be bundled up into a string and returned.

Characters in {control-string} are printed directly, except for the
\texttt{\~} character which indicates that some action should be taken.
The \texttt{\~} may be followed by a number or by a \texttt{:} or
\texttt{@}, which vary the action that would normally be taken in some
way.

Currently defined \texttt{\~} characters and their associated actions
are:

\begin{itemize}
\item[\texttt{A}] Print and argument with \dffl{print-escape} bound to
	\df{\#f}.

\item[\texttt{\~}] Print a \texttt{\~}.

\item[\texttt{\%}] Do a \df{newline}.

\item[\texttt{\&}] Do a \df{freshline}.

\item[\texttt{S}] Print an argument with \dffl{print-escape} bount to \df{\#t}.

\item[\texttt{B}] Print an argument in binary.

\item[\texttt{D}] Print an argument in decimal.

\item[\texttt{O}] Print an argument in octal.

\item[\texttt{X}] Print an argument in hex.

\item[\texttt{\emph{n}R}] Print an argument in base \emph{n}.

\item[\texttt{C}] Print an argument which is a character.

\item[\texttt{P}] Print an \texttt{s} if the argument is not 1.

\item[\texttt{!}] Print a weak pointer to the argument, preceded by an
expression which evaluates to the argument if \dffl{fancy-references}
is on.  This is used to print unique id's for objects without nice
printed representations, like operations.

\end{itemize}

A tilde followed by a newline is ignored; this construct is used for
making \emph{control-string} more readable by breaking it across lines.}


\op{print}{object stream}
\doc{Writes a representation of \emph{object} to \emph{stream}.  Users
are encouraged to add informative print methods for types they define.}

\op{define-simple-print-method}{type string}
\doc{Instructs the printer to include \emph{string} in the printed
representation of instances of \emph{type}.}

\fv{print-radix}
\doc{The radix in which numbers will be printed.  The default is ten.}

\fv{print-level}
\doc{The number of levels of list structure to be printed before the
printer abbreviates.  The default is \df{\#f}, meaning never abbreviate.}

\fv{print-length}
\doc{The number of elements of a list to be printed before the printer
abbreviates.  The default is \df{\#f}, meaning never abbreviate.}

\fv{print-escape}
\doc{This controls whether the printer tries to print things that are
easy for people to read, or ones that can be read back in to Oaklisp.
The default is \df{\#t}, meaning to maintain print/read consistency at
the expense of readability.}

\fv{symbol-slashification-style}
\doc{This controls the style of printing of symbols when they are
escaped.  See the implementation manual for details.}

\fv{fraction-display-style}
\doc{This can be either \df{normal}, \df{fancy} or \df{float}.  In
these cases, \texttt{(/ -5 3)} would print as either \texttt{-5/3},
\texttt{-1$\cdot$2/3} or \texttt{-1.6666666666}, respectively.}