-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
+
+Complex Regexp Example
+----------------------
+
+ Here is a complicated regexp, used by XEmacs to recognize the end of
+a sentence together with any whitespace that follows. It is the value
+of the variable `sentence-end'.
+
+ First, we show the regexp as a string in Lisp syntax to distinguish
+spaces from tab characters. The string constant begins and ends with a
+double-quote. `\"' stands for a double-quote as part of the string,
+`\\' for a backslash as part of the string, `\t' for a tab and `\n' for
+a newline.
+
+ "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
+
+ In contrast, if you evaluate the variable `sentence-end', you will
+see the following:
+
+ sentence-end
+ =>
+ "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
+ ]*"
+
+In this output, tab and newline appear as themselves.
+
+ This regular expression contains four parts in succession and can be
+deciphered as follows:
+
+`[.?!]'
+ The first part of the pattern is a character set that matches any
+ one of three characters: period, question mark, and exclamation
+ mark. The match must begin with one of these three characters.
+
+`[]\"')}]*'
+ The second part of the pattern matches any closing braces and
+ quotation marks, zero or more of them, that may follow the period,
+ question mark or exclamation mark. The `\"' is Lisp syntax for a
+ double-quote in a string. The `*' at the end indicates that the
+ immediately preceding regular expression (a character set, in this
+ case) may be repeated zero or more times.
+
+`\\($\\| $\\|\t\\| \\)'
+ The third part of the pattern matches the whitespace that follows
+ the end of a sentence: the end of a line, or a tab, or two spaces.
+ The double backslashes mark the parentheses and vertical bars as
+ regular expression syntax; the parentheses delimit a group and the
+ vertical bars separate alternatives. The dollar sign is used to
+ match the end of a line.
+
+`[ \t\n]*'
+ Finally, the last part of the pattern matches any additional
+ whitespace beyond the minimum needed to end a sentence.
+
+\1f
+File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching
+
+Regular Expression Searching
+============================
+
+ In XEmacs, you can search for the next match for a regexp either
+incrementally or not. Incremental search commands are described in the
+`The XEmacs Reference 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 match found. It
+ returns the new value of point.
+
+ 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.
+
+ 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 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). If these successive searches
+ succeed, the function succeeds, moving point and returning its new
+ value. Otherwise the search fails.
+
+ In the following example, point is initially before the `T'.
+ Evaluating the search call moves point to the end of that line
+ (between the `t' of `hat' and the newline).
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (re-search-forward "[a-z]+" nil t 5)
+ => 27
+
+ ---------- 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 to the starting point. 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 starts at a specified
+ beginning position.
+
+ A true mirror-image of `re-search-forward' would require a special
+ feature for matching regexps from end to beginning. It's not
+ worth the trouble of implementing that.
+
+ - 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
+
+ - Function: split-string string &optional pattern
+ This function splits STRING to substrings delimited by PATTERN,
+ and returns a list of substrings. If PATTERN is omitted, it
+ defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
+ white-space.
+
+ (split-string "foo bar")
+ => ("foo" "bar")
+
+ (split-string "something")
+ => ("something")
+
+ (split-string "a:b:c" ":")
+ => ("a" "b" "c")
+
+ (split-string ":a::b:c" ":")
+ => ("" "a" "" "b" "c")
+
+ - Function: split-path path
+ This function splits a search path into a list of strings. The
+ path components are separated with the characters specified with
+ `path-separator'. Under Unix, `path-separator' will normally be
+ `:', while under Windows, it will be `;'.
+
+ - 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 can succeed only 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' and `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
+
+\1f
+File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching
+
+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.
+
+ In Emacs versions prior to 19.29, these functions did not exist, and
+the functions described above implemented full POSIX backtracking.
+
+ - Function: 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.
+
+ - Function: 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.
+
+\1f
+File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
+
+Search and Replace
+==================
+
+ - 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. Then it
+ specifies how many times to use each of the strings in the
+ REPLACEMENTS list before advancing cyclicly to the next one.
+
+ Normally, the keymap `query-replace-map' defines the possible user
+ responses for queries. 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 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.
+
+\1f
+File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
+
+The Match Data
+==============
+
+ XEmacs 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 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:
+
+* 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.
+
+\1f
+File: lispref.info, 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 out what was
+matched by the last search or match operation.
+
+ 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.
+
+ - 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 COUNT is
+ out of range, or if that subexpression didn't match anything, the
+ value is `nil'.
+
+ 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. Otherwise, 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.
+
+ - 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 in the match.
+
+ - 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))
+ => (9 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.)
+
+\1f
+File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
+
+Replacing the Text That Matched
+-------------------------------
+
+ This function replaces the text matched by the last search with
+REPLACEMENT.
+
+ - Function: replace-match replacement &optional fixedcase literal
+ string
+ 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. 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 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. If the first word of the
+ original text is capitalized, then the first word of the
+ replacement text is capitalized. If the original text contains
+ just one word, and that word is a capital letter, `replace-match'
+ considers this a capitalized first word rather than all upper case.
+
+ If `case-replace' is `nil', then case conversion is not done,
+ regardless of the value of FIXED-CASE. *Note Searching and Case::.
+
+ 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 `\(...\)'.
+
+ `\\'
+ `\\' stands for a single `\' in the replacement text.
+
+\1f
File: lispref.info, Node: Entire Match Data, Next: Saving Match Data, Prev: Replacing Match, Up: Match Data
Accessing the Entire Match Data
flag. Optional argument BUFFER defaults to the current buffer if
omitted.
-\1f
-File: lispref.info, 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, also known as "sexps", in which parentheses match in
-pairs. 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 buffer
- 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 value describing
- the status of the parse at the point where it stops.
-
- 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.
-
- 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 an eight-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 eight elements describing the final state
- of the parse:
-
- 0. The depth in parentheses, counting from 0.
-
- 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.
-
- 4. `t' if inside a comment (of either style).
-
- 5. `t' if point is just after a quote character.
-
- 6. The minimum parenthesis depth encountered during this scan.
-
- 7. `t' if inside a comment of style "b".
-
- Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
-
- This function is most often used to compute indentation for
- languages that have nested parentheses.
-
- - Function: scan-lists from count depth &optional buffer noerror
- This function scans forward COUNT balanced parenthetical groupings
- from character number FROM. It returns the character position
- where the scan stops.
-
- 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.
-
- If optional arg BUFFER is non-`nil', scanning occurs in that
- buffer instead of in the current buffer.
-
- If optional arg NOERROR is non-`nil', `scan-lists' will return
- `nil' instead of signalling an error.
-
- - Function: scan-sexps from count &optional buffer noerror
- This function scans forward COUNT sexps from character position
- FROM. It returns the character position where the scan stops.
-
- 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 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.
-
- If optional arg BUFFER is non-`nil', scanning occurs in that
- buffer instead of in the current buffer.
-
- If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
- instead of signalling an error.
-
- - 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 &optional buffer
- 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.
-
- Optional argument BUFFER defaults to the current buffer.
-
- 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.
-
-\1f
-File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
-
-Some Standard Syntax Tables
-===========================
-
- Most of the major modes in XEmacs 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.)
-
-\1f
-File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
-
-Syntax Table Internals
-======================
-
- Each element of a syntax table is an integer that encodes the syntax
-of one character: the syntax class, possible matching character, and
-flags. Lisp programs don't usually work with the elements directly; 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 indicate 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
-
-13
- inherit
-
- 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.
-
-\1f
-File: lispref.info, Node: Abbrevs, Next: Extents, 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 function to do the
-expansion (*note Defining Abbrevs::); 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,
-normally they are never 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 XEmacs 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.
-
-\1f
-File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, 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 of `abbrev-mode' for buffers that do not
- override it. This is the same as `(default-value 'abbrev-mode)'.
-
-\1f
-File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
-
-Abbrev Tables
-=============
-
- This section describes how to create and manipulate abbrev tables.
-
- - Function: make-abbrev-table
- This function creates and returns a new, empty abbrev table--an
- obarray containing no symbols. It is a vector filled with zeros.
-
- - Function: clear-abbrev-table table
- This function undefines all the abbrevs in abbrev table TABLE,
- leaving it empty. The function returns `nil'.
-
- - Function: define-abbrev-table tabname definitions
- 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 USECOUNT)'. The value is
- always `nil'.
-
- - 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 value is always `nil'.
-
- If HUMAN is non-`nil', the description is human-oriented.
- Otherwise the description is a Lisp expression--a call to
- `define-abbrev-table' that would define NAME exactly as it is
- currently defined.
-
-\1f
-File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
-
-Defining Abbrevs
-================
-
- These functions define an abbrev in a specified abbrev table.
-`define-abbrev' is the low-level basic function, while `add-abbrev' is
-used by commands that ask for information from the user.
-
- - Function: add-abbrev table type arg
- This function adds an abbreviation to abbrev table TABLE based on
- information from the user. The argument TYPE is a string
- describing in English the kind of abbrev this will be (typically,
- `"global"' or `"mode-specific"'); this is used in prompting the
- user. The argument ARG is the number of words in the expansion.
-
- The return value is the symbol that internally represents the new
- abbrev, or `nil' if the user declines to confirm redefining an
- existing abbrev.
-
- - Function: define-abbrev table name expansion hook
- This function defines an abbrev in TABLE named NAME, to expand to
- EXPANSION, and call HOOK. The return value is an uninterned
- symbol that represents the abbrev inside XEmacs; its name is NAME.
-
- The argument NAME should be a string. The argument EXPANSION
- should be a string, or `nil' to undefine the abbrev.
-
- 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.
-
- The use count of the abbrev is initialized to zero.
-
- - 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.
-
-\1f
-File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
-
-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 filename
- This function reads abbrev definitions from a file named FILENAME,
- previously written with `write-abbrev-file'. If FILENAME is
- `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-abbrev' means that XEmacs should save
- abbrevs when files are saved. `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. This serves as a flag for various XEmacs commands to
- offer to save your abbrevs.
-
- - Command: write-abbrev-file filename
- Save all abbrev definitions, in all abbrev tables, in the file
- FILENAME, in the form of a Lisp program that when loaded will
- define the same abbrevs. This function returns `nil'.
-
-\1f
-File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
-
-Looking Up and Expanding Abbreviations
-======================================
-
- Abbrevs are usually expanded by commands for interactive use,
-including `self-insert-command'. This section describes the
-subroutines used in writing such functions, 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
- to look it up in. 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). 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 `t' if it did expansion, `nil' otherwise.
-
- - Command: abbrev-prefix-mark &optional arg
- Mark current 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.
-
- - 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
- This is the buffer position for `expand-abbrev' to use as the start
- of the next abbrev to be expanded. (`nil' means 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 last abbrev expanded. This
- information is left by `expand-abbrev' for the sake of the
- `unexpand-abbrev' command.
-
- - Variable: last-abbrev-location
- This is the location of the last 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 last 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: pre-abbrev-expand-hook
- This is a normal hook whose functions are executed, in sequence,
- just before any expansion of an abbrev. *Note Hooks::. Since it
- is a normal hook, the hook functions receive no arguments.
- However, they can find the abbrev to be expanded by looking in the
- buffer before point.
-
- The following sample code shows a simple use of
-`pre-abbrev-expand-hook'. If the user terminates an abbrev with a
-punctuation character, the hook function asks for confirmation. Thus,
-this hook allows the user to decide whether to expand the abbrev, and
-aborts expansion if it is not confirmed.
-
- (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
-
- ;; This is the function invoked by `pre-abbrev-expand-hook'.
-
- ;; If the user terminated the abbrev with a space, the function does
- ;; nothing (that is, it returns so that the abbrev can expand). If the
- ;; user entered some other character, this function asks whether
- ;; expansion should continue.
-
- ;; If the user answers the prompt with `y', the function returns
- ;; `nil' (because of the `not' function), but that is
- ;; acceptable; the return value has no effect on expansion.
-
- (defun query-if-not-space ()
- (if (/= ?\ (preceding-char))
- (if (not (y-or-n-p "Do you want to expand this abbrev? "))
- (error "Not expanding this abbrev"))))
-
-\1f
-File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
-
-Standard Abbrev Tables
-======================
-
- Here we list the variables that hold the abbrev tables for the
-preloaded major modes of XEmacs.
-
- - 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.
-
- - 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: c-mode-abbrev-table
- This is the local abbrev table used in C mode.
-
- - Variable: lisp-mode-abbrev-table
- This is the local abbrev table used in Lisp mode and Emacs Lisp
- mode.
-
projects / chise / xemacs-chise.git / blobdiff