This is ../../info/elisp, produced by makeinfo version 4.11 from elisp.texi. This is edition 3.0 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 23.2. Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License," 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 the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom." INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY  File: elisp, Node: POSIX Regexps, Next: Match Data, Prev: Regexp Search, Up: Searching and Matching 34.5 POSIX Regular Expression Searching ======================================= The usual regular expression functions do backtracking when necessary to handle the `\|' and repetition constructs, but they continue this only until they find _some_ match. Then they succeed and report the first match found. This section describes alternative search functions which perform the full backtracking specified by the POSIX standard for regular expression matching. They continue backtracking until they have tried all possibilities and found all matches, so they can report the longest match, as required by POSIX. This is much slower, so use these functions only when you really need the longest match. The POSIX search and match functions do not properly support the non-greedy repetition operators (*note non-greedy: Regexp Special.). This is because POSIX backtracking conflicts with the semantics of non-greedy repetition. -- Command: posix-search-forward regexp &optional limit noerror repeat This is like `re-search-forward' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. -- Command: posix-search-backward regexp &optional limit noerror repeat This is like `re-search-backward' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. -- Function: posix-looking-at regexp This is like `looking-at' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. -- Function: posix-string-match regexp string &optional start This is like `string-match' except that it performs the full backtracking specified by the POSIX standard for regular expression matching.  File: elisp, Node: Match Data, Next: Search and Replace, Prev: POSIX Regexps, Up: Searching and Matching 34.6 The Match Data =================== Emacs keeps track of the start and end positions of the segments of text found during a search; this is called the "match data". Thanks to the match data, you can search for a complex pattern, such as a date in a mail message, and then extract parts of the match under control of the pattern. Because the match data normally describe the most recent search only, you must be careful not to do another search inadvertently between the search you wish to refer back to and the use of the match data. If you can't avoid another intervening search, you must save and restore the match data around it, to prevent it from being overwritten. * Menu: * Replacing Match:: Replacing a substring that was matched. * Simple Match Data:: Accessing single items of match data, such as where a particular subexpression started. * Entire Match Data:: Accessing the entire match data at once, as a list. * Saving Match Data:: Saving and restoring the match data.  File: elisp, Node: Replacing Match, Next: Simple Match Data, Up: Match Data 34.6.1 Replacing the Text that Matched -------------------------------------- This function replaces all or part of the text matched by the last search. It works by means of the match data. -- Function: replace-match replacement &optional fixedcase literal string subexp This function replaces the text in the buffer (or in STRING) that was matched by the last search. It replaces that text with REPLACEMENT. If you did the last search in a buffer, you should specify `nil' for STRING and make sure that the current buffer when you call `replace-match' is the one in which you did the searching or matching. Then `replace-match' does the replacement by editing the buffer; it leaves point at the end of the replacement text, and returns `t'. If you did the search in a string, pass the same string as STRING. Then `replace-match' does the replacement by constructing and returning a new string. If FIXEDCASE is non-`nil', then `replace-match' uses the replacement text without case conversion; otherwise, it converts the replacement text depending upon the capitalization of the text to be replaced. If the original text is all upper case, this converts the replacement text to upper case. If all words of the original text are capitalized, this capitalizes all the words of the replacement text. If all the words are one-letter and they are all upper case, they are treated as capitalized words rather than all-upper-case words. If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as it is, the only alterations being case changes as needed. If it is `nil' (the default), then the character `\' is treated specially. If a `\' appears in REPLACEMENT, then it must be part of one of the following sequences: `\&' `\&' stands for the entire text being replaced. `\N' `\N', where N is a digit, stands for the text that matched the Nth subexpression in the original regexp. Subexpressions are those expressions grouped inside `\(...\)'. If the Nth subexpression never matched, an empty string is substituted. `\\' `\\' stands for a single `\' in the replacement text. These substitutions occur after case conversion, if any, so the strings they substitute are never case-converted. If SUBEXP is non-`nil', that says to replace just subexpression number SUBEXP of the regexp that was matched, not the entire match. For example, after matching `foo \(ba*r\)', calling `replace-match' with 1 as SUBEXP means to replace just the text that matched `\(ba*r\)'. -- Function: match-substitute-replacement replacement &optional fixedcase literal string subexp This function returns the text that would be inserted into the buffer by `replace-match', but without modifying the buffer. It is useful if you want to present the user with actual replacement result, with constructs like `\N' or `\&' substituted with matched groups. Arguments REPLACEMENT and optional FIXEDCASE, LITERAL, STRING and SUBEXP have the same meaning as for `replace-match'.  File: elisp, Node: Simple Match Data, Next: Entire Match Data, Prev: Replacing Match, Up: Match Data 34.6.2 Simple Match Data Access ------------------------------- This section explains how to use the match data to find out what was matched by the last search or match operation, if it succeeded. You can ask about the entire matching text, or about a particular parenthetical subexpression of a regular expression. The COUNT argument in the functions below specifies which. If COUNT is zero, you are asking about the entire match. If COUNT is positive, it specifies which subexpression you want. Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, `\(...\)'. The COUNTth subexpression is found by counting occurrences of `\(' from the beginning of the whole regular expression. The first subexpression is numbered 1, the second 2, and so on. Only regular expressions can have subexpressions--after a simple string search, the only information available is about the entire match. Every successful search sets the match data. Therefore, you should query the match data immediately after searching, before calling any other function that might perform another search. Alternatively, you may save and restore the match data (*note Saving Match Data::) around the call to functions that could perform another search. A search which fails may or may not alter the match data. In the past, a failing search did not do this, but we may change it in the future. So don't try to rely on the value of the match data after a failing search. -- Function: match-string count &optional in-string This function returns, as a string, the text matched in the last search or match operation. It returns the entire text if COUNT is zero, or just the portion corresponding to the COUNTth parenthetical subexpression, if COUNT is positive. If the last such operation was done against a string with `string-match', then you should pass the same string as the argument IN-STRING. After a buffer search or match, you should omit IN-STRING or pass `nil' for it; but you should make sure that the current buffer when you call `match-string' is the one in which you did the searching or matching. The value is `nil' if COUNT is out of range, or for a subexpression inside a `\|' alternative that wasn't used or a repetition that repeated zero times. -- Function: match-string-no-properties count &optional in-string This function is like `match-string' except that the result has no text properties. -- Function: match-beginning count This function returns the position of the start of text matched by the last regular expression searched for, or a subexpression of it. If COUNT is zero, then the value is the position of the start of the entire match. Otherwise, COUNT specifies a subexpression in the regular expression, and the value of the function is the starting position of the match for that subexpression. The value is `nil' for a subexpression inside a `\|' alternative that wasn't used or a repetition that repeated zero times. -- Function: match-end count This function is like `match-beginning' except that it returns the position of the end of the match, rather than the position of the beginning. Here is an example of using the match data, with a comment showing the positions within the text: (string-match "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.") ;0123456789 => 4 (match-string 0 "The quick fox jumped quickly.") => "quick" (match-string 1 "The quick fox jumped quickly.") => "qu" (match-string 2 "The quick fox jumped quickly.") => "ick" (match-beginning 1) ; The beginning of the match => 4 ; with `qu' is at index 4. (match-beginning 2) ; The beginning of the match => 6 ; with `ick' is at index 6. (match-end 1) ; The end of the match => 6 ; with `qu' is at index 6. (match-end 2) ; The end of the match => 9 ; with `ick' is at index 9. Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word `in'. The beginning of the entire match is at the 9th character of the buffer (`T'), and the beginning of the match for the first subexpression is at the 13th character (`c'). (list (re-search-forward "The \\(cat \\)") (match-beginning 0) (match-beginning 1)) => (17 9 13) ---------- Buffer: foo ---------- I read "The cat -!-in the hat comes back" twice. ^ ^ 9 13 ---------- Buffer: foo ---------- (In this case, the index returned is a buffer position; the first character of the buffer counts as 1.)  File: elisp, Node: Entire Match Data, Next: Saving Match Data, Prev: Simple Match Data, Up: Match Data 34.6.3 Accessing the Entire Match Data -------------------------------------- The functions `match-data' and `set-match-data' read or write the entire match data, all at once. -- Function: match-data &optional integers reuse reseat This function returns a list of positions (markers or integers) that record all the information on what text the last search matched. Element zero is the position of the beginning of the match for the whole expression; element one is the position of the end of the match for the expression. The next two elements are the positions of the beginning and end of the match for the first subexpression, and so on. In general, element number 2N corresponds to `(match-beginning N)'; and element number 2N + 1 corresponds to `(match-end N)'. Normally all the elements are markers or `nil', but if INTEGERS is non-`nil', that means to use integers instead of markers. (In that case, the buffer itself is appended as an additional element at the end of the list, to facilitate complete restoration of the match data.) If the last match was done on a string with `string-match', then integers are always used, since markers can't point into a string. If REUSE is non-`nil', it should be a list. In that case, `match-data' stores the match data in REUSE. That is, REUSE is destructively modified. REUSE does not need to have the right length. If it is not long enough to contain the match data, it is extended. If it is too long, the length of REUSE stays the same, but the elements that were not used are set to `nil'. The purpose of this feature is to reduce the need for garbage collection. If RESEAT is non-`nil', all markers on the REUSE list are reseated to point to nowhere. As always, there must be no possibility of intervening searches between the call to a search function and the call to `match-data' that is intended to access the match data for that search. (match-data) => (# # # #) -- Function: set-match-data match-list &optional reseat This function sets the match data from the elements of MATCH-LIST, which should be a list that was the value of a previous call to `match-data'. (More precisely, anything that has the same format will work.) If MATCH-LIST refers to a buffer that doesn't exist, you don't get an error; that sets the match data in a meaningless but harmless way. If RESEAT is non-`nil', all markers on the MATCH-LIST list are reseated to point to nowhere. `store-match-data' is a semi-obsolete alias for `set-match-data'.  File: elisp, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data 34.6.4 Saving and Restoring the Match Data ------------------------------------------ When you call a function that may do a search, you may need to save and restore the match data around that call, if you want to preserve the match data from an earlier search for later use. Here is an example that shows the problem that arises if you fail to save the match data: (re-search-forward "The \\(cat \\)") => 48 (foo) ; Perhaps `foo' does ; more searching. (match-end 0) => 61 ; Unexpected result--not 48! You can save and restore the match data with `save-match-data': -- Macro: save-match-data body... This macro executes BODY, saving and restoring the match data around it. The return value is the value of the last form in BODY. You could use `set-match-data' together with `match-data' to imitate the effect of the special form `save-match-data'. Here is how: (let ((data (match-data))) (unwind-protect ... ; Ok to change the original match data. (set-match-data data))) Emacs automatically saves and restores the match data when it runs process filter functions (*note Filter Functions::) and process sentinels (*note Sentinels::).  File: elisp, Node: Search and Replace, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching 34.7 Search and Replace ======================= If you want to find all matches for a regexp in part of the buffer, and replace them, the best way is to write an explicit loop using `re-search-forward' and `replace-match', like this: (while (re-search-forward "foo[ \t]+bar" nil t) (replace-match "foobar")) *Note Replacing the Text that Matched: Replacing Match, for a description of `replace-match'. However, replacing matches in a string is more complex, especially if you want to do it efficiently. So Emacs provides a function to do this. -- Function: replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start This function copies STRING and searches it for matches for REGEXP, and replaces them with REP. It returns the modified copy. If START is non-`nil', the search for matches starts at that index in STRING, so matches starting before that index are not changed. This function uses `replace-match' to do the replacement, and it passes the optional arguments FIXEDCASE, LITERAL and SUBEXP along to `replace-match'. Instead of a string, REP can be a function. In that case, `replace-regexp-in-string' calls REP for each match, passing the text of the match as its sole argument. It collects the value REP returns and passes that to `replace-match' as the replacement string. The match-data at this point are the result of matching REGEXP against a substring of STRING. If you want to write a command along the lines of `query-replace', you can use `perform-replace' to do the work. -- Function: perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end This function is the guts of `query-replace' and related commands. It searches for occurrences of FROM-STRING in the text between positions START and END and replaces some or all of them. If START is `nil' (or omitted), point is used instead, and the end of the buffer's accessible portion is used for END. If QUERY-FLAG is `nil', it replaces all occurrences; otherwise, it asks the user what to do about each one. If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a regular expression; otherwise, it must match literally. If DELIMITED-FLAG is non-`nil', then only replacements surrounded by word boundaries are considered. The argument REPLACEMENTS specifies what to replace occurrences with. If it is a string, that string is used. It can also be a list of strings, to be used in cyclic order. If REPLACEMENTS is a cons cell, `(FUNCTION . DATA)', this means to call FUNCTION after each match to get the replacement text. This function is called with two arguments: DATA, and the number of replacements already made. If REPEAT-COUNT is non-`nil', it should be an integer. Then it specifies how many times to use each of the strings in the REPLACEMENTS list before advancing cyclically to the next one. If FROM-STRING contains upper-case letters, then `perform-replace' binds `case-fold-search' to `nil', and it uses the `replacements' without altering the case of them. Normally, the keymap `query-replace-map' defines the possible user responses for queries. The argument MAP, if non-`nil', specifies a keymap to use instead of `query-replace-map'. This function uses one of two functions to search for the next occurrence of FROM-STRING. These functions are specified by the values of two variables: `replace-re-search-function' and `replace-search-function'. The former is called when the argument REGEXP-FLAG is non-`nil', the latter when it is `nil'. -- Variable: query-replace-map This variable holds a special keymap that defines the valid user responses for `perform-replace' and the commands that use it, as well as `y-or-n-p' and `map-y-or-n-p'. This map is unusual in two ways: * The "key bindings" are not commands, just symbols that are meaningful to the functions that use this map. * Prefix keys are not supported; each key binding must be for a single-event key sequence. This is because the functions don't use `read-key-sequence' to get the input; instead, they read a single event and look it up "by hand." Here are the meaningful "bindings" for `query-replace-map'. Several of them are meaningful only for `query-replace' and friends. `act' Do take the action being considered--in other words, "yes." `skip' Do not take action for this question--in other words, "no." `exit' Answer this question "no," and give up on the entire series of questions, assuming that the answers will be "no." `act-and-exit' Answer this question "yes," and give up on the entire series of questions, assuming that subsequent answers will be "no." `act-and-show' Answer this question "yes," but show the results--don't advance yet to the next question. `automatic' Answer this question and all subsequent questions in the series with "yes," without further user interaction. `backup' Move back to the previous place that a question was asked about. `edit' Enter a recursive edit to deal with this question--instead of any other action that would normally be taken. `delete-and-edit' Delete the text being considered, then enter a recursive edit to replace it. `recenter' Redisplay and center the window, then ask the same question again. `quit' Perform a quit right away. Only `y-or-n-p' and related functions use this answer. `help' Display some help, then ask again. -- Variable: multi-query-replace-map This variable holds a keymap that extends `query-replace-map' by providing additional keybindings that are useful in multi-buffer replacements. -- Variable: replace-search-function This variable specifies a function that `perform-replace' calls to search for the next string to replace. Its default value is `search-forward'. Any other value should name a function of 3 arguments: the first 3 arguments of `search-forward' (*note String Search::). -- Variable: replace-re-search-function This variable specifies a function that `perform-replace' calls to search for the next regexp to replace. Its default value is `re-search-forward'. Any other value should name a function of 3 arguments: the first 3 arguments of `re-search-forward' (*note Regexp Search::).  File: elisp, Node: Standard Regexps, Prev: Search and Replace, Up: Searching and Matching 34.8 Standard Regular Expressions Used in Editing ================================================= This section describes some variables that hold regular expressions used for certain purposes in editing: -- User Option: page-delimiter This is the regular expression describing line-beginnings that separate pages. The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this matches a line that starts with a formfeed character. The following two regular expressions should _not_ assume the match always starts at the beginning of a line; they should not use `^' to anchor the match. Most often, the paragraph commands do check for a match only at the beginning of a line, which means that `^' would be superfluous. When there is a nonzero left margin, they accept matches that start after the left margin. In that case, a `^' would be incorrect. However, a `^' is harmless in modes where a left margin is never used. -- User Option: paragraph-separate This is the regular expression for recognizing the beginning of a line that separates paragraphs. (If you change this, you may have to change `paragraph-start' also.) The default value is `"[ \t\f]*$"', which matches a line that consists entirely of spaces, tabs, and form feeds (after its left margin). -- User Option: paragraph-start This is the regular expression for recognizing the beginning of a line that starts _or_ separates paragraphs. The default value is `"\f\\|[ \t]*$"', which matches a line containing only whitespace or starting with a form feed (after its left margin). -- User Option: sentence-end If non-`nil', the value should be a regular expression describing the end of a sentence, including the whitespace following the sentence. (All paragraph boundaries also end sentences, regardless.) If the value is `nil', the default, then the function `sentence-end' has to construct the regexp. That is why you should always call the function `sentence-end' to obtain the regexp to be used to recognize the end of a sentence. -- Function: sentence-end This function returns the value of the variable `sentence-end', if non-`nil'. Otherwise it returns a default value based on the values of the variables `sentence-end-double-space' (*note Definition of sentence-end-double-space::), `sentence-end-without-period' and `sentence-end-without-space'.  File: elisp, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top 35 Syntax Tables **************** A "syntax table" specifies the syntactic textual function of each character. This information is used by the "parsing functions", the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (*note Word Motion::) and the list motion functions (*note List Motion::), as well as the functions in this chapter. * Menu: * Basics: Syntax Basics. Basic concepts of syntax tables. * Desc: Syntax Descriptors. How characters are classified. * Syntax Table Functions:: How to create, examine and alter syntax tables. * Syntax Properties:: Overriding syntax with text properties. * Motion and Syntax:: Moving over characters with certain syntaxes. * Parsing Expressions:: Parsing balanced expressions using the syntax table. * Standard Syntax Tables:: Syntax tables used by various major modes. * Syntax Table Internals:: How syntax table information is stored. * Categories:: Another way of classifying character syntax.  File: elisp, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables 35.1 Syntax Table Concepts ========================== A "syntax table" provides Emacs with the information that determines the syntactic use of each character in a buffer. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (*note Word Motion::) and the list motion functions (*note List Motion::) as well as the functions in this chapter. A syntax table is a char-table (*note Char-Tables::). The element at index C describes the character with code C. The element's value should be a list that encodes the syntax of the character in question. Syntax tables are used only for moving across text, not for the Emacs Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed. (Some Lisp systems provide ways to redefine the read syntax, but we decided to leave this feature out of Emacs Lisp for simplicity.) Each buffer has its own major mode, and each major mode has its own idea of the syntactic class of various characters. For example, in Lisp mode, the character `;' begins a comment, but in C mode, it terminates a statement. To support these variations, Emacs makes the choice of syntax table local to each buffer. Typically, each major mode has its own syntax table and installs that table in each buffer that uses that mode. Changing this table alters the syntax in all those buffers as well as in any buffers subsequently put in that mode. Occasionally several similar modes share one syntax table. *Note Example Major Modes::, for an example of how to set up a syntax table. A syntax table can inherit the data for some characters from the standard syntax table, while specifying other characters itself. The "inherit" syntax class means "inherit this character's syntax from the standard syntax table." Just changing the standard syntax for a character affects all syntax tables that inherit from it. -- Function: syntax-table-p object This function returns `t' if OBJECT is a syntax table.  File: elisp, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables 35.2 Syntax Descriptors ======================= This section describes the syntax classes and flags that denote the syntax of a character, and how they are represented as a "syntax descriptor", which is a Lisp string that you pass to `modify-syntax-entry' to specify the syntax you want. The syntax table specifies a syntax class for each character. There is no necessary relationship between the class of a character in one syntax table and its class in any other table. Each class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually the designator character is one that is often assigned that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has. Thus, `\' as a designator character always gives "escape character" syntax, regardless of what syntax `\' currently has. A syntax descriptor is a Lisp string that specifies a syntax class, a matching character (used only for the parenthesis classes) and flags. The first character is the designator for a syntax class. The second character is the character to match; if it is unused, put a space there. Then come the characters for any desired flags. If no matching character or flags are needed, one character is sufficient. For example, the syntax descriptor for the character `*' in C mode is `. 23' (i.e., punctuation, matching character slot unused, second character of a comment-starter, first character of a comment-ender), and the entry for `/' is `. 14' (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender). * Menu: * Syntax Class Table:: Table of syntax classes. * Syntax Flags:: Additional flags each character can have.  File: elisp, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors 35.2.1 Table of Syntax Classes ------------------------------ Here is a table of syntax classes, the characters that stand for them, their meanings, and examples of their use. -- Syntax class: whitespace character "Whitespace characters" (designated by ` ' or `-') separate symbols and words from each other. Typically, whitespace characters have no other syntactic significance, and multiple whitespace characters are syntactically equivalent to a single one. Space, tab, newline and formfeed are classified as whitespace in almost all major modes. -- Syntax class: word constituent "Word constituents" (designated by `w') are parts of words in human languages, and are typically used in variable and command names in programs. All upper- and lower-case letters, and the digits, are typically word constituents. -- Syntax class: symbol constituent "Symbol constituents" (designated by `_') are the extra characters that are used in variable and command names along with word constituents. For example, the symbol constituents class is used in Lisp mode to indicate that certain characters may be part of symbol names even though they are not part of English words. These characters are `$&*+-_<>'. In standard C, the only non-word-constituent character that is valid in symbols is underscore (`_'). -- Syntax class: punctuation character "Punctuation characters" (designated by `.') are those characters that are used as punctuation in English, or are used in some way in a programming language to separate symbols from one another. Some programming language modes, such as Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or word constituents all have other uses. Other programming language modes, such as C mode, use punctuation syntax for operators. -- Syntax class: open parenthesis character -- Syntax class: close parenthesis character Open and close "parenthesis characters" are characters used in dissimilar pairs to surround sentences or expressions. Such a grouping is begun with an open parenthesis character and terminated with a close. Each open parenthesis character matches a particular close parenthesis character, and vice versa. Normally, Emacs indicates momentarily the matching open parenthesis when you insert a close parenthesis. *Note Blinking::. The class of open parentheses is designated by `(', and that of close parentheses by `)'. In English text, and in C code, the parenthesis pairs are `()', `[]', and `{}'. In Emacs Lisp, the delimiters for lists and vectors (`()' and `[]') are classified as parenthesis characters. -- Syntax class: string quote "String quote characters" (designated by `"') are used in many languages, including Lisp and C, to delimit string constants. The same string quote character appears at the beginning and the end of a string. Such quoted strings do not nest. The parsing facilities of Emacs consider a string as a single token. The usual syntactic meanings of the characters in the string are suppressed. The Lisp modes have two string quote characters: double-quote (`"') and vertical bar (`|'). `|' is not used in Emacs Lisp, but it is used in Common Lisp. C also has two string quote characters: double-quote for strings, and single-quote (`'') for character constants. English text has no string quote characters because English is not a programming language. Although quotation marks are used in English, we do not want them to turn off the usual syntactic properties of other characters in the quotation. -- Syntax class: escape-syntax character An "escape character" (designated by `\') starts an escape sequence such as is used in C string and character constants. The character `\' belongs to this class in both C and Lisp. (In C, it is used thus only inside strings, but it turns out to cause no trouble to treat it this way throughout C code.) Characters in this class count as part of words if `words-include-escapes' is non-`nil'. *Note Word Motion::. -- Syntax class: character quote A "character quote character" (designated by `/') quotes the following character so that it loses its normal syntactic meaning. This differs from an escape character in that only the character immediately following is ever affected. Characters in this class count as part of words if `words-include-escapes' is non-`nil'. *Note Word Motion::. This class is used for backslash in TeX mode. -- Syntax class: paired delimiter "Paired delimiter characters" (designated by `$') are like string quote characters except that the syntactic properties of the characters between the delimiters are not suppressed. Only TeX mode uses a paired delimiter presently--the `$' that both enters and leaves math mode. -- Syntax class: expression prefix An "expression prefix operator" (designated by `'') is used for syntactic operators that are considered as part of an expression if they appear next to one. In Lisp modes, these characters include the apostrophe, `'' (used for quoting), the comma, `,' (used in macros), and `#' (used in the read syntax for certain data types). -- Syntax class: comment starter -- Syntax class: comment ender The "comment starter" and "comment ender" characters are used in various languages to delimit comments. These classes are designated by `<' and `>', respectively. English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one. -- Syntax class: inherit standard syntax This syntax class does not specify a particular syntax. It says to look in the standard syntax table to find the syntax of this character. The designator for this syntax class is `@'. -- Syntax class: generic comment delimiter A "generic comment delimiter" (designated by `!') starts or ends a special kind of comment. _Any_ generic comment delimiter matches _any_ generic comment delimiter, but they cannot match a comment starter or comment ender; generic comment delimiters can only match each other. This syntax class is primarily meant for use with the `syntax-table' text property (*note Syntax Properties::). You can mark any range of characters as forming a comment, by giving the first and last characters of the range `syntax-table' properties identifying them as generic comment delimiters. -- Syntax class: generic string delimiter A "generic string delimiter" (designated by `|') starts or ends a string. This class differs from the string quote class in that _any_ generic string delimiter can match any other generic string delimiter; but they do not match ordinary string quote characters. This syntax class is primarily meant for use with the `syntax-table' text property (*note Syntax Properties::). You can mark any range of characters as forming a string constant, by giving the first and last characters of the range `syntax-table' properties identifying them as generic string delimiters.  File: elisp, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors 35.2.2 Syntax Flags ------------------- In addition to the classes, entries for characters in a syntax table can specify flags. There are seven possible flags, represented by the characters `1', `2', `3', `4', `b', `n', and `p'. All the flags except `n' and `p' are used to describe multi-character comment delimiters. The digit flags indicate that a character can _also_ be part of a comment sequence, in addition to the syntactic properties associated with its character class. The flags are independent of the class and each other for the sake of characters such as `*' in C mode, which is a punctuation character, _and_ the second character of a start-of-comment sequence (`/*'), _and_ the first character of an end-of-comment sequence (`*/'). Here is a table of the possible flags for a character C, and what they mean: * `1' means C is the start of a two-character comment-start sequence. * `2' means C is the second character of such a sequence. * `3' means C is the start of a two-character comment-end sequence. * `4' means C is the second character of such a sequence. * `b' means that C as a comment delimiter belongs to the alternative "b" comment style. Emacs supports two comment styles simultaneously in any one syntax table. This is for the sake of C++. Each style of comment syntax has its own comment-start sequence and its own comment-end sequence. Each comment must stick to one style or the other; thus, if it starts with the comment-start sequence of style "b," it must also end with the comment-end sequence of style "b." The two comment-start sequences must begin with the same character; only the second character may differ. Mark the second character of the "b"-style comment-start sequence with the `b' flag. A comment-end sequence (one or two characters) applies to the "b" style if its first character has the `b' flag set; otherwise, it applies to the "a" style. The appropriate comment syntax settings for C++ are as follows: `/' `124b' `*' `23' newline `>b' This defines four comment-delimiting sequences: `/*' This is a comment-start sequence for "a" style because the second character, `*', does not have the `b' flag. `//' This is a comment-start sequence for "b" style because the second character, `/', does have the `b' flag. `*/' This is a comment-end sequence for "a" style because the first character, `*', does not have the `b' flag. newline This is a comment-end sequence for "b" style, because the newline character has the `b' flag. * `n' on a comment delimiter character specifies that this kind of comment can be nested. For a two-character comment delimiter, `n' on either character makes it nestable. * `p' identifies an additional "prefix character" for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax classes. The function `backward-prefix-chars' moves back over these characters, as well as over characters whose primary syntax class is prefix (`''). *Note Motion and Syntax::.  File: elisp, Node: Syntax Table Functions, Next: Syntax Properties, Prev: Syntax Descriptors, Up: Syntax Tables 35.3 Syntax Table Functions =========================== In this section we describe functions for creating, accessing and altering syntax tables. -- Function: make-syntax-table &optional table This function creates a new syntax table, with all values initialized to `nil'. If TABLE is non-`nil', it becomes the parent of the new syntax table, otherwise the standard syntax table is the parent. Like all char-tables, a syntax table inherits from its parent. Thus the original syntax of all characters in the returned syntax table is determined by the parent. *Note Char-Tables::. Most major mode syntax tables are created in this way. -- Function: copy-syntax-table &optional table This function constructs a copy of TABLE and returns it. If TABLE is not supplied (or is `nil'), it returns a copy of the standard syntax table. Otherwise, an error is signaled if TABLE is not a syntax table. -- Command: modify-syntax-entry char syntax-descriptor &optional table This function sets the syntax entry for CHAR according to SYNTAX-DESCRIPTOR. CHAR can be a character, or a cons cell of the form `(MIN . MAX)'; in the latter case, the function sets the syntax entries for all characters in the range between MIN and MAX, inclusive. The syntax is changed only for TABLE, which defaults to the current buffer's syntax table, and not in any other syntax table. The argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a string beginning with a class designator character, and optionally containing a matching character and flags as well. *Note Syntax Descriptors::. This function always returns `nil'. The old syntax information in the table for this character is discarded. An error is signaled if the first character of the syntax descriptor is not one of the seventeen syntax class designator characters. An error is also signaled if CHAR is not a character. Examples: ;; Put the space character in class whitespace. (modify-syntax-entry ?\s " ") => nil ;; Make `$' an open parenthesis character, ;; with `^' as its matching close. (modify-syntax-entry ?$ "(^") => nil ;; Make `^' a close parenthesis character, ;; with `$' as its matching open. (modify-syntax-entry ?^ ")$") => nil ;; Make `/' a punctuation character, ;; the first character of a start-comment sequence, ;; and the second character of an end-comment sequence. ;; This is used in C mode. (modify-syntax-entry ?/ ". 14") => nil -- Function: char-syntax character This function returns the syntax class of CHARACTER, represented by its mnemonic designator character. This returns _only_ the class, not any matching parenthesis or flags. An error is signaled if CHAR is not a character. The following examples apply to C mode. The first example shows that the syntax class of space is whitespace (represented by a space). The second example shows that the syntax of `/' is punctuation. This does not show the fact that it is also part of comment-start and -end sequences. The third example shows that open parenthesis is in the class of open parentheses. This does not show the fact that it has a matching character, `)'. (string (char-syntax ?\s)) => " " (string (char-syntax ?/)) => "." (string (char-syntax ?\()) => "(" We use `string' to make it easier to see the character returned by `char-syntax'. -- Function: set-syntax-table table This function makes TABLE the syntax table for the current buffer. It returns TABLE. -- Function: syntax-table This function returns the current syntax table, which is the table for the current buffer. -- Macro: with-syntax-table TABLE BODY... This macro executes BODY using TABLE as the current syntax table. It returns the value of the last form in BODY, after restoring the old current syntax table. Since each buffer has its own current syntax table, we should make that more precise: `with-syntax-table' temporarily alters the current syntax table of whichever buffer is current at the time the macro execution starts. Other buffers are not affected.  File: elisp, Node: Syntax Properties, Next: Motion and Syntax, Prev: Syntax Table Functions, Up: Syntax Tables 35.4 Syntax Properties ====================== When the syntax table is not flexible enough to specify the syntax of a language, you can use `syntax-table' text properties to override the syntax table for specific character occurrences in the buffer. *Note Text Properties::. You can use Font Lock mode to set `syntax-table' text properties. *Note Setting Syntax Properties::. The valid values of `syntax-table' text property are: SYNTAX-TABLE If the property value is a syntax table, that table is used instead of the current buffer's syntax table to determine the syntax for this occurrence of the character. `(SYNTAX-CODE . MATCHING-CHAR)' A cons cell of this format specifies the syntax for this occurrence of the character. (*note Syntax Table Internals::) `nil' If the property is `nil', the character's syntax is determined from the current syntax table in the usual way. -- Variable: parse-sexp-lookup-properties If this is non-`nil', the syntax scanning functions pay attention to syntax text properties. Otherwise they use only the current syntax table.  File: elisp, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Properties, Up: Syntax Tables 35.5 Motion and Syntax ====================== This section describes functions for moving across characters that have certain syntax classes. -- Function: skip-syntax-forward syntaxes &optional limit This function moves point forward across characters having syntax classes mentioned in SYNTAXES (a string of syntax class characters). It stops when it encounters the end of the buffer, or position LIMIT (if specified), or a character it is not supposed to skip. If SYNTAXES starts with `^', then the function skips characters whose syntax is _not_ in SYNTAXES. The return value is the distance traveled, which is a nonnegative integer. -- Function: skip-syntax-backward syntaxes &optional limit This function moves point backward across characters whose syntax classes are mentioned in SYNTAXES. It stops when it encounters the beginning of the buffer, or position LIMIT (if specified), or a character it is not supposed to skip. If SYNTAXES starts with `^', then the function skips characters whose syntax is _not_ in SYNTAXES. The return value indicates the distance traveled. It is an integer that is zero or less. -- Function: backward-prefix-chars This function moves point backward over any number of characters with expression prefix syntax. This includes both characters in the expression prefix syntax class, and characters with the `p' flag.  File: elisp, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables 35.6 Parsing Expressions ======================== This section describes functions for parsing and scanning balanced expressions, also known as "sexps". Basically, a sexp is either a balanced parenthetical grouping, a string, or a symbol name (a sequence of characters whose syntax is either word constituent or symbol constituent). However, characters whose syntax is expression prefix are treated as part of the sexp if they appear next to it. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C expressions when in C mode. *Note List Motion::, for convenient higher-level functions for moving over balanced expressions. A character's syntax controls how it changes the state of the parser, rather than describing the state itself. For example, a string delimiter character toggles the parser state between "in-string" and "in-code," but the syntax of characters does not directly say whether they are inside a string. For example (note that 15 is the syntax code for generic string delimiters), (put-text-property 1 9 'syntax-table '(15 . nil)) does not tell Emacs that the first eight chars of the current buffer are a string, but rather that they are all string delimiters. As a result, Emacs treats them as four consecutive empty string constants. * Menu: * Motion via Parsing:: Motion functions that work by parsing. * Position Parse:: Determining the syntactic state of a position. * Parser State:: How Emacs represents a syntactic state. * Low-Level Parsing:: Parsing across a specified region. * Control Parsing:: Parameters that affect parsing.  File: elisp, Node: Motion via Parsing, Next: Position Parse, Up: Parsing Expressions 35.6.1 Motion Commands Based on Parsing --------------------------------------- This section describes simple point-motion functions that operate based on parsing expressions. -- Function: scan-lists from count depth This function scans forward COUNT balanced parenthetical groupings from position FROM. It returns the position where the scan stops. If COUNT is negative, the scan moves backwards. If DEPTH is nonzero, parenthesis depth counting begins from that value. The only candidates for stopping are places where the depth in parentheses becomes zero; `scan-lists' counts COUNT such places and then stops. Thus, a positive value for DEPTH means go out DEPTH levels of parenthesis. Scanning ignores comments if `parse-sexp-ignore-comments' is non-`nil'. If the scan reaches the beginning or end of the buffer (or its accessible portion), and the depth is not zero, an error is signaled. If the depth is zero but the count is not used up, `nil' is returned. -- Function: scan-sexps from count This function scans forward COUNT sexps from position FROM. It returns the position where the scan stops. If COUNT is negative, the scan moves backwards. Scanning ignores comments if `parse-sexp-ignore-comments' is non-`nil'. If the scan reaches the beginning or end of (the accessible part of) the buffer while in the middle of a parenthetical grouping, an error is signaled. If it reaches the beginning or end between groupings but before count is used up, `nil' is returned. -- Function: forward-comment count This function moves point forward across COUNT complete comments (that is, including the starting delimiter and the terminating delimiter if any), plus any whitespace encountered on the way. It moves backward if COUNT is negative. If it encounters anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. This includes (for instance) finding the end of a comment when moving forward and expecting the beginning of one. The function also stops immediately after moving over the specified number of complete comments. If COUNT comments are found as expected, with nothing except whitespace between them, it returns `t'; otherwise it returns `nil'. This function cannot tell whether the "comments" it traverses are embedded within a string. If they look like comments, it treats them as comments. To move forward over all comments and whitespace following point, use `(forward-comment (buffer-size))'. `(buffer-size)' is a good argument to use, because the number of comments in the buffer cannot exceed that many.  File: elisp, Node: Position Parse, Next: Parser State, Prev: Motion via Parsing, Up: Parsing Expressions 35.6.2 Finding the Parse State for a Position --------------------------------------------- For syntactic analysis, such as in indentation, often the useful thing is to compute the syntactic state corresponding to a given buffer position. This function does that conveniently. -- Function: syntax-ppss &optional pos This function returns the parser state (see next section) that the parser would reach at position POS starting from the beginning of the buffer. This is equivalent to `(parse-partial-sexp (point-min) POS)', except that `syntax-ppss' uses a cache to speed up the computation. Due to this optimization, the 2nd value (previous complete subexpression) and 6th value (minimum parenthesis depth) of the returned parser state are not meaningful. `syntax-ppss' automatically hooks itself to `before-change-functions' to keep its cache consistent. But updating can fail if `syntax-ppss' is called while `before-change-functions' is temporarily let-bound, or if the buffer is modified without obeying the hook, such as when using `inhibit-modification-hooks'. For this reason, it is sometimes necessary to flush the cache manually. -- Function: syntax-ppss-flush-cache beg &rest ignored-args This function flushes the cache used by `syntax-ppss', starting at position BEG. The remaining arguments, IGNORED-ARGS, are ignored; this function accepts them so that it can be directly used on hooks such as `before-change-functions' (*note Change Hooks::). Major modes can make `syntax-ppss' run faster by specifying where it needs to start parsing. -- Variable: syntax-begin-function If this is non-`nil', it should be a function that moves to an earlier buffer position where the parser state is equivalent to `nil'--in other words, a position outside of any comment, string, or parenthesis. `syntax-ppss' uses it to further optimize its computations, when the cache gives no help.  File: elisp, Node: Parser State, Next: Low-Level Parsing, Prev: Position Parse, Up: Parsing Expressions 35.6.3 Parser State ------------------- A "parser state" is a list of ten elements describing the final state of parsing text syntactically as part of an expression. The parsing functions in the following sections return a parser state as the value, and in some cases accept one as an argument also, so that you can resume parsing after it stops. Here are the meanings of the elements of the parser state: 0. The depth in parentheses, counting from 0. *Warning:* this can be negative if there are more close parens than open parens between the start of the defun and point. 1. The character position of the start of the innermost parenthetical grouping containing the stopping point; `nil' if none. 2. The character position of the start of the last complete subexpression terminated; `nil' if none. 3. Non-`nil' if inside a string. More precisely, this is the character that will terminate the string, or `t' if a generic string delimiter character should terminate it. 4. `t' if inside a comment (of either style), or the comment nesting level if inside a kind of comment that can be nested. 5. `t' if point is just after a quote character. 6. The minimum parenthesis depth encountered during this scan. 7. What kind of comment is active: `nil' for a comment of style "a" or when not inside a comment, `t' for a comment of style "b," and `syntax-table' for a comment that should be ended by a generic comment delimiter character. 8. The string or comment start position. While inside a comment, this is the position where the comment began; while inside a string, this is the position where the string began. When outside of strings and comments, this element is `nil'. 9. Internal data for continuing the parsing. The meaning of this data is subject to change; it is used if you pass this list as the STATE argument to another call. Elements 1, 2, and 6 are ignored in a state which you pass as an argument to continue parsing, and elements 8 and 9 are used only in trivial cases. Those elements serve primarily to convey information to the Lisp program which does the parsing. One additional piece of useful information is available from a parser state using this function: -- Function: syntax-ppss-toplevel-pos state This function extracts, from parser state STATE, the last position scanned in the parse which was at top level in grammatical structure. "At top level" means outside of any parentheses, comments, or strings. The value is `nil' if STATE represents a parse which has arrived at a top level position. We have provided this access function rather than document how the data is represented in the state, because we plan to change the representation in the future.  File: elisp, Node: Low-Level Parsing, Next: Control Parsing, Prev: Parser State, Up: Parsing Expressions 35.6.4 Low-Level Parsing ------------------------ The most basic way to use the expression parser is to tell it to start at a given position with a certain state, and parse up to a specified end position. -- Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment This function parses a sexp in the current buffer starting at START, not scanning past LIMIT. It stops at position LIMIT or when certain criteria described below are met, and sets point to the location where parsing stops. It returns a parser state describing the status of the parse at the point where it stops. If the third argument TARGET-DEPTH is non-`nil', parsing stops if the depth in parentheses becomes equal to TARGET-DEPTH. The depth starts at 0, or at whatever is given in STATE. If the fourth argument STOP-BEFORE is non-`nil', parsing stops when it comes to any character that starts a sexp. If STOP-COMMENT is non-`nil', parsing stops when it comes to the start of a comment. If STOP-COMMENT is the symbol `syntax-table', parsing stops after the start of a comment or a string, or the end of a comment or a string, whichever comes first. If STATE is `nil', START is assumed to be at the top level of parenthesis structure, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of the structure. To do this, you must provide a STATE argument that describes the initial status of parsing. The value returned by a previous call to `parse-partial-sexp' will do nicely.  File: elisp, Node: Control Parsing, Prev: Low-Level Parsing, Up: Parsing Expressions 35.6.5 Parameters to Control Parsing ------------------------------------ -- Variable: multibyte-syntax-as-symbol If this variable is non-`nil', `scan-sexps' treats all non-ASCII characters as symbol constituents regardless of what the syntax table says about them. (However, text properties can still override the syntax.) -- User Option: parse-sexp-ignore-comments If the value is non-`nil', then comments are treated as whitespace by the functions in this section and by `forward-sexp', `scan-lists' and `scan-sexps'. The behavior of `parse-partial-sexp' is also affected by `parse-sexp-lookup-properties' (*note Syntax Properties::). You can use `forward-comment' to move forward or backward over one comment or several comments.  File: elisp, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables 35.7 Some Standard Syntax Tables ================================ Most of the major modes in Emacs have their own syntax tables. Here are several of them: -- Function: standard-syntax-table This function returns the standard syntax table, which is the syntax table used in Fundamental mode. -- Variable: text-mode-syntax-table The value of this variable is the syntax table used in Text mode. -- Variable: c-mode-syntax-table The value of this variable is the syntax table for C-mode buffers. -- Variable: emacs-lisp-mode-syntax-table The value of this variable is the syntax table used in Emacs Lisp mode by editing commands. (It has no effect on the Lisp `read' function.)  File: elisp, Node: Syntax Table Internals, Next: Categories, Prev: Standard Syntax Tables, Up: Syntax Tables 35.8 Syntax Table Internals =========================== Lisp programs don't usually work with the elements directly; the Lisp-level syntax table functions usually work with syntax descriptors (*note Syntax Descriptors::). Nonetheless, here we document the internal format. This format is used mostly when manipulating syntax properties. Each element of a syntax table is a cons cell of the form `(SYNTAX-CODE . MATCHING-CHAR)'. The CAR, SYNTAX-CODE, is an integer that encodes the syntax class, and any flags. The CDR, MATCHING-CHAR, is non-`nil' if a character to match was specified. This table gives the value of SYNTAX-CODE which corresponds to each syntactic type. Integer Class Integer Class Integer Class 0 whitespace 5 close parenthesis 10 character quote 1 punctuation 6 expression prefix 11 comment-start 2 word 7 string quote 12 comment-end 3 symbol 8 paired delimiter 13 inherit 4 open parenthesis 9 escape 14 generic comment 15 generic string For example, the usual syntax value for `(' is `(4 . 41)'. (41 is the character code for `)'.) The flags are encoded in higher order bits, starting 16 bits from the least significant bit. This table gives the power of two which corresponds to each syntax flag. Prefix Flag Prefix Flag Prefix Flag `1' `(lsh 1 16)' `4' `(lsh 1 19)' `b' `(lsh 1 21)' `2' `(lsh 1 17)' `p' `(lsh 1 20)' `n' `(lsh 1 22)' `3' `(lsh 1 18)' -- Function: string-to-syntax DESC This function returns the internal form corresponding to the syntax descriptor DESC, a cons cell `(SYNTAX-CODE . MATCHING-CHAR)'. -- Function: syntax-after pos This function returns the syntax code of the character in the buffer after position POS, taking account of syntax properties as well as the syntax table. If POS is outside the buffer's accessible portion (*note accessible portion: Narrowing.), this function returns `nil'. -- Function: syntax-class syntax This function returns the syntax class of the syntax code SYNTAX. (It masks off the high 16 bits that hold the flags encoded in the syntax descriptor.) If SYNTAX is `nil', it returns `nil'; this is so evaluating the expression (syntax-class (syntax-after pos)) where `pos' is outside the buffer's accessible portion, will yield `nil' without throwing errors or producing wrong syntax class codes.  File: elisp, Node: Categories, Prev: Syntax Table Internals, Up: Syntax Tables 35.9 Categories =============== "Categories" provide an alternate way of classifying characters syntactically. You can define several categories as needed, then independently assign each character to one or more categories. Unlike syntax classes, categories are not mutually exclusive; it is normal for one character to belong to several categories. Each buffer has a "category table" which records which categories are defined and also which characters belong to each category. Each category table defines its own categories, but normally these are initialized by copying from the standard categories table, so that the standard categories are available in all modes. Each category has a name, which is an ASCII printing character in the range ` ' to `~'. You specify the name of a category when you define it with `define-category'. The category table is actually a char-table (*note Char-Tables::). The element of the category table at index C is a "category set"--a bool-vector--that indicates which categories character C belongs to. In this category set, if the element at index CAT is `t', that means category CAT is a member of the set, and that character C belongs to category CAT. For the next three functions, the optional argument TABLE defaults to the current buffer's category table. -- Function: define-category char docstring &optional table This function defines a new category, with name CHAR and documentation DOCSTRING, for the category table TABLE. -- Function: category-docstring category &optional table This function returns the documentation string of category CATEGORY in category table TABLE. (category-docstring ?a) => "ASCII" (category-docstring ?l) => "Latin" -- Function: get-unused-category &optional table This function returns a category name (a character) which is not currently defined in TABLE. If all possible categories are in use in TABLE, it returns `nil'. -- Function: category-table This function returns the current buffer's category table. -- Function: category-table-p object This function returns `t' if OBJECT is a category table, otherwise `nil'. -- Function: standard-category-table This function returns the standard category table. -- Function: copy-category-table &optional table This function constructs a copy of TABLE and returns it. If TABLE is not supplied (or is `nil'), it returns a copy of the standard category table. Otherwise, an error is signaled if TABLE is not a category table. -- Function: set-category-table table This function makes TABLE the category table for the current buffer. It returns TABLE. -- Function: make-category-table This creates and returns an empty category table. In an empty category table, no categories have been allocated, and no characters belong to any categories. -- Function: make-category-set categories This function returns a new category set--a bool-vector--whose initial contents are the categories listed in the string CATEGORIES. The elements of CATEGORIES should be category names; the new category set has `t' for each of those categories, and `nil' for all other categories. (make-category-set "al") => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -- Function: char-category-set char This function returns the category set for character CHAR in the current buffer's category table. This is the bool-vector which records which categories the character CHAR belongs to. The function `char-category-set' does not allocate storage, because it returns the same bool-vector that exists in the category table. (char-category-set ?a) => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -- Function: category-set-mnemonics category-set This function converts the category set CATEGORY-SET into a string containing the characters that designate the categories that are members of the set. (category-set-mnemonics (char-category-set ?a)) => "al" -- Function: modify-category-entry char category &optional table reset This function modifies the category set of CHAR in category table TABLE (which defaults to the current buffer's category table). CHAR can be a character, or a cons cell of the form `(MIN . MAX)'; in the latter case, the function modifies the category sets of all characters in the range between MIN and MAX, inclusive. Normally, it modifies a category set by adding CATEGORY to it. But if RESET is non-`nil', then it deletes CATEGORY instead. -- Command: describe-categories &optional buffer-or-name This function describes the category specifications in the current category table. It inserts the descriptions in a buffer, and then displays that buffer. If BUFFER-OR-NAME is non-`nil', it describes the category table of that buffer instead.  File: elisp, Node: Abbrevs, Next: Processes, Prev: Syntax Tables, Up: Top 36 Abbrevs and Abbrev Expansion ******************************* An abbreviation or "abbrev" is a string of characters that may be expanded to a longer string. The user can insert the abbrev string and find it replaced automatically with the expansion of the abbrev. This saves typing. The set of abbrevs currently in effect is recorded in an "abbrev table". Each buffer has a local abbrev table, but normally all buffers in the same major mode share one abbrev table. There is also a global abbrev table. Normally both are used. An abbrev table is represented as an obarray. *Note Creating Symbols::, for information about obarrays. Each abbreviation is represented by a symbol in the obarray. The symbol's name is the abbreviation; its value is the expansion; its function definition is the hook function for performing the expansion (*note Defining Abbrevs::); and its property list cell contains various additional properties, including the use count and the number of times the abbreviation has been expanded (*note Abbrev Properties::). Certain abbrevs, called "system abbrevs", are defined by a major mode instead of the user. A system abbrev is identified by its non-`nil' `:system' property (*note Abbrev Properties::). When abbrevs are saved to an abbrev file, system abbrevs are omitted. *Note Abbrev Files::. Because the symbols used for abbrevs are not interned in the usual obarray, they will never appear as the result of reading a Lisp expression; in fact, normally they are never used except by the code that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. For the user-level commands for abbrevs, see *note Abbrev Mode: (emacs)Abbrevs. * Menu: * Abbrev Mode:: Setting up Emacs for abbreviation. * Tables: Abbrev Tables. Creating and working with abbrev tables. * Defining Abbrevs:: Specifying abbreviations and their expansions. * Files: Abbrev Files. Saving abbrevs in files. * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. * Standard Abbrev Tables:: Abbrev tables used by various major modes. * Abbrev Properties:: How to read and set abbrev properties. Which properties have which effect. * Abbrev Table Properties:: How to read and set abbrev table properties. Which properties have which effect.  File: elisp, Node: Abbrev Mode, Next: Abbrev Tables, Prev: Abbrevs, Up: Abbrevs 36.1 Setting Up Abbrev Mode =========================== Abbrev mode is a minor mode controlled by the variable `abbrev-mode'. -- User Option: abbrev-mode If this variable is non-`nil', abbrevs are automatically expanded in the buffer. If the value is `nil', abbrevs may be defined, but they are not expanded automatically. This variable automatically becomes buffer-local when set in any fashion.  File: elisp, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs 36.2 Abbrev Tables ================== This section describes how to create and manipulate abbrev tables. -- Function: make-abbrev-table &optional props This function creates and returns a new, empty abbrev table--an obarray containing no symbols. It is a vector filled with zeros. PROPS is a property list that is applied to the new table (*note Abbrev Table Properties::). -- Function: abbrev-table-p object This function returns a non-`nil' value if OBJECT is an abbrev table. -- Function: clear-abbrev-table abbrev-table This function undefines all the abbrevs in ABBREV-TABLE, leaving it empty. It always returns `nil'. -- Function: copy-abbrev-table abbrev-table This function returns a copy of ABBREV-TABLE--a new abbrev table containing the same abbrev definitions. There is one difference between the contents of ABBREV-TABLE and the returned copy: all abbrevs in the latter have their property lists set to `nil'. -- Function: define-abbrev-table tabname definitions &optional docstring &rest props This function defines TABNAME (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table. It defines abbrevs in the table according to DEFINITIONS, a list of elements of the form `(ABBREVNAME EXPANSION [HOOK] [PROPS...])'. These elements are passed as arguments to `define-abbrev'. The return value is always `nil'. The optional string DOCSTRING is the documentation string of the variable TABNAME. The property list PROPS is applied to the abbrev table (*note Abbrev Table Properties::). If this function is called more than once for the same TABNAME, subsequent calls add the definitions in DEFINITIONS to TABNAME, rather than overriding the entire original contents. (A subsequent call only overrides abbrevs explicitly redefined or undefined in DEFINITIONS.) -- Variable: abbrev-table-name-list This is a list of symbols whose values are abbrev tables. `define-abbrev-table' adds the new abbrev table name to this list. -- Function: insert-abbrev-table-description name &optional human This function inserts before point a description of the abbrev table named NAME. The argument NAME is a symbol whose value is an abbrev table. The return value is always `nil'. If HUMAN is non-`nil', the description is human-oriented. System abbrevs are listed and identified as such. Otherwise the description is a Lisp expression--a call to `define-abbrev-table' that would define NAME as it is currently defined, but without the system abbrevs. (The mode or package using NAME is supposed to add these to NAME separately.)  File: elisp, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs 36.3 Defining Abbrevs ===================== `define-abbrev' is the low-level basic function for defining an abbrev in an abbrev table. When a major mode defines a system abbrev, it should call `define-abbrev' and specify a `t' for the `:system' property. Be aware that any saved non-"system" abbrevs are restored at startup, i.e. before some major modes are loaded. Therefore, major modes should not assume that their abbrev tables are empty when they are first loaded. -- Function: define-abbrev abbrev-table name expansion &optional hook &rest props This function defines an abbrev named NAME, in ABBREV-TABLE, to expand to EXPANSION and call HOOK, with properties PROPS (*note Abbrev Properties::). The return value is NAME. The `:system' property in PROPS is treated specially here: if it has the value `force', then it will overwrite an existing definition even for a non-"system" abbrev of the same name. NAME should be a string. The argument EXPANSION is normally the desired expansion (a string), or `nil' to undefine the abbrev. If it is anything but a string or `nil', then the abbreviation "expands" solely by running HOOK. The argument HOOK is a function or `nil'. If HOOK is non-`nil', then it is called with no arguments after the abbrev is replaced with EXPANSION; point is located at the end of EXPANSION when HOOK is called. If HOOK is a non-`nil' symbol whose `no-self-insert' property is non-`nil', HOOK can explicitly control whether to insert the self-inserting input character that triggered the expansion. If HOOK returns non-`nil' in this case, that inhibits insertion of the character. By contrast, if HOOK returns `nil', `expand-abbrev' also returns `nil', as if expansion had not really occurred. Normally, `define-abbrev' sets the variable `abbrevs-changed' to `t', if it actually changes the abbrev. (This is so that some commands will offer to save the abbrevs.) It does not do this for a system abbrev, since those aren't saved anyway. -- User Option: only-global-abbrevs If this variable is non-`nil', it means that the user plans to use global abbrevs only. This tells the commands that define mode-specific abbrevs to define global ones instead. This variable does not alter the behavior of the functions in this section; it is examined by their callers.  File: elisp, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs 36.4 Saving Abbrevs in Files ============================ A file of saved abbrev definitions is actually a file of Lisp code. The abbrevs are saved in the form of a Lisp program to define the same abbrev tables with the same contents. Therefore, you can load the file with `load' (*note How Programs Do Loading::). However, the function `quietly-read-abbrev-file' is provided as a more convenient interface. User-level facilities such as `save-some-buffers' can save abbrevs in a file automatically, under the control of variables described here. -- User Option: abbrev-file-name This is the default file name for reading and saving abbrevs. -- Function: quietly-read-abbrev-file &optional filename This function reads abbrev definitions from a file named FILENAME, previously written with `write-abbrev-file'. If FILENAME is omitted or `nil', the file specified in `abbrev-file-name' is used. `save-abbrevs' is set to `t' so that changes will be saved. This function does not display any messages. It returns `nil'. -- User Option: save-abbrevs A non-`nil' value for `save-abbrevs' means that Emacs should offer the user to save abbrevs when files are saved. If the value is `silently', Emacs saves the abbrevs without asking the user. `abbrev-file-name' specifies the file to save the abbrevs in. -- Variable: abbrevs-changed This variable is set non-`nil' by defining or altering any abbrevs (except system abbrevs). This serves as a flag for various Emacs commands to offer to save your abbrevs. -- Command: write-abbrev-file &optional filename Save all abbrev definitions (except system abbrevs), for all abbrev tables listed in `abbrev-table-name-list', in the file FILENAME, in the form of a Lisp program that when loaded will define the same abbrevs. If FILENAME is `nil' or omitted, `abbrev-file-name' is used. This function returns `nil'.  File: elisp, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs 36.5 Looking Up and Expanding Abbreviations =========================================== Abbrevs are usually expanded by certain interactive commands, including `self-insert-command'. This section describes the subroutines used in writing such commands, as well as the variables they use for communication. -- Function: abbrev-symbol abbrev &optional table This function returns the symbol representing the abbrev named ABBREV. The value returned is `nil' if that abbrev is not defined. The optional second argument TABLE is the abbrev table in which to look it up. If TABLE is `nil', this function tries first the current buffer's local abbrev table, and second the global abbrev table. -- Function: abbrev-expansion abbrev &optional table This function returns the string that ABBREV would expand into (as defined by the abbrev tables used for the current buffer). If ABBREV is not a valid abbrev, the function returns `nil'. The optional argument TABLE specifies the abbrev table to use, as in `abbrev-symbol'. -- Command: expand-abbrev This command expands the abbrev before point, if any. If point does not follow an abbrev, this command does nothing. The command returns the abbrev symbol if it did expansion, `nil' otherwise. If the abbrev symbol has a hook function which is a symbol whose `no-self-insert' property is non-`nil', and if the hook function returns `nil' as its value, then `expand-abbrev' returns `nil' even though expansion did occur. -- Function: abbrev-insert abbrev &optional name start end This function inserts the abbrev expansion of `abbrev', replacing the text between `start' and `end'. If `start' is omitted, it defaults to point. `name', if non-`nil', should be the name by which this abbrev was found (a string); it is used to figure out whether to adjust the capitalization of the expansion. The function returns `abbrev' if the abbrev was successfully inserted. -- Command: abbrev-prefix-mark &optional arg This command marks the current location of point as the beginning of an abbrev. The next call to `expand-abbrev' will use the text from here to point (where it is then) as the abbrev to expand, rather than using the previous word as usual. First, this command expands any abbrev before point, unless ARG is non-`nil'. (Interactively, ARG is the prefix argument.) Then it inserts a hyphen before point, to indicate the start of the next abbrev to be expanded. The actual expansion removes the hyphen. -- User Option: abbrev-all-caps When this is set non-`nil', an abbrev entered entirely in upper case is expanded using all upper case. Otherwise, an abbrev entered entirely in upper case is expanded by capitalizing each word of the expansion. -- Variable: abbrev-start-location The value of this variable is a buffer position (an integer or a marker) for `expand-abbrev' to use as the start of the next abbrev to be expanded. The value can also be `nil', which means to use the word before point instead. `abbrev-start-location' is set to `nil' each time `expand-abbrev' is called. This variable is also set by `abbrev-prefix-mark'. -- Variable: abbrev-start-location-buffer The value of this variable is the buffer for which `abbrev-start-location' has been set. Trying to expand an abbrev in any other buffer clears `abbrev-start-location'. This variable is set by `abbrev-prefix-mark'. -- Variable: last-abbrev This is the `abbrev-symbol' of the most recent abbrev expanded. This information is left by `expand-abbrev' for the sake of the `unexpand-abbrev' command (*note Expanding Abbrevs: (emacs)Expanding Abbrevs.). -- Variable: last-abbrev-location This is the location of the most recent abbrev expanded. This contains information left by `expand-abbrev' for the sake of the `unexpand-abbrev' command. -- Variable: last-abbrev-text This is the exact expansion text of the most recent abbrev expanded, after case conversion (if any). Its value is `nil' if the abbrev has already been unexpanded. This contains information left by `expand-abbrev' for the sake of the `unexpand-abbrev' command. -- Variable: abbrev-expand-functions This is a special hook run _around_ the `expand-abbrev' function. Each function on this hook is called with a single argument: a function that performs the normal abbrev expansion. The hook function can hence do anything it wants before and after performing the expansion. It can also choose not to call its argument, thus overriding the default behavior; or it may even call it several times. The function should return the abbrev symbol if expansion took place. The following sample code shows a simple use of `abbrev-expand-functions'. It assumes that `foo-mode' is a mode for editing certain files in which lines that start with `#' are comments. You want to use Text mode abbrevs for those lines. The regular local abbrev table, `foo-mode-abbrev-table' is appropriate for all other lines. Then you can put the following code in your `.emacs' file. *Note Standard Abbrev Tables::, for the definitions of `local-abbrev-table' and `text-mode-abbrev-table'. (defun foo-mode-abbrev-expand-function (expand) (if (not (save-excursion (forward-line 0) (eq (char-after) ?#))) ;; Performs normal expansion. (funcall expand) ;; We're inside a comment: use the text-mode abbrevs. (let ((local-abbrev-table text-mode-abbrev-table)) (funcall expand)))) (add-hook 'foo-mode-hook #'(lambda () (add-hook 'abbrev-expand-functions 'foo-mode-abbrev-expand-function nil t)))  File: elisp, Node: Standard Abbrev Tables, Next: Abbrev Properties, Prev: Abbrev Expansion, Up: Abbrevs 36.6 Standard Abbrev Tables =========================== Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs. -- Variable: global-abbrev-table This is the abbrev table for mode-independent abbrevs. The abbrevs defined in it apply to all buffers. Each buffer may also have a local abbrev table, whose abbrev definitions take precedence over those in the global table. -- Variable: local-abbrev-table The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer. It can also be a list of such tables. -- Variable: abbrev-minor-mode-table-alist The value of this variable is a list of elements of the form `(MODE . ABBREV-TABLE)' where MODE is the name of a variable: if the variable is bound to a non-`nil' value, then the ABBREV-TABLE is active, otherwise it is ignored. ABBREV-TABLE can also be a list of abbrev tables. -- Variable: fundamental-mode-abbrev-table This is the local abbrev table used in Fundamental mode; in other words, it is the local abbrev table in all buffers in Fundamental mode. -- Variable: text-mode-abbrev-table This is the local abbrev table used in Text mode. -- Variable: lisp-mode-abbrev-table This is the local abbrev table used in Lisp mode and Emacs Lisp mode.  File: elisp, Node: Abbrev Properties, Next: Abbrev Table Properties, Prev: Standard Abbrev Tables, Up: Abbrevs 36.7 Abbrev Properties ====================== Abbrevs have properties, some of which influence the way they work. You can provide them as arguments to `define-abbrev' and you can manipulate them with the following functions: -- Function: abbrev-put abbrev prop val Set the property PROP of ABBREV to value VAL. -- Function: abbrev-get abbrev prop Return the property PROP of ABBREV, or `nil' if the abbrev has no such property. The following properties have special meanings: `:count' This property counts the number of times the abbrev has been expanded. If not explicitly set, it is initialized to 0 by `define-abbrev'. `:system' If non-`nil', this property marks the abbrev as a system abbrev. Such abbrevs are not saved (*note Abbrev Files::). `:enable-function' If non-`nil', this property should be a function of no arguments which returns `nil' if the abbrev should not be used and `t' otherwise. `:case-fixed' If non-`nil', this property indicates that the case of the abbrev's name is significant and should only match a text with the same pattern of capitalization. It also disables the code that modifies the capitalization of the expansion.  File: elisp, Node: Abbrev Table Properties, Prev: Abbrev Properties, Up: Abbrevs 36.8 Abbrev Table Properties ============================ Like abbrevs, abbrev tables have properties, some of which influence the way they work. You can provide them as arguments to `define-abbrev-table' and you can manipulate them with the functions: -- Function: abbrev-table-put table prop val Set the property PROP of abbrev table TABLE to value VAL. -- Function: abbrev-table-get table prop Return the property PROP of abbrev table TABLE, or `nil' if the abbrev has no such property. The following properties have special meaning: `:enable-function' This is like the `:enable-function' abbrev property except that it applies to all abbrevs in the table and is used even before trying to find the abbrev before point so it can dynamically modify the abbrev table. `:case-fixed' This is like the `:case-fixed' abbrev property except that it applies to all abbrevs in the table. `:regexp' If non-`nil', this property is a regular expression that indicates how to extract the name of the abbrev before point before looking it up in the table. When the regular expression matches before point, the abbrev name is expected to be in submatch 1. If this property is `nil', `expand-function' defaults to `"\\<\\(\\w+\\)\\W"'. This property allows the use of abbrevs whose name contains characters of non-word syntax. `:parents' This property holds the list of tables from which to inherit other abbrevs. `:abbrev-table-modiff' This property holds a counter incremented each time a new abbrev is added to the table.  File: elisp, Node: Processes, Next: Display, Prev: Abbrevs, Up: Top 37 Processes ************ In the terminology of operating systems, a "process" is a space in which a program can execute. Emacs runs in a process. Emacs Lisp programs can invoke other programs in processes of their own. These are called "subprocesses" or "child processes" of the Emacs process, which is their "parent process". A subprocess of Emacs may be "synchronous" or "asynchronous", depending on how it is created. When you create a synchronous subprocess, the Lisp program waits for the subprocess to terminate before continuing execution. When you create an asynchronous subprocess, it can run in parallel with the Lisp program. This kind of subprocess is represented within Emacs by a Lisp object which is also called a "process." Lisp programs can use this object to communicate with the subprocess or to control it. For example, you can send signals, obtain status information, receive output from the process, or send input to it. -- Function: processp object This function returns `t' if OBJECT represents an Emacs subprocess, `nil' otherwise. In addition to subprocesses of the current Emacs session, you can also access other processes running on your machine. *Note System Processes::. * Menu: * Subprocess Creation:: Functions that start subprocesses. * Shell Arguments:: Quoting an argument to pass it to a shell. * Synchronous Processes:: Details of using synchronous subprocesses. * Asynchronous Processes:: Starting up an asynchronous subprocess. * Deleting Processes:: Eliminating an asynchronous subprocess. * Process Information:: Accessing run-status and other attributes. * Input to Processes:: Sending input to an asynchronous subprocess. * Signals to Processes:: Stopping, continuing or interrupting an asynchronous subprocess. * Output from Processes:: Collecting output from an asynchronous subprocess. * Sentinels:: Sentinels run when process run-status changes. * Query Before Exit:: Whether to query if exiting will kill a process. * System Processes:: Accessing other processes running on your system. * Transaction Queues:: Transaction-based communication with subprocesses. * Network:: Opening network connections. * Network Servers:: Network servers let Emacs accept net connections. * Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function to create connections and servers. * Misc Network:: Additional relevant functions for network connections. * Serial Ports:: Communicating with serial ports. * Byte Packing:: Using bindat to pack and unpack binary data.  File: elisp, Node: Subprocess Creation, Next: Shell Arguments, Up: Processes 37.1 Functions that Create Subprocesses ======================================= There are three primitives that create a new subprocess in which to run a program. One of them, `start-process', creates an asynchronous process and returns a process object (*note Asynchronous Processes::). The other two, `call-process' and `call-process-region', create a synchronous process and do not return a process object (*note Synchronous Processes::). Synchronous and asynchronous processes are explained in the following sections. Since the three functions are all called in a similar fashion, their common arguments are described here. In all cases, the function's PROGRAM argument specifies the program to be run. An error is signaled if the file is not found or cannot be executed. If the file name is relative, the variable `exec-path' contains a list of directories to search. Emacs initializes `exec-path' when it starts up, based on the value of the environment variable `PATH'. The standard file name constructs, `~', `.', and `..', are interpreted as usual in `exec-path', but environment variable substitutions (`$HOME', etc.) are not recognized; use `substitute-in-file-name' to perform them (*note File Name Expansion::). `nil' in this list refers to `default-directory'. Executing a program can also try adding suffixes to the specified name: -- Variable: exec-suffixes This variable is a list of suffixes (strings) to try adding to the specified program file name. The list should include `""' if you want the name to be tried exactly as specified. The default value is system-dependent. *Please note:* The argument PROGRAM contains only the name of the program; it may not contain any command-line arguments. You must use ARGS to provide those. Each of the subprocess-creating functions has a BUFFER-OR-NAME argument which specifies where the standard output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also be `nil', which says to discard the output unless a filter function handles it. (*Note Filter Functions::, and *note Read and Print::.) Normally, you should avoid having multiple processes send output to the same buffer because their output would be intermixed randomly. All three of the subprocess-creating functions have a `&rest' argument, ARGS. The ARGS must all be strings, and they are supplied to PROGRAM as separate command line arguments. Wildcard characters and other shell constructs have no special meanings in these strings, since the strings are passed directly to the specified program. The subprocess gets its current directory from the value of `default-directory' (*note File Name Expansion::). The subprocess inherits its environment from Emacs, but you can specify overrides for it with `process-environment'. *Note System Environment::. -- Variable: exec-directory The value of this variable is a string, the name of a directory that contains programs that come with GNU Emacs, programs intended for Emacs to invoke. The program `movemail' is an example of such a program; Rmail uses it to fetch new mail from an inbox. -- User Option: exec-path The value of this variable is a list of directories to search for programs to run in subprocesses. Each element is either the name of a directory (i.e., a string), or `nil', which stands for the default directory (which is the value of `default-directory'). The value of `exec-path' is used by `call-process' and `start-process' when the PROGRAM argument is not an absolute file name.  File: elisp, Node: Shell Arguments, Next: Synchronous Processes, Prev: Subprocess Creation, Up: Processes 37.2 Shell Arguments ==================== Lisp programs sometimes need to run a shell and give it a command that contains file names that were specified by the user. These programs ought to be able to support any valid file name. But the shell gives special treatment to certain characters, and if these characters occur in the file name, they will confuse the shell. To handle these characters, use the function `shell-quote-argument': -- Function: shell-quote-argument argument This function returns a string which represents, in shell syntax, an argument whose actual contents are ARGUMENT. It should work reliably to concatenate the return value into a shell command and then pass it to a shell for execution. Precisely what this function does depends on your operating system. The function is designed to work with the syntax of your system's standard shell; if you use an unusual shell, you will need to redefine this function. ;; This example shows the behavior on GNU and Unix systems. (shell-quote-argument "foo > bar") => "foo\\ \\>\\ bar" ;; This example shows the behavior on MS-DOS and MS-Windows. (shell-quote-argument "foo > bar") => "\"foo > bar\"" Here's an example of using `shell-quote-argument' to construct a shell command: (concat "diff -c " (shell-quote-argument oldfile) " " (shell-quote-argument newfile)) The following two functions are useful for creating shell commands from individual argument strings, and taking shell command lines apart into individual arguments. -- Function: split-string-and-unquote string &optional separators This function splits STRING into substrings at matches for the regular expression SEPARATORS, like `split-string' does (*note Creating Strings::); in addition, it removes quoting from the substrings. It then makes a list of the substrings and returns it. If SEPARATORS is omitted or `nil', it defaults to `"\\s-+"', which is a regular expression that matches one or more characters with whitespace syntax (*note Syntax Class Table::). This function performs two types of quoting: enclosing a whole string in double quotes `"..."', and quoting individual characters with a backslash escape `\'. The latter is also used in Lisp strings, so this function can handle those as well. -- Function: combine-and-quote-strings list-of-strings &optional separator This function concatenates LIST-OF-STRINGS into a single string, quoting each string as necessary. It also sticks the SEPARATOR string between each pair of strings; if SEPARATOR is omitted or `nil', it defaults to `" "'. The return value is the resulting string. The strings in LIST-OF-STRINGS that need quoting are those that include SEPARATOR as their substring. Quoting a string encloses it in double quotes `"..."'. In the simplest case, if you are consing a shell command from the individual command-line arguments, every argument that includes embedded blanks will be quoted.  File: elisp, Node: Synchronous Processes, Next: Asynchronous Processes, Prev: Shell Arguments, Up: Processes 37.3 Creating a Synchronous Process =================================== After a "synchronous process" is created, Emacs waits for the process to terminate before continuing. Starting Dired on GNU or Unix(1) is an example of this: it runs `ls' in a synchronous process, then modifies the output slightly. Because the process is synchronous, the entire directory listing arrives in the buffer before Emacs tries to do anything with it. While Emacs waits for the synchronous subprocess to terminate, the user can quit by typing `C-g'. The first `C-g' tries to kill the subprocess with a `SIGINT' signal; but it waits until the subprocess actually terminates before quitting. If during that time the user types another `C-g', that kills the subprocess instantly with `SIGKILL' and quits immediately (except on MS-DOS, where killing other processes doesn't work). *Note Quitting::. The synchronous subprocess functions return an indication of how the process terminated. The output from a synchronous subprocess is generally decoded using a coding system, much like text read from a file. The input sent to a subprocess by `call-process-region' is encoded using a coding system, much like text written into a file. *Note Coding Systems::. -- Function: call-process program &optional infile destination display &rest args This function calls PROGRAM in a separate process and waits for it to finish. The standard input for the process comes from file INFILE if INFILE is not `nil', and from the null device otherwise. The argument DESTINATION says where to put the process output. Here are the possibilities: a buffer Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process. a string Insert the output in a buffer with that name, before point. `t' Insert the output in the current buffer, before point. `nil' Discard the output. 0 Discard the output, and return `nil' immediately without waiting for the subprocess to finish. In this case, the process is not truly synchronous, since it can run in parallel with Emacs; but you can think of it as synchronous in that Emacs is essentially finished with the subprocess as soon as this function returns. MS-DOS doesn't support asynchronous subprocesses, so this option doesn't work there. `(REAL-DESTINATION ERROR-DESTINATION)' Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by REAL-DESTINATION, and dispose of the error output according to ERROR-DESTINATION. If ERROR-DESTINATION is `nil', that means to discard the error output, `t' means mix it with the ordinary output, and a string specifies a file name to redirect error output into. You can't directly specify a buffer to put the error output in; that is too difficult to implement. But you can achieve this result by sending the error output to a temporary file and then inserting the file into a buffer. If DISPLAY is non-`nil', then `call-process' redisplays the buffer as output is inserted. (However, if the coding system chosen for decoding output is `undecided', meaning deduce the encoding from the actual data, then redisplay sometimes cannot continue once non-ASCII characters are encountered. There are fundamental reasons why it is hard to fix this; see *note Output from Processes::.) Otherwise the function `call-process' does no redisplay, and the results become visible on the screen only when Emacs redisplays that buffer in the normal course of events. The remaining arguments, ARGS, are strings that specify command line arguments for the program. The value returned by `call-process' (unless you told it not to wait) indicates the reason for process termination. A number gives the exit status of the subprocess; 0 means success, and any other value means failure. If the process terminated with a signal, `call-process' returns a string describing the signal. In the examples below, the buffer `foo' is current. (call-process "pwd" nil t) => 0 ---------- Buffer: foo ---------- /usr/user/lewis/manual ---------- Buffer: foo ---------- (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") => 0 ---------- Buffer: bar ---------- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh ---------- Buffer: bar ---------- Here is a good example of the use of `call-process', which used to be found in the definition of `insert-directory': (call-process insert-directory-program nil t nil SWITCHES (if full-directory-p (concat (file-name-as-directory file) ".") file)) -- Function: process-file program &optional infile buffer display &rest args This function processes files synchronously in a separate process. It is similar to `call-process' but may invoke a file handler based on the value of the variable `default-directory'. The current working directory of the subprocess is `default-directory'. The arguments are handled in almost the same way as for `call-process', with the following differences: Some file handlers may not support all combinations and forms of the arguments INFILE, BUFFER, and DISPLAY. For example, some file handlers might behave as if DISPLAY were `nil', regardless of the value actually passed. As another example, some file handlers might not support separating standard output and error output by way of the BUFFER argument. If a file handler is invoked, it determines the program to run based on the first argument PROGRAM. For instance, consider that a handler for remote files is invoked. Then the path that is used for searching the program might be different than `exec-path'. The second argument INFILE may invoke a file handler. The file handler could be different from the handler chosen for the `process-file' function itself. (For example, `default-directory' could be on a remote host, whereas INFILE is on another remote host. Or `default-directory' could be non-special, whereas INFILE is on a remote host.) If BUFFER is a list of the form `(REAL-DESTINATION ERROR-DESTINATION)', and ERROR-DESTINATION names a file, then the same remarks as for INFILE apply. The remaining arguments (ARGS) will be passed to the process verbatim. Emacs is not involved in processing file names that are present in ARGS. To avoid confusion, it may be best to avoid absolute file names in ARGS, but rather to specify all file names as relative to `default-directory'. The function `file-relative-name' is useful for constructing such relative file names. -- Variable: process-file-side-effects This variable indicates, whether a call of `process-file' changes remote files. Per default, this variable is always set to `t', meaning that a call of `process-file' could potentially change any file on a remote host. When set to `nil', a file handler could optimize its behaviour with respect to remote file attributes caching. This variable should never be changed by `setq'. Instead of, it shall be set only by let-binding. -- Function: call-process-region start end program &optional delete destination display &rest args This function sends the text from START to END as standard input to a process running PROGRAM. It deletes the text sent if DELETE is non-`nil'; this is useful when DESTINATION is `t', to insert the output in the current buffer in place of the input. The arguments DESTINATION and DISPLAY control what to do with the output from the subprocess, and whether to update the display as it comes in. For details, see the description of `call-process', above. If DESTINATION is the integer 0, `call-process-region' discards the output and returns `nil' immediately, without waiting for the subprocess to finish (this only works if asynchronous subprocesses are supported). The remaining arguments, ARGS, are strings that specify command line arguments for the program. The return value of `call-process-region' is just like that of `call-process': `nil' if you told it to return without waiting; otherwise, a number or string which indicates how the subprocess terminated. In the following example, we use `call-process-region' to run the `cat' utility, with standard input being the first five characters in buffer `foo' (the word `input'). `cat' copies its standard input into its standard output. Since the argument DESTINATION is `t', this output is inserted in the current buffer. ---------- Buffer: foo ---------- input-!- ---------- Buffer: foo ---------- (call-process-region 1 6 "cat" nil t) => 0 ---------- Buffer: foo ---------- inputinput-!- ---------- Buffer: foo ---------- The `shell-command-on-region' command uses `call-process-region' like this: (call-process-region start end shell-file-name ; Name of program. nil ; Do not delete region. buffer ; Send output to `buffer'. nil ; No redisplay during output. "-c" command) ; Arguments for the shell. -- Function: call-process-shell-command command &optional infile destination display &rest args This function executes the shell command COMMAND synchronously in a separate process. The final arguments ARGS are additional arguments to add at the end of COMMAND. The other arguments are handled as in `call-process'. -- Function: process-file-shell-command command &optional infile destination display &rest args This function is like `call-process-shell-command', but uses `process-file' internally. Depending on `default-directory', COMMAND can be executed also on remote hosts. -- Function: shell-command-to-string command This function executes COMMAND (a string) as a shell command, then returns the command's output as a string. -- Function: process-lines program &rest args This function runs PROGRAM in a separate process, waits for it to finish, and returns its output as a list of strings. Each string in the list holds a single line of text output by the program; the end-of-line characters are stripped from each line. The arguments beyond PROGRAM, ARGS, are strings that specify command-line arguments with which to run the program. If PROGRAM exits with a non-zero exit status, this function signals an error. This function works by calling `call-process', so program output is decoded in the same way as for `call-process'. ---------- Footnotes ---------- (1) On other systems, Emacs uses a Lisp emulation of `ls'; see *note Contents of Directories::.  File: elisp, Node: Asynchronous Processes, Next: Deleting Processes, Prev: Synchronous Processes, Up: Processes 37.4 Creating an Asynchronous Process ===================================== After an "asynchronous process" is created, Emacs and the subprocess both continue running immediately. The process thereafter runs in parallel with Emacs, and the two can communicate with each other using the functions described in the following sections. However, communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data from the process only when Emacs is waiting for input or for a time delay. Here we describe how to create an asynchronous process. -- Function: start-process name buffer-or-name program &rest args This function creates a new asynchronous subprocess and starts the program PROGRAM running in it. It returns a process object that stands for the new subprocess in Lisp. The argument NAME specifies the name for the process object; if a process with this name already exists, then NAME is modified (by appending `<1>', etc.) to be unique. The buffer BUFFER-OR-NAME is the buffer to associate with the process. The remaining arguments, ARGS, are strings that specify command line arguments for the program. In the example below, the first process is started and runs (rather, sleeps) for 100 seconds. Meanwhile, the second process is started, and given the name `my-process<1>' for the sake of uniqueness. It inserts the directory listing at the end of the buffer `foo', before the first process finishes. Then it finishes, and a message to that effect is inserted in the buffer. Much later, the first process finishes, and another message is inserted in the buffer for it. (start-process "my-process" "foo" "sleep" "100") => # (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") => #> ---------- Buffer: foo ---------- total 2 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon Process my-process<1> finished Process my-process finished ---------- Buffer: foo ---------- -- Function: start-file-process name buffer-or-name program &rest args Like `start-process', this function starts a new asynchronous subprocess running PROGRAM in it, and returns its process object--when `default-directory' is not a magic file name. If `default-directory' is magic, the function invokes its file handler instead. This handler ought to run PROGRAM, perhaps on the local host, perhaps on a remote host that corresponds to `default-directory'. In the latter case, the local part of `default-directory' becomes the working directory of the process. This function does not try to invoke file name handlers for PROGRAM or for the PROGRAM-ARGS. Depending on the implementation of the file handler, it might not be possible to apply `process-filter' or `process-sentinel' to the resulting process object (*note Filter Functions::, *note Sentinels::). Some file handlers may not support `start-file-process' (for example `ange-ftp-hook-function'). In such cases, the function does nothing and returns `nil'. -- Function: start-process-shell-command name buffer-or-name command This function is like `start-process' except that it uses a shell to execute the specified command. The argument COMMAND is a shell command name. The variable `shell-file-name' specifies which shell to use. The point of running a program through the shell, rather than directly with `start-process', is so that you can employ shell features such as wildcards in the arguments. It follows that if you include an arbitrary user-specified arguments in the command, you should quote it with `shell-quote-argument' first, so that any special shell characters do _not_ have their special shell meanings. *Note Shell Arguments::. -- Function: start-file-process-shell-command name buffer-or-name command This function is like `start-process-shell-command', but uses `start-file-process' internally. By this, COMMAND can be executed also on remote hosts, depending on `default-directory'. -- Variable: process-connection-type This variable controls the type of device used to communicate with asynchronous subprocesses. If it is non-`nil', then PTYs are used, when available. Otherwise, pipes are used. PTYs are usually preferable for processes visible to the user, as in Shell mode, because they allow job control (`C-c', `C-z', etc.) to work between the process and its children, whereas pipes do not. For subprocesses used for internal purposes by programs, it is often better to use a pipe, because they are more efficient. In addition, the total number of PTYs is limited on many systems and it is good not to waste them. The value of `process-connection-type' takes effect when `start-process' is called. So you can specify how to communicate with one subprocess by binding the variable around the call to `start-process'. (let ((process-connection-type nil)) ; Use a pipe. (start-process ...)) To determine whether a given subprocess actually got a pipe or a PTY, use the function `process-tty-name' (*note Process Information::).  File: elisp, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes 37.5 Deleting Processes ======================= "Deleting a process" disconnects Emacs immediately from the subprocess. Processes are deleted automatically after they terminate, but not necessarily right away. You can delete a process explicitly at any time. If you delete a terminated process explicitly before it is deleted automatically, no harm results. Deleting a running process sends a signal to terminate it (and its child processes if any), and calls the process sentinel if it has one. *Note Sentinels::. When a process is deleted, the process object itself continues to exist as long as other Lisp objects point to it. All the Lisp primitives that work on process objects accept deleted processes, but those that do I/O or send signals will report an error. The process mark continues to point to the same place as before, usually into a buffer where output from the process was being inserted. -- User Option: delete-exited-processes This variable controls automatic deletion of processes that have terminated (due to calling `exit' or to a signal). If it is `nil', then they continue to exist until the user runs `list-processes'. Otherwise, they are deleted immediately after they exit. -- Function: delete-process process This function deletes a process, killing it with a `SIGKILL' signal. The argument may be a process, the name of a process, a buffer, or the name of a buffer. (A buffer or buffer-name stands for the process that `get-buffer-process' returns.) Calling `delete-process' on a running process terminates it, updates the process status, and runs the sentinel (if any) immediately. If the process has already terminated, calling `delete-process' has no effect on its status, or on the running of its sentinel (which will happen sooner or later). (delete-process "*shell*") => nil  File: elisp, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes 37.6 Process Information ======================== Several functions return information about processes. `list-processes' is provided for interactive use. -- Command: list-processes &optional query-only This command displays a listing of all living processes. In addition, it finally deletes any process whose status was `Exited' or `Signaled'. It returns `nil'. If QUERY-ONLY is non-`nil' then it lists only processes whose query flag is non-`nil'. *Note Query Before Exit::. -- Function: process-list This function returns a list of all processes that have not been deleted. (process-list) => (# #) -- Function: get-process name This function returns the process named NAME, or `nil' if there is none. An error is signaled if NAME is not a string. (get-process "shell") => # -- Function: process-command process This function returns the command that was executed to start PROCESS. This is a list of strings, the first string being the program executed and the rest of the strings being the arguments that were given to the program. (process-command (get-process "shell")) => ("/bin/csh" "-i") -- Function: process-contact process &optional key This function returns information about how a network or serial process was set up. For a network process, when KEY is `nil', it returns `(HOSTNAME SERVICE)' which specifies what you connected to. For a serial process, when KEY is `nil', it returns `(PORT SPEED)'. For an ordinary child process, this function always returns `t'. If KEY is `t', the value is the complete status information for the connection, server, or serial port; that is, the list of keywords and values specified in `make-network-process' or `make-serial-process', except that some of the values represent the current status instead of what you specified. For a network process: `:buffer' The associated value is the process buffer. `:filter' The associated value is the process filter function. `:sentinel' The associated value is the process sentinel function. `:remote' In a connection, the address in internal format of the remote peer. `:local' The local address, in internal format. `:service' In a server, if you specified `t' for SERVICE, this value is the actual port number. `:local' and `:remote' are included even if they were not specified explicitly in `make-network-process'. For a serial process, see `make-serial-process' and `serial-process-configure' for a list of keys. If KEY is a keyword, the function returns the value corresponding to that keyword. -- Function: process-id process This function returns the PID of PROCESS. This is an integer that distinguishes the process PROCESS from all other processes running on the same computer at the current time. The PID of a process is chosen by the operating system kernel when the process is started and remains constant as long as the process exists. -- Function: process-name process This function returns the name of PROCESS. -- Function: process-status process-name This function returns the status of PROCESS-NAME as a symbol. The argument PROCESS-NAME must be a process, a buffer, or a process name (a string). The possible values for an actual subprocess are: `run' for a process that is running. `stop' for a process that is stopped but continuable. `exit' for a process that has exited. `signal' for a process that has received a fatal signal. `open' for a network connection that is open. `closed' for a network connection that is closed. Once a connection is closed, you cannot reopen it, though you might be able to open a new connection to the same place. `connect' for a non-blocking connection that is waiting to complete. `failed' for a non-blocking connection that has failed to complete. `listen' for a network server that is listening. `nil' if PROCESS-NAME is not the name of an existing process. (process-status (get-buffer "*shell*")) => run x => #> (process-status x) => exit For a network connection, `process-status' returns one of the symbols `open' or `closed'. The latter means that the other side closed the connection, or Emacs did `delete-process'. -- Function: process-type process This function returns the symbol `network' for a network connection or server, `serial' for a serial port connection, or `real' for a real subprocess. -- Function: process-exit-status process This function returns the exit status of PROCESS or the signal number that killed it. (Use the result of `process-status' to determine which of those it is.) If PROCESS has not yet terminated, the value is 0. -- Function: process-tty-name process This function returns the terminal name that PROCESS is using for its communication with Emacs--or `nil' if it is using pipes instead of a terminal (see `process-connection-type' in *note Asynchronous Processes::). -- Function: process-coding-system process This function returns a cons cell describing the coding systems in use for decoding output from PROCESS and for encoding input to PROCESS (*note Coding Systems::). The value has this form: (CODING-SYSTEM-FOR-DECODING . CODING-SYSTEM-FOR-ENCODING) -- Function: set-process-coding-system process &optional decoding-system encoding-system This function specifies the coding systems to use for subsequent output from and input to PROCESS. It will use DECODING-SYSTEM to decode subprocess output, and ENCODING-SYSTEM to encode subprocess input. Every process also has a property list that you can use to store miscellaneous values associated with the process. -- Function: process-get process propname This function returns the value of the PROPNAME property of PROCESS. -- Function: process-put process propname value This function sets the value of the PROPNAME property of PROCESS to VALUE. -- Function: process-plist process This function returns the process plist of PROCESS. -- Function: set-process-plist process plist This function sets the process plist of PROCESS to PLIST.  File: elisp, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes 37.7 Sending Input to Processes =============================== Asynchronous subprocesses receive input when it is sent to them by Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The data appears on the "standard input" of the subprocess. Some operating systems have limited space for buffered input in a PTY. On these systems, Emacs sends an EOF periodically amidst the other characters, to force them through. For most programs, these EOFs do no harm. Subprocess input is normally encoded using a coding system before the subprocess receives it, much like text written into a file. You can use `set-process-coding-system' to specify which coding system to use (*note Process Information::). Otherwise, the coding system comes from `coding-system-for-write', if that is non-`nil'; or else from the defaulting mechanism (*note Default Coding Systems::). Sometimes the system is unable to accept input for that process, because the input buffer is full. When this happens, the send functions wait a short while, accepting output from subprocesses, and then try again. This gives the subprocess a chance to read more of its pending input and make space in the buffer. It also allows filters, sentinels and timers to run--so take account of that in writing your code. In these functions, the PROCESS argument can be a process or the name of a process, or a buffer or buffer name (which stands for a process via `get-buffer-process'). `nil' means the current buffer's process. -- Function: process-send-string process string This function sends PROCESS the contents of STRING as standard input. If it is `nil', the current buffer's process is used. The function returns `nil'. (process-send-string "shell<1>" "ls\n") => nil ---------- Buffer: *shell* ---------- ... introduction.texi syntax-tables.texi~ introduction.texi~ text.texi introduction.txt text.texi~ ... ---------- Buffer: *shell* ---------- -- Function: process-send-region process start end This function sends the text in the region defined by START and END as standard input to PROCESS. An error is signaled unless both START and END are integers or markers that indicate positions in the current buffer. (It is unimportant which number is larger.) -- Function: process-send-eof &optional process This function makes PROCESS see an end-of-file in its input. The EOF comes after any text already sent to it. The function returns PROCESS. (process-send-eof "shell") => "shell" -- Function: process-running-child-p &optional process This function will tell you whether a PROCESS has given control of its terminal to its own child process. The value is `t' if this is true, or if Emacs cannot tell; it is `nil' if Emacs can be certain that this is not so.  File: elisp, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes 37.8 Sending Signals to Processes ================================= "Sending a signal" to a subprocess is a way of interrupting its activities. There are several different signals, each with its own meaning. The set of signals and their names is defined by the operating system. For example, the signal `SIGINT' means that the user has typed `C-c', or that some analogous thing has happened. Each signal has a standard effect on the subprocess. Most signals kill the subprocess, but some stop or resume execution instead. Most signals can optionally be handled by programs; if the program handles the signal, then we can say nothing in general about its effects. You can send signals explicitly by calling the functions in this section. Emacs also sends signals automatically at certain times: killing a buffer sends a `SIGHUP' signal to all its associated processes; killing Emacs sends a `SIGHUP' signal to all remaining processes. (`SIGHUP' is a signal that usually indicates that the user hung up the phone.) Each of the signal-sending functions takes two optional arguments: PROCESS and CURRENT-GROUP. The argument PROCESS must be either a process, a process name, a buffer, a buffer name, or `nil'. A buffer or buffer name stands for a process through `get-buffer-process'. `nil' stands for the process associated with the current buffer. An error is signaled if PROCESS does not identify a process. The argument CURRENT-GROUP is a flag that makes a difference when you are running a job-control shell as an Emacs subprocess. If it is non-`nil', then the signal is sent to the current process-group of the terminal that Emacs uses to communicate with the subprocess. If the process is a job-control shell, this means the shell's current subjob. If it is `nil', the signal is sent to the process group of the immediate subprocess of Emacs. If the subprocess is a job-control shell, this is the shell itself. The flag CURRENT-GROUP has no effect when a pipe is used to communicate with the subprocess, because the operating system does not support the distinction in the case of pipes. For the same reason, job-control shells won't work when a pipe is used. See `process-connection-type' in *note Asynchronous Processes::. -- Function: interrupt-process &optional process current-group This function interrupts the process PROCESS by sending the signal `SIGINT'. Outside of Emacs, typing the "interrupt character" (normally `C-c' on some systems, and `DEL' on others) sends this signal. When the argument CURRENT-GROUP is non-`nil', you can think of this function as "typing `C-c'" on the terminal by which Emacs talks to the subprocess. -- Function: kill-process &optional process current-group This function kills the process PROCESS by sending the signal `SIGKILL'. This signal kills the subprocess immediately, and cannot be handled by the subprocess. -- Function: quit-process &optional process current-group This function sends the signal `SIGQUIT' to the process PROCESS. This signal is the one sent by the "quit character" (usually `C-b' or `C-\') when you are not inside Emacs. -- Function: stop-process &optional process current-group This function stops the process PROCESS by sending the signal `SIGTSTP'. Use `continue-process' to resume its execution. Outside of Emacs, on systems with job control, the "stop character" (usually `C-z') normally sends this signal. When CURRENT-GROUP is non-`nil', you can think of this function as "typing `C-z'" on the terminal Emacs uses to communicate with the subprocess. -- Function: continue-process &optional process current-group This function resumes execution of the process PROCESS by sending it the signal `SIGCONT'. This presumes that PROCESS was stopped previously. -- Function: signal-process process signal This function sends a signal to process PROCESS. The argument SIGNAL specifies which signal to send; it should be an integer. The PROCESS argument can be a system process ID; that allows you to send signals to processes that are not children of Emacs. *Note System Processes::.  File: elisp, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes 37.9 Receiving Output from Processes ==================================== There are two ways to receive the output that a subprocess writes to its standard output stream. The output can be inserted in a buffer, which is called the associated buffer of the process, or a function called the "filter function" can be called to act on the output. If the process has no buffer and no filter function, its output is discarded. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the subprocess has children that are still live and still producing output, Emacs won't receive that output. Output from a subprocess can arrive only while Emacs is waiting: when reading terminal input, in `sit-for' and `sleep-for' (*note Waiting::), and in `accept-process-output' (*note Accepting Output::). This minimizes the problem of timing errors that usually plague parallel programming. For example, you can safely create a process and only then specify its buffer or filter function; no output can arrive before you finish, if the code in between does not call any primitive that waits. -- Variable: process-adaptive-read-buffering On some systems, when Emacs reads the output from a subprocess, the output data is read in very small blocks, potentially resulting in very poor performance. This behavior can be remedied to some extent by setting the variable PROCESS-ADAPTIVE-READ-BUFFERING to a non-`nil' value (the default), as it will automatically delay reading from such processes, thus allowing them to produce more output before Emacs tries to read it. It is impossible to separate the standard output and standard error streams of the subprocess, because Emacs normally spawns the subprocess inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If you want to keep the output to those streams separate, you should redirect one of them to a file--for example, by using an appropriate shell command. * Menu: * Process Buffers:: If no filter, output is put in a buffer. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives.  File: elisp, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes 37.9.1 Process Buffers ---------------------- A process can (and usually does) have an "associated buffer", which is an ordinary Emacs buffer that is used for two purposes: storing the output from the process, and deciding when to kill the process. You can also use the buffer to identify a process to operate on, since in normal practice only one process is associated with any given buffer. Many applications of processes also use the buffer for editing input to be sent to the process, but this is not built into Emacs Lisp. Unless the process has a filter function (*note Filter Functions::), its output is inserted in the associated buffer. The position to insert the output is determined by the `process-mark', which is then updated to point to the end of the text just inserted. Usually, but not always, the `process-mark' is at the end of the buffer. Killing the associated buffer of a process also kills the process. Emacs asks for confirmation first, if the process's `process-query-on-exit-flag' is non-`nil' (*note Query Before Exit::). This confirmation is done by the function `process-kill-buffer-query-function', which is run from `kill-buffer-query-functions' (*note Killing Buffers::). -- Function: process-buffer process This function returns the associated buffer of the process PROCESS. (process-buffer (get-process "shell")) => # -- Function: process-mark process This function returns the process marker for PROCESS, which is the marker that says where to insert output from the process. If PROCESS does not have a buffer, `process-mark' returns a marker that points nowhere. Insertion of process output in a buffer uses this marker to decide where to insert, and updates it to point after the inserted text. That is why successive batches of output are inserted consecutively. Filter functions normally should use this marker in the same fashion as is done by direct insertion of output in the buffer. A good example of a filter function that uses `process-mark' is found at the end of the following section. When the user is expected to enter input in the process buffer for transmission to the process, the process marker separates the new input from previous output. -- Function: set-process-buffer process buffer This function sets the buffer associated with PROCESS to BUFFER. If BUFFER is `nil', the process becomes associated with no buffer. -- Function: get-buffer-process buffer-or-name This function returns a nondeleted process associated with the buffer specified by BUFFER-OR-NAME. If there are several processes associated with it, this function chooses one (currently, the one most recently created, but don't count on that). Deletion of a process (see `delete-process') makes it ineligible for this function to return. It is usually a bad idea to have more than one process associated with the same buffer. (get-buffer-process "*shell*") => # Killing the process's buffer deletes the process, which kills the subprocess with a `SIGHUP' signal (*note Signals to Processes::).  File: elisp, Node: Filter Functions, Next: Decoding Output, Prev: Process Buffers, Up: Output from Processes 37.9.2 Process Filter Functions ------------------------------- A process "filter function" is a function that receives the standard output from the associated process. If a process has a filter, then _all_ output from that process is passed to the filter. The process buffer is used directly for output from the process only when there is no filter. The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs waits when reading terminal input, in `sit-for' and `sleep-for' (*note Waiting::), and in `accept-process-output' (*note Accepting Output::). A filter function must accept two arguments: the associated process and a string, which is output just received from it. The function is then free to do whatever it chooses with the output. Quitting is normally inhibited within a filter function--otherwise, the effect of typing `C-g' at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a filter function, bind `inhibit-quit' to `nil'. In most cases, the right way to do this is with the macro `with-local-quit'. *Note Quitting::. If an error happens during execution of a filter function, it is caught automatically, so that it doesn't stop the execution of whatever program was running when the filter function was started. However, if `debug-on-error' is non-`nil', the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the filter function. *Note Debugger::. Many filter functions sometimes or always insert the text in the process's buffer, mimicking the actions of Emacs when there is no filter. Such filter functions need to use `set-buffer' in order to be sure to insert in that buffer. To avoid setting the current buffer semipermanently, these filter functions must save and restore the current buffer. They should also update the process marker, and in some cases update the value of point. Here is how to do these things: (defun ordinary-insertion-filter (proc string) (with-current-buffer (process-buffer proc) (let ((moving (= (point) (process-mark proc)))) (save-excursion ;; Insert the text, advancing the process marker. (goto-char (process-mark proc)) (insert string) (set-marker (process-mark proc) (point))) (if moving (goto-char (process-mark proc)))))) The reason to use `with-current-buffer', rather than using `save-excursion' to save and restore the current buffer, is so as to preserve the change in point made by the second call to `goto-char'. To make the filter force the process buffer to be visible whenever new text arrives, insert the following line just before the `with-current-buffer' construct: (display-buffer (process-buffer proc)) To force point to the end of the new output, no matter where it was previously, eliminate the variable `moving' and call `goto-char' unconditionally. In earlier Emacs versions, every filter function that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for filter functions; they never need to do it explicitly. *Note Match Data::. A filter function that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. The expression `(buffer-name (process-buffer PROCESS))' returns `nil' if the buffer is dead. The output to the function may come in chunks of any size. A program that produces the same output twice in a row may send it as one batch of 200 characters one time, and five batches of 40 characters the next. If the filter looks for certain text strings in the subprocess output, make sure to handle the case where one of these strings is split across two or more batches of output; one way to do this is to insert the received text into a temporary buffer, which can then be searched. -- Function: set-process-filter process filter This function gives PROCESS the filter function FILTER. If FILTER is `nil', it gives the process no filter. -- Function: process-filter process This function returns the filter function of PROCESS, or `nil' if it has none. Here is an example of use of a filter function: (defun keep-output (process output) (setq kept (cons output kept))) => keep-output (setq kept nil) => nil (set-process-filter (get-process "shell") 'keep-output) => keep-output (process-send-string "shell" "ls ~/other\n") => nil kept => ("lewis@slug[8] % " "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ address.txt backup.psf kolstad.psf backup.bib~ david.mss resume-Dec-86.mss~ backup.err david.psf resume-Dec.psf backup.mss dland syllabus.mss " "#backups.mss# backup.mss~ kolstad.mss ")  File: elisp, Node: Decoding Output, Next: Accepting Output, Prev: Filter Functions, Up: Output from Processes 37.9.3 Decoding Process Output ------------------------------ When Emacs writes process output directly into a multibyte buffer, it decodes the output according to the process output coding system. If the coding system is `raw-text' or `no-conversion', Emacs converts the unibyte output to multibyte using `string-to-multibyte', and inserts the resulting multibyte text. You can use `set-process-coding-system' to specify which coding system to use (*note Process Information::). Otherwise, the coding system comes from `coding-system-for-read', if that is non-`nil'; or else from the defaulting mechanism (*note Default Coding Systems::). If the text output by a process contains null bytes, Emacs by default uses `no-conversion' for it; see *note inhibit-null-byte-detection: Lisp and Coding Systems, for how to control this behavior. *Warning:* Coding systems such as `undecided' which determine the coding system from the data do not work entirely reliably with asynchronous subprocess output. This is because Emacs has to process asynchronous subprocess output in batches, as it arrives. Emacs must try to detect the proper coding system from one batch at a time, and this does not always work. Therefore, if at all possible, specify a coding system that determines both the character code conversion and the end of line conversion--that is, one like `latin-1-unix', rather than `undecided' or `latin-1'. When Emacs calls a process filter function, it provides the process output as a multibyte string or as a unibyte string according to the process's filter coding system. Emacs decodes the output according to the process output coding system, which usually produces a multibyte string, except for coding systems such as `binary' and `raw-text'  File: elisp, Node: Accepting Output, Prev: Decoding Output, Up: Output from Processes 37.9.4 Accepting Output from Processes -------------------------------------- Output from asynchronous subprocesses normally arrives only while Emacs is waiting for some sort of external event, such as elapsed time or terminal input. Occasionally it is useful in a Lisp program to explicitly permit output to arrive at a specific point, or even to wait until output arrives from a process. -- Function: accept-process-output &optional process seconds millisec just-this-one This function allows Emacs to read pending output from processes. The output is inserted in the associated buffers or given to their filter functions. If PROCESS is non-`nil' then this function does not return until some output has been received from PROCESS. The arguments SECONDS and MILLISEC let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and `accept-process-output' returns after that much time, whether or not there has been any subprocess output. The argument MILLISEC is semi-obsolete nowadays because SECONDS can be a floating point number to specify waiting a fractional number of seconds. If SECONDS is 0, the function accepts whatever output is pending but does not wait. If PROCESS is a process, and the argument JUST-THIS-ONE is non-`nil', only output from that process is handled, suspending output from other processes until some output has been received from that process or the timeout expires. If JUST-THIS-ONE is an integer, also inhibit running timers. This feature is generally not recommended, but may be necessary for specific applications, such as speech synthesis. The function `accept-process-output' returns non-`nil' if it did get some output, or `nil' if the timeout expired before output arrived.  File: elisp, Node: Sentinels, Next: Query Before Exit, Prev: Output from Processes, Up: Processes 37.10 Sentinels: Detecting Process Status Changes ================================================= A "process sentinel" is a function that is called whenever the associated process changes status for any reason, including signals (whether sent by Emacs or caused by the process's own actions) that terminate, stop, or continue the process. The process sentinel is also called if the process exits. The sentinel receives two arguments: the process for which the event occurred, and a string describing the type of event. The string describing the event looks like one of the following: * `"finished\n"'. * `"exited abnormally with code EXITCODE\n"'. * `"NAME-OF-SIGNAL\n"'. * `"NAME-OF-SIGNAL (core dumped)\n"'. A sentinel runs only while Emacs is waiting (e.g., for terminal input, or for time to elapse, or for process output). This avoids the timing errors that could result from running them at random places in the middle of other Lisp programs. A program can wait, so that sentinels will run, by calling `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output' (*note Accepting Output::). Emacs also allows sentinels to run when the command loop is reading input. `delete-process' calls the sentinel when it terminates a running process. Emacs does not keep a queue of multiple reasons to call the sentinel of one process; it records just the current status and the fact that there has been a change. Therefore two changes in status, coming in quick succession, can call the sentinel just once. However, process termination will always run the sentinel exactly once. This is because the process status can't change again after termination. Emacs explicitly checks for output from the process before running the process sentinel. Once the sentinel runs due to process termination, no further output can arrive from the process. A sentinel that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, `(buffer-name (process-buffer PROCESS))' returns `nil'. Quitting is normally inhibited within a sentinel--otherwise, the effect of typing `C-g' at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a sentinel, bind `inhibit-quit' to `nil'. In most cases, the right way to do this is with the macro `with-local-quit'. *Note Quitting::. If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if `debug-on-error' is non-`nil', the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the sentinel. *Note Debugger::. While a sentinel is running, the process sentinel is temporarily set to `nil' so that the sentinel won't run recursively. For this reason it is not possible for a sentinel to specify a new sentinel. In earlier Emacs versions, every sentinel that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for sentinels; they never need to do it explicitly. *Note Match Data::. -- Function: set-process-sentinel process sentinel This function associates SENTINEL with PROCESS. If SENTINEL is `nil', then the process will have no sentinel. The default behavior when there is no sentinel is to insert a message in the process's buffer when the process status changes. Changes in process sentinel take effect immediately--if the sentinel is slated to be run but has not been called yet, and you specify a new sentinel, the eventual call to the sentinel will use the new one. (defun msg-me (process event) (princ (format "Process: %s had the event `%s'" process event))) (set-process-sentinel (get-process "shell") 'msg-me) => msg-me (kill-process (get-process "shell")) -| Process: # had the event `killed' => # -- Function: process-sentinel process This function returns the sentinel of PROCESS, or `nil' if it has none. -- Function: waiting-for-user-input-p While a sentinel or filter function is running, this function returns non-`nil' if Emacs was waiting for keyboard input from the user at the time the sentinel or filter function was called, `nil' if it was not.  File: elisp, Node: Query Before Exit, Next: System Processes, Prev: Sentinels, Up: Processes 37.11 Querying Before Exit ========================== When Emacs exits, it terminates all its subprocesses by sending them the `SIGHUP' signal. Because subprocesses may be doing valuable work, Emacs normally asks the user to confirm that it is ok to terminate them. Each process has a query flag which, if non-`nil', says that Emacs should ask for confirmation before exiting and thus killing that process. The default for the query flag is `t', meaning _do_ query. -- Function: process-query-on-exit-flag process This returns the query flag of PROCESS. -- Function: set-process-query-on-exit-flag process flag This function sets the query flag of PROCESS to FLAG. It returns FLAG. ;; Don't query about the shell process (set-process-query-on-exit-flag (get-process "shell") nil) => t -- Function: process-kill-without-query process &optional do-query This function clears the query flag of PROCESS, so that Emacs will not query the user on account of that process. Actually, the function does more than that: it returns the old value of the process's query flag, and sets the query flag to DO-QUERY. Please don't use this function to do those things any more--please use the newer, cleaner functions `process-query-on-exit-flag' and `set-process-query-on-exit-flag' in all but the simplest cases. The only way you should use `process-kill-without-query' nowadays is like this: ;; Don't query about the shell process (process-kill-without-query (get-process "shell"))  File: elisp, Node: System Processes, Next: Transaction Queues, Prev: Query Before Exit, Up: Processes 37.12 Accessing Other Processes =============================== In addition to accessing and manipulating processes that are subprocesses of the current Emacs session, Emacs Lisp programs can also access other processes running on the same machine. We call these "system processes", to distinguish between them and Emacs subprocesses. Emacs provides several primitives for accessing system processes. Not all platforms support these primitives; on those which don't, these primitives return `nil'. -- Function: list-system-processes This function returns a list of all the processes running on the system. Each process is identified by its PID, a numerical process ID that is assigned by the OS and distinguishes the process from all the other processes running on the same machine at the same time. -- Function: process-attributes pid This function returns an alist of attributes for the process specified by its process ID PID. Each association in the alist is of the form `(KEY . VALUE)', where KEY designates the attribute and VALUE is the value of that attribute. The various attribute KEY's that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. Values that are numbers can be either integer or floating-point, depending on the magnitude of the value. `euid' The effective user ID of the user who invoked the process. The corresponding VALUE is a number. If the process was invoked by the same user who runs the current Emacs session, the value is identical to what `user-uid' returns (*note User Identification::). `user' User name corresponding to the process's effective user ID, a string. `egid' The group ID of the effective user ID, a number. `group' Group name corresponding to the effective user's group ID, a string. `comm' The name of the command that runs in the process. This is a string that usually specifies the name of the executable file of the process, without the leading directories. However, some special system processes can report strings that do not correspond to an executable file of a program. `state' The state code of the process. This is a short string that encodes the scheduling state of the process. Here's a list of the most frequently seen codes: `"D"' uninterruptible sleep (usually I/O) `"R"' running `"S"' interruptible sleep (waiting for some event) `"T"' stopped, e.g., by a job control signal `"Z"' "zombie": a process that terminated, but was not reaped by its parent For the full list of the possible states, see the manual page of the `ps' command. `ppid' The process ID of the parent process, a number. `pgrp' The process group ID of the process, a number. `sess' The session ID of the process. This is a number that is the process ID of the process's "session leader". `ttname' A string that is the name of the process's controlling terminal. On Unix and GNU systems, this is normally the file name of the corresponding terminal device, such as `/dev/pts65'. `tpgid' The numerical process group ID of the foreground process group that uses the process's terminal. `minflt' The number of minor page faults caused by the process since its beginning. (Minor page faults are those that don't involve reading from disk.) `majflt' The number of major page faults caused by the process since its beginning. (Major page faults require a disk to be read, and are thus more expensive than minor page faults.) `cminflt' `cmajflt' Like `minflt' and `majflt', but include the number of page faults for all the child processes of the given process. `utime' Time spent by the process in the user context, for running the application's code. The corresponding VALUE is in the `(HIGH LOW MICROSEC)' format, the same format used by functions `current-time' (*note current-time: Time of Day.) and `file-attributes' (*note File Attributes::). `stime' Time spent by the process in the system (kernel) context, for processing system calls. The corresponding VALUE is in the same format as for `utime'. `time' The sum of `utime' and `stime'. The corresponding VALUE is in the same format as for `utime'. `cutime' `cstime' `ctime' Like `utime', `stime', and `time', but include the times of all the child processes of the given process. `pri' The numerical priority of the process. `nice' The "nice value" of the process, a number. (Processes with smaller nice values get scheduled more favorably.) `thcount' The number of threads in the process. `start' The time the process was started, in the `(HIGH LOW MICROSEC)' format used by `current-time' and `file-attributes'. `etime' The time elapsed since the process started, in the `(HIGH LOW MICROSEC)' format. `vsize' The virtual memory size of the process, measured in kilobytes. `rss' The size of the process's "resident set", the number of kilobytes occupied by the process in the machine's physical memory. `pcpu' The percentage of the CPU time used by the process since it started. The corresponding VALUE is a floating-point number between 0 and 100. `pmem' The percentage of the total physical memory installed on the machine used by the process's resident set. The value is a floating-point number between 0 and 100. `args' The command-line with which the process was invoked. This is a string in which individual command-line arguments are separated by blanks; whitespace characters that are embedded in the arguments are quoted as appropriate for the system's shell: escaped by backslash characters on GNU and Unix, and enclosed in double quote characters on Windows. Thus, this command-line string can be directly used in primitives such as `shell-command'.  File: elisp, Node: Transaction Queues, Next: Network, Prev: System Processes, Up: Processes 37.13 Transaction Queues ======================== You can use a "transaction queue" to communicate with a subprocess using transactions. First use `tq-create' to create a transaction queue communicating with a specified process. Then you can call `tq-enqueue' to send a transaction. -- Function: tq-create process This function creates and returns a transaction queue communicating with PROCESS. The argument PROCESS should be a subprocess capable of sending and receiving streams of bytes. It may be a child process, or it may be a TCP connection to a server, possibly on another machine. -- Function: tq-enqueue queue question regexp closure fn &optional delay-question This function sends a transaction to queue QUEUE. Specifying the queue has the effect of specifying the subprocess to talk to. The argument QUESTION is the outgoing message that starts the transaction. The argument FN is the function to call when the corresponding answer comes back; it is called with two arguments: CLOSURE, and the answer received. The argument REGEXP is a regular expression that should match text at the end of the entire answer, but nothing before; that's how `tq-enqueue' determines where the answer ends. If the argument DELAY-QUESTION is non-`nil', delay sending this question until the process has finished replying to any previous questions. This produces more reliable results with some processes. The return value of `tq-enqueue' itself is not meaningful. -- Function: tq-close queue Shut down transaction queue QUEUE, waiting for all pending transactions to complete, and then terminate the connection or child process. Transaction queues are implemented by means of a filter function. *Note Filter Functions::.  File: elisp, Node: Network, Next: Network Servers, Prev: Transaction Queues, Up: Processes 37.14 Network Connections ========================= Emacs Lisp programs can open stream (TCP) and datagram (UDP) network connections to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, so it has no process ID, and you can't kill it or send it signals. All you can do is send and receive data. `delete-process' closes the connection, but does not kill the program at the other end; that program must decide what to do about closure of the connection. Lisp programs can listen for connections by creating network servers. A network server is also represented by a kind of process object, but unlike a network connection, the network server never transfers data itself. When it receives a connection request, it creates a new network connection to represent the connection just made. (The network connection inherits certain information, including the process plist, from the server.) The network server then goes back to listening for more connection requests. Network connections and servers are created by calling `make-network-process' with an argument list consisting of keyword/argument pairs, for example `:server t' to create a server process, or `:type 'datagram' to create a datagram connection. *Note Low-Level Network::, for details. You can also use the `open-network-stream' function described below. To distinguish the different types of processes, the `process-type' function returns the symbol `network' for a network connection or server, `serial' for a serial port connection, or `real' for a real subprocess. The `process-status' function returns `open', `closed', `connect', and `failed' for network connections. For a network server, the status is always `listen'. None of those values is possible for a real subprocess. *Note Process Information::. You can stop and resume operation of a network process by calling `stop-process' and `continue-process'. For a server process, being stopped means not accepting new connections. (Up to 5 connection requests will be queued for when you resume the server; you can increase this limit, unless it is imposed by the operating system.) For a network stream connection, being stopped means not processing input (any arriving input waits until you resume the connection). For a datagram connection, some number of packets may be queued but input may be lost. You can use the function `process-command' to determine whether a network connection or server is stopped; a non-`nil' value means yes. -- Function: open-network-stream name buffer-or-name host service This function opens a TCP connection, and returns a process object that represents the connection. The NAME argument specifies the name for the process object. It is modified as necessary to make it unique. The BUFFER-OR-NAME argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify a filter function to handle the output. If BUFFER-OR-NAME is `nil', it means that the connection is not associated with any buffer. The arguments HOST and SERVICE specify where to connect to; HOST is the host name (a string), and SERVICE is the name of a defined network service (a string) or a port number (an integer).  File: elisp, Node: Network Servers, Next: Datagrams, Prev: Network, Up: Processes 37.15 Network Servers ===================== You create a server by calling `make-network-process' with `:server t'. The server will listen for connection requests from clients. When it accepts a client connection request, that creates a new network connection, itself a process object, with the following parameters: * The connection's process name is constructed by concatenating the server process' NAME with a client identification string. The client identification string for an IPv4 connection looks like `'. Otherwise, it is a unique number in brackets, as in `'. The number is unique for each connection in the Emacs session. * If the server's filter is non-`nil', the connection process does not get a separate process buffer; otherwise, Emacs creates a new buffer for the purpose. The buffer name is the server's buffer name or process name, concatenated with the client identification string. The server's process buffer value is never used directly by Emacs, but it is passed to the log function, which can log connections by inserting text there. * The communication type and the process filter and sentinel are inherited from those of the server. The server never directly uses its filter and sentinel; their sole purpose is to initialize connections made to the server. * The connection's process contact info is set according to the client's addressing information (typically an IP address and a port number). This information is associated with the `process-contact' keywords `:host', `:service', `:remote'. * The connection's local address is set up according to the port number used for the connection. * The client process' plist is initialized from the server's plist.  File: elisp, Node: Datagrams, Next: Low-Level Network, Prev: Network Servers, Up: Processes 37.16 Datagrams =============== A datagram connection communicates with individual packets rather than streams of data. Each call to `process-send' sends one datagram packet (*note Input to Processes::), and each datagram received results in one call to the filter function. The datagram connection doesn't have to talk with the same remote peer all the time. It has a "remote peer address" which specifies where to send datagrams to. Each time an incoming datagram is passed to the filter function, the peer address is set to the address that datagram came from; that way, if the filter function sends a datagram, it will go back to that place. You can specify the remote peer address when you create the datagram connection using the `:remote' keyword. You can change it later on by calling `set-process-datagram-address'. -- Function: process-datagram-address process If PROCESS is a datagram connection or server, this function returns its remote peer address. -- Function: set-process-datagram-address process address If PROCESS is a datagram connection or server, this function sets its remote peer address to ADDRESS.  File: elisp, Node: Low-Level Network, Next: Misc Network, Prev: Datagrams, Up: Processes 37.17 Low-Level Network Access ============================== You can also create network connections by operating at a lower level than that of `open-network-stream', using `make-network-process'. * Menu: * Proc: Network Processes. Using `make-network-process'. * Options: Network Options. Further control over network connections. * Features: Network Feature Testing. Determining which network features work on the machine you are using.  File: elisp, Node: Network Processes, Next: Network Options, Up: Low-Level Network 37.17.1 `make-network-process' ------------------------------ The basic function for creating network connections and network servers is `make-network-process'. It can do either of those jobs, depending on the arguments you give it. -- Function: make-network-process &rest args This function creates a network connection or server and returns the process object that represents it. The arguments ARGS are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value `nil', except for `:coding', `:filter-multibyte', and `:reuseaddr'. Here are the meaningful keywords: :name NAME Use the string NAME as the process name. It is modified if necessary to make it unique. :type TYPE Specify the communication type. A value of `nil' specifies a stream connection (the default); `datagram' specifies a datagram connection; `seqpacket' specifies a "sequenced packet stream" connection. Both connections and servers can be of these types. :server SERVER-FLAG If SERVER-FLAG is non-`nil', create a server. Otherwise, create a connection. For a stream type server, SERVER-FLAG may be an integer which then specifies the length of the queue of pending connections to the server. The default queue length is 5. :host HOST Specify the host to connect to. HOST should be a host name or Internet address, as a string, or the symbol `local' to specify the local host. If you specify HOST for a server, it must specify a valid address for the local host, and only clients connecting to that address will be accepted. :service SERVICE SERVICE specifies a port number to connect to, or, for a server, the port number to listen on. It should be a service name that translates to a port number, or an integer specifying the port number directly. For a server, it can also be `t', which means to let the system select an unused port number. :family FAMILY FAMILY specifies the address (and protocol) family for communication. `nil' means determine the proper address family automatically for the given HOST and SERVICE. `local' specifies a Unix socket, in which case HOST is ignored. `ipv4' and `ipv6' specify to use IPv4 and IPv6 respectively. :local LOCAL-ADDRESS For a server process, LOCAL-ADDRESS is the address to listen on. It overrides FAMILY, HOST and SERVICE, and you may as well not specify them. :remote REMOTE-ADDRESS For a connection, REMOTE-ADDRESS is the address to connect to. It overrides FAMILY, HOST and SERVICE, and you may as well not specify them. For a datagram server, REMOTE-ADDRESS specifies the initial setting of the remote datagram address. The format of LOCAL-ADDRESS or REMOTE-ADDRESS depends on the address family: - An IPv4 address is represented as a five-element vector of four 8-bit integers and one 16-bit integer `[A B C D P]' corresponding to numeric IPv4 address A.B.C.D and port number P. - An IPv6 address is represented as a nine-element vector of 16-bit integers `[A B C D E F G H P]' corresponding to numeric IPv6 address A:B:C:D:E:F:G:H and port number P. - A local address is represented as a string which specifies the address in the local address space. - An "unsupported family" address is represented by a cons `(F . AV)', where F is the family number and AV is a vector specifying the socket address using one element per address data byte. Do not rely on this format in portable code, as it may depend on implementation defined constants, data sizes, and data structure alignment. :nowait BOOL If BOOL is non-`nil' for a stream connection, return without waiting for the connection to complete. When the connection succeeds or fails, Emacs will call the sentinel function, with a second argument matching `"open"' (if successful) or `"failed"'. The default is to block, so that `make-network-process' does not return until the connection has succeeded or failed. :stop STOPPED Start the network connection or server in the `stopped' state if STOPPED is non-`nil'. :buffer BUFFER Use BUFFER as the process buffer. :coding CODING Use CODING as the coding system for this process. To specify different coding systems for decoding data from the connection and for encoding data sent to it, specify `(DECODING . ENCODING)' for CODING. If you don't specify this keyword at all, the default is to determine the coding systems from the data. :noquery QUERY-FLAG Initialize the process query flag to QUERY-FLAG. *Note Query Before Exit::. :filter FILTER Initialize the process filter to FILTER. :sentinel SENTINEL Initialize the process sentinel to SENTINEL. :log LOG Initialize the log function of a server process to LOG. The log function is called each time the server accepts a network connection from a client. The arguments passed to the log function are SERVER, CONNECTION, and MESSAGE, where SERVER is the server process, CONNECTION is the new process for the connection, and MESSAGE is a string describing what has happened. :plist PLIST Initialize the process plist to PLIST. The original argument list, modified with the actual connection information, is available via the `process-contact' function.  File: elisp, Node: Network Options, Next: Network Feature Testing, Prev: Network Processes, Up: Low-Level Network 37.17.2 Network Options ----------------------- The following network options can be specified when you create a network process. Except for `:reuseaddr', you can also set or modify these options later, using `set-network-process-option'. For a server process, the options specified with `make-network-process' are not inherited by the client connections, so you will need to set the necessary options for each child connection as it is created. :bindtodevice DEVICE-NAME If DEVICE-NAME is a non-empty string identifying a network interface name (see `network-interface-list'), only handle packets received on that interface. If DEVICE-NAME is `nil' (the default), handle packets received on any interface. Using this option may require special privileges on some systems. :broadcast BROADCAST-FLAG If BROADCAST-FLAG is non-`nil' for a datagram process, the process will receive datagram packet sent to a broadcast address, and be able to send packets to a broadcast address. Ignored for a stream connection. :dontroute DONTROUTE-FLAG If DONTROUTE-FLAG is non-`nil', the process can only send to hosts on the same network as the local host. :keepalive KEEPALIVE-FLAG If KEEPALIVE-FLAG is non-`nil' for a stream connection, enable exchange of low-level keep-alive messages. :linger LINGER-ARG If LINGER-ARG is non-`nil', wait for successful transmission of all queued packets on the connection before it is deleted (see `delete-process'). If LINGER-ARG is an integer, it specifies the maximum time in seconds to wait for queued packets to be sent before closing the connection. Default is `nil' which means to discard unsent queued packets when the process is deleted. :oobinline OOBINLINE-FLAG If OOBINLINE-FLAG is non-`nil' for a stream connection, receive out-of-band data in the normal data stream. Otherwise, ignore out-of-band data. :priority PRIORITY Set the priority for packets sent on this connection to the integer PRIORITY. The interpretation of this number is protocol specific, such as setting the TOS (type of service) field on IP packets sent on this connection. It may also have system dependent effects, such as selecting a specific output queue on the network interface. :reuseaddr REUSEADDR-FLAG If REUSEADDR-FLAG is non-`nil' (the default) for a stream server process, allow this server to reuse a specific port number (see `:service') unless another process on this host is already listening on that port. If REUSEADDR-FLAG is `nil', there may be a period of time after the last use of that port (by any process on the host), where it is not possible to make a new server on that port. -- Function: set-network-process-option process option value &optional no-error This function sets or modifies a network option for network process PROCESS. See `make-network-process' for details of options OPTION and their corresponding values VALUE. If NO-ERROR is non-`nil', this function returns `nil' instead of signaling an error if OPTION is not a supported option. If the function successfully completes, it returns `t'. The current setting of an option is available via the `process-contact' function.  File: elisp, Node: Network Feature Testing, Prev: Network Options, Up: Low-Level Network 37.17.3 Testing Availability of Network Features ------------------------------------------------ To test for the availability of a given network feature, use `featurep' like this: (featurep 'make-network-process '(KEYWORD VALUE)) The result of the first form is `t' if it works to specify KEYWORD with value VALUE in `make-network-process'. The result of the second form is `t' if KEYWORD is supported by `make-network-process'. Here are some of the KEYWORD--VALUE pairs you can test in this way. `(:nowait t)' Non-`nil' if non-blocking connect is supported. `(:type datagram)' Non-`nil' if datagrams are supported. `(:family local)' Non-`nil' if local (a.k.a. "UNIX domain") sockets are supported. `(:family ipv6)' Non-`nil' if IPv6 is supported. `(:service t)' Non-`nil' if the system can select the port for a server. To test for the availability of a given network option, use `featurep' like this: (featurep 'make-network-process 'KEYWORD) Here are some of the options you can test in this way. `:bindtodevice' `:broadcast' `:dontroute' `:keepalive' `:linger' `:oobinline' `:priority' `:reuseaddr' That particular network option is supported by `make-network-process' and `set-network-process-option'.  File: elisp, Node: Misc Network, Next: Serial Ports, Prev: Low-Level Network, Up: Processes 37.18 Misc Network Facilities ============================= These additional functions are useful for creating and operating on network connections. Note that they are supported only on some systems. -- Function: network-interface-list This function returns a list describing the network interfaces of the machine you are using. The value is an alist whose elements have the form `(NAME . ADDRESS)'. ADDRESS has the same form as the LOCAL-ADDRESS and REMOTE-ADDRESS arguments to `make-network-process'. -- Function: network-interface-info ifname This function returns information about the network interface named IFNAME. The value is a list of the form `(ADDR BCAST NETMASK HWADDR FLAGS)'. ADDR The Internet protocol address. BCAST The broadcast address. NETMASK The network mask. HWADDR The layer 2 address (Ethernet MAC address, for instance). FLAGS The current flags of the interface. -- Function: format-network-address address &optional omit-port This function converts the Lisp representation of a network address to a string. A five-element vector `[A B C D P]' represents an IPv4 address A.B.C.D and port number P. `format-network-address' converts that to the string `"A.B.C.D:P"'. A nine-element vector `[A B C D E F G H P]' represents an IPv6 address along with a port number. `format-network-address' converts that to the string `"[A:B:C:D:E:F:G:H]:P"'. If the vector does not include the port number, P, or if OMIT-PORT is non-`nil', the result does not include the `:P' suffix.  File: elisp, Node: Serial Ports, Next: Byte Packing, Prev: Misc Network, Up: Processes 37.19 Communicating with Serial Ports ===================================== Emacs can communicate with serial ports. For interactive use, `M-x serial-term' opens a terminal window. In a Lisp program, `make-serial-process' creates a process object. The serial port can be configured at run-time, without having to close and re-open it. The function `serial-process-configure' lets you change the speed, bytesize, and other parameters. In a terminal window created by `serial-term', you can click on the mode line for configuration. A serial connection is represented by a process object which can be used similar to a subprocess or network process. You can send and receive data and configure the serial port. A serial process object has no process ID, you can't send signals to it, and the status codes are different from other types of processes. `delete-process' on the process object or `kill-buffer' on the process buffer close the connection, but this does not affect the device connected to the serial port. The function `process-type' returns the symbol `serial' for a process object representing a serial port connection. Serial ports are available on GNU/Linux, Unix, and Windows systems. -- Command: serial-term port speed Start a terminal-emulator for a serial port in a new buffer. PORT is the name of the serial port to which to connect. For example, this could be `/dev/ttyS0' on Unix. On Windows, this could be `COM1', or `\\.\COM10' (double the backslashes in Lisp strings). SPEED is the speed of the serial port in bits per second. 9600 is a common value. The buffer is in Term mode; see *note Term Mode: (emacs)Term Mode, for the commands to use in that buffer. You can change the speed and the configuration in the mode line menu. -- Function: make-serial-process &rest args This function creates a process and a buffer. Arguments are specified as keyword/argument pairs. Here's the list of the meaningful keywords: `:port PORT (mandatory)' This is the name of the serial port. On Unix and GNU systems, this is a file name such as `/dev/ttyS0'. On Windows, this could be `COM1', or `\\.\COM10' for ports higher than `COM9' (double the backslashes in Lisp strings). `:speed SPEED (mandatory)' The speed of the serial port in bits per second. This function calls `serial-process-configure' to handle the speed. `:name NAME' The name of the process. If NAME is not given, PORT will serve as the process name as well. `:buffer BUFFER' The buffer to associate with the process. The value could be either a buffer or a string that names a buffer. Process output goes at the end of that buffer, unless you specify an output stream or filter function to handle the output. If BUFFER is not given, the process buffer's name is taken from the value of the `:name' keyword. `:coding CODING' If CODING is a symbol, it specifies the coding system used for both reading and writing for this process. If CODING is a cons `(decoding . encoding)', DECODING is used for reading, and ENCODING is used for writing. If not specified, the default is to determine the coding systems from data itself. `:noquery QUERY-FLAG' Initialize the process query flag to QUERY-FLAG. *Note Query Before Exit::. The flags defaults to `nil' if unspecified. `:stop BOOL' Start process in the `stopped' state if BOOL is non-`nil'. In the stopped state, a serial process does not accept incoming data, but you can send outgoing data. The stopped state is cleared by `continue-process' and set by `stop-process'. `:filter FILTER' Install FILTER as the process filter. `:sentinel SENTINEL' Install SENTINEL as the process sentinel. `:plist PLIST' Install PLIST as the initial plist of the process. `:speed' `:bytesize' `:parity' `:stopbits' `:flowcontrol' These arguments are handled by `serial-process-configure', which is called by `make-serial-process'. The original argument list, possibly modified by later configuration, is available via the function `process-contact'. Examples: (make-serial-process :port "/dev/ttyS0" :speed 9600) (make-serial-process :port "COM1" :speed 115200 :stopbits 2) (make-serial-process :port "\\\\.\\COM13" :speed 1200 :bytesize 7 :parity 'odd) (make-serial-process :port "/dev/tty.BlueConsole-SPP-1" :speed nil) -- Function: serial-process-configure &rest args This functions configures a serial port connection. Arguments are specified as keyword/argument pairs. Attributes that are not given are re-initialized from the process's current configuration (available via the function `process-contact') or set to reasonable default values. The following arguments are defined: `:process PROCESS' `:name NAME' `:buffer BUFFER' `:port PORT' Any of these arguments can be given to identify the process that is to be configured. If none of these arguments is given, the current buffer's process is used. `:speed SPEED' The speed of the serial port in bits per second, a.k.a. "baud rate". The value can be any number, but most serial ports work only at a few defined values between 1200 and 115200, with 9600 being the most common value. If SPEED is `nil', the function ignores all other arguments and does not configure the port. This may be useful for special serial ports such as Bluetooth-to-serial converters which can only be configured through AT commands sent through the connection. The value of `nil' for SPEED is valid only for connections that were already opened by a previous call to `make-serial-process' or `serial-term'. `:bytesize BYTESIZE' The number of bits per byte, which can be 7 or 8. If BYTESIZE is not given or `nil', it defaults to 8. `:parity PARITY' The value can be `nil' (don't use parity), the symbol `odd' (use odd parity), or the symbol `even' (use even parity). If PARITY is not given, it defaults to no parity. `:stopbits STOPBITS' The number of stopbits used to terminate a transmission of each byte. STOPBITS can be 1 or 2. If STOPBITS is not given or `nil', it defaults to 1. `:flowcontrol FLOWCONTROL' The type of flow control to use for this connection, which is either `nil' (don't use flow control), the symbol `hw' (use RTS/CTS hardware flow control), or the symbol `sw' (use XON/XOFF software flow control). If FLOWCONTROL is not given, it defaults to no flow control. `serial-process-configure' is called by `make-serial-process' for the initial configuration of the serial port. Examples: (serial-process-configure :process "/dev/ttyS0" :speed 1200) (serial-process-configure :buffer "COM1" :stopbits 1 :parity 'odd :flowcontrol 'hw) (serial-process-configure :port "\\\\.\\COM13" :bytesize 7)  File: elisp, Node: Byte Packing, Prev: Serial Ports, Up: Processes 37.20 Packing and Unpacking Byte Arrays ======================================= This section describes how to pack and unpack arrays of bytes, usually for binary network protocols. These functions convert byte arrays to alists, and vice versa. The byte array can be represented as a unibyte string or as a vector of integers, while the alist associates symbols either with fixed-size objects or with recursive sub-alists. Conversion from byte arrays to nested alists is also known as "deserializing" or "unpacking", while going in the opposite direction is also known as "serializing" or "packing". * Menu: * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. * Bindat Examples:: Samples of what bindat.el can do for you!  File: elisp, Node: Bindat Spec, Next: Bindat Functions, Up: Byte Packing 37.20.1 Describing Data Layout ------------------------------ To control unpacking and packing, you write a "data layout specification", a special nested list describing named and typed "fields". This specification controls length of each field to be processed, and how to pack or unpack it. We normally keep bindat specs in variables whose names end in `-bindat-spec'; that kind of name is automatically recognized as "risky." A field's "type" describes the size (in bytes) of the object that the field represents and, in the case of multibyte fields, how the bytes are ordered within the field. The two possible orderings are "big endian" (also known as "network byte ordering") and "little endian." For instance, the number `#x23cd' (decimal 9165) in big endian would be the two bytes `#x23' `#xcd'; and in little endian, `#xcd' `#x23'. Here are the possible type values: `u8' `byte' Unsigned byte, with length 1. `u16' `word' `short' Unsigned integer in network byte order, with length 2. `u24' Unsigned integer in network byte order, with length 3. `u32' `dword' `long' Unsigned integer in network byte order, with length 4. Note: These values may be limited by Emacs' integer implementation limits. `u16r' `u24r' `u32r' Unsigned integer in little endian order, with length 2, 3 and 4, respectively. `str LEN' String of length LEN. `strz LEN' Zero-terminated string, in a fixed-size field with length LEN. `vec LEN [TYPE]' Vector of LEN elements of type TYPE, or bytes if not TYPE is specified. The TYPE is any of the simple types above, or another vector specified as a list `(vec LEN [TYPE])'. `ip' Four-byte vector representing an Internet address. For example: `[127 0 0 1]' for localhost. `bits LEN' List of set bits in LEN bytes. The bytes are taken in big endian order and the bits are numbered starting with `8 * LEN - 1' and ending with zero. For example: `bits 2' unpacks `#x28' `#x1c' to `(2 3 4 11 13)' and `#x1c' `#x28' to `(3 5 10 11 12)'. `(eval FORM)' FORM is a Lisp expression evaluated at the moment the field is unpacked or packed. The result of the evaluation should be one of the above-listed type specifications. For a fixed-size field, the length LEN is given as an integer specifying the number of bytes in the field. When the length of a field is not fixed, it typically depends on the value of a preceding field. In this case, the length LEN can be given either as a list `(NAME ...)' identifying a "field name" in the format specified for `bindat-get-field' below, or by an expression `(eval FORM)' where FORM should evaluate to an integer, specifying the field length. A field specification generally has the form `([NAME] HANDLER)'. The square braces indicate that NAME is optional. (Don't use names that are symbols meaningful as type specifications (above) or handler specifications (below), since that would be ambiguous.) NAME can be a symbol or the expression `(eval FORM)', in which case FORM should evaluate to a symbol. HANDLER describes how to unpack or pack the field and can be one of the following: `TYPE' Unpack/pack this field according to the type specification TYPE. `eval FORM' Evaluate FORM, a Lisp expression, for side-effect only. If the field name is specified, the value is bound to that field name. `fill LEN' Skip LEN bytes. In packing, this leaves them unchanged, which normally means they remain zero. In unpacking, this means they are ignored. `align LEN' Skip to the next multiple of LEN bytes. `struct SPEC-NAME' Process SPEC-NAME as a sub-specification. This describes a structure nested within another structure. `union FORM (TAG SPEC)...' Evaluate FORM, a Lisp expression, find the first TAG that matches it, and process its associated data layout specification SPEC. Matching can occur in one of three ways: * If a TAG has the form `(eval EXPR)', evaluate EXPR with the variable `tag' dynamically bound to the value of FORM. A non-`nil' result indicates a match. * TAG matches if it is `equal' to the value of FORM. * TAG matches unconditionally if it is `t'. `repeat COUNT FIELD-SPECS...' Process the FIELD-SPECS recursively, in order, then repeat starting from the first one, processing all the specs COUNT times overall. The COUNT is given using the same formats as a field length--if an `eval' form is used, it is evaluated just once. For correct operation, each spec in FIELD-SPECS must include a name. For the `(eval FORM)' forms used in a bindat specification, the FORM can access and update these dynamically bound variables during evaluation: `last' Value of the last field processed. `bindat-raw' The data as a byte array. `bindat-idx' Current index (within `bindat-raw') for unpacking or packing. `struct' The alist containing the structured data that have been unpacked so far, or the entire structure being packed. You can use `bindat-get-field' to access specific fields of this structure. `count' `index' Inside a `repeat' block, these contain the maximum number of repetitions (as specified by the COUNT parameter), and the current repetition number (counting from 0). Setting `count' to zero will terminate the inner-most repeat block after the current repetition has completed.  File: elisp, Node: Bindat Functions, Next: Bindat Examples, Prev: Bindat Spec, Up: Byte Packing 37.20.2 Functions to Unpack and Pack Bytes ------------------------------------------ In the following documentation, SPEC refers to a data layout specification, `bindat-raw' to a byte array, and STRUCT to an alist representing unpacked field data. -- Function: bindat-unpack spec bindat-raw &optional bindat-idx This function unpacks data from the unibyte string or byte array `bindat-raw' according to SPEC. Normally this starts unpacking at the beginning of the byte array, but if BINDAT-IDX is non-`nil', it specifies a zero-based starting position to use instead. The value is an alist or nested alist in which each element describes one unpacked field. -- Function: bindat-get-field struct &rest name This function selects a field's data from the nested alist STRUCT. Usually STRUCT was returned by `bindat-unpack'. If NAME corresponds to just one argument, that means to extract a top-level field value. Multiple NAME arguments specify repeated lookup of sub-structures. An integer name acts as an array index. For example, if NAME is `(a b 2 c)', that means to find field `c' in the third element of subfield `b' of field `a'. (This corresponds to `struct.a.b[2].c' in C.) Although packing and unpacking operations change the organization of data (in memory), they preserve the data's "total length", which is the sum of all the fields' lengths, in bytes. This value is not generally inherent in either the specification or alist alone; instead, both pieces of information contribute to its calculation. Likewise, the length of a string or array being unpacked may be longer than the data's total length as described by the specification. -- Function: bindat-length spec struct This function returns the total length of the data in STRUCT, according to SPEC. -- Function: bindat-pack spec struct &optional bindat-raw bindat-idx This function returns a byte array packed according to SPEC from the data in the alist STRUCT. Normally it creates and fills a new byte array starting at the beginning. However, if BINDAT-RAW is non-`nil', it specifies a pre-allocated unibyte string or vector to pack into. If BINDAT-IDX is non-`nil', it specifies the starting offset for packing into `bindat-raw'. When pre-allocating, you should make sure `(length BINDAT-RAW)' meets or exceeds the total length to avoid an out-of-range error. -- Function: bindat-ip-to-string ip Convert the Internet address vector IP to a string in the usual dotted notation. (bindat-ip-to-string [127 0 0 1]) => "127.0.0.1"  File: elisp, Node: Bindat Examples, Prev: Bindat Functions, Up: Byte Packing 37.20.3 Examples of Byte Unpacking and Packing ---------------------------------------------- Here is a complete example of byte unpacking and packing: (defvar fcookie-index-spec '((:version u32) (:count u32) (:longest u32) (:shortest u32) (:flags u32) (:delim u8) (:ignored fill 3) (:offset repeat (:count) (:foo u32))) "Description of a fortune cookie index file's contents.") (defun fcookie (cookies &optional index) "Display a random fortune cookie from file COOKIES. Optional second arg INDEX specifies the associated index filename, which is by default constructed by appending \".dat\" to COOKIES. Display cookie text in possibly new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME is COOKIES without the directory part." (interactive "fCookies file: ") (let* ((info (with-temp-buffer (insert-file-contents-literally (or index (concat cookies ".dat"))) (bindat-unpack fcookie-index-spec (buffer-string)))) (sel (random (bindat-get-field info :count))) (beg (cdar (bindat-get-field info :offset sel))) (end (or (cdar (bindat-get-field info :offset (1+ sel))) (nth 7 (file-attributes cookies))))) (switch-to-buffer (get-buffer-create (format "*Fortune Cookie: %s*" (file-name-nondirectory cookies)))) (erase-buffer) (insert-file-contents-literally cookies nil beg (- end 3)))) (defun fcookie-create-index (cookies &optional index delim) "Scan file COOKIES, and write out its index file. Optional second arg INDEX specifies the index filename, which is by default constructed by appending \".dat\" to COOKIES. Optional third arg DELIM specifies the unibyte character which, when found on a line of its own in COOKIES, indicates the border between entries." (interactive "fCookies file: ") (setq delim (or delim ?%)) (let ((delim-line (format "\n%c\n" delim)) (count 0) (max 0) min p q len offsets) (unless (= 3 (string-bytes delim-line)) (error "Delimiter cannot be represented in one byte")) (with-temp-buffer (insert-file-contents-literally cookies) (while (and (setq p (point)) (search-forward delim-line (point-max) t) (setq len (- (point) 3 p))) (setq count (1+ count) max (max max len) min (min (or min max) len) offsets (cons (1- p) offsets)))) (with-temp-buffer (set-buffer-multibyte nil) (insert (bindat-pack fcookie-index-spec `((:version . 2) (:count . ,count) (:longest . ,max) (:shortest . ,min) (:flags . 0) (:delim . ,delim) (:offset . ,(mapcar (lambda (o) (list (cons :foo o))) (nreverse offsets)))))) (let ((coding-system-for-write 'raw-text-unix)) (write-file (or index (concat cookies ".dat"))))))) Following is an example of defining and unpacking a complex structure. Consider the following C structures: struct header { unsigned long dest_ip; unsigned long src_ip; unsigned short dest_port; unsigned short src_port; }; struct data { unsigned char type; unsigned char opcode; unsigned short length; /* In network byte order */ unsigned char id[8]; /* null-terminated string */ unsigned char data[/* (length + 3) & ~3 */]; }; struct packet { struct header header; unsigned long counters[2]; /* In little endian order */ unsigned char items; unsigned char filler[3]; struct data item[/* items */]; }; The corresponding data layout specification: (setq header-spec '((dest-ip ip) (src-ip ip) (dest-port u16) (src-port u16))) (setq data-spec '((type u8) (opcode u8) (length u16) ;; network byte order (id strz 8) (data vec (length)) (align 4))) (setq packet-spec '((header struct header-spec) (counters vec 2 u32r) ;; little endian order (items u8) (fill 3) (item repeat (items) (struct data-spec)))) A binary data representation: (setq binary-data [ 192 168 1 100 192 168 1 101 01 28 21 32 160 134 1 0 5 1 0 0 2 0 0 0 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) The corresponding decoded structure: (setq decoded (bindat-unpack packet-spec binary-data)) => ((header (dest-ip . [192 168 1 100]) (src-ip . [192 168 1 101]) (dest-port . 284) (src-port . 5408)) (counters . [100000 261]) (items . 2) (item ((data . [1 2 3 4 5]) (id . "ABCDEF") (length . 5) (opcode . 3) (type . 2)) ((data . [6 7 8 9 10 11 12]) (id . "BCDEFG") (length . 7) (opcode . 4) (type . 1)))) Fetching data from this structure: (bindat-get-field decoded 'item 1 'id) => "BCDEFG"  File: elisp, Node: Display, Next: System Interface, Prev: Processes, Up: Top 38 Emacs Display **************** This chapter describes a number of features related to the display that Emacs presents to the user. * Menu: * Refresh Screen:: Clearing the screen and redrawing everything on it. * Forcing Redisplay:: Forcing redisplay. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Displaying messages at the bottom of the screen. * Warnings:: Displaying warning messages for the user. * Invisible Text:: Hiding part of the buffer text. * Selective Display:: Hiding part of the buffer text (the old way). * Temporary Displays:: Displays that go away automatically. * Overlays:: Use overlays to highlight parts of the buffer. * Width:: How wide a character or string is on the screen. * Line Height:: Controlling the height of lines. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. * Scroll Bars:: Controlling vertical scroll bars. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs' Widget for Object Collections. * Blinking:: How Emacs shows the matching open parenthesis. * Usual Display:: The usual conventions for displaying nonprinting chars. * Display Tables:: How to specify other conventions. * Beeping:: Audible signal to the user. * Window Systems:: Which window system is being used.  File: elisp, Node: Refresh Screen, Next: Forcing Redisplay, Up: Display 38.1 Refreshing the Screen ========================== The function `redraw-frame' clears and redisplays the entire contents of a given frame (*note Frames::). This is useful if the screen is corrupted. -- Function: redraw-frame frame This function clears and redisplays frame FRAME. Even more powerful is `redraw-display': -- Command: redraw-display This function clears and redisplays all visible frames. In Emacs, processing user input takes priority over redisplay. If you call these functions when input is available, they don't redisplay immediately, but the requested redisplay does happen eventually--after all the input has been processed. On text-only terminals, suspending and resuming Emacs normally also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as Emacs and for ordinary sequential display. If you are using such a terminal, you might want to inhibit the redisplay on resumption. -- User Option: no-redraw-on-reenter This variable controls whether Emacs redraws the entire screen after it has been suspended and resumed. Non-`nil' means there is no need to redraw, `nil' means redrawing is needed. The default is `nil'.  File: elisp, Node: Forcing Redisplay, Next: Truncation, Prev: Refresh Screen, Up: Display 38.2 Forcing Redisplay ====================== Emacs normally tries to redisplay the screen whenever it waits for input. With the following function, you can request an immediate attempt to redisplay, in the middle of Lisp code, without actually waiting for input. -- Function: redisplay &optional force This function tries immediately to redisplay, provided there are no pending input events. If the optional argument FORCE is non-`nil', it does all pending redisplay work even if input is available, with no pre-emption. The function returns `t' if it actually tried to redisplay, and `nil' otherwise. A value of `t' does not mean that redisplay proceeded to completion; it could have been pre-empted by newly arriving terminal input. `redisplay' with no argument tries immediately to redisplay, but has no effect on the usual rules for what parts of the screen to redisplay. By contrast, the following function adds certain windows to the pending redisplay work (as if their contents had completely changed), but doesn't immediately try to do any redisplay work. -- Function: force-window-update &optional object This function forces some or all windows to be updated on next redisplay. If OBJECT is a window, it requires eventual redisplay of that window. If OBJECT is a buffer or buffer name, it requires eventual redisplay of all windows displaying that buffer. If OBJECT is `nil' (or omitted), it requires eventual redisplay of all windows. `force-window-update' does not do a redisplay immediately. (Emacs will do that when it waits for input.) Rather, its effect is to put more work on the queue to be done by redisplay whenever there is a chance. Emacs redisplay normally stops if input arrives, and does not happen at all if input is available before it starts. Most of the time, this is exactly what you want. However, you can prevent preemption by binding `redisplay-dont-pause' to a non-`nil' value. -- Variable: redisplay-dont-pause If this variable is non-`nil', pending input does not prevent or halt redisplay; redisplay occurs, and finishes, regardless of whether input is available. -- Variable: redisplay-preemption-period This variable specifies how many seconds Emacs waits between checks for new input during redisplay. (The default is 0.1 seconds.) If input has arrived when Emacs checks, it pre-empts redisplay and processes the available input before trying again to redisplay. If this variable is `nil', Emacs does not check for input during redisplay, and redisplay cannot be preempted by input. This variable is only obeyed on graphical terminals. For text terminals, see *note Terminal Output::.  File: elisp, Node: Truncation, Next: The Echo Area, Prev: Forcing Redisplay, Up: Display 38.3 Truncation =============== When a line of text extends beyond the right edge of a window, Emacs can "continue" the line (make it "wrap" to the next screen line), or "truncate" the line (limit it to one screen line). The additional screen lines used to display a long text line are called "continuation" lines. Continuation is not the same as filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. *Note Filling::. On a graphical display, tiny arrow images in the window fringes indicate truncated and continued lines (*note Fringes::). On a text terminal, a `$' in the rightmost column of the window indicates truncation; a `\' on the rightmost column indicates a line that "wraps." (The display table can specify alternate characters to use for this; *note Display Tables::). -- User Option: truncate-lines If this buffer-local variable is non-`nil', lines that extend beyond the right edge of the window are truncated; otherwise, they are continued. As a special exception, the variable `truncate-partial-width-windows' takes precedence in "partial-width" windows (i.e., windows that do not occupy the entire frame width). -- User Option: truncate-partial-width-windows This variable controls line truncation in "partial-width" windows. A partial-width window is one that does not occupy the entire frame width (*note Splitting Windows::). If the value is `nil', line truncation is determined by the variable `truncate-lines' (see above). If the value is an integer N, lines are truncated if the partial-width window has fewer than N columns, regardless of the value of `truncate-lines'; if the partial-width window has N or more columns, line truncation is determined by `truncate-lines'. For any other non-`nil' value, lines are truncated in every partial-width window, regardless of the value of `truncate-lines'. When horizontal scrolling (*note Horizontal Scrolling::) is in use in a window, that forces truncation. -- Variable: wrap-prefix If this buffer-local variable is non-`nil', it defines a "prefix" that is prepended to every continuation line at display-time. (If lines are truncated, the wrap-prefix is never used.) It may be a string, an image, or a stretch-glyph; the value is interpreted in the same way as a `display' text property. *Note Display Property::. A wrap-prefix may also be specified for regions of text, using the `wrap-prefix' text or overlay property. This takes precedence over the `wrap-prefix' variable. *Note Special Properties::. -- Variable: line-prefix If this buffer-local variable is non-`nil', it defines a "prefix" that is prepended to every non-continuation line at display-time. It may be a string, an image, or a stretch-glyph; the value is interpreted in the same way as a `display' text property. *Note Display Property::. A line-prefix may also be specified for regions of text using the `line-prefix' text or overlay property. This takes precedence over the `line-prefix' variable. *Note Special Properties::. If your buffer contains _very_ long lines, and you use continuation to display them, computing the continuation lines can make Emacs redisplay slow. The column computation and indentation functions also become slow. Then you might find it advisable to set `cache-long-line-scans' to `t'. -- Variable: cache-long-line-scans If this variable is non-`nil', various indentation and motion functions, and Emacs redisplay, cache the results of scanning the buffer, and consult the cache to avoid rescanning regions of the buffer unless they are modified. Turning on the cache slows down processing of short lines somewhat. This variable is automatically buffer-local in every buffer.  File: elisp, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display 38.4 The Echo Area ================== The "echo area" is used for displaying error messages (*note Errors::), for messages made with the `message' primitive, and for echoing keystrokes. It is not the same as the minibuffer, despite the fact that the minibuffer appears (when active) in the same place on the screen as the echo area. The `GNU Emacs Manual' specifies the rules for resolving conflicts between the echo area and the minibuffer for use of that screen space (*note The Minibuffer: (emacs)Minibuffer.). You can write output in the echo area by using the Lisp printing functions with `t' as the stream (*note Output Functions::), or explicitly. * Menu: * Displaying Messages:: Explicitly displaying text in the echo area. * Progress:: Informing user about progress of a long operation. * Logging Messages:: Echo area messages are logged for the user. * Echo Area Customization:: Controlling the echo area.  File: elisp, Node: Displaying Messages, Next: Progress, Up: The Echo Area 38.4.1 Displaying Messages in the Echo Area ------------------------------------------- This section describes the functions for explicitly producing echo area messages. Many other Emacs features display messages there, too. -- Function: message format-string &rest arguments This function displays a message in the echo area. The argument FORMAT-STRING is similar to a C language `printf' format string. See `format' in *note Formatting Strings::, for the details on the conversion specifications. `message' returns the constructed string. In batch mode, `message' prints the message text on the standard error stream, followed by a newline. If FORMAT-STRING, or strings among the ARGUMENTS, have `face' text properties, these affect the way the message is displayed. If FORMAT-STRING is `nil' or the empty string, `message' clears the echo area; if the echo area has been expanded automatically, this brings it back to its normal size. If the minibuffer is active, this brings the minibuffer contents back onto the screen immediately. (message "Minibuffer depth is %d." (minibuffer-depth)) -| Minibuffer depth is 0. => "Minibuffer depth is 0." ---------- Echo Area ---------- Minibuffer depth is 0. ---------- Echo Area ---------- To automatically display a message in the echo area or in a pop-buffer, depending on its size, use `display-message-or-buffer' (see below). -- Macro: with-temp-message message &rest body This construct displays a message in the echo area temporarily, during the execution of BODY. It displays MESSAGE, executes BODY, then returns the value of the last body form while restoring the previous echo area contents. -- Function: message-or-box format-string &rest arguments This function displays a message like `message', but may display it in a dialog box instead of the echo area. If this function is called in a command that was invoked using the mouse--more precisely, if `last-nonmenu-event' (*note Command Loop Info::) is either `nil' or a list--then it uses a dialog box or pop-up menu to display the message. Otherwise, it uses the echo area. (This is the same criterion that `y-or-n-p' uses to make a similar decision; see *note Yes-or-No Queries::.) You can force use of the mouse or of the echo area by binding `last-nonmenu-event' to a suitable value around the call. -- Function: message-box format-string &rest arguments This function displays a message like `message', but uses a dialog box (or a pop-up menu) whenever that is possible. If it is impossible to use a dialog box or pop-up menu, because the terminal does not support them, then `message-box' uses the echo area, like `message'. -- Function: display-message-or-buffer message &optional buffer-name not-this-window frame This function displays the message MESSAGE, which may be either a string or a buffer. If it is shorter than the maximum height of the echo area, as defined by `max-mini-window-height', it is displayed in the echo area, using `message'. Otherwise, `display-buffer' is used to show it in a pop-up buffer. Returns either the string shown in the echo area, or when a pop-up buffer is used, the window used to display it. If MESSAGE is a string, then the optional argument BUFFER-NAME is the name of the buffer used to display it when a pop-up buffer is used, defaulting to `*Message*'. In the case where MESSAGE is a string and displayed in the echo area, it is not specified whether the contents are inserted into the buffer anyway. The optional arguments NOT-THIS-WINDOW and FRAME are as for `display-buffer', and only used if a buffer is displayed. -- Function: current-message This function returns the message currently being displayed in the echo area, or `nil' if there is none.  File: elisp, Node: Progress, Next: Logging Messages, Prev: Displaying Messages, Up: The Echo Area 38.4.2 Reporting Operation Progress ----------------------------------- When an operation can take a while to finish, you should inform the user about the progress it makes. This way the user can estimate remaining time and clearly see that Emacs is busy working, not hung. Functions listed in this section provide simple and efficient way of reporting operation progress. Here is a working example that does nothing useful: (let ((progress-reporter (make-progress-reporter "Collecting mana for Emacs..." 0 500))) (dotimes (k 500) (sit-for 0.01) (progress-reporter-update progress-reporter k)) (progress-reporter-done progress-reporter)) -- Function: make-progress-reporter message min-value max-value &optional current-value min-change min-time This function creates and returns a "progress reporter"--an object you will use as an argument for all other functions listed here. The idea is to precompute as much data as possible to make progress reporting very fast. When this progress reporter is subsequently used, it will display MESSAGE in the echo area, followed by progress percentage. MESSAGE is treated as a simple string. If you need it to depend on a filename, for instance, use `format' before calling this function. MIN-VALUE and MAX-VALUE arguments stand for starting and final states of your operation. For instance, if you scan a buffer, they should be the results of `point-min' and `point-max' correspondingly. It is required that MAX-VALUE is greater than MIN-VALUE. If you create progress reporter when some part of the operation has already been completed, then specify CURRENT-VALUE argument. But normally you should omit it or set it to `nil'--it will default to MIN-VALUE then. Remaining arguments control the rate of echo area updates. Progress reporter will wait for at least MIN-CHANGE more percents of the operation to be completed before printing next message. MIN-TIME specifies the minimum time in seconds to pass between successive prints. It can be fractional. Depending on Emacs and system capabilities, progress reporter may or may not respect this last argument or do it with varying precision. Default value for MIN-CHANGE is 1 (one percent), for MIN-TIME--0.2 (seconds.) This function calls `progress-reporter-update', so the first message is printed immediately. -- Function: progress-reporter-update reporter value This function does the main work of reporting progress of your operation. It displays the message of REPORTER, followed by progress percentage determined by VALUE. If percentage is zero, or close enough according to the MIN-CHANGE and MIN-TIME arguments, then it is omitted from the output. REPORTER must be the result of a call to `make-progress-reporter'. VALUE specifies the current state of your operation and must be between MIN-VALUE and MAX-VALUE (inclusive) as passed to `make-progress-reporter'. For instance, if you scan a buffer, then VALUE should be the result of a call to `point'. This function respects MIN-CHANGE and MIN-TIME as passed to `make-progress-reporter' and so does not output new messages on every invocation. It is thus very fast and normally you should not try to reduce the number of calls to it: resulting overhead will most likely negate your effort. -- Function: progress-reporter-force-update reporter value &optional new-message This function is similar to `progress-reporter-update' except that it prints a message in the echo area unconditionally. The first two arguments have the same meaning as for `progress-reporter-update'. Optional NEW-MESSAGE allows you to change the message of the REPORTER. Since this functions always updates the echo area, such a change will be immediately presented to the user. -- Function: progress-reporter-done reporter This function should be called when the operation is finished. It prints the message of REPORTER followed by word "done" in the echo area. You should always call this function and not hope for `progress-reporter-update' to print "100%." Firstly, it may never print it, there are many good reasons for this not to happen. Secondly, "done" is more explicit. -- Macro: dotimes-with-progress-reporter (var count [result]) message body... This is a convenience macro that works the same way as `dotimes' does, but also reports loop progress using the functions described above. It allows you to save some typing. You can rewrite the example in the beginning of this node using this macro this way: (dotimes-with-progress-reporter (k 500) "Collecting some mana for Emacs..." (sit-for 0.01))  File: elisp, Node: Logging Messages, Next: Echo Area Customization, Prev: Progress, Up: The Echo Area 38.4.3 Logging Messages in `*Messages*' --------------------------------------- Almost all the messages displayed in the echo area are also recorded in the `*Messages*' buffer so that the user can refer back to them. This includes all the messages that are output with `message'. -- User Option: message-log-max This variable specifies how many lines to keep in the `*Messages*' buffer. The value `t' means there is no limit on how many lines to keep. The value `nil' disables message logging entirely. Here's how to display a message and prevent it from being logged: (let (message-log-max) (message ...)) To make `*Messages*' more convenient for the user, the logging facility combines successive identical messages. It also combines successive related messages for the sake of two cases: question followed by answer, and a series of progress messages. A "question followed by an answer" means two messages like the ones produced by `y-or-n-p': the first is `QUESTION', and the second is `QUESTION...ANSWER'. The first message conveys no additional information beyond what's in the second, so logging the second message discards the first from the log. A "series of progress messages" means successive messages like those produced by `make-progress-reporter'. They have the form `BASE...HOW-FAR', where BASE is the same each time, while HOW-FAR varies. Logging each message in the series discards the previous one, provided they are consecutive. The functions `make-progress-reporter' and `y-or-n-p' don't have to do anything special to activate the message log combination feature. It operates whenever two consecutive messages are logged that share a common prefix ending in `...'.  File: elisp, Node: Echo Area Customization, Prev: Logging Messages, Up: The Echo Area 38.4.4 Echo Area Customization ------------------------------ These variables control details of how the echo area works. -- Variable: cursor-in-echo-area This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-`nil', then the cursor appears at the end of the message. Otherwise, the cursor appears at point--not in the echo area at all. The value is normally `nil'; Lisp programs bind it to `t' for brief periods of time. -- Variable: echo-area-clear-hook This normal hook is run whenever the echo area is cleared--either by `(message nil)' or for any other reason. -- User Option: echo-keystrokes This variable determines how much time should elapse before command characters echo. Its value must be an integer or floating point number, which specifies the number of seconds to wait before echoing. If the user types a prefix key (such as `C-x') and then delays this many seconds before continuing, the prefix key is echoed in the echo area. (Once echoing begins in a key sequence, all subsequent characters in the same key sequence are echoed immediately.) If the value is zero, then command input is not echoed. -- Variable: message-truncate-lines Normally, displaying a long message resizes the echo area to display the entire message. But if the variable `message-truncate-lines' is non-`nil', the echo area does not resize, and the message is truncated to fit it, as in Emacs 20 and before. The variable `max-mini-window-height', which specifies the maximum height for resizing minibuffer windows, also applies to the echo area (which is really a special use of the minibuffer window. *Note Minibuffer Misc::.).  File: elisp, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display 38.5 Reporting Warnings ======================= "Warnings" are a facility for a program to inform the user of a possible problem, but continue running. * Menu: * Warning Basics:: Warnings concepts and functions to report them. * Warning Variables:: Variables programs bind to customize their warnings. * Warning Options:: Variables users set to control display of warnings.  File: elisp, Node: Warning Basics, Next: Warning Variables, Up: Warnings 38.5.1 Warning Basics --------------------- Every warning has a textual message, which explains the problem for the user, and a "severity level" which is a symbol. Here are the possible severity levels, in order of decreasing severity, and their meanings: `:emergency' A problem that will seriously impair Emacs operation soon if you do not attend to it promptly. `:error' A report of data or circumstances that are inherently wrong. `:warning' A report of data or circumstances that are not inherently wrong, but raise suspicion of a possible problem. `:debug' A report of information that may be useful if you are debugging. When your program encounters invalid input data, it can either signal a Lisp error by calling `error' or `signal' or report a warning with severity `:error'. Signaling a Lisp error is the easiest thing to do, but it means the program cannot continue processing. If you want to take the trouble to implement a way to continue processing despite the bad data, then reporting a warning of severity `:error' is the right way to inform the user of the problem. For instance, the Emacs Lisp byte compiler can report an error that way and continue compiling other functions. (If the program signals a Lisp error and then handles it with `condition-case', the user won't see the error message; it could show the message to the user by reporting it as a warning.) Each warning has a "warning type" to classify it. The type is a list of symbols. The first symbol should be the custom group that you use for the program's user options. For example, byte compiler warnings use the warning type `(bytecomp)'. You can also subcategorize the warnings, if you wish, by using more symbols in the list. -- Function: display-warning type message &optional level buffer-name This function reports a warning, using MESSAGE as the message and TYPE as the warning type. LEVEL should be the severity level, with `:warning' being the default. BUFFER-NAME, if non-`nil', specifies the name of the buffer for logging the warning. By default, it is `*Warnings*'. -- Function: lwarn type level message &rest args This function reports a warning using the value of `(format MESSAGE ARGS...)' as the message. In other respects it is equivalent to `display-warning'. -- Function: warn message &rest args This function reports a warning using the value of `(format MESSAGE ARGS...)' as the message, `(emacs)' as the type, and `:warning' as the severity level. It exists for compatibility only; we recommend not using it, because you should specify a specific warning type.  File: elisp, Node: Warning Variables, Next: Warning Options, Prev: Warning Basics, Up: Warnings 38.5.2 Warning Variables ------------------------ Programs can customize how their warnings appear by binding the variables described in this section. -- Variable: warning-levels This list defines the meaning and severity order of the warning severity levels. Each element defines one severity level, and they are arranged in order of decreasing severity. Each element has the form `(LEVEL STRING FUNCTION)', where LEVEL is the severity level it defines. STRING specifies the textual description of this level. STRING should use `%s' to specify where to put the warning type information, or it can omit the `%s' so as not to include that information. The optional FUNCTION, if non-`nil', is a function to call with no arguments, to get the user's attention. Normally you should not change the value of this variable. -- Variable: warning-prefix-function If non-`nil', the value is a function to generate prefix text for warnings. Programs can bind the variable to a suitable function. `display-warning' calls this function with the warnings buffer current, and the function can insert text in it. That text becomes the beginning of the warning message. The function is called with two arguments, the severity level and its entry in `warning-levels'. It should return a list to use as the entry (this value need not be an actual member of `warning-levels'). By constructing this value, the function can change the severity of the warning, or specify different handling for a given severity level. If the variable's value is `nil' then there is no function to call. -- Variable: warning-series Programs can bind this variable to `t' to say that the next warning should begin a series. When several warnings form a series, that means to leave point on the first warning of the series, rather than keep moving it for each warning so that it appears on the last one. The series ends when the local binding is unbound and `warning-series' becomes `nil' again. The value can also be a symbol with a function definition. That is equivalent to `t', except that the next warning will also call the function with no arguments with the warnings buffer current. The function can insert text which will serve as a header for the series of warnings. Once a series has begun, the value is a marker which points to the buffer position in the warnings buffer of the start of the series. The variable's normal value is `nil', which means to handle each warning separately. -- Variable: warning-fill-prefix When this variable is non-`nil', it specifies a fill prefix to use for filling each warning's text. -- Variable: warning-type-format This variable specifies the format for displaying the warning type in the warning message. The result of formatting the type this way gets included in the message under the control of the string in the entry in `warning-levels'. The default value is `" (%s)"'. If you bind it to `""' then the warning type won't appear at all.  File: elisp, Node: Warning Options, Prev: Warning Variables, Up: Warnings 38.5.3 Warning Options ---------------------- These variables are used by users to control what happens when a Lisp program reports a warning. -- User Option: warning-minimum-level This user option specifies the minimum severity level that should be shown immediately to the user. The default is `:warning', which means to immediately display all warnings except `:debug' warnings. -- User Option: warning-minimum-log-level This user option specifies the minimum severity level that should be logged in the warnings buffer. The default is `:warning', which means to log all warnings except `:debug' warnings. -- User Option: warning-suppress-types This list specifies which warning types should not be displayed immediately for the user. Each element of the list should be a list of symbols. If its elements match the first elements in a warning type, then that warning is not displayed immediately. -- User Option: warning-suppress-log-types This list specifies which warning types should not be logged in the warnings buffer. Each element of the list should be a list of symbols. If it matches the first few elements in a warning type, then that warning is not logged.  File: elisp, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display 38.6 Invisible Text =================== You can make characters "invisible", so that they do not appear on the screen, with the `invisible' property. This can be either a text property (*note Text Properties::) or a property of an overlay (*note Overlays::). Cursor motion also partly ignores these characters; if the command loop finds point within them, it moves point to the other side of them. In the simplest case, any non-`nil' `invisible' property makes a character invisible. This is the default case--if you don't alter the default value of `buffer-invisibility-spec', this is how the `invisible' property works. You should normally use `t' as the value of the `invisible' property if you don't plan to set `buffer-invisibility-spec' yourself. More generally, you can use the variable `buffer-invisibility-spec' to control which values of the `invisible' property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different `invisible' values, and subsequently make various subsets visible or invisible by changing the value of `buffer-invisibility-spec'. Controlling visibility with `buffer-invisibility-spec' is especially useful in a program to display the list of entries in a database. It permits the implementation of convenient filtering commands to view just a part of the entries in the database. Setting this variable is very fast, much faster than scanning all the text in the buffer looking for properties to change. -- Variable: buffer-invisibility-spec This variable specifies which kinds of `invisible' properties actually make a character invisible. Setting this variable makes it buffer-local. `t' A character is invisible if its `invisible' property is non-`nil'. This is the default. a list Each element of the list specifies a criterion for invisibility; if a character's `invisible' property fits any one of these criteria, the character is invisible. The list can have two kinds of elements: `ATOM' A character is invisible if its `invisible' property value is ATOM or if it is a list with ATOM as a member. `(ATOM . t)' A character is invisible if its `invisible' property value is ATOM or if it is a list with ATOM as a member. Moreover, a sequence of such characters displays as an ellipsis. Two functions are specifically provided for adding elements to `buffer-invisibility-spec' and removing elements from it. -- Function: add-to-invisibility-spec element This function adds the element ELEMENT to `buffer-invisibility-spec'. If `buffer-invisibility-spec' was `t', it changes to a list, `(t)', so that text whose `invisible' property is `t' remains invisible. -- Function: remove-from-invisibility-spec element This removes the element ELEMENT from `buffer-invisibility-spec'. This does nothing if ELEMENT is not in the list. A convention for use of `buffer-invisibility-spec' is that a major mode should use the mode's own name as an element of `buffer-invisibility-spec' and as the value of the `invisible' property: ;; If you want to display an ellipsis: (add-to-invisibility-spec '(my-symbol . t)) ;; If you don't want ellipsis: (add-to-invisibility-spec 'my-symbol) (overlay-put (make-overlay beginning end) 'invisible 'my-symbol) ;; When done with the overlays: (remove-from-invisibility-spec '(my-symbol . t)) ;; Or respectively: (remove-from-invisibility-spec 'my-symbol) You can check for invisibility using the following function: -- Function: invisible-p pos-or-prop If POS-OR-PROP is a marker or number, this function returns a non-`nil' value if the text at that position is invisible. If POS-OR-PROP is any other kind of Lisp object, that is taken to mean a possible value of the `invisible' text or overlay property. In that case, this function returns a non-`nil' value if that value would cause text to become invisible, based on the current value of `buffer-invisibility-spec'. Ordinarily, functions that operate on text or move point do not care whether the text is invisible. The user-level line motion commands ignore invisible newlines if `line-move-ignore-invisible' is non-`nil' (the default), but only because they are explicitly programmed to do so. However, if a command ends with point inside or immediately before invisible text, the main editing loop moves point further forward or further backward (in the same direction that the command already moved it) until that condition is no longer true. Thus, if the command moved point back into an invisible range, Emacs moves point back to the beginning of that range, and then back one more character. If the command moved point forward into an invisible range, Emacs moves point forward up to the first visible character that follows the invisible text. Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable this, the overlay should have a non-`nil' `isearch-open-invisible' property. The property value should be a function to be called with the overlay as an argument. This function should make the overlay visible permanently; it is used when the match overlaps the overlay on exit from the search. During the search, such overlays are made temporarily visible by temporarily modifying their invisible and intangible properties. If you want this to be done differently for a certain overlay, give it an `isearch-open-invisible-temporary' property which is a function. The function is called with two arguments: the first is the overlay, and the second is `nil' to make the overlay visible, or `t' to make it invisible again.  File: elisp, Node: Selective Display, Next: Temporary Displays, Prev: Invisible Text, Up: Display 38.7 Selective Display ====================== "Selective display" refers to a pair of related features for hiding certain lines on the screen. The first variant, explicit selective display, is designed for use in a Lisp program: it controls which lines are hidden by altering the text. This kind of hiding in some ways resembles the effect of the `invisible' property (*note Invisible Text::), but the two features are different and do not work the same way. In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a user-level feature. The way you control explicit selective display is by replacing a newline (control-j) with a carriage return (control-m). The text that was formerly a line following that newline is now hidden. Strictly speaking, it is temporarily no longer a line at all, since only newlines can separate lines; it is now part of the previous line. Selective display does not directly affect editing commands. For example, `C-f' (`forward-char') moves point unhesitatingly into hidden text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, `next-line' skips hidden lines, since it searches only for newlines. Modes that use selective display can also define commands that take account of the newlines, or that control which parts of the text are hidden. When you write a selectively displayed buffer into a file, all the control-m's are output as newlines. This means that when you next read in the file, it looks OK, with nothing hidden. The selective display effect is seen only within Emacs. -- Variable: selective-display This buffer-local variable enables selective display. This means that lines, or portions of lines, may be made hidden. * If the value of `selective-display' is `t', then the character control-m marks the start of hidden text; the control-m, and the rest of the line following it, are not displayed. This is explicit selective display. * If the value of `selective-display' is a positive integer, then lines that start with more than that many columns of indentation are not displayed. When some portion of a buffer is hidden, the vertical movement commands operate as if that portion did not exist, allowing a single `next-line' command to skip any number of hidden lines. However, character movement commands (such as `forward-char') do not skip the hidden portion, and it is possible (if tricky) to insert or delete text in an hidden portion. In the examples below, we show the _display appearance_ of the buffer `foo', which changes with the value of `selective-display'. The _contents_ of the buffer do not change. (setq selective-display nil) => nil ---------- Buffer: foo ---------- 1 on this column 2on this column 3n this column 3n this column 2on this column 1 on this column ---------- Buffer: foo ---------- (setq selective-display 2) => 2 ---------- Buffer: foo ---------- 1 on this column 2on this column 2on this column 1 on this column ---------- Buffer: foo ---------- -- User Option: selective-display-ellipses If this buffer-local variable is non-`nil', then Emacs displays `...' at the end of a line that is followed by hidden text. This example is a continuation of the previous one. (setq selective-display-ellipses t) => t ---------- Buffer: foo ---------- 1 on this column 2on this column ... 2on this column 1 on this column ---------- Buffer: foo ---------- You can use a display table to substitute other text for the ellipsis (`...'). *Note Display Tables::.  File: elisp, Node: Temporary Displays, Next: Overlays, Prev: Selective Display, Up: Display 38.8 Temporary Displays ======================= Temporary displays are used by Lisp programs to put output into a buffer and then present it to the user for perusal rather than for editing. Many help commands use this feature. -- Special Form: with-output-to-temp-buffer buffer-name forms... This function executes FORMS while arranging to insert any output they print into the buffer named BUFFER-NAME, which is first created if necessary, and put into Help mode. Finally, the buffer is displayed in some window, but not selected. If the FORMS do not change the major mode in the output buffer, so that it is still Help mode at the end of their execution, then `with-output-to-temp-buffer' makes this buffer read-only at the end, and also scans it for function and variable names to make them into clickable cross-references. *Note Tips for Documentation Strings: Docstring hyperlinks, in particular the item on hyperlinks in documentation strings, for more details. The string BUFFER-NAME specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. The buffer is erased initially (with no questions asked), and it is marked as unmodified after `with-output-to-temp-buffer' exits. `with-output-to-temp-buffer' binds `standard-output' to the temporary buffer, then it evaluates the forms in FORMS. Output using the Lisp output functions within FORMS goes by default to that buffer (but screen display and messages in the echo area, although they are "output" in the general sense of the word, are not affected). *Note Output Functions::. Several hooks are available for customizing the behavior of this construct; they are listed below. The value of the last form in FORMS is returned. ---------- Buffer: foo ---------- This is the contents of foo. ---------- Buffer: foo ---------- (with-output-to-temp-buffer "foo" (print 20) (print standard-output)) => # ---------- Buffer: foo ---------- 20 # ---------- Buffer: foo ---------- -- User Option: temp-buffer-show-function If this variable is non-`nil', `with-output-to-temp-buffer' calls it as a function to do the job of displaying a help buffer. The function gets one argument, which is the buffer it should display. It is a good idea for this function to run `temp-buffer-show-hook' just as `with-output-to-temp-buffer' normally would, inside of `save-selected-window' and with the chosen window and buffer selected. -- Variable: temp-buffer-setup-hook This normal hook is run by `with-output-to-temp-buffer' before evaluating BODY. When the hook runs, the temporary buffer is current. This hook is normally set up with a function to put the buffer in Help mode. -- Variable: temp-buffer-show-hook This normal hook is run by `with-output-to-temp-buffer' after displaying the temporary buffer. When the hook runs, the temporary buffer is current, and the window it was displayed in is selected. -- Function: momentary-string-display string position &optional char message This function momentarily displays STRING in the current buffer at POSITION. It has no effect on the undo list or on the buffer's modification status. The momentary display remains until the next input event. If the next input event is CHAR, `momentary-string-display' ignores it and returns. Otherwise, that event remains buffered for subsequent use as input. Thus, typing CHAR will simply remove the string from the display, while typing (say) `C-f' will remove the string from the display and later (presumably) move point forward. The argument CHAR is a space by default. The return value of `momentary-string-display' is not meaningful. If the string STRING does not contain control characters, you can do the same job in a more general way by creating (and then subsequently deleting) an overlay with a `before-string' property. *Note Overlay Properties::. If MESSAGE is non-`nil', it is displayed in the echo area while STRING is displayed in the buffer. If it is `nil', a default message says to type CHAR to continue. In this example, point is initially located at the beginning of the second line: ---------- Buffer: foo ---------- This is the contents of foo. -!-Second line. ---------- Buffer: foo ---------- (momentary-string-display "**** Important Message! ****" (point) ?\r "Type RET when done reading") => t ---------- Buffer: foo ---------- This is the contents of foo. **** Important Message! ****Second line. ---------- Buffer: foo ---------- ---------- Echo Area ---------- Type RET when done reading ---------- Echo Area ----------  File: elisp, Node: Overlays, Next: Width, Prev: Temporary Displays, Up: Display 38.9 Overlays ============= You can use "overlays" to alter the appearance of a buffer's text on the screen, for the sake of presentation features. An overlay is an object that belongs to a particular buffer, and has a specified beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay. The visual effect of an overlay is the same as of the corresponding text property (*note Text Properties::). However, due to a different implementation, overlays generally don't scale well (many operations take a time that is proportional to the number of overlays in the buffer). If you need to affect the visual appearance of many portions in the buffer, we recommend using text properties. An overlay uses markers to record its beginning and end; thus, editing the text of the buffer adjusts the beginning and end of each overlay so that it stays with the text. When you create the overlay, you can specify whether text inserted at the beginning should be inside the overlay or outside, and likewise for the end of the overlay. * Menu: * Managing Overlays:: Creating and moving overlays. * Overlay Properties:: How to read and set properties. What properties do to the screen display. * Finding Overlays:: Searching for overlays.  File: elisp, Node: Managing Overlays, Next: Overlay Properties, Up: Overlays 38.9.1 Managing Overlays ------------------------ This section describes the functions to create, delete and move overlays, and to examine their contents. Overlay changes are not recorded in the buffer's undo list, since the overlays are not part of the buffer's contents. -- Function: overlayp object This function returns `t' if OBJECT is an overlay. -- Function: make-overlay start end &optional buffer front-advance rear-advance This function creates and returns an overlay that belongs to BUFFER and ranges from START to END. Both START and END must specify buffer positions; they may be integers or markers. If BUFFER is omitted, the overlay is created in the current buffer. The arguments FRONT-ADVANCE and REAR-ADVANCE specify the marker insertion type for the start of the overlay and for the end of the overlay, respectively. *Note Marker Insertion Types::. If they are both `nil', the default, then the overlay extends to include any text inserted at the beginning, but not text inserted at the end. If FRONT-ADVANCE is non-`nil', text inserted at the beginning of the overlay is excluded from the overlay. If REAR-ADVANCE is non-`nil', text inserted at the end of the overlay is included in the overlay. -- Function: overlay-start overlay This function returns the position at which OVERLAY starts, as an integer. -- Function: overlay-end overlay This function returns the position at which OVERLAY ends, as an integer. -- Function: overlay-buffer overlay This function returns the buffer that OVERLAY belongs to. It returns `nil' if OVERLAY has been deleted. -- Function: delete-overlay overlay This function deletes OVERLAY. The overlay continues to exist as a Lisp object, and its property list is unchanged, but it ceases to be attached to the buffer it belonged to, and ceases to have any effect on display. A deleted overlay is not permanently disconnected. You can give it a position in a buffer again by calling `move-overlay'. -- Function: move-overlay overlay start end &optional buffer This function moves OVERLAY to BUFFER, and places its bounds at START and END. Both arguments START and END must specify buffer positions; they may be integers or markers. If BUFFER is omitted, OVERLAY stays in the same buffer it was already associated with; if OVERLAY was deleted, it goes into the current buffer. The return value is OVERLAY. This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be "lost." -- Function: remove-overlays &optional start end name value This function removes all the overlays between START and END whose property NAME has the value VALUE. It can move the endpoints of the overlays in the region, or split them. If NAME is omitted or `nil', it means to delete all overlays in the specified region. If START and/or END are omitted or `nil', that means the beginning and end of the buffer respectively. Therefore, `(remove-overlays)' removes all the overlays in the current buffer. -- Function: copy-overlay overlay This function returns a copy of OVERLAY. The copy has the same endpoints and properties as OVERLAY. However, the marker insertion type for the start of the overlay and for the end of the overlay are set to their default values (*note Marker Insertion Types::). Here are some examples: ;; Create an overlay. (setq foo (make-overlay 1 10)) => # (overlay-start foo) => 1 (overlay-end foo) => 10 (overlay-buffer foo) => # ;; Give it a property we can check later. (overlay-put foo 'happy t) => t ;; Verify the property is present. (overlay-get foo 'happy) => t ;; Move the overlay. (move-overlay foo 5 20) => # (overlay-start foo) => 5 (overlay-end foo) => 20 ;; Delete the overlay. (delete-overlay foo) => nil ;; Verify it is deleted. foo => # ;; A deleted overlay has no position. (overlay-start foo) => nil (overlay-end foo) => nil (overlay-buffer foo) => nil ;; Undelete the overlay. (move-overlay foo 1 20) => # ;; Verify the results. (overlay-start foo) => 1 (overlay-end foo) => 20 (overlay-buffer foo) => # ;; Moving and deleting the overlay does not change its properties. (overlay-get foo 'happy) => t Emacs stores the overlays of each buffer in two lists, divided around an arbitrary "center position." One list extends backwards through the buffer from that center position, and the other extends forwards from that center position. The center position can be anywhere in the buffer. -- Function: overlay-recenter pos This function recenters the overlays of the current buffer around position POS. That makes overlay lookup faster for positions near POS, but slower for positions far away from POS. A loop that scans the buffer forwards, creating overlays, can run faster if you do `(overlay-recenter (point-max))' first.  File: elisp, Node: Overlay Properties, Next: Finding Overlays, Prev: Managing Overlays, Up: Overlays 38.9.2 Overlay Properties ------------------------- Overlay properties are like text properties in that the properties that alter how a character is displayed can come from either source. But in most respects they are different. *Note Text Properties::, for comparison. Text properties are considered a part of the text; overlays and their properties are specifically considered not to be part of the text. Thus, copying text between various buffers and strings preserves text properties, but does not try to preserve overlays. Changing a buffer's text properties marks the buffer as modified, while moving an overlay or changing its properties does not. Unlike text property changes, overlay property changes are not recorded in the buffer's undo list. Since more than one overlay can specify a property value for the same character, Emacs lets you specify a priority value of each overlay. You should not make assumptions about which overlay will prevail when there is a conflict and they have the same priority. These functions read and set the properties of an overlay: -- Function: overlay-get overlay prop This function returns the value of property PROP recorded in OVERLAY, if any. If OVERLAY does not record any value for that property, but it does have a `category' property which is a symbol, that symbol's PROP property is used. Otherwise, the value is `nil'. -- Function: overlay-put overlay prop value This function sets the value of property PROP recorded in OVERLAY to VALUE. It returns VALUE. -- Function: overlay-properties overlay This returns a copy of the property list of OVERLAY. See also the function `get-char-property' which checks both overlay properties and text properties for a given character. *Note Examining Properties::. Many overlay properties have special meanings; here is a table of them: `priority' This property's value (which should be a nonnegative integer number) determines the priority of the overlay. No priority, or `nil', means zero. The priority matters when two or more overlays cover the same character and both specify the same property; the one whose `priority' value is larger overrides the other. For the `face' property, the higher priority overlay's value does not completely override the other value; instead, its face attributes override the face attributes of the lower priority `face' property. Currently, all overlays take priority over text properties. Please avoid using negative priority values, as we have not yet decided just what they should mean. `window' If the `window' property is non-`nil', then the overlay applies only on that window. `category' If an overlay has a `category' property, we call it the "category" of the overlay. It should be a symbol. The properties of the symbol serve as defaults for the properties of the overlay. `face' This property controls the way text is displayed--for example, which font and which colors. *Note Faces::, for more information. In the simplest case, the value is a face name. It can also be a list; then each element can be any of these possibilities: * A face name (a symbol or string). * A property list of face attributes. This has the form (KEYWORD VALUE ...), where each KEYWORD is a face attribute name and VALUE is a meaningful value for that attribute. With this feature, you do not need to create a face each time you want to specify a particular attribute for certain text. *Note Face Attributes::. * A cons cell, either of the form `(foreground-color . COLOR-NAME)' or `(background-color . COLOR-NAME)'. These elements specify just the foreground color or just the background color. `(foreground-color . COLOR-NAME)' has the same effect as `(:foreground COLOR-NAME)'; likewise for the background. `mouse-face' This property is used instead of `face' when the mouse is within the range of the overlay. `display' This property activates various features that change the way text is displayed. For example, it can make text appear taller or shorter, higher or lower, wider or narrower, or replaced with an image. *Note Display Property::. `help-echo' If an overlay has a `help-echo' property, then when you move the mouse onto the text in the overlay, Emacs displays a help string in the echo area, or in the tooltip window. For details see *note Text help-echo::. `modification-hooks' This property's value is a list of functions to be called if any character within the overlay is changed or if text is inserted strictly within the overlay. The hook functions are called both before and after each change. If the functions save the information they receive, and compare notes between calls, they can determine exactly what change has been made in the buffer text. When called before a change, each function receives four arguments: the overlay, `nil', and the beginning and end of the text range to be modified. When called after a change, each function receives five arguments: the overlay, `t', the beginning and end of the text range just modified, and the length of the pre-change text replaced by that range. (For an insertion, the pre-change length is zero; for a deletion, that length is the number of characters deleted, and the post-change beginning and end are equal.) If these functions modify the buffer, they should bind `inhibit-modification-hooks' to `t' around doing so, to avoid confusing the internal mechanism that calls these hooks. Text properties also support the `modification-hooks' property, but the details are somewhat different (*note Special Properties::). `insert-in-front-hooks' This property's value is a list of functions to be called before and after inserting text right at the beginning of the overlay. The calling conventions are the same as for the `modification-hooks' functions. `insert-behind-hooks' This property's value is a list of functions to be called before and after inserting text right at the end of the overlay. The calling conventions are the same as for the `modification-hooks' functions. `invisible' The `invisible' property can make the text in the overlay invisible, which means that it does not appear on the screen. *Note Invisible Text::, for details. `intangible' The `intangible' property on an overlay works just like the `intangible' text property. *Note Special Properties::, for details. `isearch-open-invisible' This property tells incremental search how to make an invisible overlay visible, permanently, if the final match overlaps it. *Note Invisible Text::. `isearch-open-invisible-temporary' This property tells incremental search how to make an invisible overlay visible, temporarily, during the search. *Note Invisible Text::. `before-string' This property's value is a string to add to the display at the beginning of the overlay. The string does not appear in the buffer in any sense--only on the screen. `after-string' This property's value is a string to add to the display at the end of the overlay. The string does not appear in the buffer in any sense--only on the screen. `line-prefix' This property specifies a display spec to prepend to each non-continuation line at display-time. *Note Truncation::. `wrap-prefix' This property specifies a display spec to prepend to each continuation line at display-time. *Note Truncation::. `evaporate' If this property is non-`nil', the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give an empty overlay a non-`nil' `evaporate' property, that deletes it immediately. `local-map' If this property is non-`nil', it specifies a keymap for a portion of the text. The property's value replaces the buffer's local map, when the character after point is within the overlay. *Note Active Keymaps::. `keymap' The `keymap' property is similar to `local-map' but overrides the buffer's local map (and the map specified by the `local-map' property) rather than replacing it. The `local-map' and `keymap' properties do not affect a string displayed by the `before-string', `after-string', or `display' properties. This is only relevant for mouse clicks and other mouse events that fall on the string, since point is never on the string. To bind special mouse events for the string, assign it a `local-map' or `keymap' text property. *Note Special Properties::.  File: elisp, Node: Finding Overlays, Prev: Overlay Properties, Up: Overlays 38.9.3 Searching for Overlays ----------------------------- -- Function: overlays-at pos This function returns a list of all the overlays that cover the character at position POS in the current buffer. The list is in no particular order. An overlay contains position POS if it begins at or before POS, and ends after POS. To illustrate usage, here is a Lisp function that returns a list of the overlays that specify property PROP for the character at point: (defun find-overlays-specifying (prop) (let ((overlays (overlays-at (point))) found) (while overlays (let ((overlay (car overlays))) (if (overlay-get overlay prop) (setq found (cons overlay found)))) (setq overlays (cdr overlays))) found)) -- Function: overlays-in beg end This function returns a list of the overlays that overlap the region BEG through END. "Overlap" means that at least one character is contained within the overlay and also contained within the specified region; however, empty overlays are included in the result if they are located at BEG, strictly between BEG and END, or at END when END denotes the position at the end of the buffer. -- Function: next-overlay-change pos This function returns the buffer position of the next beginning or end of an overlay, after POS. If there is none, it returns `(point-max)'. -- Function: previous-overlay-change pos This function returns the buffer position of the previous beginning or end of an overlay, before POS. If there is none, it returns `(point-min)'. As an example, here's a simplified (and inefficient) version of the primitive function `next-single-char-property-change' (*note Property Search::). It searches forward from position POS for the next position where the value of a given property `prop', as obtained from either overlays or text properties, changes. (defun next-single-char-property-change (position prop) (save-excursion (goto-char position) (let ((propval (get-char-property (point) prop))) (while (and (not (eobp)) (eq (get-char-property (point) prop) propval)) (goto-char (min (next-overlay-change (point)) (next-single-property-change (point) prop))))) (point)))  File: elisp, Node: Width, Next: Line Height, Prev: Overlays, Up: Display 38.10 Width =========== Since not all characters have the same width, these functions let you check the width of a character. *Note Primitive Indent::, and *note Screen Lines::, for related functions. -- Function: char-width char This function returns the width in columns of the character CHAR, if it were displayed in the current buffer and the selected window. -- Function: string-width string This function returns the width in columns of the string STRING, if it were displayed in the current buffer and the selected window. -- Function: truncate-string-to-width string width &optional start-column padding ellipsis This function returns the part of STRING that fits within WIDTH columns, as a new string. If STRING does not reach WIDTH, then the result ends where STRING ends. If one multi-column character in STRING extends across the column WIDTH, that character is not included in the result. Thus, the result can fall short of WIDTH but cannot go beyond it. The optional argument START-COLUMN specifies the starting column. If this is non-`nil', then the first START-COLUMN columns of the string are omitted from the value. If one multi-column character in STRING extends across the column START-COLUMN, that character is not included. The optional argument PADDING, if non-`nil', is a padding character added at the beginning and end of the result string, to extend it to exactly WIDTH columns. The padding character is used at the end of the result if it falls short of WIDTH. It is also used at the beginning of the result if one multi-column character in STRING extends across the column START-COLUMN. If ELLIPSIS is non-`nil', it should be a string which will replace the end of STR (including any padding) if it extends beyond END-COLUMN, unless the display width of STR is equal to or less than the display width of ELLIPSIS. If ELLIPSIS is non-`nil' and not a string, it stands for `"..."'. (truncate-string-to-width "\tab\t" 12 4) => "ab" (truncate-string-to-width "\tab\t" 12 4 ?\s) => " ab "  File: elisp, Node: Line Height, Next: Faces, Prev: Width, Up: Display 38.11 Line Height ================= The total height of each display line consists of the height of the contents of the line, plus optional additional vertical line spacing above or below the display line. The height of the line contents is the maximum height of any character or image on that display line, including the final newline if there is one. (A display line that is continued doesn't include a final newline.) That is the default line height, if you do nothing to specify a greater height. (In the most common case, this equals the height of the default frame font.) There are several ways to explicitly specify a larger line height, either by specifying an absolute height for the display line, or by specifying vertical space. However, no matter what you specify, the actual line height can never be less than the default. A newline can have a `line-height' text or overlay property that controls the total height of the display line ending in that newline. If the property value is `t', the newline character has no effect on the displayed height of the line--the visible contents alone determine the height. This is useful for tiling small images (or image slices) without adding blank areas between the images. If the property value is a list of the form `(HEIGHT TOTAL)', that adds extra space _below_ the display line. First Emacs uses HEIGHT as a height spec to control extra space _above_ the line; then it adds enough space _below_ the line to bring the total line height up to TOTAL. In this case, the other ways to specify the line spacing are ignored. Any other kind of property value is a height spec, which translates into a number--the specified line height. There are several ways to write a height spec; here's how each of them translates into a number: `INTEGER' If the height spec is a positive integer, the height value is that integer. `FLOAT' If the height spec is a float, FLOAT, the numeric height value is FLOAT times the frame's default line height. `(FACE . RATIO)' If the height spec is a cons of the format shown, the numeric height is RATIO times the height of face FACE. RATIO can be any type of number, or `nil' which means a ratio of 1. If FACE is `t', it refers to the current face. `(nil . RATIO)' If the height spec is a cons of the format shown, the numeric height is RATIO times the height of the contents of the line. Thus, any valid height spec determines the height in pixels, one way or another. If the line contents' height is less than that, Emacs adds extra vertical space above the line to achieve the specified total height. If you don't specify the `line-height' property, the line's height consists of the contents' height plus the line spacing. There are several ways to specify the line spacing for different parts of Emacs text. On graphical terminals, you can specify the line spacing for all lines in a frame, using the `line-spacing' frame parameter (*note Layout Parameters::). However, if the default value of `line-spacing' is non-`nil', it overrides the frame's `line-spacing' parameter. An integer value specifies the number of pixels put below lines. A floating point number specifies the spacing relative to the frame's default line height. You can specify the line spacing for all lines in a buffer via the buffer-local `line-spacing' variable. An integer value specifies the number of pixels put below lines. A floating point number specifies the spacing relative to the default frame line height. This overrides line spacings specified for the frame. Finally, a newline can have a `line-spacing' text or overlay property that overrides the default frame line spacing and the buffer local `line-spacing' variable, for the display line ending in that newline. One way or another, these mechanisms specify a Lisp value for the spacing of each line. The value is a height spec, and it translates into a Lisp value as described above. However, in this case the numeric height value specifies the line spacing, rather than the line height. On text-only terminals, the line spacing cannot be altered.  File: elisp, Node: Faces, Next: Fringes, Prev: Line Height, Up: Display 38.12 Faces =========== A "face" is a collection of graphical attributes for displaying text: font family, foreground color, background color, optional underlining, and so on. Faces control how buffer text is displayed, and how some parts of the frame, such as the mode-line, are displayed. *Note Standard Faces: (emacs)Standard Faces, for the list of faces Emacs normally comes with. For most purposes, you refer to a face in Lisp programs using its "face name". This is either a string or (equivalently) a Lisp symbol whose name is equal to that string. -- Function: facep object This function returns a non-`nil' value if OBJECT is a Lisp symbol or string that names a face. Otherwise, it returns `nil'. Each face name is meaningful for all frames, and by default it has the same meaning in all frames. But you can arrange to give a particular face name a special meaning in one frame if you wish. * Menu: * Defining Faces:: How to define a face with `defface'. * Face Attributes:: What is in a face? * Attribute Functions:: Functions to examine and set face attributes. * Displaying Faces:: How Emacs combines the faces specified for a character. * Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. * Fontsets:: A fontset is a collection of fonts that handle a range of character sets. * Low-Level Font:: Lisp representation for character display fonts.  File: elisp, Node: Defining Faces, Next: Face Attributes, Up: Faces 38.12.1 Defining Faces ---------------------- The way to define a new face is with `defface'. This creates a kind of customization item (*note Customization::) which the user can customize using the Customization buffer (*note Easy Customization: (emacs)Easy Customization.). People are sometimes tempted to create variables whose values specify which faces to use (for example, Font-Lock does this). In the vast majority of cases, this is not necessary, and simply using faces directly is preferable. -- Macro: defface face spec doc [keyword value]... This declares FACE as a customizable face whose default attributes are given by SPEC. You should not quote the symbol FACE, and it should not end in `-face' (that would be redundant). The argument DOC specifies the face documentation. The keywords you can use in `defface' are the same as in `defgroup' and `defcustom' (*note Common Keywords::). When `defface' executes, it defines the face according to SPEC, then uses any customizations that were read from the init file (*note Init File::) to override that specification. When you evaluate a `defface' form with `C-M-x' in Emacs Lisp mode (`eval-defun'), a special feature of `eval-defun' overrides any customizations of the face. This way, the face reflects exactly what the `defface' says. The purpose of SPEC is to specify how the face should appear on different kinds of terminals. It should be an alist whose elements have the form `(DISPLAY ATTS)'. Each element's CAR, DISPLAY, specifies a class of terminals. (The first element, if its CAR is `default', is special--it specifies defaults for the remaining elements). The element's CADR, ATTS, is a list of face attributes and their values; it specifies what the face should look like on that kind of terminal. The possible attributes are defined in the value of `custom-face-attributes'. The DISPLAY part of an element of SPEC determines which frames the element matches. If more than one element of SPEC matches a given frame, the first element that matches is the one used for that frame. There are three possibilities for DISPLAY: `default' This element of SPEC doesn't match any frames; instead, it specifies defaults that apply to all frames. This kind of element, if used, must be the first element of SPEC. Each of the following elements can override any or all of these defaults. `t' This element of SPEC matches all frames. Therefore, any subsequent elements of SPEC are never used. Normally `t' is used in the last (or only) element of SPEC. a list If DISPLAY is a list, each element should have the form `(CHARACTERISTIC VALUE...)'. Here CHARACTERISTIC specifies a way of classifying frames, and the VALUEs are possible classifications which DISPLAY should apply to. Here are the possible values of CHARACTERISTIC: `type' The kind of window system the frame uses--either `graphic' (any graphics-capable display), `x', `pc' (for the MS-DOS console), `w32' (for MS Windows 9X/NT/2K/XP), or `tty' (a non-graphics-capable display). *Note window-system: Window Systems. `class' What kinds of colors the frame supports--either `color', `grayscale', or `mono'. `background' The kind of background--either `light' or `dark'. `min-colors' An integer that represents the minimum number of colors the frame should support. This matches a frame if its `display-color-cells' value is at least the specified integer. `supports' Whether or not the frame can display the face attributes given in VALUE... (*note Face Attributes::). *Note Display Face Attribute Testing::, for more information on exactly how this testing is done. If an element of DISPLAY specifies more than one VALUE for a given CHARACTERISTIC, any of those values is acceptable. If DISPLAY has more than one element, each element should specify a different CHARACTERISTIC; then _each_ characteristic of the frame must match one of the VALUEs specified for it in DISPLAY. Here's how the standard face `region' is defined: (defface region '((((class color) (min-colors 88) (background dark)) :background "blue3") (((class color) (min-colors 88) (background light)) :background "lightgoldenrod2") (((class color) (min-colors 16) (background dark)) :background "blue3") (((class color) (min-colors 16) (background light)) :background "lightgoldenrod2") (((class color) (min-colors 8)) :background "blue" :foreground "white") (((type tty) (class mono)) :inverse-video t) (t :background "gray")) "Basic face for highlighting the region." :group 'basic-faces) Internally, `defface' uses the symbol property `face-defface-spec' to record the specified face attributes. The attributes saved by the user with the customization buffer are recorded in the symbol property `saved-face'; the attributes customized by the user for the current session, but not saved, are recorded in the symbol property `customized-face'. The documentation string is recorded in the symbol property `face-documentation'. -- User Option: frame-background-mode This option, if non-`nil', specifies the background type to use for interpreting face definitions. If it is `dark', then Emacs treats all frames as if they had a dark background, regardless of their actual background colors. If it is `light', then Emacs treats all frames as if they had a light background.  File: elisp, Node: Face Attributes, Next: Attribute Functions, Prev: Defining Faces, Up: Faces 38.12.2 Face Attributes ----------------------- The effect of using a face is determined by a fixed set of "face attributes". This table lists all the face attributes, their possible values, and their effects. You can specify more than one face for a given piece of text; Emacs merges the attributes of all the faces to determine how to display the text. *Note Displaying Faces::. In addition to the values given below, each face attribute can also have the value `unspecified'. This special value means the face doesn't specify that attribute. In face merging, when the first face fails to specify a particular attribute, the next face gets a chance. However, the `default' face must specify all attributes. Some of these font attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the attribute is ignored. `:family' Font family name or fontset name (a string). If you specify a font family name, the wild-card characters `*' and `?' are allowed. The function `font-family-list', described below, returns a list of available family names. *Note Fontsets::, for information about fontsets. `:foundry' The name of the "font foundry" in which the font family specified by the `:family' attribute is located (a string). The wild-card characters `*' and `?' are allowed. `:width' Relative proportionate character width, also known as the character set width. This should be one of the symbols `ultra-condensed', `extra-condensed', `condensed', `semi-condensed', `normal', `semi-expanded', `expanded', `extra-expanded', or `ultra-expanded'. `:height' The height of the font. In the simplest case, this is an integer in units of 1/10 point. The value can also be a floating point number or a function, which specifies the height relative to an "underlying face" (i.e., a face that has a lower priority in the list described in *note Displaying Faces::). If the value is a floating point number, that specifies the amount by which to scale the height of the underlying face. If the value is a function, that function is called with one argument, the height of the underlying face, and returns the height of the new face. If the function is passed an integer argument, it must return an integer. The height of the default face must be specified using an integer; floating point and function values are not allowed. `:weight' Font weight--one of the symbols (from densest to faintest) `ultra-bold', `extra-bold', `bold', `semi-bold', `normal', `semi-light', `light', `extra-light', or `ultra-light'. On text-only terminals that support variable-brightness text, any weight greater than normal is displayed as extra bright, and any weight less than normal is displayed as half-bright. `:slant' Font slant--one of the symbols `italic', `oblique', `normal', `reverse-italic', or `reverse-oblique'. On text-only terminals that support variable-brightness text, slanted text is displayed as half-bright. `:foreground' Foreground color, a string. The value can be a system-defined color name, or a hexadecimal color specification. *Note Color Names::. On black-and-white displays, certain shades of gray are implemented by stipple patterns. `:background' Background color, a string. The value can be a system-defined color name, or a hexadecimal color specification. *Note Color Names::. `:underline' Whether or not characters should be underlined, and in what color. If the value is `t', underlining uses the foreground color of the face. If the value is a string, underlining uses that color. The value `nil' means do not underline. `:overline' Whether or not characters should be overlined, and in what color. The value is used like that of `:underline'. `:strike-through' Whether or not characters should be strike-through, and in what color. The value is used like that of `:underline'. `:box' Whether or not a box should be drawn around characters, its color, the width of the box lines, and 3D appearance. Here are the possible values of the `:box' attribute, and what they mean: `nil' Don't draw a box. `t' Draw a box with lines of width 1, in the foreground color. COLOR Draw a box with lines of width 1, in color COLOR. `(:line-width WIDTH :color COLOR :style STYLE)' This way you can explicitly specify all aspects of the box. The value WIDTH specifies the width of the lines to draw; it defaults to 1. The value COLOR specifies the color to draw with. The default is the foreground color of the face for simple boxes, and the background color of the face for 3D boxes. The value STYLE specifies whether to draw a 3D box. If it is `released-button', the box looks like a 3D button that is not being pressed. If it is `pressed-button', the box looks like a 3D button that is being pressed. If it is `nil' or omitted, a plain 2D box is used. `:inverse-video' Whether or not characters should be displayed in inverse video. The value should be `t' (yes) or `nil' (no). `:stipple' The background stipple, a bitmap. The value can be a string; that should be the name of a file containing external-format X bitmap data. The file is found in the directories listed in the variable `x-bitmap-file-path'. Alternatively, the value can specify the bitmap directly, with a list of the form `(WIDTH HEIGHT DATA)'. Here, WIDTH and HEIGHT specify the size in pixels, and DATA is a string containing the raw bits of the bitmap, row by row. Each row occupies (WIDTH + 7) / 8 consecutive bytes in the string (which should be a unibyte string for best results). This means that each row always occupies at least one whole byte. If the value is `nil', that means use no stipple pattern. Normally you do not need to set the stipple attribute, because it is used automatically to handle certain shades of gray. `:font' The font used to display the face. Its value should be a font object. *Note Font Selection::, for information about font objects. When specifying this attribute using `set-face-attribute' (*note Attribute Functions::), you may also supply a font spec, a font entity, or a string. Emacs converts such values to an appropriate font object, and stores that font object as the actual attribute value. If you specify a string, the contents of the string should be a font name (*note Font Specification Options: (emacs)Font X.); if the font name is an XLFD containing wildcards, Emacs chooses the first font matching those wildcards. Specifying this attribute also changes the values of the `:family', `:foundry', `:width', `:height', `:weight', and `:slant' attributes. `:inherit' The name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like an underlying face would be, with higher priority than underlying faces (*note Displaying Faces::). If a list of faces is used, attributes from faces earlier in the list override those from later faces. For compatibility with Emacs 20, you can also specify values for two "fake" face attributes: `:bold' and `:italic'. Their values must be either `t' or `nil'; a value of `unspecified' is not allowed. Setting `:bold' to `t' is equivalent to setting the `:weight' attribute to `bold', and setting it to `nil' is equivalent to setting `:weight' to `normal'. Setting `:italic' to `t' is equivalent to setting the `:slant' attribute to `italic', and setting it to `nil' is equivalent to setting `:slant' to `normal'. -- Function: font-family-list &optional frame This function returns a list of available font family names. The optional argument FRAME specifies the frame on which the text is to be displayed; if it is `nil', the selected frame is used. -- User Option: underline-minimum-offset This variable specifies the minimum distance between the baseline and the underline, in pixels, when displaying underlined text. -- User Option: x-bitmap-file-path This variable specifies a list of directories for searching for bitmap files, for the `:stipple' attribute. -- Function: bitmap-spec-p object This returns `t' if OBJECT is a valid bitmap specification, suitable for use with `:stipple' (see above). It returns `nil' otherwise.