This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls Specification List .................. A "specification list" is required for an Edebug specification if some arguments of a macro call are evaluated while others are not. Some elements in a specification list match one or more arguments, but others modify the processing of all following elements. The latter, called "specification keywords", are symbols beginning with `&' (such as `&optional'). A specification list may contain sublists which match arguments that are themselves lists, or it may contain vectors used for grouping. Sublists and groups thus subdivide the specification list into a hierarchy of levels. Specification keywords apply only to the remainder of the sublist or group they are contained in. When a specification list involves alternatives or repetition, matching it against an actual macro call may require backtracking. *Note Backtracking::, for more details. Edebug specifications provide the power of regular expression matching, plus some context-free grammar constructs: the matching of sublists with balanced parentheses, recursive processing of forms, and recursion via indirect specifications. Here's a table of the possible elements of a specification list, with their meanings: `sexp' A single unevaluated Lisp object, which is not instrumented. `form' A single evaluated expression, which is instrumented. `place' A place to store a value, as in the Common Lisp `setf' construct. `body' Short for `&rest form'. See `&rest' below. `function-form' A function form: either a quoted function symbol, a quoted lambda expression, or a form (that should evaluate to a function symbol or lambda expression). This is useful when an argument that's a lambda expression might be quoted with `quote' rather than `function', since it instruments the body of the lambda expression either way. `lambda-expr' A lambda expression with no quoting. `&optional' All following elements in the specification list are optional; as soon as one does not match, Edebug stops matching at this level. To make just a few elements optional followed by non-optional elements, use `[&optional SPECS...]'. To specify that several elements must all match or none, use `&optional [SPECS...]'. See the `defun' example below. `&rest' All following elements in the specification list are repeated zero or more times. In the last repetition, however, it is not a problem if the expression runs out before matching all of the elements of the specification list. To repeat only a few elements, use `[&rest SPECS...]'. To specify several elements that must all match on every repetition, use `&rest [SPECS...]'. `&or' Each of the following elements in the specification list is an alternative. One of the alternatives must match, or the `&or' specification fails. Each list element following `&or' is a single alternative. To group two or more list elements as a single alternative, enclose them in `[...]'. `¬' Each of the following elements is matched as alternatives as if by using `&or', but if any of them match, the specification fails. If none of them match, nothing is matched, but the `¬' specification succeeds. `&define' Indicates that the specification is for a defining form. The defining form itself is not instrumented (that is, Edebug does not stop before and after the defining form), but forms inside it typically will be instrumented. The `&define' keyword should be the first element in a list specification. `nil' This is successful when there are no more arguments to match at the current argument list level; otherwise it fails. See sublist specifications and the backquote example below. `gate' No argument is matched but backtracking through the gate is disabled while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See *Note Backtracking::, for more details. Also see the `let' example below. `OTHER-SYMBOL' Any other symbol in a specification list may be a predicate or an indirect specification. If the symbol has an Edebug specification, this "indirect specification" should be either a list specification that is used in place of the symbol, or a function that is called to process the arguments. The specification may be defined with `def-edebug-spec' just as for macros. See the `defun' example below. Otherwise, the symbol should be a predicate. The predicate is called with the argument and the specification fails if the predicate returns `nil'. In either case, that argument is not instrumented. Some suitable predicates include `symbolp', `integerp', `stringp', `vectorp', and `atom'. `[ELEMENTS...]' A vector of elements groups the elements into a single "group specification". Its meaning has nothing to do with vectors. `"STRING"' The argument should be a symbol named STRING. This specification is equivalent to the quoted symbol, `'SYMBOL', where the name of SYMBOL is the STRING, but the string form is preferred. `(vector ELEMENTS...)' The argument should be a vector whose elements must match the ELEMENTS in the specification. See the backquote example below. `(ELEMENTS...)' Any other list is a "sublist specification" and the argument must be a list whose elements match the specification ELEMENTS. A sublist specification may be a dotted list and the corresponding list argument may then be a dotted list. Alternatively, the last CDR of a dotted list specification may be another sublist specification (via a grouping or an indirect specification, e.g., `(spec . [(more specs...)])') whose elements match the non-dotted list arguments. This is useful in recursive specifications such as in the backquote example below. Also see the description of a `nil' specification above for terminating such recursion. Note that a sublist specification written as `(specs . nil)' is equivalent to `(specs)', and `(specs . (sublist-elements...))' is equivalent to `(specs sublist-elements...)'. Here is a list of additional specifications that may appear only after `&define'. See the `defun' example below. `name' The argument, a symbol, is the name of the defining form. A defining form is not required to have a name field; and it may have multiple name fields. `:name' This construct does not actually match an argument. The element following `:name' should be a symbol; it is used as an additional name component for the definition. You can use this to add a unique, static component to the name of the definition. It may be used more than once. `arg' The argument, a symbol, is the name of an argument of the defining form. However, lambda-list keywords (symbols starting with `&') are not allowed. `lambda-list' This matches a lambda list--the argument list of a lambda expression. `def-body' The argument is the body of code in a definition. This is like `body', described above, but a definition body must be instrumented with a different Edebug call that looks up information associated with the definition. Use `def-body' for the highest level list of forms within the definition. `def-form' The argument is a single, highest-level form in a definition. This is like `def-body', except use this to match a single form rather than a list of forms. As a special case, `def-form' also means that tracing information is not output when the form is executed. See the `interactive' example below.  File: elisp, Node: Backtracking, Next: Specification Examples, Prev: Specification List, Up: Instrumenting Macro Calls Backtracking in Specifications .............................. If a specification fails to match at some point, this does not necessarily mean a syntax error will be signaled; instead, "backtracking" will take place until all alternatives have been exhausted. Eventually every element of the argument list must be matched by some element in the specification, and every required element in the specification must match some argument. When a syntax error is detected, it might not be reported until much later after higher-level alternatives have been exhausted, and with the point positioned further from the real error. But if backtracking is disabled when an error occurs, it can be reported immediately. Note that backtracking is also reenabled automatically in several situations; it is reenabled when a new alternative is established by `&optional', `&rest', or `&or', or at the start of processing a sublist, group, or indirect specification. The effect of enabling or disabling backtracking is limited to the remainder of the level currently being processed and lower levels. Backtracking is disabled while matching any of the form specifications (that is, `form', `body', `def-form', and `def-body'). These specifications will match any form so any error must be in the form itself rather than at a higher level. Backtracking is also disabled after successfully matching a quoted symbol or string specification, since this usually indicates a recognized construct. But if you have a set of alternative constructs that all begin with the same symbol, you can usually work around this constraint by factoring the symbol out of the alternatives, e.g., `["foo" &or [first case] [second case] ...]'. Most needs are satisfied by these two ways that bactracking is automatically disabled, but occasionally it is useful to explicitly disable backtracking by using the `gate' specification. This is useful when you know that no higher alternatives could apply. See the example of the `let' specification.  File: elisp, Node: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls Specification Examples ...................... It may be easier to understand Edebug specifications by studying the examples provided here. A `let' special form has a sequence of bindings and a body. Each of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the `gate' inside of the sublist to prevent backtracking once a sublist is found. (def-edebug-spec let ((&rest &or symbolp (gate symbolp &optional form)) body)) Edebug uses the following specifications for `defun' and `defmacro' and the associated argument list and `interactive' specifications. It is necessary to handle interactive forms specially since an expression argument it is actually evaluated outside of the function body. (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec. (def-edebug-spec defun (&define name lambda-list [&optional stringp] ; Match the doc string, if present. [&optional ("interactive" interactive)] def-body)) (def-edebug-spec lambda-list (([&rest arg] [&optional ["&optional" arg &rest arg]] &optional ["&rest" arg] ))) (def-edebug-spec interactive (&optional &or stringp def-form)) ; Notice: `def-form' The specification for backquote below illustrates how to match dotted lists and use `nil' to terminate recursion. It also illustrates how components of a vector may be matched. (The actual specification defined by Edebug does not support dotted lists because doing so causes very deep recursion that could fail.) (def-edebug-spec ` (backquote-form)) ; Alias just for clarity. (def-edebug-spec backquote-form (&or ([&or "," ",@"] &or ("quote" backquote-form) form) (backquote-form . [&or nil backquote-form]) (vector &rest backquote-form) sexp))  File: elisp, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug Edebug Options -------------- These options affect the behavior of Edebug: - User Option: edebug-setup-hook Functions to call before Edebug is used. Each time it is set to a new value, Edebug will call those functions once and then `edebug-setup-hook' is reset to `nil'. You could use this to load up Edebug specifications associated with a package you are using but only when you also use Edebug. *Note Instrumenting::. - User Option: edebug-all-defs If this is non-`nil', normal evaluation of defining forms such as `defun' and `defmacro' instruments them for Edebug. This applies to `eval-defun', `eval-region', `eval-buffer', and `eval-current-buffer'. Use the command `M-x edebug-all-defs' to toggle the value of this option. *Note Instrumenting::. - User Option: edebug-all-forms If this is non-`nil', the commands `eval-defun', `eval-region', `eval-buffer', and `eval-current-buffer' instrument all forms, even those that don't define anything. This doesn't apply to loading or evaluations in the minibuffer. Use the command `M-x edebug-all-forms' to toggle the value of this option. *Note Instrumenting::. - User Option: edebug-save-windows If this is non-`nil', Edebug saves and restores the window configuration. That takes some time, so if your program does not care what happens to the window configurations, it is better to set this variable to `nil'. If the value is a list, only the listed windows are saved and restored. You can use the `W' command in Edebug to change this variable interactively. *Note Edebug Display Update::. - User Option: edebug-save-displayed-buffer-points If this is non-`nil', Edebug saves and restores point in all displayed buffers. Saving and restoring point in other buffers is necessary if you are debugging code that changes the point of a buffer which is displayed in a non-selected window. If Edebug or the user then selects the window, point in that buffer will move to the window's value of point. Saving and restoring point in all buffers is expensive, since it requires selecting each window twice, so enable this only if you need it. *Note Edebug Display Update::. - User Option: edebug-initial-mode If this variable is non-`nil', it specifies the initial execution mode for Edebug when it is first activated. Possible values are `step', `next', `go', `Go-nonstop', `trace', `Trace-fast', `continue', and `Continue-fast'. The default value is `step'. *Note Edebug Execution Modes::. - User Option: edebug-trace Non-`nil' means display a trace of function entry and exit. Tracing output is displayed in a buffer named `*edebug-trace*', one function entry or exit per line, indented by the recursion level. The default value is `nil'. Also see `edebug-tracing', in *Note Trace Buffer::. - User Option: edebug-test-coverage If non-`nil', Edebug tests coverage of all expressions debugged. *Note Coverage Testing::. - User Option: edebug-continue-kbd-macro If non-`nil', continue defining or executing any keyboard macro that is executing outside of Edebug. Use this with caution since it is not debugged. *Note Edebug Execution Modes::. - User Option: edebug-on-error Edebug binds `debug-on-error' to this value, if `debug-on-error' was previously `nil'. *Note Trapping Errors::. - User Option: edebug-on-quit Edebug binds `debug-on-quit' to this value, if `debug-on-quit' was previously `nil'. *Note Trapping Errors::. If you change the values of `edebug-on-error' or `edebug-on-quit' while Edebug is active, their values won't be used until the _next_ time Edebug is invoked via a new command. - User Option: edebug-global-break-condition If non-`nil', an expression to test for at every stop point. If the result is non-nil, then break. Errors are ignored. *Note Global Break Condition::.  File: elisp, Node: Syntax Errors, Next: Compilation Errors, Prev: Edebug, Up: Debugging Debugging Invalid Lisp Syntax ============================= The Lisp reader reports invalid syntax, but cannot say where the real problem is. For example, the error "End of file during parsing" in evaluating an expression indicates an excess of open parentheses (or square brackets). The reader detects this imbalance at the end of the file, but it cannot figure out where the close parenthesis should have been. Likewise, "Invalid read syntax: ")"" indicates an excess close parenthesis or missing open parenthesis, but does not say where the missing parenthesis belongs. How, then, to find what to change? If the problem is not simply an imbalance of parentheses, a useful technique is to try `C-M-e' at the beginning of each defun, and see if it goes to the place where that defun appears to end. If it does not, there is a problem in that defun. However, unmatched parentheses are the most common syntax errors in Lisp, and we can give further advice for those cases. (In addition, just moving point through the code with Show Paren mode enabled might find the mismatch.) * Menu: * Excess Open:: How to find a spurious open paren or missing close. * Excess Close:: How to find a spurious close paren or missing open.  File: elisp, Node: Excess Open, Next: Excess Close, Up: Syntax Errors Excess Open Parentheses ----------------------- The first step is to find the defun that is unbalanced. If there is an excess open parenthesis, the way to do this is to go to the end of the file and type `C-u C-M-u'. This will move you to the beginning of the defun that is unbalanced. The next step is to determine precisely what is wrong. There is no way to be sure of this except by studying the program, but often the existing indentation is a clue to where the parentheses should have been. The easiest way to use this clue is to reindent with `C-M-q' and see what moves. *But don't do this yet!* Keep reading, first. Before you do this, make sure the defun has enough close parentheses. Otherwise, `C-M-q' will get an error, or will reindent all the rest of the file until the end. So move to the end of the defun and insert a close parenthesis there. Don't use `C-M-e' to move there, since that too will fail to work until the defun is balanced. Now you can go to the beginning of the defun and type `C-M-q'. Usually all the lines from a certain point to the end of the function will shift to the right. There is probably a missing close parenthesis, or a superfluous open parenthesis, near that point. (However, don't assume this is true; study the code to make sure.) Once you have found the discrepancy, undo the `C-M-q' with `C-_', since the old indentation is probably appropriate to the intended parentheses. After you think you have fixed the problem, use `C-M-q' again. If the old indentation actually fit the intended nesting of parentheses, and you have put back those parentheses, `C-M-q' should not change anything.  File: elisp, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors Excess Close Parentheses ------------------------ To deal with an excess close parenthesis, first go to the beginning of the file, then type `C-u -1 C-M-u' to find the end of the unbalanced defun. Then find the actual matching close parenthesis by typing `C-M-f' at the beginning of that defun. This will leave you somewhere short of the place where the defun ought to end. It is possible that you will find a spurious close parenthesis in that vicinity. If you don't see a problem at that point, the next thing to do is to type `C-M-q' at the beginning of the defun. A range of lines will probably shift left; if so, the missing open parenthesis or spurious close parenthesis is probably near the first of those lines. (However, don't assume this is true; study the code to make sure.) Once you have found the discrepancy, undo the `C-M-q' with `C-_', since the old indentation is probably appropriate to the intended parentheses. After you think you have fixed the problem, use `C-M-q' again. If the old indentation actually fits the intended nesting of parentheses, and you have put back those parentheses, `C-M-q' should not change anything.  File: elisp, Node: Compilation Errors, Prev: Syntax Errors, Up: Debugging Debugging Problems in Compilation ================================= When an error happens during byte compilation, it is normally due to invalid syntax in the program you are compiling. The compiler prints a suitable error message in the `*Compile-Log*' buffer, and then stops. The message may state a function name in which the error was found, or it may not. Either way, here is how to find out where in the file the error occurred. What you should do is switch to the buffer ` *Compiler Input*'. (Note that the buffer name starts with a space, so it does not show up in `M-x list-buffers'.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read. If the error was due to invalid Lisp syntax, point shows exactly where the invalid syntax was _detected_. The cause of the error is not necessarily near by! Use the techniques in the previous section to find the error. If the error was detected while compiling a form that had been read successfully, then point is located at the end of the form. In this case, this technique can't localize the error precisely, but can still show you which function to check.  File: elisp, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top Reading and Printing Lisp Objects ********************************* "Printing" and "reading" are the operations of converting Lisp objects to textual form and vice versa. They use the printed representations and read syntax described in *Note Lisp Data Types::. This chapter describes the Lisp functions for reading and printing. It also describes "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.  File: elisp, Node: Streams Intro, Next: Input Streams, Up: Read and Print Introduction to Reading and Printing ==================================== "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 "read syntax" of the object. For example, the text `(a . 5)' is the read syntax for a cons cell whose CAR is `a' and whose CDR is the number 5. "Printing" a Lisp object means producing text that represents that object--converting the object to its "printed representation" (*note Printed Representation::). Printing the cons cell described above produces the text `(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 `foo' produces the text `foo', and reading that text returns the symbol `foo'. Printing a list whose elements are `a' and `b' produces the text `(a b)', and reading that text produces a list (but not the same list) with elements `a' and `b'. However, these two operations are not precisely inverse to each other. There are three kinds of exceptions: * Printing can produce text that cannot be read. For example, buffers, windows, frames, subprocesses and markers print as text that starts with `#'; if you try to read this text, you get an error. There is no way to read those data types. * One object can have multiple textual representations. For example, `1' and `01' represent the same integer, and `(a b)' and `(a . (b))' represent the same list. Reading will accept any of the alternatives, but printing must choose one of them. * Comments can appear at certain points in the middle of an object's read sequence without affecting the result of reading it.  File: elisp, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print Input Streams ============= Most of the Lisp functions for reading text take an "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: BUFFER The input characters are read from BUFFER, starting with the character directly after point. Point advances as characters are read. MARKER The input characters are read from the buffer that 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. STRING The input characters are taken from STRING, starting at the first character in the string and using as many characters as required. FUNCTION The input characters are generated by FUNCTION, which must support two kinds of calls: * When it is called with no arguments, it should return the next character. * When it is called with one argument (always a character), FUNCTION should save the argument and arrange to return it on the next call. This is called "unreading" 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 FUNCTION returns. `t' `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. If Emacs is running in batch mode, standard input is used instead of the minibuffer. For example, (message "%s" (read t)) will read a Lisp expression from standard input and print the result to standard output. `nil' `nil' supplied as an input stream means to use the value of `standard-input' instead; that value is the "default input stream", and must be a non-`nil' input stream. SYMBOL A symbol as input stream is equivalent to the symbol's function definition (if any). Here is an example of reading from a stream that is a buffer, showing where point is located before and after: ---------- Buffer: foo ---------- This-!- is the contents of foo. ---------- Buffer: foo ---------- (read (get-buffer "foo")) => is (read (get-buffer "foo")) => the ---------- Buffer: foo ---------- This is the-!- contents of foo. ---------- Buffer: foo ---------- Note that the first read skips a space. Reading skips any amount of whitespace preceding the significant text. 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 `This'. ---------- Buffer: foo ---------- This is the contents of foo. ---------- Buffer: foo ---------- (setq m (set-marker (make-marker) 1 (get-buffer "foo"))) => # (read m) => This m => # ;; Before the first space. Here we read from the contents of a string: (read "(When in) the course") => (When in) The following example reads from the minibuffer. The prompt is: `Lisp expression: '. (That is always the prompt used when you read from the stream `t'.) The user's input is shown following the prompt. (read t) => 23 ---------- Buffer: Minibuffer ---------- Lisp expression: 23 ---------- Buffer: Minibuffer ---------- Finally, here is an example of a stream that is a function, named `useless-stream'. Before we use the stream, we initialize the variable `useless-list' to a list of characters. Then each call to the function `useless-stream' obtains the next character in the list or unreads a character by adding it to the front of the list. (setq useless-list (append "XY()" nil)) => (88 89 40 41) (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 Now we read using the stream thus constructed: (read 'useless-stream) => XY useless-list => (40 41) 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 `()' and return `nil'. - Function: get-file-char This function is used internally as an input stream to read from the input file opened by the function `load'. Don't use this function yourself.  File: elisp, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print Input Functions =============== This section describes the Lisp functions and variables that pertain to reading. In the functions below, STREAM stands for an input stream (see the previous section). If STREAM is `nil' or omitted, it defaults to the value of `standard-input'. An `end-of-file' error is signaled if reading encounters an unterminated list, vector, or string. - Function: read &optional stream This function reads one textual Lisp expression from STREAM, returning it as a Lisp object. This is the basic Lisp input function. - Function: read-from-string string &optional start end This function reads the first textual Lisp expression from the text in STRING. It returns a cons cell whose CAR is that expression, and whose CDR is an integer giving the position of the next remaining character in the string (i.e., the first one not read). If START is supplied, then reading begins at index START in the string (where the first character is at index 0). If you specify END, then reading is forced to stop just before that index, as if the rest of the string were not there. For example: (read-from-string "(setq x 55) (setq y 5)") => ((setq x 55) . 11) (read-from-string "\"A short string\"") => ("A short string" . 16) ;; Read starting at the first character. (read-from-string "(list 112)" 0) => ((list 112) . 10) ;; Read starting at the second character. (read-from-string "(list 112)" 1) => (list . 5) ;; Read starting at the seventh character, ;; and stopping at the ninth. (read-from-string "(list 112)" 6 8) => (11 . 8) - Variable: standard-input This variable holds the default input stream--the stream that `read' uses when the STREAM argument is `nil'.  File: elisp, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print Output Streams ============== 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: BUFFER The output characters are inserted into BUFFER at point. Point advances as characters are inserted. MARKER The output characters are inserted into the buffer that MARKER points into, at the marker position. The marker position advances as characters are inserted. The value of point in the buffer has no effect on printing when the stream is a marker, and this kind of printing does not move point. FUNCTION The output characters are passed to 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 responsible for storing the characters wherever you want to put them. `t' The output characters are displayed in the echo area. `nil' `nil' specified as an output stream means to use the value of `standard-output' instead; that value is the "default output stream", and must not be `nil'. SYMBOL A symbol as output stream is equivalent to the symbol's function definition (if any). Many of the valid output streams are also valid as input streams. The difference between input and output streams is therefore more a matter of how you use a Lisp object, than of different types of object. Here is an example of a buffer used as an output stream. Point is initially located as shown immediately before the `h' in `the'. At the end, point is located directly before that same `h'. ---------- Buffer: foo ---------- This is t-!-he contents of foo. ---------- Buffer: foo ---------- (print "This is the output" (get-buffer "foo")) => "This is the output" ---------- Buffer: foo ---------- This is t "This is the output" -!-he contents of foo. ---------- Buffer: foo ---------- Now we show a use of a marker as an output stream. Initially, the marker is in buffer `foo', between the `t' and the `h' in the word `the'. At the end, the marker has advanced over the inserted text so that it remains positioned before the same `h'. Note that the location of point, shown in the usual fashion, has no effect. ---------- Buffer: foo ---------- This is the -!-output ---------- Buffer: foo ---------- (setq m (copy-marker 10)) => # (print "More output for foo." m) => "More output for foo." ---------- Buffer: foo ---------- This is t "More output for foo." he -!-output ---------- Buffer: foo ---------- m => # The following example shows output to the echo area: (print "Echo Area output" t) => "Echo Area output" ---------- Echo Area ---------- "Echo Area output" ---------- Echo Area ---------- Finally, we show the use of a function as an output stream. The function `eat-output' takes each character that it is given and conses it onto the front of the list `last-output' (*note Building Lists::). At the end, the list contains all the characters output, but in reverse order. (setq last-output nil) => nil (defun eat-output (c) (setq last-output (cons c last-output))) => eat-output (print "This is the output" 'eat-output) => "This is the output" last-output => (10 34 116 117 112 116 117 111 32 101 104 116 32 115 105 32 115 105 104 84 34 10) Now we can put the output in the proper order by reversing the list: (concat (nreverse last-output)) => " \"This is the output\" " Calling `concat' converts the list to a string so you can see its contents more clearly.  File: elisp, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print Output Functions ================ This section describes the Lisp functions for printing Lisp objects--converting objects into their printed representation. 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 `"' and `\'; they distinguish strings from symbols, and prevent punctuation characters in strings and symbols from being taken as delimiters when reading. *Note 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 you should 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 usually better to print without quoting. Lisp objects can refer to themselves. Printing a self-referential object in the normal way would require an infinite amount of text, and the attempt could cause infinite recursion. Emacs detects such recursion and prints `#LEVEL' instead of recursively printing an object already being printed. For example, here `#0' indicates a recursive reference to the object at level 0 of the current print operation: (setq foo (list nil)) => (nil) (setcar foo foo) => (#0) In the functions below, STREAM stands for an output stream. (See the previous section for a description of output streams.) If STREAM is `nil' or omitted, it defaults to the value of `standard-output'. - Function: print object &optional stream The `print' function is a convenient way of printing. It outputs the printed representation of OBJECT to STREAM, printing in addition one newline before OBJECT and another after it. Quoting characters are used. `print' returns OBJECT. For example: (progn (print 'The\ cat\ in) (print "the hat") (print " came back")) -| -| The\ cat\ in -| -| "the hat" -| -| " came back" -| => " came back" - Function: prin1 object &optional stream This function outputs the printed representation of OBJECT to STREAM. It does not print newlines to separate output as `print' does, but it does use quoting characters just like `print'. It returns OBJECT. (progn (prin1 'The\ cat\ in) (prin1 "the hat") (prin1 " came back")) -| The\ cat\ in"the hat"" came back" => " came back" - Function: princ object &optional stream This function outputs the printed representation of OBJECT to STREAM. It returns OBJECT. This function is intended to produce output that is readable by people, not by `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. (progn (princ 'The\ cat) (princ " in the \"hat\"")) -| The cat in the "hat" => " in the \"hat\"" - Function: terpri &optional stream This function outputs a newline to STREAM. The name stands for "terminate print". - Function: write-char character &optional stream This function outputs CHARACTER to STREAM. It returns CHARACTER. - Function: prin1-to-string object &optional noescape This function returns a string containing the text that `prin1' would have printed for the same argument. (prin1-to-string 'foo) => "foo" (prin1-to-string (mark-marker)) => "#" If NOESCAPE is non-`nil', that inhibits use of quoting characters in the output. (This argument is supported in Emacs versions 19 and later.) (prin1-to-string "foo") => "\"foo\"" (prin1-to-string "foo" t) => "foo" See `format', in *Note String Conversion::, for other ways to obtain the printed representation of a Lisp object as a string. - Macro: with-output-to-string body... This macro executes the BODY forms with `standard-output' set up to feed output into a string. Then it returns that string. For example, if the current buffer name is `foo', (with-output-to-string (princ "The buffer is ") (princ (buffer-name))) returns `"The buffer is foo"'.  File: elisp, Node: Output Variables, Prev: Output Functions, Up: Read and Print Variables Affecting Output ========================== - Variable: standard-output The value of this variable is the default output stream--the stream that print functions use when the STREAM argument is `nil'. - Variable: print-escape-newlines If this variable is non-`nil', then newline characters in strings are printed as `\n' and formfeeds are printed as `\f'. Normally these characters are printed as actual newlines and formfeeds. This variable affects the print functions `prin1' and `print' that print with quoting. It does not affect `princ'. Here is an example using `prin1': (prin1 "a\nb") -| "a -| b" => "a b" (let ((print-escape-newlines t)) (prin1 "a\nb")) -| "a\nb" => "a b" In the second expression, the local binding of `print-escape-newlines' is in effect during the call to `prin1', but not during the printing of the result. - Variable: print-escape-nonascii If this variable is non-`nil', then unibyte non-ASCII characters in strings are unconditionally printed as backslash sequences by the print functions `prin1' and `print' that print with quoting. Those functions also use backslash sequences for unibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a multibyte buffer or a marker pointing into one. - Variable: print-escape-multibyte If this variable is non-`nil', then multibyte non-ASCII characters in strings are unconditionally printed as backslash sequences by the print functions `prin1' and `print' that print with quoting. Those functions also use backslash sequences for multibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a unibyte buffer or a marker pointing into one. - Variable: print-length The value of this variable is the maximum number of elements to print in any list, vector or bool-vector. If an object being printed has more than this many elements, it is abbreviated with an ellipsis. If the value is `nil' (the default), then there is no limit. (setq print-length 2) => 2 (print '(1 2 3 4 5)) -| (1 2 ...) => (1 2 ...) - Variable: print-level The value of this variable is the maximum depth of nesting of parentheses and brackets when printed. Any list or vector at a depth exceeding this limit is abbreviated with an ellipsis. A value of `nil' (which is the default) means no limit. These variables are used for detecting and reporting circular and shared structure--but they are only defined in Emacs 21. - Variable: print-circle If non-`nil', this variable enables detection of circular and shared structure in printing. - Variable: print-gensym If non-`nil', this variable enables detection of uninterned symbols (*note Creating Symbols::) in printing. When this is enabled, uninterned symbols print with the prefix `#:', which tells the Lisp reader to produce an uninterned symbol.  File: elisp, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top Minibuffers *********** A "minibuffer" is a special buffer that Emacs commands use to read arguments more complicated than the single numeric prefix argument. These arguments include file names, buffer names, and command names (as in `M-x'). The minibuffer is displayed on the bottom line of the frame, in the same place as the echo area, but only while it is in use for reading an argument. * Menu: * Intro to Minibuffers:: Basic information about minibuffers. * Text from Minibuffer:: How to read a straight text string. * Object from Minibuffer:: How to read a Lisp object or expression. * Minibuffer History:: Recording previous minibuffer inputs so the user can reuse them. * Completion:: How to invoke and customize completion. * Yes-or-No Queries:: Asking a question with a simple answer. * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. * Minibuffer Misc:: Various customization hooks and variables.  File: elisp, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers Introduction to Minibuffers =========================== In most ways, a minibuffer is a normal Emacs buffer. Most operations _within_ a buffer, such as editing commands, work normally in a minibuffer. However, many operations for managing buffers do not apply to minibuffers. The name of a minibuffer always has the form ` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are displayed only in special windows used only for minibuffers; these windows always appear at the bottom of a frame. (Sometimes frames have no minibuffer window, and sometimes a special kind of frame contains nothing but a minibuffer window; see *Note Minibuffers and Frames::.) The text in the minibuffer always starts with the "prompt string", the text that was specified by the program that is using the minibuffer to tell the user what sort of input to type. This text is marked read-only so you won't accidentally delete or change it. It is also marked as a field (*note Fields::), so that certain motion functions, including `beginning-of-line', `forward-word', `forward-sentence', and `forward-paragraph', stop at the boundary between the prompt and the actual text. (In older Emacs versions, the prompt was displayed using a special mechanism and was not part of the buffer contents.) The minibuffer's window is normally a single line; it grows automatically if necessary if the contents require more space. You can explicitly resize it temporarily with the window sizing commands; it reverts to its normal size when the minibuffer is exited. You can resize it permanently by using the window sizing commands in the frame's other window, when the minibuffer is not active. If the frame contains just a minibuffer, you can change the minibuffer's size by changing the frame's size. If a command uses a minibuffer while there is an active minibuffer, this is called a "recursive minibuffer". The first minibuffer is named ` *Minibuf-0*'. Recursive minibuffers are named by incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently entered) is the active minibuffer. We usually call this "the" minibuffer. You can permit or forbid recursive minibuffers by setting the variable `enable-recursive-minibuffers' or by putting properties of that name on command symbols (*note Minibuffer Misc::). Like other buffers, a minibuffer may use any of several local keymaps (*note Keymaps::); these contain various exit commands and in some cases completion commands (*note Completion::). * `minibuffer-local-map' is for ordinary input (no completion). * `minibuffer-local-ns-map' is similar, except that exits just like . This is used mainly for Mocklisp compatibility. * `minibuffer-local-completion-map' is for permissive completion. * `minibuffer-local-must-match-map' is for strict completion and for cautious completion. When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started.