diff options
Diffstat (limited to 'devdocs/elisp/input-streams.html')
| -rw-r--r-- | devdocs/elisp/input-streams.html | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/devdocs/elisp/input-streams.html b/devdocs/elisp/input-streams.html new file mode 100644 index 00000000..1c4c11c6 --- /dev/null +++ b/devdocs/elisp/input-streams.html @@ -0,0 +1,76 @@ + <h3 class="section">Input Streams</h3> <p>Most of the Lisp functions for reading text take an <em>input stream</em> as an argument. The input stream specifies where or how to get the characters of the text to be read. Here are the possible types of input stream: </p> <dl compact> <dt><var>buffer</var></dt> <dd> + <p>The input characters are read from <var>buffer</var>, starting with the character directly after point. Point advances as characters are read. </p> </dd> <dt><var>marker</var></dt> <dd> + <p>The input characters are read from the buffer that <var>marker</var> is in, starting with the character directly after the marker. The marker position advances as characters are read. The value of point in the buffer has no effect when the stream is a marker. </p> </dd> <dt><var>string</var></dt> <dd> + <p>The input characters are taken from <var>string</var>, starting at the first character in the string and using as many characters as required. </p> </dd> <dt><var>function</var></dt> <dd> + <p>The input characters are generated by <var>function</var>, which must support two kinds of calls: </p> <ul> <li> When it is called with no arguments, it should return the next character. </li> +<li> When it is called with one argument (always a character), <var>function</var> should save the argument and arrange to return it on the next call. This is called <em>unreading</em> the character; it happens when the Lisp reader reads one character too many and wants to put it back where it came from. In this case, it makes no difference what value <var>function</var> returns. </li> +</ul> </dd> <dt><code>t</code></dt> <dd> + <p><code>t</code> used as a stream means that the input is read from the minibuffer. In fact, the minibuffer is invoked once and the text given by the user is made into a string that is then used as the input stream. If Emacs is running in batch mode (see <a href="batch-mode">Batch Mode</a>), standard input is used instead of the minibuffer. For example, </p> +<div class="example"> <pre class="example">(message "%s" (read t)) +</pre> +</div> <p>will in batch mode read a Lisp expression from standard input and print the result to standard output. </p> </dd> <dt><code>nil</code></dt> <dd> + <p><code>nil</code> supplied as an input stream means to use the value of <code>standard-input</code> instead; that value is the <em>default input stream</em>, and must be a non-<code>nil</code> input stream. </p> </dd> <dt><var>symbol</var></dt> <dd><p>A symbol as input stream is equivalent to the symbol’s function definition (if any). </p></dd> </dl> <p>Here is an example of reading from a stream that is a buffer, showing where point is located before and after: </p> <div class="example"> <pre class="example">---------- Buffer: foo ---------- +This∗ is the contents of foo. +---------- Buffer: foo ---------- +</pre> + +<pre class="example">(read (get-buffer "foo")) + ⇒ is +</pre> +<pre class="example">(read (get-buffer "foo")) + ⇒ the +</pre> + +<pre class="example">---------- Buffer: foo ---------- +This is the∗ contents of foo. +---------- Buffer: foo ---------- +</pre> +</div> <p>Note that the first read skips a space. Reading skips any amount of whitespace preceding the significant text. </p> <p>Here is an example of reading from a stream that is a marker, initially positioned at the beginning of the buffer shown. The value read is the symbol <code>This</code>. </p> <div class="example"> <pre class="example"> + +---------- Buffer: foo ---------- +This is the contents of foo. +---------- Buffer: foo ---------- +</pre> + +<pre class="example">(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) + ⇒ #<marker at 1 in foo> +</pre> +<pre class="example">(read m) + ⇒ This +</pre> +<pre class="example">m + ⇒ #<marker at 5 in foo> ;; <span class="roman">Before the first space.</span> +</pre> +</div> <p>Here we read from the contents of a string: </p> <div class="example"> <pre class="example">(read "(When in) the course") + ⇒ (When in) +</pre> +</div> <p>The following example reads from the minibuffer. The prompt is: ‘<samp>Lisp expression: </samp>’. (That is always the prompt used when you read from the stream <code>t</code>.) The user’s input is shown following the prompt. </p> <div class="example"> <pre class="example">(read t) + ⇒ 23 +---------- Buffer: Minibuffer ---------- +Lisp expression: <kbd>23 <span class="key">RET</span></kbd> +---------- Buffer: Minibuffer ---------- +</pre> +</div> <p>Finally, here is an example of a stream that is a function, named <code>useless-stream</code>. Before we use the stream, we initialize the variable <code>useless-list</code> to a list of characters. Then each call to the function <code>useless-stream</code> obtains the next character in the list or unreads a character by adding it to the front of the list. </p> <div class="example"> <pre class="example">(setq useless-list (append "XY()" nil)) + ⇒ (88 89 40 41) +</pre> + +<pre class="example">(defun useless-stream (&optional unread) + (if unread + (setq useless-list (cons unread useless-list)) + (prog1 (car useless-list) + (setq useless-list (cdr useless-list))))) + ⇒ useless-stream +</pre> +</div> <p>Now we read using the stream thus constructed: </p> <div class="example"> <pre class="example">(read 'useless-stream) + ⇒ XY +</pre> + +<pre class="example">useless-list + ⇒ (40 41) +</pre> +</div> <p>Note that the open and close parentheses remain in the list. The Lisp reader encountered the open parenthesis, decided that it ended the input, and unread it. Another attempt to read from the stream at this point would read ‘<samp>()</samp>’ and return <code>nil</code>. </p><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Input-Streams.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Input-Streams.html</a> + </p> +</div> |