# HG changeset patch # User Richard M. Stallman # Date 763847599 0 # Node ID 52f4a94c8c3d701bc7a336cf72231d07ea048693 # Parent 510a3c16068afd8df75aec32cf9ad5e9e646e5cb Initial revision diff -r 510a3c16068a -r 52f4a94c8c3d lispref/help.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/help.texi Wed Mar 16 19:53:19 1994 +0000 @@ -0,0 +1,624 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/help +@node Documentation, Files, Modes, Top +@chapter Documentation +@cindex documentation strings + + GNU Emacs Lisp has convenient on-line help facilities, most of which +derive their information from the documentation strings associated with +functions and variables. This chapter describes how to write good +documentation strings for your Lisp programs, as well as how to write +programs to access documentation. + + Note that the documentation strings for Emacs are not the same thing +as the Emacs manual. Manuals have their own source files, written in +the Texinfo language; documentation strings are specified in the +definitions of the functions and variables they apply to. A collection +of documentation strings is not sufficient as a manual because a good +manual is not organized in that fashion; it is organized in terms of +topics of discussion. + +@menu +* Documentation Basics:: Good style for doc strings. + Where to put them. How Emacs stores them. +* Accessing Documentation:: How Lisp programs can access doc strings. +* Keys in Documentation:: Substituting current key bindings. +* Describing Characters:: Making printable descriptions of + non-printing characters and key sequences. +* Help Functions:: Subroutines used by Emacs help facilities. +@end menu + +@node Documentation Basics +@comment node-name, next, previous, up +@section Documentation Basics +@cindex documentation conventions +@cindex writing a documentation string +@cindex string, writing a doc string + + A documentation string is written using the Lisp syntax for strings, +with double-quote characters surrounding the text of the string. This +is because it really is a Lisp string object. The string serves as +documentation when it is written in the proper place in the definition +of a function or variable. In a function definition, the documentation +string follows the argument list. In a variable definition, the +documentation string follows the initial value of the variable. + + When you write a documentation string, make the first line a complete +sentence (or two complete sentences) since some commands, such as +@code{apropos}, show only the first line of a multi-line documentation +string. Also, you should not indent the second line of a documentation +string, if you have one, because that looks odd when you use @kbd{C-h f} +(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}). +@xref{Documentation Tips}. + + Documentation strings may contain several special substrings, which +stand for key bindings to be looked up in the current keymaps when the +documentation is displayed. This allows documentation strings to refer +to the keys for related commands and be accurate even when a user +rearranges the key bindings. (@xref{Accessing Documentation}.) + + Within the Lisp world, a documentation string is kept with the +function or variable that it describes: + +@itemize @bullet +@item +The documentation for a function is stored in the function definition +itself (@pxref{Lambda Expressions}). The function +@code{documentation} knows how to extract it. + +@item +@kindex variable-documentation +The documentation for a variable is stored in the variable's property +list under the property name @code{variable-documentation}. The +function @code{documentation-property} knows how to extract it. +@end itemize + +@cindex @file{DOC} (documentation) file +@cindex @file{emacs/etc/DOC-@var{version}} +@cindex @file{etc/DOC-@var{version}} +To save space, the documentation for preloaded functions and variables +(including primitive functions and autoloaded functions) are stored in +the file @file{emacs/etc/DOC-@var{version}}. The data structure inside +Emacs has an integer offset into the file, where the documentation +string ought to be. The functions @code{documentation} the +@code{documentation-property} read the documentation from the file +@file{emacs/etc/DOC-@var{version}} when they notice the integer there; +this is transparent to the user. Keeping the documentation strings out +of the Emacs core image saves a significant amount of space. +@xref{Building Emacs}. + + For information on the uses of documentation strings, see @ref{Help, , +Help, emacs, The GNU Emacs Manual}. + +@c Wordy to prevent overfull hbox. --rjc 15mar92 + The @file{emacs/etc} directory contains two utilities that you can use +to print nice-looking hardcopy for the file +@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and +@file{digest-doc.c}. + +@node Accessing Documentation +@section Access to Documentation Strings + +@defun documentation-property symbol property &optional verbatim +This function returns the documentation string that is recorded +@var{symbol}'s property list under property @var{property}. It +retrieves the text from the file @file{emacs/etc/DOC-@var{version}} if +necessary, and runs @code{substitute-command-keys} to substitute actual +key bindings. (This substitution is not done if @var{verbatim} is +non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.) + +@smallexample +@group +(documentation-property 'command-line-processed + 'variable-documentation) + @result{} "t once command line has been processed" +@end group +@group +(symbol-plist 'command-line-processed) + @result{} (variable-documentation 188902) +@end group +@end smallexample +@end defun + +@defun documentation function &optional verbatim +This function returns the documentation string of @var{function}. +This function will access the documentation string if it is stored in +the @file{emacs/etc/DOC-@var{version}} file. + +In addition, @code{documentation} runs @code{substitute-command-keys} +on the resulting string, so the value contains the actual (current) key +bindings. (This is not done if @var{verbatim} is non-@code{nil}; the +@var{verbatim} argument exists only as of Emacs 19.) + +The function @code{documentation} signals a @code{void-function} error +unless @var{function} has a function definition. However, it is ok if +the function definition has no documentation string. In that case, +@code{documentation} returns @code{nil}. +@end defun + +@c Wordy to prevent overfull hboxes. --rjc 15mar92 + Here is an example of using the two functions, @code{documentation} and +@code{documentation-property}, to display the documentation strings for +several symbols in a @samp{*Help*} buffer. + +@smallexample +@group +(defun describe-symbols (pattern) + "Describe the Emacs Lisp symbols matching PATTERN. +All symbols that have PATTERN in their name are described +in the `*Help*' buffer." + (interactive "sDescribe symbols matching: ") + (let ((describe-func + (function + (lambda (s) +@end group +@group + ;; @r{Print description of symbol.} + (if (fboundp s) ; @r{It is a function.} + (princ + (format "%s\t%s\n%s\n\n" s + (if (commandp s) + (let ((keys (where-is-internal s))) + (if keys + (concat + "Keys: " + (mapconcat 'key-description + keys " ")) + "Keys: none")) + "Function") +@end group +@group + (or (documentation s) + "not documented")))) + + (if (boundp s) ; @r{It is a variable.} +@end group +@group + (princ + (format "%s\t%s\n%s\n\n" s + (if (user-variable-p s) + "Option " "Variable") +@end group +@group + (or (documentation-property + s 'variable-documentation) + "not documented"))))))) + sym-list) +@end group + +@group + ;; @r{Build a list of symbols that match pattern.} + (mapatoms (function + (lambda (sym) + (if (string-match pattern (symbol-name sym)) + (setq sym-list (cons sym sym-list)))))) +@end group + +@group + ;; @r{Display the data.} + (with-output-to-temp-buffer "*Help*" + (mapcar describe-func (sort sym-list 'string<)) + (print-help-return-message)))) +@end group +@end smallexample + + The @code{describe-symbols} function works like @code{apropos}, +but provides more information. + +@smallexample +@group +(describe-symbols "goal") + +---------- Buffer: *Help* ---------- +goal-column Option +*Semipermanent goal column for vertical motion, as set by C-x C-n, or nil. +@end group +@c Do not blithely break or fill these lines. +@c That makes them incorrect. + +@group +set-goal-column Command: C-x C-n +Set the current horizontal position as a goal for C-n and C-p. +@end group +@c DO NOT put a blank line here! That is factually inaccurate! +@group +Those commands will move to this position in the line moved to +rather than trying to keep the same horizontal position. +With a non-nil argument, clears out the goal column +so that C-n and C-p resume vertical motion. +The goal column is stored in the variable `goal-column'. +@end group + +@group +temporary-goal-column Variable +Current goal column for vertical motion. +It is the column where point was +at the start of current run of vertical motion commands. +When the `track-eol' feature is doing its job, the value is 9999. +---------- Buffer: *Help* ---------- +@end group +@end smallexample + +@defun Snarf-documentation filename + This function is used only during Emacs initialization, just before +the runnable Emacs is dumped. It finds the file offsets of the +documentation strings stored in the file @var{filename}, and records +them in the in-core function definitions and variable property lists in +place of the actual strings. @xref{Building Emacs}. + + Emacs finds the file @var{filename} in the @file{emacs/etc} directory. +When the dumped Emacs is later executed, the same file is found in the +directory @code{doc-directory}. Usually @var{filename} is +@code{"DOC-@var{version}"}. +@end defun + +@c Emacs 19 feature +@defvar doc-directory +This variable holds the name of the directory which should contion the +file @code{"DOC-@var{version}"} that contains documentation strings for +built-in and preloaded functions and variables. + +In most cases, this is the same as @code{data-directory}. They may be +different when you run Emacs from the directory where you built it, +without actually installing it. See @code{data-directory} in @ref{Help +Functions}. + +In older Emacs versions, @code{exec-directory} was used for this. +@end defvar + +@node Keys in Documentation +@section Substituting Key Bindings in Documentation +@cindex documentation, keys in +@cindex keys in documentation strings +@cindex substituting keys in documentation + + When documentation strings refer to key sequences, they should do so +based on the current, actual key bindings. They can do so using certain +special text sequences described below. Accessing documentation strings +in the usual way substitutes current key binding information for these +special sequences. This works by calling @code{substitute-command-keys}. +You can also call that function yourself. + + Here is a list of the special sequences and what they mean: + +@table @code +@item \[@var{command}] +stands for a key sequence that will invoke @var{command}, or @samp{M-x +@var{command}} if @var{command} has no key bindings. + +@item \@{@var{mapvar}@} +stands for a summary of the value of @var{mapvar}, which should be a +keymap. The summary is made by @code{describe-bindings}. + +@item \<@var{mapvar}> +stands for no text itself. It is used for a side effect: it specifies +@var{mapvar} as the keymap for any following @samp{\[@var{command}]} +sequences in this documentation string. +@end table + +@strong{Please note:} each @samp{\} must be doubled when written in a +string in Emacs Lisp. + +@defun substitute-command-keys string +This function scans @var{string} for the above special sequences and +replaces them by what they stand for, returning the result as a string. +This permits display of documentation that refers accurately to the +users's own customized key bindings. +@end defun + + Here are examples of the special sequences: + +@smallexample +@group +(substitute-command-keys + "To abort recursive edit, type: \\[abort-recursive-edit]") +@result{} "To abort recursive edit, type: C-]" +@end group + +@group +(substitute-command-keys + "The keys that are defined for the minibuffer here are: + \\@{minibuffer-local-must-match-map@}") +@result{} "The keys that are defined for the minibuffer here are: +@end group + +? minibuffer-completion-help +SPC minibuffer-complete-word +TAB minibuffer-complete +LFD minibuffer-complete-and-exit +RET minibuffer-complete-and-exit +C-g abort-recursive-edit +" + +@group +(substitute-command-keys + "To abort a recursive edit from the minibuffer, type\ +\\\\[abort-recursive-edit].") +@result{} "To abort a recursive edit from the minibuffer, type C-g." +@end group +@end smallexample + +@node Describing Characters +@section Describing Characters for Help Messages + + These functions convert events, key sequences or characters to textual +descriptions. These descriptions are useful for including arbitrary +text characters or key sequences in messages, because they convert +non-printing and whitespace characters to sequences of printing +characters. The description of a non-whitespace printing character is +the character itself. + +@defun key-description sequence +@cindex Emacs event standard notation +This function returns a string containing the Emacs standard notation +for the input events in @var{sequence}. The argument @var{sequence} may +be a string, vector or list. @xref{Input Events}, for more information +about valid events. See also the examples for +@code{single-key-description}, below. +@end defun + +@defun single-key-description event +@cindex event printing +@cindex character printing +@cindex control character printing +@cindex meta character printing +This function returns a string describing @var{event} in the standard +Emacs notation for keyboard input. A normal printing character appears +as itself, but a control character turns into a string starting with +@samp{C-}, a meta character turns into a string starting with @samp{M-}, +and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A +function key symbol appears as itself. An event which is a list appears +as the name of the symbol in the @sc{car} of the list. + +@smallexample +@group +(single-key-description ?\C-x) + @result{} "C-x" +@end group +@group +(key-description "\C-x \M-y \n \t \r \f123") + @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3" +@end group +@group +(single-key-description 'C-mouse-1) + @result{} "C-mouse-1" +@end group +@end smallexample +@end defun + +@defun text-char-description character +This function returns a string describing @var{character} in the +standard Emacs notation for characters that appear in text---like +@code{single-key-description}, except that control characters are +represented with a leading caret (which is how control characters in +Emacs buffers are usually displayed). + +@smallexample +@group +(text-char-description ?\C-c) + @result{} "^C" +@end group +@group +(text-char-description ?\M-m) + @result{} "M-m" +@end group +@group +(text-char-description ?\C-\M-m) + @result{} "M-^M" +@end group +@end smallexample +@end defun + +@node Help Functions +@section Help Functions + + Emacs provides a variety of on-line help functions, all accessible to +the user as subcommands of the prefix @kbd{C-h}. For more information +about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here +we describe some program-level interfaces to the same information. + +@deffn Command apropos regexp &optional do-all predicate + This function finds all symbols whose names contain a match for the +regular expression @var{regexp}, and returns a list of them. +It also displays the symbols in a buffer named @samp{*Help*}, each with a +one-line description. + +@c Emacs 19 feature + If @var{do-all} is non-@code{nil}, then @code{apropos} also shows +key bindings for the functions that are found. + + If @var{predicate} is non-@code{nil}, it should be a function to be +called on each symbol that has matched @var{regexp}. Only symbols for +which @var{predicate} returns a non-@code{nil} value are listed or +displayed. + + In the first of the following examples, @code{apropos} finds all the +symbols with names containing @samp{exec}. In the second example, it +finds and returns only those symbols that are also commands. +(We don't show the output that results in the @samp{*Help*} buffer.) + +@smallexample +@group +(apropos "exec") + @result{} (Buffer-menu-execute command-execute exec-directory + exec-path execute-extended-command execute-kbd-macro + executing-kbd-macro executing-macro) +@end group + +@group +(apropos "exec" nil 'commandp) + @result{} (Buffer-menu-execute execute-extended-command) +@end group +@ignore +@group +---------- Buffer: *Help* ---------- +Buffer-menu-execute + Function: Save and/or delete buffers marked with + M-x Buffer-menu-save or M-x Buffer-menu-delete commands. +execute-extended-command ESC x + Function: Read function name, then read its + arguments and call it. +---------- Buffer: *Help* ---------- +@end group +@end ignore +@end smallexample + + The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos}, +but specifies a @var{predicate} to restrict the output to symbols that +are commands. The call to @code{apropos} looks like this: + +@smallexample +(apropos string t 'commandp) +@end smallexample +@end deffn + +@c Emacs 19 feature +@deffn Command super-apropos regexp &optional do-all +This function differs from @code{apropos} in that it searches +documentation strings as well as symbol names for matches for +@var{regexp}. By default, it searches only the documentation strings, +and only those of functions and variables that are included in Emacs +when it is dumped. If @var{do-all} is non-@code{nil}, it scans the +names and documentation strings of all functions and variables. +@end deffn + +@defvar help-map +The value of this variable is a local keymap for characters following the +Help key, @kbd{C-h}. +@end defvar + +@deffn {Prefix Command} help-command +This symbol is not a function; its function definition is actually the +keymap known as @code{help-map}. It is defined in @file{help.el} as +follows: + +@smallexample +@group +(define-key global-map "\C-h" 'help-command) +(fset 'help-command help-map) +@end group +@end smallexample +@end deffn + +@defun print-help-return-message &optional function +This function builds a string which is a message explaining how to +restore the previous state of the windows after a help command. After +building the message, it applies @var{function} to it if @var{function} +is non-@code{nil}. Otherwise it calls @code{message} to display it in +the echo area. + +This function expects to be called inside a +@code{with-output-to-temp-buffer} special form, and expects +@code{standard-output} to have the value bound by that special form. +For an example of its use, see the long example in @ref{Accessing +Documentation}. +@end defun + +@defvar help-char +The value of this variable is the help character---the character that +Emacs recognizes as meaning Help. By default, it is 8, which is +@kbd{C-h}. When Emacs reads this character, if @code{help-form} is +non-@code{nil} Lisp expression, it evaluates that expression, and +displays the result in a window if it is a string. + +Usually the value of @code{help-form}'s value is @code{nil}. Then the +help character has no special meaning at the level of command input, and +it becomes part of a key sequence in the normal way. The standard key +binding of @kbd{C-h} is a prefix key for several general-purpose help +features. + +The help character is special after prefix keys, too. If it has no +binding as a subcommand of the prefix key, it runs +@code{describe-prefix-bindings}, which displays a list of all the +subcommands of the prefix key. +@end defvar + +@defvar help-form +If this variable is non-@code{nil}, its value is a form to evaluate +whenever the character @code{help-char} is read. If evaluating the form +produces a string, that string is displayed. + +A command that calls @code{read-event} or @code{read-char} probably +should bind @code{help-form} to a non-@code{nil} expression while it +does input. (The exception is when @kbd{C-h} is meaningful input.) +Evaluating this expression should result in a string that explains what +the input is for and how to enter it properly. + +Entry to the minibuffer binds this variable to the value of +@code{minibuffer-help-form} (@pxref{Minibuffer Misc}). +@end defvar + +@defvar prefix-help-command +This variable holds a function to print help for a prefix character. +The function is called when the user types a prefix key followed by the +help character, and the help character has no binding after that prefix. +The variable's default value is @code{describe-prefix-bindings}. +@end defvar + +@defun describe-prefix-bindings +This function calls @code{describe-bindings} to display a list of all +the subcommands of the prefix key of the most recent key sequence. The +prefix described consists of all but the last event of that key +sequence. +@end defun + + The following two functions are found in the library @file{helper}. +They are for modes that want to provide help without relinquishing +control, such as the ``electric'' modes. You must load that library +with @code{(require 'helper)} in order to use them. Their names begin +with @samp{Helper} to distinguish them from the ordinary help functions. + +@deffn Command Helper-describe-bindings +This command pops up a window displaying a help buffer containing a +listing of all of the key bindings from both the local and global keymaps. +It works by calling @code{describe-bindings}. +@end deffn + +@deffn Command Helper-help +This command provides help for the current mode. It prompts the user +in the minibuffer with the message @samp{Help (Type ? for further +options)}, and then provides assistance in finding out what the key +bindings are, and what the mode is intended for. It returns @code{nil}. + +This can be customized by changing the map @code{Helper-help-map}. +@end deffn + +@c Emacs 19 feature +@defvar data-directory +This variable holds the name of the directory in which Emacs finds +certain documentation and text files that come with Emacs. In older +Emacs versions, @code{exec-directory} was used for this. +@end defvar + +@c Emacs 19 feature +@defmac make-help-screen fname help-line help-text help-map +This macro defines a help command named @var{fname} which acts like a +prefix key which shows a list of the subcommands it offers. + +When invoked, @var{fname} displays @var{help-text} in a window, then +reads and executes a key sequence according to @var{help-map}. The +string @var{help-text} should describe of the bindings available in +@var{help-map}. + +The command @var{fname} is defined to handle a few events itself, by +scrolling the display of @var{help-text}. When @var{fname} reads one of +those special events, it does the scrolling and then reads another +event. When it reads an event which is not one of those few, and which +has a binding in @var{help-map}, it executes that key's binding and +then returns. + +The argument @var{help-line} should be a single-line summary of the +alternatives in @var{help-map}. In the current version of Emacs, this +argument is used only if you set the option @code{three-step-help} to +@code{t}. +@end defmac + +@defopt three-step-help +If this variable is non-@code{nil}, commands defined with +@code{make-help-screen} display their @var{help-line} strings in the +echo area at first, and display the longer @var{help-text} strings only +if the user types the help character again. +@end defopt diff -r 510a3c16068a -r 52f4a94c8c3d lispref/streams.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/streams.texi Wed Mar 16 19:53:19 1994 +0000 @@ -0,0 +1,713 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/streams +@node Streams, Minibuffers, Debugging, Top +@comment node-name, next, previous, up +@chapter Reading and Printing Lisp Objects + + @dfn{Printing} and @dfn{reading} are the operations of converting Lisp +objects to textual form and vice versa. They use the printed +representations and read syntax described in @ref{Types of Lisp Object}. + + This chapter describes the Lisp functions for reading and printing. +It also describes @dfn{streams}, which specify where to get the text (if +reading) or where to put it (if printing). + +@menu +* Streams Intro:: Overview of streams, reading and printing. +* Input Streams:: Various data types that can be used as input streams. +* Input Functions:: Functions to read Lisp objects from text. +* Output Streams:: Various data types that can be used as output streams. +* Output Functions:: Functions to print Lisp objects as text. +* Output Variables:: Variables that control what the printing functions do. +@end menu + +@node Streams Intro +@section Introduction to Reading and Printing +@cindex Lisp reader +@cindex printing +@cindex reading + + @dfn{Reading} a Lisp object means parsing a Lisp expression in textual +form and producing a corresponding Lisp object. This is how Lisp +programs get into Lisp from files of Lisp code. We call the text the +@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} +is the read syntax for a cons cell whose @sc{car} is @code{a} and whose +@sc{cdr} is the number 5. + + @dfn{Printing} a Lisp object means producing text that represents that +object---converting the object to its printed representation. Printing +the cons cell described above produces the text @samp{(a .@: 5)}. + + Reading and printing are more or less inverse operations: printing the +object that results from reading a given piece of text often produces +the same text, and reading the text that results from printing an object +usually produces a similar-looking object. For example, printing the +symbol @code{foo} produces the text @samp{foo}, and reading that text +returns the symbol @code{foo}. Printing a list whose elements are +@code{a} and @code{b} produces the text @samp{(a b)}, and reading that +text produces a list (but not the same list) with elements are @code{a} +and @code{b}. + + However, these two operations are not precisely inverses. There are +two kinds of exceptions: + +@itemize @bullet +@item +Printing can produce text that cannot be read. For example, buffers, +windows, frames, subprocesses and markers print into text that starts +with @samp{#}; if you try to read this text, you get an error. There is +no way to read those data types. + +@item +One object can have multiple textual representations. For example, +@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and +@samp{(a .@: (b))} represent the same list. Reading will accept any of +the alternatives, but printing must choose one of them. +@end itemize + +@node Input Streams +@section Input Streams +@cindex stream (for reading) +@cindex input stream + + Most of the Lisp functions for reading text take an @dfn{input stream} +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: + +@table @asis +@item @var{buffer} +@cindex buffer input stream +The input characters are read from @var{buffer}, starting with the +character directly after point. Point advances as characters are read. + +@item @var{marker} +@cindex marker input stream +The input characters are read from the buffer that @var{marker} 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. + +@item @var{string} +@cindex string input stream +The input characters are taken from @var{string}, starting at the first +character in the string and using as many characters as required. + +@item @var{function} +@cindex function input stream +The input characters are generated by @var{function}, one character per +call. Normally @var{function} is called with no arguments, and should +return a character. + +@cindex unreading +Occasionally @var{function} is called with one argument (always a +character). When that happens, @var{function} should save the argument +and arrange to return it on the next call. This is called +@dfn{unreading} the character; it happens when the Lisp reader reads one +character too many and wants to ``put it back where it came from''. + +@item @code{t} +@cindex @code{t} input stream +@code{t} 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. + +@item @code{nil} +@cindex @code{nil} input stream +@code{nil} supplied as an input stream means to use the value of +@code{standard-input} instead; that value is the @dfn{default input +stream}, and must be a non-@code{nil} input stream. + +@item @var{symbol} +A symbol as input stream is equivalent to the symbol's function +definition (if any). +@end table + + Here is an example of reading from a stream which is a buffer, showing +where point is located before and after: + +@example +@group +---------- Buffer: foo ---------- +This@point{} is the contents of foo. +---------- Buffer: foo ---------- +@end group + +@group +(read (get-buffer "foo")) + @result{} is +@end group +@group +(read (get-buffer "foo")) + @result{} the +@end group + +@group +---------- Buffer: foo ---------- +This is the@point{} contents of foo. +---------- Buffer: foo ---------- +@end group +@end example + +@noindent +Note that the first read skips a space at the beginning of the buffer. +Reading skips any amount of whitespace preceding the significant text. + + In Emacs 18, reading a symbol discarded the delimiter terminating the +symbol. Thus, point would end up at the beginning of @samp{contents} +rather than after @samp{the}. The Emacs 19 behavior is superior because +it correctly handles input such as @samp{bar(foo)}, where the delimiter +that ends one object is needed as the beginning of another object. + + Here is an example of reading from a stream that is a marker, +initialized to point at the beginning of the buffer shown. The value +read is the symbol @code{This}. + +@example +@group + +---------- Buffer: foo ---------- +This is the contents of foo. +---------- Buffer: foo ---------- +@end group + +@group +(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) + @result{} # +@end group +@group +(read m) + @result{} This +@end group +@group +m + @result{} # ;; @r{After the first space.} +@end group +@end example + + Here we read from the contents of a string: + +@example +@group +(read "(When in) the course") + @result{} (When in) +@end group +@end example + + The following example reads from the minibuffer. The +prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt +used when you read from the stream @code{t}.) The user's input is shown +following the prompt. + +@example +@group +(read t) + @result{} 23 +---------- Buffer: Minibuffer ---------- +Lisp expression: @kbd{23 @key{RET}} +---------- Buffer: Minibuffer ---------- +@end group +@end example + + Finally, here is an example of a stream that is a function, named +@code{useless-stream}. Before we use the stream, we initialize the +variable @code{useless-list} to a list of characters. Then each call to +the function @code{useless-stream} obtains the next characters in the list +or unreads a character by adding it to the front of the list. + +@example +@group +(setq useless-list (append "XY()" nil)) + @result{} (88 89 40 41) +@end group + +@group +(defun useless-stream (&optional unread) + (if unread + (setq useless-list (cons unread useless-list)) + (prog1 (car useless-list) + (setq useless-list (cdr useless-list))))) + @result{} useless-stream +@end group +@end example + +@noindent +Now we read using the stream thus constructed: + +@example +@group +(read 'useless-stream) + @result{} XY +@end group + +@group +useless-list + @result{} (41) +@end group +@end example + +@noindent +Note that the close parenthesis remains in the list. The reader has +read it, discovered that it ended the input, and unread it. Another +attempt to read from the stream at this point would get an error due to +the unmatched close parenthesis. + +@defun get-file-char +This function is used internally as an input stream to read from the +input file opened by the function @code{load}. Don't use this function +yourself. +@end defun + +@node Input Functions +@section Input Functions + + This section describes the Lisp functions and variables that pertain +to reading. + + In the functions below, @var{stream} stands for an input stream (see +the previous section). If @var{stream} is @code{nil} or omitted, it +defaults to the value of @code{standard-input}. + +@kindex end-of-file + An @code{end-of-file} error is signaled if reading encounters an +unterminated list, vector or string. + +@defun read &optional stream +This function reads one textual Lisp expression from @var{stream}, +returning it as a Lisp object. This is the basic Lisp input function. +@end defun + +@defun read-from-string string &optional start end +@cindex string to object +This function reads the first textual Lisp expression from the text in +@var{string}. It returns a cons cell whose @sc{car} is that expression, +and whose @sc{cdr} is an integer giving the position of the next +remaining character in the string (i.e., the first one not read). + +If @var{start} is supplied, then reading begins at index @var{start} in the +string (where the first character is at index 0). If @var{end} is also +supplied, then reading stops at that index as if the rest of the string +were not there. + +For example: + +@example +@group +(read-from-string "(setq x 55) (setq y 5)") + @result{} ((setq x 55) . 11) +@end group +@group +(read-from-string "\"A short string\"") + @result{} ("A short string" . 16) +@end group + +@group +;; @r{Read starting at the first character.} +(read-from-string "(list 112)" 0) + @result{} ((list 112) . 10) +@end group +@group +;; @r{Read starting at the second character.} +(read-from-string "(list 112)" 1) + @result{} (list . 6) +@end group +@group +;; @r{Read starting at the seventh character,} +;; @r{and stopping at the ninth.} +(read-from-string "(list 112)" 6 8) + @result{} (11 . 8) +@end group +@end example +@end defun + +@defvar standard-input +This variable holds the default input stream---the stream that +@code{read} uses when the @var{stream} argument is @code{nil}. +@end defvar + +@node Output Streams +@section Output Streams +@cindex stream (for printing) +@cindex output stream + + An output stream specifies what to do with the characters produced +by printing. Most print functions accept an output stream as an +optional argument. Here are the possible types of output stream: + +@table @asis +@item @var{buffer} +@cindex buffer output stream +The output characters are inserted into @var{buffer} at point. +Point advances as characters are inserted. + +@item @var{marker} +@cindex marker output stream +The output characters are inserted into the buffer that @var{marker} +points into, at the marker position. The position advances as +characters are inserted. The value of point in the buffer has no effect +on printing when the stream is a marker. + +@item @var{function} +@cindex function output stream +The output characters are passed to @var{function}, which is responsible +for storing them away. It is called with a single character as +argument, as many times as there are characters to be output, and is +free to do anything at all with the characters it receives. + +@item @code{t} +@cindex @code{t} output stream +The output characters are displayed in the echo area. + +@item @code{nil} +@cindex @code{nil} output stream +@code{nil} specified as an output stream means to the value of +@code{standard-output} instead; that value is the @dfn{default output +stream}, and must be a non-@code{nil} output stream. + +@item @var{symbol} +A symbol as output stream is equivalent to the symbol's function +definition (if any). +@end table + + Here is an example of a buffer used as an output stream. Point is +initially located as shown immediately before the @samp{h} in +@samp{the}. At the end, point is located directly before that same +@samp{h}. + +@cindex print example +@example +@group +---------- Buffer: foo ---------- +This is t@point{}he contents of foo. +---------- Buffer: foo ---------- +@end group + +(print "This is the output" (get-buffer "foo")) + @result{} "This is the output" + +@group +---------- Buffer: foo ---------- +This is t +"This is the output" +@point{}he contents of foo. +---------- Buffer: foo ---------- +@end group +@end example + + Now we show a use of a marker as an output stream. Initially, the +marker points in buffer @code{foo}, between the @samp{t} and the +@samp{h} in the word @samp{the}. At the end, the marker has been +advanced over the inserted text so that it still points before the same +@samp{h}. Note that the location of point, shown in the usual fashion, +has no effect. + +@example +@group +---------- Buffer: foo ---------- +"This is the @point{}output" +---------- Buffer: foo ---------- +@end group + +@group +m + @result{} # +@end group + +@group +(print "More output for foo." m) + @result{} "More output for foo." +@end group + +@group +---------- Buffer: foo ---------- +"This is t +"More output for foo." +he @point{}output" +---------- Buffer: foo ---------- +@end group + +@group +m + @result{} # +@end group +@end example + + The following example shows output to the echo area: + +@example +@group +(print "Echo Area output" t) + @result{} "Echo Area output" +---------- Echo Area ---------- +"Echo Area output" +---------- Echo Area ---------- +@end group +@end example + + Finally, we show the use of a function as an output stream. The +function @code{eat-output} takes each character that it is given and +conses it onto the front of the list @code{last-output} (@pxref{Building +Lists}). At the end, the list contains all the characters output, but +in reverse order. + +@example +@group +(setq last-output nil) + @result{} nil +@end group + +@group +(defun eat-output (c) + (setq last-output (cons c last-output))) + @result{} eat-output +@end group + +@group +(print "This is the output" 'eat-output) + @result{} "This is the output" +@end group + +@group +last-output + @result{} (10 34 116 117 112 116 117 111 32 101 104 + 116 32 115 105 32 115 105 104 84 34 10) +@end group +@end example + +@noindent +Now we can put the output in the proper order by reversing the list: + +@example +@group +(concat (nreverse last-output)) + @result{} " +\"This is the output\" +" +@end group +@end example + +@node Output Functions +@section Output Functions + + This section describes the Lisp functions for printing Lisp objects. + +@cindex @samp{"} in printing +@cindex @samp{\} in printing +@cindex quoting characters in printing +@cindex escape characters in printing + Some of the Emacs printing functions add quoting characters to the +output when necessary so that it can be read properly. The quoting +characters used are @samp{"} and @samp{\}; they distinguish strings from +symbols, and prevent punctuation characters in strings and symbols from +being taken as delimiters. @xref{Printed Representation}, for full +details. You specify quoting or no quoting by the choice of printing +function. + + If the text is to be read back into Lisp, then it is best to print +with quoting characters to avoid ambiguity. Likewise, if the purpose is +to describe a Lisp object clearly for a Lisp programmer. However, if +the purpose of the output is to look nice for humans, then it is better +to print without quoting. + + Printing a self-referent Lisp object requires an infinite amount of +text. In certain cases, trying to produce this text leads to a stack +overflow. Emacs detects such recursion and prints @samp{#@var{level}} +instead of recursively printing an object already being printed. For +example, here @samp{#0} indicates a recursive reference to the object at +level 0 of the current print operation: + +@example +(setq foo (list nil)) + @result{} (nil) +(setcar foo foo) + @result{} (#0) +@end example + + In the functions below, @var{stream} stands for an output stream. +(See the previous section for a description of output streams.) If +@var{stream} is @code{nil} or omitted, it defaults to the value of +@code{standard-output}. + +@defun print object &optional stream +@cindex Lisp printer +The @code{print} function is a convenient way of printing. It outputs +the printed representation of @var{object} to @var{stream}, printing in +addition one newline before @var{object} and another after it. Quoting +characters are used. @code{print} returns @var{object}. For example: + +@example +@group +(progn (print 'The\ cat\ in) + (print "the hat") + (print " came back")) + @print{} + @print{} The\ cat\ in + @print{} + @print{} "the hat" + @print{} + @print{} " came back" + @print{} + @result{} " came back" +@end group +@end example +@end defun + +@defun prin1 object &optional stream +This function outputs the printed representation of @var{object} to +@var{stream}. It does not print any spaces or newlines to separate +output as @code{print} does, but it does use quoting characters just +like @code{print}. It returns @var{object}. + +@example +@group +(progn (prin1 'The\ cat\ in) + (prin1 "the hat") + (prin1 " came back")) + @print{} The\ cat\ in"the hat"" came back" + @result{} " came back" +@end group +@end example +@end defun + +@defun princ object &optional stream +This function outputs the printed representation of @var{object} to +@var{stream}. It returns @var{object}. + +This function is intended to produce output that is readable by people, +not by @code{read}, so it doesn't insert quoting characters and doesn't +put double-quotes around the contents of strings. It does not add any +spacing between calls. + +@example +@group +(progn + (princ 'The\ cat) + (princ " in the \"hat\"")) + @print{} The cat in the "hat" + @result{} " in the \"hat\"" +@end group +@end example +@end defun + +@defun terpri &optional stream +@cindex newline in print +This function outputs a newline to @var{stream}. The name stands +for ``terminate print''. +@end defun + +@defun write-char character &optional stream +This function outputs @var{character} to @var{stream}. It returns +@var{character}. +@end defun + +@defun prin1-to-string object &optional noescape +@cindex object to string +This function returns a string containing the text that @code{prin1} +would have printed for the same argument. + +@example +@group +(prin1-to-string 'foo) + @result{} "foo" +@end group +@group +(prin1-to-string (mark-marker)) + @result{} "#" +@end group +@end example + +If @var{noescape} is non-@code{nil}, that inhibits use of quoting +characters in the output. (This argument is supported in Emacs versions +19 and later.) + +@example +@group +(prin1-to-string "foo") + @result{} "\"foo\"" +@end group +@group +(prin1-to-string "foo" t) + @result{} "foo" +@end group +@end example + +See @code{format}, in @ref{String Conversion}, for other ways to obtain +the printed representation of a Lisp object as a string. +@end defun + +@node Output Variables +@section Variables Affecting Output + +@defvar standard-output +The value of this variable is the default output stream---the stream +that print functions use when the @var{stream} argument is @code{nil}. +@end defvar + +@defvar print-escape-newlines +@cindex @samp{\n} in print +@cindex escape characters +If this variable is non-@code{nil}, then newline characters in strings +are printed as @samp{\n} and formfeeds are printed as @samp{\f}. +Normally these characters are printed as actual newlines and formfeeds. + +This variable affects the print functions @code{prin1} and @code{print}, +as well as everything that uses them. It does not affect @code{princ}. +Here is an example using @code{prin1}: + +@example +@group +(prin1 "a\nb") + @print{} "a + @print{} b" + @result{} "a +b" +@end group + +@group +(let ((print-escape-newlines t)) + (prin1 "a\nb")) + @print{} "a\nb" + @result{} "a +b" +@end group +@end example + +@noindent +In the second expression, the local binding of +@code{print-escape-newlines} is in effect during the call to +@code{prin1}, but not during the printing of the result. +@end defvar + +@defvar print-length +@cindex printing limits +The value of this variable is the maximum number of elements of a list +that will be printed. If a list being printed has more than this many +elements, then it is abbreviated with an ellipsis. + +If the value is @code{nil} (the default), then there is no limit. + +@example +@group +(setq print-length 2) + @result{} 2 +@end group +@group +(print '(1 2 3 4 5)) + @print{} (1 2 ...) + @result{} (1 2 ...) +@end group +@end example +@end defvar + +@defvar print-level +The value of this variable is the maximum depth of nesting of +parentheses that will be printed. Any list or vector at a depth +exceeding this limit is abbreviated with an ellipsis. A value of +@code{nil} (which is the default) means no limit. + +This variable exists in version 19 and later versions. +@end defvar