Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

Diff of /io.xmlf [f587e9] .. [9e7c20] Maximize Restore

  Switch to unified view

a/io.xmlf b/io.xmlf
1
<?xml version="1.0" encoding="utf-8"?>
1
<?xml version="1.0"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd">
2
<!DOCTYPE book [
2
<book lang="en">
3
<!ENTITY % eclent SYSTEM "ecl.ent">
4
%eclent;
5
]>
6
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
7
<chapter xml:id="Input-and-output">
3
<chapter id="Input-and-output">
8
<title>Input and Output</title>
4
<title>Input and Output</title>
9
<section xml:id="Read-macros">
5
<section id="Read-macros">
10
<title>Read macros</title>
6
<title>Read macros</title>
11
<variablelist>
7
<variablelist>
12
<varlistentry>
8
<varlistentry>
13
<term>#P"</term>
9
<term>#P"</term>
14
<listitem>
10
<listitem>
...
...
36
<para>Otherwise, the effect of using '<literal>#,</literal>' is unpredictable.  Note that, when
32
<para>Otherwise, the effect of using '<literal>#,</literal>' is unpredictable.  Note that, when
37
interpreted code is loaded, '<literal>#,</literal>' has the same effect as the <literal>#</literal>
33
interpreted code is loaded, '<literal>#,</literal>' has the same effect as the <literal>#</literal>
38
macro '<literal>#.</literal>'.</para>
34
macro '<literal>#.</literal>'.</para>
39
</section>
35
</section>
40
36
41
<section xml:id="Input-Output-functions">
37
<section id="Input-Output-functions">
42
<title>Input and Output Functions</title>
38
<title>Input and Output Functions</title>
43
<para>The input and output functions of &ECL; almost follow the definitions in
39
<para>The input and output functions of &ECL; almost follow the definitions in
44
Chapter 22 of &Steele84;.  Most of the differences come from the fact
40
Chapter 22 of &Steele84;.  Most of the differences come from the fact
45
that, in &ECL;, input from the terminal is always in line mode and binary I/O
41
that, in &ECL;, input from the terminal is always in line mode and binary I/O
46
is not supported.</para>
42
is not supported.</para>
...
...
49
underlying operating system.  In particular, when a disk file is assigned to
45
underlying operating system.  In particular, when a disk file is assigned to
50
the standard output, nothing will be echoed at the terminal.</para>
46
the standard output, nothing will be echoed at the terminal.</para>
51
<para>Those functions that deviate from the definitions in &Steele84; are
47
<para>Those functions that deviate from the definitions in &Steele84; are
52
listed below.</para>
48
listed below.</para>
53
<blockquote>
49
<blockquote>
54
<screen><indexterm role="fn"><primary>load</primary></indexterm>&#151; Function: <function>load</function> <varname>pathname &amp;key :print :verbose :if-does-not-exist</varname></screen>
50
<screen><indexterm role="fn"><primary>load</primary></indexterm>&mdash; Function: <function>load</function> <varname>pathname &amp;key :print :verbose :if-does-not-exist</varname></screen>
55
<para>If <replaceable>pathname</replaceable> does not specify the filetype of the input file, then load
51
<para>If <replaceable>pathname</replaceable> does not specify the filetype of the input file, then load
56
uses the association list <replaceable>si::*load-search-list*</replaceable> to find out a suitable
52
uses the association list <replaceable>si::*load-search-list*</replaceable> to find out a suitable
57
filetype and the function to load it. Typically, this search list is made of
53
filetype and the function to load it. Typically, this search list is made of
58
the elements <literal>.fas</literal>, <literal>.lsp</literal> and <literal>.lisp</literal>, in this order. If
54
the elements <literal>.fas</literal>, <literal>.lsp</literal> and <literal>.lisp</literal>, in this order. If
59
everything fails, a file without filetype will be loaded.</para>
55
everything fails, a file without filetype will be loaded.</para>
60
</blockquote>
56
</blockquote>
61
<blockquote>
57
<blockquote>
62
<screen><indexterm role="fn"><primary>open</primary></indexterm>&#151; Function: <function>open</function> <varname></varname></screen>
58
<screen><indexterm role="fn"><primary>open</primary></indexterm>&mdash; Function: <function>open</function> <varname></varname></screen>
63
<para>Streams can only have element type <literal>base-char</literal>, <literal>(signed-byte 8)</literal>
59
<para>Streams can only have element type <literal>base-char</literal>, <literal>(signed-byte 8)</literal>
64
and <literal>(unsigned-byte 8)</literal>. The <literal>:external-format</literal> is always <literal>:default</literal>.</para>
60
and <literal>(unsigned-byte 8)</literal>. The <literal>:external-format</literal> is always <literal>:default</literal>.</para>
65
</blockquote>
61
</blockquote>
66
<blockquote>
62
<blockquote>
67
<screen><indexterm role="fn"><primary>close</primary></indexterm>&#151; Function: <function>close</function> <varname></varname></screen>
63
<screen><indexterm role="fn"><primary>close</primary></indexterm>&mdash; Function: <function>close</function> <varname></varname></screen>
68
<para>The keyword variable <replaceable>:abort</replaceable> is always ignored.</para>
64
<para>The keyword variable <replaceable>:abort</replaceable> is always ignored.</para>
69
</blockquote>
65
</blockquote>
70
<blockquote>
66
<blockquote>
71
<screen><indexterm role="fn"><primary>listen</primary></indexterm>&#151; Function: <function>listen</function> <varname></varname></screen>
67
<screen><indexterm role="fn"><primary>listen</primary></indexterm>&mdash; Function: <function>listen</function> <varname></varname></screen>
72
<para>This routine requires some low level functions which are not available on
68
<para>This routine requires some low level functions which are not available on
73
all platforms (For instance on <literal>Windows</literal>). When ECL is not able to
69
all platforms (For instance on <literal>Windows</literal>). When ECL is not able to
74
determine whether a stream is interactive, <literal>listen</literal> returns true unless
70
determine whether a stream is interactive, <literal>listen</literal> returns true unless
75
an end of file has been previously detected.</para>
71
an end of file has been previously detected.</para>
76
</blockquote>
72
</blockquote>
77
<blockquote>
73
<blockquote>
78
<screen><indexterm role="fn"><primary>clear-input</primary></indexterm>&#151; Function: <function>clear-input</function> <varname></varname></screen>
74
<screen><indexterm role="fn"><primary>clear-input</primary></indexterm>&mdash; Function: <function>clear-input</function> <varname></varname></screen>
79
<para>The functions <literal>clear-input</literal> and <literal>clear-output</literal> do nothing.</para>
75
<para>The functions <literal>clear-input</literal> and <literal>clear-output</literal> do nothing.</para>
80
</blockquote>
76
</blockquote>
81
<blockquote>
77
<blockquote>
82
<screen><indexterm role="fn"><primary>read-char-no-hang</primary></indexterm>&#151; Function: <function>read-char-no-hang</function> <varname></varname></screen>
78
<screen><indexterm role="fn"><primary>read-char-no-hang</primary></indexterm>&mdash; Function: <function>read-char-no-hang</function> <varname></varname></screen>
83
<para><literal>read-char-no-hang</literal> is equivalent to <literal>read-char</literal>.</para>
79
<para><literal>read-char-no-hang</literal> is equivalent to <literal>read-char</literal>.</para>
84
</blockquote>
80
</blockquote>
85
<para>The functions <literal>princ</literal>, <literal>write-char</literal> and <literal>write-byte</literal> do not
81
<para>The functions <literal>princ</literal>, <literal>write-char</literal> and <literal>write-byte</literal> do not
86
always flush the stream.  The stream is flushed when</para>
82
always flush the stream.  The stream is flushed when</para>
87
<orderedlist numeration="arabic">
83
<orderedlist numeration="arabic">
...
...
93
functions operate on <literal>*terminal-io*</literal></para>
89
functions operate on <literal>*terminal-io*</literal></para>
94
</listitem>
90
</listitem>
95
</orderedlist>
91
</orderedlist>
96
</section>
92
</section>
97
93
98
<section xml:id="Network-streams">
94
<section id="Network-streams">
99
<title>Network Streams</title>
95
<title>Network Streams</title>
100
<para>With a configuration option, the following function is available which opens
96
<para>With a configuration option, the following function is available which opens
101
streams across network connections.</para>
97
streams across network connections.</para>
102
<blockquote>
98
<blockquote>
103
<screen><indexterm role="fn"><primary>open-client-stream</primary></indexterm>&#151; Function: <function>open-client-stream</function> <varname>host port</varname></screen>
99
<screen><indexterm role="fn"><primary>open-client-stream</primary></indexterm>&mdash; Function: <function>open-client-stream</function> <varname>host port</varname></screen>
104
<para>The string <replaceable>host</replaceable> indicates the name of the host, while <replaceable>port</replaceable> is an
100
<para>The string <replaceable>host</replaceable> indicates the name of the host, while <replaceable>port</replaceable> is an
105
integer which identifies the port number to which to connect.  This function
101
integer which identifies the port number to which to connect.  This function
106
returns a two-way stream which can be used in any of the stream operations.</para>
102
returns a two-way stream which can be used in any of the stream operations.</para>
107
</blockquote>
103
</blockquote>
108
<blockquote>
104
<blockquote>
109
<screen><indexterm role="fn"><primary>open-server-stream</primary></indexterm>&#151; Function: <function>open-server-stream</function> <varname>host port</varname></screen>
105
<screen><indexterm role="fn"><primary>open-server-stream</primary></indexterm>&mdash; Function: <function>open-server-stream</function> <varname>host port</varname></screen>
110
<para>A stream connected to port number <replaceable>port</replaceable> is created to which clients can
106
<para>A stream connected to port number <replaceable>port</replaceable> is created to which clients can
111
connect.  This function returns a two-way stream which can be used in any of
107
connect.  This function returns a two-way stream which can be used in any of
112
the stream operations.</para>
108
the stream operations.</para>
113
</blockquote>
109
</blockquote>
114
</section>
110
</section>
115
111
116
<section xml:id="CLOS-streams">
112
<section id="CLOS-streams">
117
<title>CLOS Streams</title>
113
<title>CLOS Streams</title>
118
<para>When the optional CLOS subsystem is available, an interface is provided by
114
<para>When the optional CLOS subsystem is available, an interface is provided by
119
&ECL; for using CLOS objects as Common-Lisp input/output character streams.
115
&ECL; for using CLOS objects as Common-Lisp input/output character streams.
120
Such support can be used for instance to build interactive character streams,
116
Such support can be used for instance to build interactive character streams,
121
which may be used by applications as the stream argument for Common-Lisp I/O
117
which may be used by applications as the stream argument for Common-Lisp I/O
...
...
127
<para>The following functions are automatically invoked by &ECL; when a stream
123
<para>The following functions are automatically invoked by &ECL; when a stream
128
operation involves a CLOS object as a stream parameter. The programmer should
124
operation involves a CLOS object as a stream parameter. The programmer should
129
define these methods for any class of objects which are to be used for
125
define these methods for any class of objects which are to be used for
130
character input/output.</para>
126
character input/output.</para>
131
127
132
<section xml:id="CLOS-Stream-Input">
128
<section id="CLOS-Stream-Input">
133
<title>CLOS Stream Input</title>
129
<title>CLOS Stream Input</title>
134
<para>Character input from an <literal>clos-stream</literal> is implemented by the
130
<para>Character input from an <literal>clos-stream</literal> is implemented by the
135
following methods.</para>
131
following methods.</para>
136
<blockquote>
132
<blockquote>
137
<screen><indexterm role="fn"><primary>stream-read-char</primary></indexterm>&#151; Method: <function>stream-read-char</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
133
<screen><indexterm role="fn"><primary>stream-read-char</primary></indexterm>&mdash; Method: <function>stream-read-char</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
138
<para>Returns the next character object read from the CLOS stream <replaceable>object</replaceable>.</para>
134
<para>Returns the next character object read from the CLOS stream <replaceable>object</replaceable>.</para>
139
</blockquote>
135
</blockquote>
140
<blockquote>
136
<blockquote>
141
<screen><indexterm role="fn"><primary>stream-unread-char</primary></indexterm>&#151; Method: <function>stream-unread-char</function> (<varname>object</varname> <varname>clos-stream</varname>) <varname>character</varname></screen>
137
<screen><indexterm role="fn"><primary>stream-unread-char</primary></indexterm>&mdash; Method: <function>stream-unread-char</function> (<varname>object</varname> <varname>clos-stream</varname>) <varname>character</varname></screen>
142
<para>Unreads the character object <replaceable>character</replaceable> from the CLOS stream <replaceable>object</replaceable>.
138
<para>Unreads the character object <replaceable>character</replaceable> from the CLOS stream <replaceable>object</replaceable>.
143
<replaceable>character</replaceable> will be the next character read by <literal>stream-read-char</literal>.</para>
139
<replaceable>character</replaceable> will be the next character read by <literal>stream-read-char</literal>.</para>
144
</blockquote>
140
</blockquote>
145
<blockquote>
141
<blockquote>
146
<screen><indexterm role="fn"><primary>stream-listen</primary></indexterm>&#151; Method: <function>stream-listen</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
142
<screen><indexterm role="fn"><primary>stream-listen</primary></indexterm>&mdash; Method: <function>stream-listen</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
147
<para>Returns () is no character is immediately available from the CLOS stream
143
<para>Returns () is no character is immediately available from the CLOS stream
148
<replaceable>object</replaceable>. Otherwise, the next character is returned, as if
144
<replaceable>object</replaceable>. Otherwise, the next character is returned, as if
149
<literal>stream-peek-char</literal> had been called.</para>
145
<literal>stream-peek-char</literal> had been called.</para>
150
</blockquote>
146
</blockquote>
151
<blockquote>
147
<blockquote>
152
<screen><indexterm role="fn"><primary>stream-clear-input</primary></indexterm>&#151; Method: <function>stream-clear-input</function> <varname>object</varname></screen>
148
<screen><indexterm role="fn"><primary>stream-clear-input</primary></indexterm>&mdash; Method: <function>stream-clear-input</function> <varname>object</varname></screen>
153
<para>Clears any buffered characters on the CLOS stream <replaceable>object</replaceable>. Returns ().</para>
149
<para>Clears any buffered characters on the CLOS stream <replaceable>object</replaceable>. Returns ().</para>
154
</blockquote>
150
</blockquote>
155
</section>
151
</section>
156
152
157
<section xml:id="CLOS-Stream-Output">
153
<section id="CLOS-Stream-Output">
158
<title>CLOS Stream Output</title>
154
<title>CLOS Stream Output</title>
159
<para>Character output from an <literal>clos-stream</literal> is implemented by the
155
<para>Character output from an <literal>clos-stream</literal> is implemented by the
160
following methods.</para>
156
following methods.</para>
161
<blockquote>
157
<blockquote>
162
<screen><indexterm role="fn"><primary>stream-write-char</primary></indexterm>&#151; Method: <function>stream-write-char</function> (<varname>object</varname> <varname>clos-stream</varname>) <varname>character</varname></screen>
158
<screen><indexterm role="fn"><primary>stream-write-char</primary></indexterm>&mdash; Method: <function>stream-write-char</function> (<varname>object</varname> <varname>clos-stream</varname>) <varname>character</varname></screen>
163
<para>Outputs the character <replaceable>character</replaceable> to the CLOS stream <replaceable>object</replaceable> and
159
<para>Outputs the character <replaceable>character</replaceable> to the CLOS stream <replaceable>object</replaceable> and
164
returns it.</para>
160
returns it.</para>
165
</blockquote>
161
</blockquote>
166
<blockquote>
162
<blockquote>
167
<screen><indexterm role="fn"><primary>stream-clear-output</primary></indexterm>&#151; Method: <function>stream-clear-output</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
163
<screen><indexterm role="fn"><primary>stream-clear-output</primary></indexterm>&mdash; Method: <function>stream-clear-output</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
168
<para>Aborts any outstanding output operation on the CLOS stream <replaceable>object</replaceable> and
164
<para>Aborts any outstanding output operation on the CLOS stream <replaceable>object</replaceable> and
169
returns ().</para>
165
returns ().</para>
170
</blockquote>
166
</blockquote>
171
<blockquote>
167
<blockquote>
172
<screen><indexterm role="fn"><primary>stream-force-output</primary></indexterm>&#151; Method: <function>stream-force-output</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
168
<screen><indexterm role="fn"><primary>stream-force-output</primary></indexterm>&mdash; Method: <function>stream-force-output</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
173
<para>Initiates the emptying of the internal buffers on the CLOS stream <replaceable>object</replaceable>
169
<para>Initiates the emptying of the internal buffers on the CLOS stream <replaceable>object</replaceable>
174
and returns ().</para>
170
and returns ().</para>
175
</blockquote>
171
</blockquote>
176
</section>
172
</section>
177
173
178
<section xml:id="CLOS-Stream-common">
174
<section id="CLOS-Stream-common">
179
<title>CLOS Stream common</title>
175
<title>CLOS Stream common</title>
180
<para>The following functions should be available for all CLOS streams.</para>
176
<para>The following functions should be available for all CLOS streams.</para>
181
<blockquote>
177
<blockquote>
182
<screen><indexterm role="fn"><primary>stream-interactive-p</primary></indexterm>&#151; Method: <function>stream-interactive-p</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
178
<screen><indexterm role="fn"><primary>stream-interactive-p</primary></indexterm>&mdash; Method: <function>stream-interactive-p</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
183
</blockquote>
179
</blockquote>
184
<blockquote>
180
<blockquote>
185
<screen><indexterm role="fn"><primary>stream-close</primary></indexterm>&#151; Method: <function>stream-close</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
181
<screen><indexterm role="fn"><primary>stream-close</primary></indexterm>&mdash; Method: <function>stream-close</function> (<varname>object</varname> <varname>clos-stream</varname>)</screen>
186
<para>Closes the stream for any further input or output.</para>
182
<para>Closes the stream for any further input or output.</para>
187
</blockquote>
183
</blockquote>
188
</section>
184
</section>
189
</section>
185
</section>
190
</chapter>
186
</chapter>