InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / elisp / elisp-25 < prev next >

Wrap

GNU Info File | 1993-05-31 | 48.3 KB | 1,212 lines

This is Info file elisp, produced by Makeinfo-1.55 from the input file elisp.texi. This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for Emacs Version 19. Published by the Free Software Foundation, 675 Massachusetts Avenue, Cambridge, MA 02139 USA Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: elisp, Node: Regexp Search, Next: Replacement, Prev: Regular Expressions, Up: Searching and Matching Regular Expression Searching ============================ In GNU Emacs, you can search for the next match for a regexp either incrementally or not. Incremental search commands are described in the `The GNU Emacs Manual'. *Note Regular Expression Search: (emacs)Regexp Search. Here we describe only the search functions useful in programs. The principal one is `re-search-forward'. - Command: re-search-forward REGEXP &optional LIMIT NOERROR REPEAT This function searches forward in the current buffer for a string of text that is matched by the regular expression REGEXP. The function skips over any amount of text that is not matched by REGEXP, and leaves point at the end of the first string found that does match. If the search is successful (i.e., if text matching REGEXP is found), then point moves to the end of that text, and the function returns the new value of point. What happens when the search fails depends on the value of NOERROR. If NOERROR is `nil', a `search-failed' error is signaled. If NOERROR is `t', `re-search-forward' does nothing and returns `nil'. If NOERROR is neither `nil' nor `t', then `re-search-forward' moves point to LIMIT (or the end of the buffer) and returns `nil'. If LIMIT is non-`nil' (it must be a position in the current buffer), then it is the upper bound to the search. No match extending after that position is accepted. If REPEAT is supplied (it must be a positive number), then the search is repeated that many times (each time starting at the end of the previous time's match). The call succeeds if all these searches succeeded, and point is left at the end of the match found by the last search. Otherwise the search fails. In the following example, point is initially located directly before the `T'. After evaluating the form, point is located at the end of that line (between the `t' of `hat' and before the newline). ---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (re-search-forward "[a-z]+" nil t 5) => t ---------- Buffer: foo ---------- I read "The cat in the hat-!- comes back" twice. ---------- Buffer: foo ---------- - Command: re-search-backward REGEXP &optional LIMIT NOERROR REPEAT This function searches backward in the current buffer for a string of text that is matched by the regular expression REGEXP, leaving point at the beginning of the first text found. This function is analogous to `re-search-forward', but they are not simple mirror images. `re-search-forward' finds the match whose beginning is as close as possible. If `re-search-backward' were a perfect mirror image, it would find the match whose end is as close as possible. However, in fact it finds the match whose beginning is as close as possible. The reason is that matching a regular expression at a given spot always works from beginning to end, and is done at a specified beginning position. Thus, true mirror-image behavior would require a special feature for matching regexps from end to beginning. - Function: string-match REGEXP STRING &optional START This function returns the index of the start of the first match for the regular expression REGEXP in STRING, or `nil' if there is no match. If START is non-`nil', the search starts at that index in STRING. For example, (string-match "quick" "The quick brown fox jumped quickly.") => 4 (string-match "quick" "The quick brown fox jumped quickly." 8) => 27 The index of the first character of the string is 0, the index of the second character is 1, and so on. After this function returns, the index of the first character beyond the match is available as `(match-end 0)'. *Note Match Data::. (string-match "quick" "The quick brown fox jumped quickly." 8) => 27 (match-end 0) => 32 The `match-beginning' and `match-end' functions are described together; see *Note Match Data::. - Function: looking-at REGEXP This function determines whether the text in the current buffer directly following point matches the regular expression REGEXP. "Directly following" means precisely that: the search is "anchored" and it must succeed starting with the first character following point. The result is `t' if so, `nil' otherwise. This function does not move point, but it updates the match data, which you can access using `match-beginning' or `match-end'. *Note Match Data::. In this example, point is located directly before the `T'. If it were anywhere else, the result would be `nil'. ---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (looking-at "The cat in the hat$") => t File: elisp, Node: Replacement, Next: Match Data, Prev: Regexp Search, Up: Searching and Matching Replacement =========== - Function: perform-replace FROM-STRING REPLACEMENTS QUERY-FLAG REGEXP-FLAG DELIMITED-FLAG &optional REPEAT-COUNT MAP This function is the guts of `query-replace' and related commands. It searches for occurrences of FROM-STRING and replaces some or all of them. 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 REPEAT-COUNT is non-`nil', it should be an integer, the number of occurrences to consider. In this case, `perform-replace' returns after considering that many occurrences. Normally, the keymap `query-replace-map' defines the possible user responses. The argument MAP, if non-`nil', is a keymap to use instead of `query-replace-map'. - Variable: query-replace-map This variable holds a special keymap that defines the valid user responses for `query-replace' and related functions, as well as `y-or-n-p' and `map-y-or-n-p'. It is special 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. 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 don't ask any more. `act-and-exit' Answer this question "yes," and don't ask any more. `act-and-show' Answer this question "yes," but show the results--don't advance yet. `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 item--instead of any other answer. `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 the `y-or-n-p' functions use this answer. `help' Display some help, then ask again. File: elisp, Node: Match Data, Next: Standard Regexps, Prev: Replacement, Up: Searching and Matching The Match Data ============== Emacs keeps track of the positions of the start and end of segments of text found during a regular expression search. This means, for example, that you can search for a complex pattern, such as a date in an Rmail message, and extract parts of it. 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: * Simple Match Data:: Accessing single items of match data, such as where a particular subexpression started. * Replacing Match:: Replacing a substring that was matched. * 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: Simple Match Data, Next: Replacing Match, Up: Match Data Simple Match Data Access ------------------------ This section explains how to use the match data to find the starting point or ending point of the text that was matched by a particular search, or by a particular parenthetical subexpression of a regular expression. - Function: match-beginning COUNT This function returns the position of the start of text matched by the last regular expression searched for. COUNT, a number, specifies a subexpression whose start position is the value. If COUNT is zero, then the value is the position of the text matched by the whole regexp. If COUNT is greater than zero, then the value is the position of the beginning of the text matched by the COUNTth subexpression, regardless of whether it was used in the final match. Subexpressions of a regular expression are those expressions grouped inside of 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. The value is `nil' for a parenthetical grouping inside of a `\|' alternative that wasn't used in the match. The `match-end' function is similar to the `match-beginning' function except that it returns the position of the end of the matched text. Here is an example, with a comment showing the numbers of the positions in the text: (string-match "\\(qu\$\$ick\$" "The quick fox jumped quickly.") => 4 ;^^^^^^^^^^ ;0123456789 (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. Before the form is evaluated, point is located at the beginning of the line. After evaluating the search form, point is located on the line 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)) => (t 9 13) ---------- Buffer: foo ---------- I read "The cat -!-in the hat comes back" twice. ^ ^ 9 13 ---------- Buffer: foo ---------- (Note that in this case, the index returned is a buffer position; the first character of the buffer counts as 1.) - Function: match-end COUNT This function returns the position of the end of text matched by the last regular expression searched for. This function is otherwise similar to `match-beginning'. File: elisp, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data Replacing the Text That Matched ------------------------------- - Function: replace-match REPLACEMENT &optional FIXEDCASE LITERAL This function replaces the text matched by the last search with REPLACEMENT. If FIXEDCASE is non-`nil', then the case of the replacement text is not changed; otherwise, the replacement text is converted to a different case depending upon the capitalization of the text to be replaced. If the original text is all upper case, the replacement text is converted to upper case, except when all of the words in the original text are only one character long. In that event, the replacement text is capitalized. If *all* of the words in the original text are capitalized, then all of the words in the replacement text are capitalized. 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' stands for the Nth subexpression in the original regexp. Subexpressions are those expressions grouped inside of `$...$'. N is a digit. `\\' `\\' stands for a single `\' in the replacement text. `replace-match' leaves point at the end of the replacement text, and returns `t'. File: elisp, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data Accessing the Entire Match Data ------------------------------- The functions `match-data' and `store-match-data' let you read or write the entire match data, all at once. - Function: match-data This function returns a new list containing 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. In general, element number 2N corresponds to `(match-beginning N)'; and element number 2N + 1 corresponds to `(match-end N)'. All the elements are markers or `nil' if matching was done on a buffer, and all are integers or `nil' if matching was done on a string with `string-match'. (In Emacs 18 and earlier versions, markers were used even for matching on a string, except in the case of the integer 0.) 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) => (#<marker at 9 in foo> #<marker at 17 in foo> #<marker at 13 in foo> #<marker at 17 in foo>) - Function: store-match-data MATCH-LIST 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'. 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. File: elisp, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data Saving and Restoring the Match Data ----------------------------------- All asynchronous process functions (filters and sentinels) and functions that use `recursive-edit' should save and restore the match data if they do a search or if they let the user type arbitrary commands. Saving the match data is useful in other cases as well--whenever you want to access the match data resulting from an earlier search, notwithstanding another intervening search. This example shows the problem that can arise if you fail to attend to this requirement: (re-search-forward "The \$cat \$") => 48 (foo) ; Perhaps `foo' does ; more searching. (match-end 0) => 61 ; Unexpected result---not 48! In Emacs versions 19 and later, you can save and restore the match data with `save-match-data': - Special Form: save-match-data BODY... This special form executes BODY, saving and restoring the match data around it. This is useful if you wish to do a search without altering the match data that resulted from an earlier search. You can use `store-match-data' together with `match-data' to imitate the effect of the special form `save-match-data'. This is useful for writing code that can run in Emacs 18. Here is how: (let ((data (match-data))) (unwind-protect ... ; May change the original match data. (store-match-data data))) File: elisp, Node: Standard Regexps, Next: Searching and Case, Prev: Match Data, Up: Searching and Matching Standard Regular Expressions Used in Editing ============================================ Here are the regular expressions standardly used in editing: - Variable: page-delimiter This is the regexp describing line-beginnings that separate pages. The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'). - Variable: 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 is a line that consists entirely of spaces, tabs, and form feeds. - Variable: paragraph-start This is the regular expression for recognizing the beginning of a line that starts *or* separates paragraphs. The default value is `"^[ \t\n\f]"', which matches a line starting with a space, tab, newline, or form feed. - Variable: sentence-end This is the regular expression describing the end of a sentence. (All paragraph boundaries also end sentences, regardless.) The default value is: "[.?!][]\"')}]*\$$\\|\t\\| \$[ \t\n]*" This means a period, question mark or exclamation mark, followed by a closing brace, followed by tabs, spaces or new lines. For a detailed explanation of this regular expression, see *Note Regexp Example::. File: elisp, Node: Searching and Case, Prev: Standard Regexps, Up: Searching and Matching Searching and Case ================== By default, searches in Emacs ignore the case of the text they are searching through; if you specify searching for `FOO', then `Foo' or `foo' is also considered a match. Regexps, and in particular character sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'. If you do not want this feature, set the variable `case-fold-search' to `nil'. Then all letters must match exactly, including case. This is a per-buffer-local variable; altering the variable affects only the current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you may change the value of `default-case-fold-search', which is the default value of `case-fold-search' for buffers that do not override it. - User Option: case-replace This variable determines whether `query-replace' should preserve case in replacements. If the variable is `nil', then case need not be preserved. - User Option: case-fold-search This buffer-local variable determines whether searches should ignore case. If the variable is `nil' they do not ignore case; otherwise they do ignore case. - Variable: default-case-fold-search The value of this variable is the default value for `case-fold-search' in buffers that do not override it. This is the same as `(default-value 'case-fold-search)'. File: elisp, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top Syntax Tables ************* 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 vector of 256 elements; it contains one entry for each of the 256 ASCII characters of an 8-bit byte. Each element is an integer that encodes the syntax of the character in question. Syntax tables are used only for moving across text, not for the GNU Emacs Lisp reader. GNU Emacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed. 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 which 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. - Function: syntax-table-p OBJECT This function returns `t' if OBJECT is a vector of length 256 elements. This means that the vector may be a syntax table. However, according to this test, any vector of length 256 is considered to be a syntax table, no matter what its contents. * Menu: * Syntax Descriptors:: How characters are classified. * Syntax Table Functions:: How to create, examine and alter syntax tables. * 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. File: elisp, Node: Syntax Descriptors, Next: Syntax Table Functions, Up: Syntax Tables 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 desired syntax. Emacs defines twelve "syntax classes". Each syntax table puts each character into one class. 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 which is frequently put in that class; however, its meaning as a designator is unvarying and independent of how it is actually classified. A syntax descriptor is a Lisp string which specifies a syntax class, a matching character (unused except for 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. Thus, the 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 an 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 Table of Syntax Classes ----------------------- Here is a summary of the classes, the characters that stand for them, their meanings, and examples of their use. - Syntax class: whitespace character "Whitespace characters" (designated with ` ' or `-') separate symbols and words from each other. Typically, whitespace characters have no other syntactic use, and multiple whitespace characters are syntactically equivalent to a single one. Space, tab, newline and formfeed are almost always considered whitespace. - Syntax class: word constituent "Word constituents" (designated with `w') are parts of normal English words 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 with `_') 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" (`.') 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. Most programming language modes, including Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or word constituents all have other uses. - 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 with `(', and that of close parentheses with `)'. 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 with `"') is used to delimit string constants in many languages, including Lisp and C. 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 An "escape character" (designated with `\') 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 with `/') 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 not currently used in any standard Emacs modes. - Syntax class: paired delimiter "Paired delimiter characters" (designated with `$') 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 identical delimiter presently--the `$' that begins and ends math mode. - Syntax class: expression prefix An "expression prefix operator" (designated with `'') is used for syntactic operators that are part of an expression if they appear next to one but are not part of an adjoining symbol. These characters in Lisp 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 different languages to delimit comments. These classes are designated with `<' and `>', respectively. English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one. File: elisp, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors Syntax Flags ------------ In addition to the classes, entries for characters in a syntax table can include flags. There are six possible flags, represented by the characters `1', `2', `3', `4', `b' and `p'. All the flags except `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 (`*/'). The flags for a character C are: * `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 can now supports two comment styles simultaneously. (This is for the sake of C++.) More specifically, it can recognize two different comment-start sequences. Both must share the same first character; only the second character may differ. Mark the second character of the "b"-style comment start sequence with the `b' flag. The two styles of comment can have different comment-end sequences. 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' Thus `/*' is a comment-start sequence for "a" style, `//' is a comment-start sequence for "b" style, `*/' is a comment-end sequence for "a" style, and newline is a comment-end sequence for "b" style. * `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 codes. The function `backward-prefix-chars' moves back over these characters, as well as over characters whose primary syntax class is prefix (`''). File: elisp, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables Syntax Table Functions ====================== In this section we describe functions for creating, accessing and altering syntax tables. - Function: make-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 current syntax table. Otherwise, an error is signaled if TABLE is not a syntax table. - Function: copy-syntax-table &optional TABLE This function is identical to `make-syntax-table'. - Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional TABLE This function sets the syntax entry for CHAR according to SYNTAX-DESCRIPTOR. 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 twelve 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 ?\ " ") => 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 ?/ ".13") => nil - Function: char-syntax CHARACTER This function returns the syntax class of CHARACTER, represented by its mnemonic designator character. This *only* returns the class, not any matching parenthesis or flags. An error is signaled if CHAR is not a character. 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 in C-mode. This does not show the fact that it is also a comment sequence character. 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, `)'. (char-to-string (char-syntax ?\ )) => " " (char-to-string (char-syntax ?/)) => "." (char-to-string (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. File: elisp, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables Motion and Syntax ================= This section describes functions for moving across characters in certain syntax classes. None of these functions exists in Emacs version 18 or earlier. - Function: skip-syntax-forward SYNTAXES &optional LIMIT This function moves point forward across characters whose syntax classes are mentioned in SYNTAXES. It stops when it encounters the end of the buffer, or position LIM (if specified), or a character it is not supposed to skip. 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 LIM (if specified), or a character it is not supposed to skip. 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 chars 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 Parsing Balanced Expressions ============================ Here are several functions for parsing and scanning balanced expressions. 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. - Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH STOP-BEFORE STATE STOP-COMMENT This function parses an expression in the current buffer starting at START, not scanning past LIMIT. Parsing stops at LIMIT or when certain criteria described below are met; point is set to the location where parsing stops. The value returned is a description of the status of the parse at the point where it stops. Normally, START is assumed to be the top level of an expression to be parsed, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of an expression. To do this, you must provide a STATE argument that describes the initial status of parsing. If STATE is omitted (or `nil'), parsing assumes that START is the beginning of a new parse at level 0. 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. The fifth argument STATE is a seven-element list of the same form as the value of this function, described below. The return value of one call may be used to initialize the state of the parse on another call to `parse-partial-sexp'. The result is a list of seven elements describing the final state of the parse: 0. The depth in parentheses, starting at 0. 1. The character position of the start of the innermost containing parenthetical grouping; `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. (It is the character that will terminate the string.) 4. `t' if inside a comment. 5. `t' if point is just after a quote character. 6. The minimum parenthesis depth encountered during this scan. Elements 1, 4, 5, and 6 are significant in the argument STATE. This function is used to determine how to indent lines in programs written in languages that have nested parentheses. - Function: scan-lists FROM COUNT DEPTH This function scans forward COUNT balanced parenthetical groupings from character number FROM. It returns the character number of the position thus found. 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 levels of parenthesis. Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'. If the beginning or end of the buffer (or its accessible portion) is reached 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 Scan from character number FROM by COUNT balanced expressions. It returns the character number of the position thus found. Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'. If the beginning or end of (the accessible part of) the buffer is reached in the middle of a parenthetical grouping, an error is signaled. If the beginning or end is reached between groupings but before count is used up, `nil' is returned. - Variable: 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'. In older Emacs versions, this feature worked only when the comment terminator is something like `*/', and appears only to end a comment. In languages where newlines terminate comments, it was necessary make this variable `nil', since not every newline is the end of a comment. This limitation no longer exists. You can use `forward-comment' to move forward or backward over one comment or several comments. - Function: forward-comment COUNT This function moves point forward across COUNT comments (backward, if COUNT is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. It also stops after satisfying COUNT. 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 to skip cannot exceed that many. File: elisp, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables Some Standard Syntax Tables =========================== Each of the major modes in Emacs has its own syntax table. 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 in use in 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, Prev: Standard Syntax Tables, Up: Syntax Tables Syntax Table Internals ====================== Each element of a syntax table is an integer that translates into the full meaning of the entry: class, possible matching character, and flags. However, it is not common for a programmer to work with the entries directly in this form since the Lisp-level syntax table functions usually work with syntax descriptors (*note Syntax Descriptors::.). The low 8 bits of each element of a syntax table indicates the syntax class. Integer Class 0 whitespace 1 punctuation 2 word 3 symbol 4 open parenthesis 5 close parenthesis 6 expression prefix 7 string quote 8 paired delimiter 9 escape 10 character quote 11 comment-start 12 comment-end The next 8 bits are the matching opposite parenthesis (if the character has parenthesis syntax); otherwise, they are not meaningful. The next 6 bits are the flags. File: elisp, Node: Abbrevs, Next: Processes, Prev: Syntax Tables, Up: Top 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 containing a symbol for each abbreviation. The symbol's name is the abbreviation. Its value is the expansion; its function definition is the hook; its property list cell contains the use count, the number of times the abbreviation has been expanded. Because these symbols are not interned in the usual obarray, they will never appear as the result of reading a Lisp expression; in fact, they will never be used except by the code that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. *Note Creating Symbols::. 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. File: elisp, Node: Abbrev Mode, Next: Abbrev Tables, Prev: Abbrevs, Up: Abbrevs Setting Up Abbrev Mode ====================== Abbrev mode is a minor mode controlled by the value of the variable `abbrev-mode'. - Variable: abbrev-mode A non-`nil' value of this variable turns on the automatic expansion of abbrevs when their abbreviations are inserted into a buffer. If the value is `nil', abbrevs may be defined, but they are not expanded automatically. This variable automatically becomes local when set in any fashion. - Variable: default-abbrev-mode This is the value `abbrev-mode' for buffers that do not override it. This is the same as `(default-value 'abbrev-mode)'.