% Copyright (c) 1996 by Lele Gaifax.  All Rights Reserved
%
% This file is part of the PyObjC package.
%
% $RCSfile: libObjCStreams.tex,v $
% $Revision: 1.1.1.2 $
% $Date: 1996/10/23 17:20:17 $
%
% Created Mon Oct  7 18:03:53 1996.
%

\section{Built-in Module \sectcode{ObjCStreams}}
\bimodindex{ObjCStreams}
\renewcommand{\indexsubitem}{(in module ObjCStreams)}

The \code{ObjCStreams} module gets automatically imported whenever you
import the ObjC module, and it's available as its \var{.streams}
member. It encapsulates the underlying Objective-C streams facility
into a Python class, \code{ObjCStream}: under NeXTSTEP it is built
around the native \code{NXStream} library, while under GNUStep and
OpenStep it actually uses a subclass of \code{NSData}.

The module provides the following methods:

\begin{funcdesc}{openfile}{filename \optional{, mode}}
Opens the given \var{filename} as a stream, and returns it. \var{mode}
may be one of \code{.READONLY}, \code{.WRITEONLY}, \code{.READWRITE}
or \code{.APPEND}.
\end{funcdesc}

\begin{funcdesc}{openmemory}{string \optional{, mode}}
Opens a \dfn{memory stream} and returns it. If \var{mode} is
\code{.READONLY}, \var{string} must be a string object, which will be
used as the data source of the stream. If \var{mode} is
\code{.WRITEONLY}, the argument \var{string} must be \code{None}.
\end{funcdesc}

\begin{funcdesc}{openport}{machport \optional{, mode}}
Opens a MACH port as a stream and returns it.
\end{funcdesc}

The module has these data members:

\begin{datadesc}{READONLY}
This constant is used to open a stream in read-only mode.
\end{datadesc}

\begin{datadesc}{WRITEONLY}
This constant is used to open a stream in write-only mode.
\end{datadesc}

\begin{datadesc}{READWRITE}
This constant is used to open a stream in read-write mode.
\end{datadesc}

\begin{datadesc}{APPEND}
This constant is used to open a stream in read-write mode moving the
stream position at the end.
\end{datadesc}

\begin{datadesc}{FROMSTART}
This constant, used by the \code{seek()} method, specify that the
displacement is relative to the start of the stream.
\end{datadesc}

\begin{datadesc}{FROMEND}
This constant, used by the \code{seek()} method, specify that the
displacement is relative to the end of the stream.
\end{datadesc}

\begin{datadesc}{FROMCURRENT}
This constant, used by the \code{seek()} method, specify that the
displacement is relative to the current position of the stream.
\end{datadesc}


\subsection{ObjCStreams objects}
\renewcommand{\indexsubitem}{(ObjCStreams method)}

This is a file-like object, and it responds to these methods:

\begin{funcdesc}{close}{}
Closes the associated stream. A closed stream cannot be read or
written anymore.
\end{funcdesc}

\begin{funcdesc}{flush}{}
Flushes the associated stream's buffer.
\end{funcdesc}

\begin{funcdesc}{read}{\optional{size}}
Read at most \var{size} bytes from the stream (less if the read hits
\EOF{} or no more data is immediately available on a pipe, tty or
similar device).  If the \var{size} argument is negative or omitted,
read all data until \EOF{} is reached.  The bytes are returned as a
string object.  An empty string is returned when \EOF{} is
encountered immediately.
\end{funcdesc}

\begin{funcdesc}{readline}{\optional{num}}
Read one entire line from the stream.  A trailing newline character is
kept in the string (but may be absent when a file ends with an
incomplete line).  If the \var{size} argument is present and
non-negative, it is a maximum byte count (including the trailing
newline) and an incomplete line may be returned. If it's negative, the
trailing newlines are stripped. An empty string is returned when
\EOF{} is hit immediately.
\end{funcdesc}

\begin{funcdesc}{readlines}{}
Read until \EOF{} using \code{readline()} and return a list containing
the lines thus read. 
\end{funcdesc}

\begin{funcdesc}{seek}{offset \optional{, from}}
Set the stream's current position. The \var{from} argument is optional
and defaults to \code{FROMSTART} (absolute file positioning); other
values are \code{FROMCURRENT} (seek relative to the current position) and
\code{FROMEND} (seek relative to the file's end). There is no return value.
\end{funcdesc}

\begin{funcdesc}{tell}{}
Returns the current position in stream.
\end{funcdesc}

\begin{funcdesc}{write}{text}
Writes \var{text}, a string object, on the stream. There is no return
value.  Note: due to buffering, the string may not actually show up in
the file until the \code{flush()} or \code{close()} method is called.
\end{funcdesc}

\begin{funcdesc}{writelines}{list-of-strings}
Writes \var{list-of-strings} on the stream. There is no return value.
(The name is intended to match \code{readlines}; \code{writelines}
does not add line separators.)
\end{funcdesc}

\begin{funcdesc}{savetofile}{filename}
Writes the content of the stream in a file named \var{filename}.
\end{funcdesc}

%
% Local Variables:
% change-log-default-name:"../ChangeLog.PyObjC"
% End:
%
