-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
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
#<marker at 13 in foo>
#<marker at 17 in foo>)
- - Function: set-match-data MATCH-LIST
+ - Function: set-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'.
You can save and restore the match data with `save-match-data':
- - Macro: save-match-data BODY...
+ - Macro: save-match-data body...
This special form executes BODY, saving and restoring the match
data around it.
(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::.).
+process filter functions (*note Filter Functions::) and process
+sentinels (*note Sentinels::).
\1f
File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching
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
+ 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
- Variable: paragraph-start
This is the regular expression for recognizing the beginning of a
- line that starts *or* separates paragraphs. The default value is
+ 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 (after its left margin).
character. 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
+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:
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.
+motion functions (*note Word Motion::) and the list motion functions
+(*note List Motion::) as well as the functions in this chapter.
Under XEmacs 20, a syntax table is a particular subtype of the
-primitive char table type (*note Char Tables::.), and each element of
-the char table is an integer that encodes the syntax of the character in
+primitive char table type (*note Char Tables::), and each element of the
+char table is an integer that encodes the syntax of the character in
question, or a cons of such an integer and a matching character (for
characters with parenthesis syntax).
alphabetic characters in the range 128 to 255. Just changing the
standard syntax for these characters affects all major modes.
- - Function: syntax-table-p OBJECT
+ - 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
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
+_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
+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:
In this section we describe functions for creating, accessing and
altering syntax tables.
- - Function: make-syntax-table &optional TABLE
+ - Function: make-syntax-table &optional table
This function creates a new syntax table. Character codes 0
through 31 and 128 through 255 are set up to inherit from the
standard syntax table. The other character codes are set up by
Most major mode syntax tables are created in this way.
- - Function: copy-syntax-table &optional TABLE
+ - 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 current
syntax table. Otherwise, an error is signaled if TABLE is not a
syntax table.
- - Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional 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
(modify-syntax-entry ?/ ". 14")
=> nil
- - Function: char-syntax CHARACTER
+ - Function: char-syntax character
This function returns the syntax class of CHARACTER, represented
- by its mnemonic designator character. This *only* returns the
+ 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.
(char-to-string (char-syntax ?\())
=> "("
- - Function: set-syntax-table TABLE &optional BUFFER
+ - Function: set-syntax-table table &optional buffer
This function makes TABLE the syntax table for BUFFER, which
defaults to the current buffer if omitted. It returns TABLE.
- - Function: syntax-table &optional BUFFER
+ - Function: syntax-table &optional buffer
This function returns the syntax table for BUFFER, which defaults
to the current buffer if omitted.
certain syntax classes. None of these functions exists in Emacs
version 18 or earlier.
- - Function: skip-syntax-forward SYNTAXES &optional LIMIT BUFFER
+ - Function: skip-syntax-forward syntaxes &optional limit buffer
This function moves point forward across characters having syntax
classes mentioned in SYNTAXES. It stops when it encounters the
end of the buffer, or position LIMIT (if specified), or a
character it is not supposed to skip. Optional argument BUFFER
defaults to the current buffer if omitted.
- - Function: skip-syntax-backward SYNTAXES &optional LIMIT BUFFER
+ - Function: skip-syntax-backward syntaxes &optional limit buffer
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
defaults to the current buffer if omitted.
- - Function: backward-prefix-chars &optional BUFFER
+ - Function: backward-prefix-chars &optional buffer
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. 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