Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text
+
+Change Hooks
+============
+
+ These hook variables let you arrange to take notice of all changes in
+all buffers (or in a particular buffer, if you make them buffer-local).
+
+ The functions you use in these hooks should save and restore the
+match data if they do anything that uses regular expressions;
+otherwise, they will interfere in bizarre ways with the editing
+operations that call them.
+
+ Buffer changes made while executing the following hooks don't
+themselves cause any change hooks to be invoked.
+
+ - Variable: before-change-functions
+ This variable holds a list of a functions to call before any buffer
+ modification. Each function gets two arguments, the beginning and
+ end of the region that is about to change, represented as
+ integers. The buffer that is about to change is always the
+ current buffer.
+
+ - Variable: after-change-functions
+ This variable holds a list of a functions to call after any buffer
+ modification. Each function receives three arguments: the
+ beginning and end of the region just changed, and the length of
+ the text that existed before the change. (To get the current
+ length, subtract the region beginning from the region end.) All
+ three arguments are integers. The buffer that's about to change
+ is always the current buffer.
+
+ - Variable: before-change-function
+ This obsolete variable holds one function to call before any buffer
+ modification (or `nil' for no function). It is called just like
+ the functions in `before-change-functions'.
+
+ - Variable: after-change-function
+ This obsolete variable holds one function to call after any buffer
+ modification (or `nil' for no function). It is called just like
+ the functions in `after-change-functions'.
+
+ - Variable: first-change-hook
+ This variable is a normal hook that is run whenever a buffer is
+ changed that was previously in the unmodified state.
+
+\1f
+File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text
+
+Textual transformations--MD5 and base64 support
+===============================================
+
+ Some textual operations inherently require examining each character
+in turn, and performing arithmetic operations on them. Such operations
+can, of course, be implemented in Emacs Lisp, but tend to be very slow
+for large portions of text or data. This is why some of them are
+implemented in C, with an appropriate interface for Lisp programmers.
+Examples of algorithms thus provided are MD5 and base64 support.
+
+ MD5 is an algorithm for calculating message digests, as described in
+rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit
+"fingerprint" ("message digest") corresponding to that message. It is
+considered computationally infeasible to produce two messages having
+the same MD5 digest, or to produce a message having a prespecified
+target digest. MD5 is used heavily by various authentication schemes.
+
+ Emacs Lisp interface to MD5 consists of a single function `md5':
+
+ - Function: md5 object &optional start end coding noerror
+ This function returns the MD5 message digest of OBJECT, a buffer
+ or string.
+
+ Optional arguments START and END denote positions for computing
+ the digest of a portion of OBJECT.
+
+ The optional CODING argument specifies the coding system the text
+ is to be represented in while computing the digest. If
+ unspecified, it defaults to the current format of the data, or is
+ guessed.
+
+ If NOERROR is non-`nil', silently assume binary coding if the
+ guesswork fails. Normally, an error is signaled in such case.
+
+ CODING and NOERROR arguments are meaningful only in XEmacsen with
+ file-coding or Mule support. Otherwise, they are ignored. Some
+ examples of usage:
+
+ ;; Calculate the digest of the entire buffer
+ (md5 (current-buffer))
+ => "8842b04362899b1cda8d2d126dc11712"
+
+ ;; Calculate the digest of the current line
+ (md5 (current-buffer) (point-at-bol) (point-at-eol))
+ => "60614d21e9dee27dfdb01fa4e30d6d00"
+
+ ;; Calculate the digest of your name and email address
+ (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
+ => "0a2188c40fd38922d941fe6032fce516"
+
+ Base64 is a portable encoding for arbitrary sequences of octets, in a
+form that need not be readable by humans. It uses a 65-character subset
+of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
+binary bodies, and to encode binary characters in message headers.
+
+ The Lisp interface to base64 consists of four functions:
+
+ - Command: base64-encode-region start end &optional no-line-break
+ This function encodes the region between START and END of the
+ current buffer to base64 format. This means that the original
+ region is deleted, and replaced with its base64 equivalent.
+
+ Normally, encoded base64 output is multi-line, with 76-character
+ lines. If NO-LINE-BREAK is non-`nil', newlines will not be
+ inserted, resulting in single-line output.
+
+ Mule note: you should make sure that you convert the multibyte
+ characters (those that do not fit into 0-255 range) to something
+ else, because they cannot be meaningfully converted to base64. If
+ the `base64-encode-region' encounters such characters, it will
+ signal an error.
+
+ `base64-encode-region' returns the length of the encoded text.
+
+ ;; Encode the whole buffer in base64
+ (base64-encode-region (point-min) (point-max))
+
+ The function can also be used interactively, in which case it
+ works on the currently active region.
+
+ - Function: base64-encode-string string &optional no-line-break
+ This function encodes STRING to base64, and returns the encoded
+ string.
+
+ Normally, encoded base64 output is multi-line, with 76-character
+ lines. If NO-LINE-BREAK is non-`nil', newlines will not be
+ inserted, resulting in single-line output.
+
+ For Mule, the same considerations apply as for
+ `base64-encode-region'.
+
+ (base64-encode-string "fubar")
+ => "ZnViYXI="
+
+ - Command: base64-decode-region start end
+ This function decodes the region between START and END of the
+ current buffer. The region should be in base64 encoding.
+
+ If the region was decoded correctly, `base64-decode-region' returns
+ the length of the decoded region. If the decoding failed, `nil' is
+ returned.
+
+ ;; Decode a base64 buffer, and replace it with the decoded version
+ (base64-decode-region (point-min) (point-max))
+
+ - Function: base64-decode-string string
+ This function decodes STRING to base64, and returns the decoded
+ string. STRING should be valid base64-encoded text.
+
+ If encoding was not possible, `nil' is returned.
+
+ (base64-decode-string "ZnViYXI=")
+ => "fubar"
+
+ (base64-decode-string "totally bogus")
+ => nil
+
+\1f
+File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top
+
+Searching and Matching
+**********************
+
+ XEmacs provides two ways to search through a buffer for specified
+text: exact string searches and regular expression searches. After a
+regular expression search, you can examine the "match data" to
+determine which text matched the whole regular expression or various
+portions of it.
+
+* Menu:
+
+* String Search:: Search for an exact match.
+* Regular Expressions:: Describing classes of strings.
+* Regexp Search:: Searching for a match for a regexp.
+* POSIX Regexps:: Searching POSIX-style for the longest match.
+* Search and Replace:: Internals of `query-replace'.
+* Match Data:: Finding out which part of the text matched
+ various parts of a regexp, after regexp search.
+* Searching and Case:: Case-independent or case-significant searching.
+* Standard Regexps:: Useful regexps for finding sentences, pages,...
+
+ The `skip-chars...' functions also perform a kind of searching.
+*Note Skipping Characters::.
+
+\1f
+File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching
+
+Searching for Strings
+=====================
+
+ These are the primitive functions for searching through the text in a
+buffer. They are meant for use in programs, but you may call them
+interactively. If you do so, they prompt for the search string; LIMIT
+and NOERROR are set to `nil', and COUNT is set to 1.
+
+ - Command: search-forward string &optional limit noerror count buffer
+ This function searches forward from point for an exact match for
+ STRING. If successful, it sets point to the end of the occurrence
+ found, and returns the new value of point. If no match is found,
+ the value and side effects depend on NOERROR (see below).
+
+ In the following example, point is initially at the beginning of
+ the line. Then `(search-forward "fox")' moves point after the last
+ letter of `fox':
+
+ ---------- Buffer: foo ----------
+ -!-The quick brown fox jumped over the lazy dog.
+ ---------- Buffer: foo ----------
+
+ (search-forward "fox")
+ => 20
+
+ ---------- Buffer: foo ----------
+ The quick brown fox-!- jumped over the lazy dog.
+ ---------- Buffer: foo ----------
+
+ The argument LIMIT specifies the upper bound to the search. (It
+ must be a position in the current buffer.) No match extending
+ after that position is accepted. If LIMIT is omitted or `nil', it
+ defaults to the end of the accessible portion of the buffer.
+
+ 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', `search-forward' returns `nil' and
+ does nothing. If NOERROR is neither `nil' nor `t', then
+ `search-forward' moves point to the upper bound and returns `nil'.
+ (It would be more consistent now to return the new position of
+ point in that case, but some programs may depend on a value of
+ `nil'.)
+
+ If COUNT is supplied (it must be an integer), then the search is
+ repeated that many times (each time starting at the end of the
+ previous time's match). If COUNT is negative, the search
+ direction is backward. If the successive searches succeed, the
+ function succeeds, moving point and returning its new value.
+ Otherwise the search fails.
+
+ BUFFER is the buffer to search in, and defaults to the current
+ buffer.
+
+ - Command: search-backward string &optional limit noerror count buffer
+ This function searches backward from point for STRING. It is just
+ like `search-forward' except that it searches backwards and leaves
+ point at the beginning of the match.
+
+ - Command: word-search-forward string &optional limit noerror count
+ buffer
+ This function searches forward from point for a "word" match for
+ STRING. If it finds a match, it sets point to the end of the
+ match found, and returns the new value of point.
+
+ Word matching regards STRING as a sequence of words, disregarding
+ punctuation that separates them. It searches the buffer for the
+ same sequence of words. Each word must be distinct in the buffer
+ (searching for the word `ball' does not match the word `balls'),
+ but the details of punctuation and spacing are ignored (searching
+ for `ball boy' does match `ball. Boy!').
+
+ In this example, point is initially at the beginning of the
+ buffer; the search leaves it between the `y' and the `!'.
+
+ ---------- Buffer: foo ----------
+ -!-He said "Please! Find
+ the ball boy!"
+ ---------- Buffer: foo ----------
+
+ (word-search-forward "Please find the ball, boy.")
+ => 35
+
+ ---------- Buffer: foo ----------
+ He said "Please! Find
+ the ball boy-!-!"
+ ---------- Buffer: foo ----------
+
+ If LIMIT is non-`nil' (it must be a position in the current
+ buffer), then it is the upper bound to the search. The match
+ found must not extend after that position.
+
+ If NOERROR is `nil', then `word-search-forward' signals an error
+ if the search fails. If NOERROR is `t', then it returns `nil'
+ instead of signaling an error. If NOERROR is neither `nil' nor
+ `t', it moves point to LIMIT (or the end of the buffer) and
+ returns `nil'.
+
+ If COUNT is non-`nil', then the search is repeated that many
+ times. Point is positioned at the end of the last match.
+
+ BUFFER is the buffer to search in, and defaults to the current
+ buffer.
+
+ - Command: word-search-backward string &optional limit noerror count
+ buffer
+ This function searches backward from point for a word match to
+ STRING. This function is just like `word-search-forward' except
+ that it searches backward and normally leaves point at the
+ beginning of the match.
+
+\1f
+File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching
+
+Regular Expressions
+===================
+
+ A "regular expression" ("regexp", for short) is a pattern that
+denotes a (possibly infinite) set of strings. Searching for matches for
+a regexp is a very powerful operation. This section explains how to
+write regexps; the following section says how to search for them.
+
+ To gain a thorough understanding of regular expressions and how to
+use them to best advantage, we recommend that you study `Mastering
+Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
+1997'. (It's known as the "Hip Owls" book, because of the picture on its
+cover.) You might also read the manuals to *Note (gawk)Top::, *Note
+(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
+(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
+regular expressions.
+
+ The XEmacs regular expression syntax most closely resembles that of
+`ed', or `grep', the GNU versions of which all utilize the GNU `regex'
+library. XEmacs' version of `regex' has recently been extended with
+some Perl-like capabilities, described in the next section.
+
+* Menu:
+
+* Syntax of Regexps:: Rules for writing regular expressions.
+* Regexp Example:: Illustrates regular expression syntax.
+
+\1f
+File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions
+
+Syntax of Regular Expressions
+-----------------------------
+
+ Regular expressions have a syntax in which a few characters are
+special constructs and the rest are "ordinary". An ordinary character
+is a simple regular expression that matches that character and nothing
+else. The special characters are `.', `*', `+', `?', `[', `]', `^',
+`$', and `\'; no new special characters will be defined in the future.
+Any other character appearing in a regular expression is ordinary,
+unless a `\' precedes it.
+
+ For example, `f' is not a special character, so it is ordinary, and
+therefore `f' is a regular expression that matches the string `f' and
+no other string. (It does _not_ match the string `ff'.) Likewise, `o'
+is a regular expression that matches only `o'.
+
+ Any two regular expressions A and B can be concatenated. The result
+is a regular expression that matches a string if A matches some amount
+of the beginning of that string and B matches the rest of the string.
+
+ As a simple example, we can concatenate the regular expressions `f'
+and `o' to get the regular expression `fo', which matches only the
+string `fo'. Still trivial. To do something more powerful, you need
+to use one of the special characters. Here is a list of them:
+
+`. (Period)'
+ is a special character that matches any single character except a
+ newline. Using concatenation, we can make regular expressions
+ like `a.b', which matches any three-character string that begins
+ with `a' and ends with `b'.
+
+`*'
+ is not a construct by itself; it is a quantifying suffix operator
+ that means to repeat the preceding regular expression as many
+ times as possible. In `fo*', the `*' applies to the `o', so `fo*'
+ matches one `f' followed by any number of `o's. The case of zero
+ `o's is allowed: `fo*' does match `f'.
+
+ `*' always applies to the _smallest_ possible preceding
+ expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
+
+ The matcher processes a `*' construct by matching, immediately, as
+ many repetitions as can be found; it is "greedy". Then it
+ continues with the rest of the pattern. If that fails,
+ backtracking occurs, discarding some of the matches of the
+ `*'-modified construct in case that makes it possible to match the
+ rest of the pattern. For example, in matching `ca*ar' against the
+ string `caaar', the `a*' first tries to match all three `a's; but
+ the rest of the pattern is `ar' and there is only `r' left to
+ match, so this try fails. The next alternative is for `a*' to
+ match only two `a's. With this choice, the rest of the regexp
+ matches successfully.
+
+ Nested repetition operators can be extremely slow if they specify
+ backtracking loops. For example, it could take hours for the
+ regular expression `\(x+y*\)*a' to match the sequence
+ `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because
+ Emacs must try each imaginable way of grouping the 35 `x''s before
+ concluding that none of them can work. To make sure your regular
+ expressions run fast, check nested repetitions carefully.
+
+`+'
+ is a quantifying suffix operator similar to `*' except that the
+ preceding expression must match at least once. It is also
+ "greedy". So, for example, `ca+r' matches the strings `car' and
+ `caaaar' but not the string `cr', whereas `ca*r' matches all three
+ strings.
+
+`?'
+ is a quantifying suffix operator similar to `*', except that the
+ preceding expression can match either once or not at all. For
+ example, `ca?r' matches `car' or `cr', but does not match anything
+ else.
+
+`*?'
+ works just like `*', except that rather than matching the longest
+ match, it matches the shortest match. `*?' is known as a
+ "non-greedy" quantifier, a regexp construct borrowed from Perl.
+
+ This construct is very useful for when you want to match the text
+ inside a pair of delimiters. For instance, `/\*.*?\*/' will match
+ C comments in a string. This could not easily be achieved without
+ the use of a non-greedy quantifier.
+
+ This construct has not been available prior to XEmacs 20.4. It is
+ not available in FSF Emacs.
+
+`+?'
+ is the non-greedy version of `+'.
+
+`??'
+ is the non-greedy version of `?'.
+
+`\{n,m\}'
+ serves as an interval quantifier, analogous to `*' or `+', but
+ specifies that the expression must match at least N times, but no
+ more than M times. This syntax is supported by most Unix regexp
+ utilities, and has been introduced to XEmacs for the version 20.3.
+
+ Unfortunately, the non-greedy version of this quantifier does not
+ exist currently, although it does in Perl.
+
+`[ ... ]'
+ `[' begins a "character set", which is terminated by a `]'. In
+ the simplest case, the characters between the two brackets form
+ the set. Thus, `[ad]' matches either one `a' or one `d', and
+ `[ad]*' matches any string composed of just `a's and `d's
+ (including the empty string), from which it follows that `c[ad]*r'
+ matches `cr', `car', `cdr', `caddaar', etc.
+
+ The usual regular expression special characters are not special
+ inside a character set. A completely different set of special
+ characters exists inside character sets: `]', `-' and `^'.
+
+ `-' is used for ranges of characters. To write a range, write two
+ characters with a `-' between them. Thus, `[a-z]' matches any
+ lower case letter. Ranges may be intermixed freely with individual
+ characters, as in `[a-z$%.]', which matches any lower case letter
+ or `$', `%', or a period.
+
+ To include a `]' in a character set, make it the first character.
+ For example, `[]a]' matches `]' or `a'. To include a `-', write
+ `-' as the first character in the set, or put it immediately after
+ a range. (You can replace one individual character C with the
+ range `C-C' to make a place to put the `-'.) There is no way to
+ write a set containing just `-' and `]'.
+
+ To include `^' in a set, put it anywhere but at the beginning of
+ the set.
+
+`[^ ... ]'
+ `[^' begins a "complement character set", which matches any
+ character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
+ all characters _except_ letters and digits.
+
+ `^' is not special in a character set unless it is the first
+ character. The character following the `^' is treated as if it
+ were first (thus, `-' and `]' are not special there).
+
+ Note that a complement character set can match a newline, unless
+ newline is mentioned as one of the characters not to match.
+
+`^'
+ is a special character that matches the empty string, but only at
+ the beginning of a line in the text being matched. Otherwise it
+ fails to match anything. Thus, `^foo' matches a `foo' that occurs
+ at the beginning of a line.
+
+ When matching a string instead of a buffer, `^' matches at the
+ beginning of the string or after a newline character `\n'.
+
+`$'
+ is similar to `^' but matches only at the end of a line. Thus,
+ `x+$' matches a string of one `x' or more at the end of a line.
+
+ When matching a string instead of a buffer, `$' matches at the end
+ of the string or before a newline character `\n'.
+
+`\'
+ has two functions: it quotes the special characters (including
+ `\'), and it introduces additional special constructs.
+
+ Because `\' quotes special characters, `\$' is a regular
+ expression that matches only `$', and `\[' is a regular expression
+ that matches only `[', and so on.
+
+ Note that `\' also has special meaning in the read syntax of Lisp
+ strings (*note String Type::), and must be quoted with `\'. For
+ example, the regular expression that matches the `\' character is
+ `\\'. To write a Lisp string that contains the characters `\\',
+ Lisp syntax requires you to quote each `\' with another `\'.
+ Therefore, the read syntax for a regular expression matching `\'
+ is `"\\\\"'.
+
+ *Please note:* For historical compatibility, special characters are
+treated as ordinary ones if they are in contexts where their special
+meanings make no sense. For example, `*foo' treats `*' as ordinary
+since there is no preceding expression on which the `*' can act. It is
+poor practice to depend on this behavior; quote the special character
+anyway, regardless of where it appears.
+
+ For the most part, `\' followed by any character matches only that
+character. However, there are several exceptions: characters that,
+when preceded by `\', are special constructs. Such characters are
+always ordinary when encountered on their own. Here is a table of `\'
+constructs:
+
+`\|'
+ specifies an alternative. Two regular expressions A and B with
+ `\|' in between form an expression that matches anything that
+ either A or B matches.
+
+ Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
+
+ `\|' applies to the largest possible surrounding expressions.
+ Only a surrounding `\( ... \)' grouping can limit the grouping
+ power of `\|'.
+
+ Full backtracking capability exists to handle multiple uses of
+ `\|'.
+
+`\( ... \)'
+ is a grouping construct that serves three purposes:
+
+ 1. To enclose a set of `\|' alternatives for other operations.
+ Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
+
+ 2. To enclose an expression for a suffix operator such as `*' to
+ act on. Thus, `ba\(na\)*' matches `bananana', etc., with any
+ (zero or more) number of `na' strings.
+
+ 3. To record a matched substring for future reference.
+
+ This last application is not a consequence of the idea of a
+ parenthetical grouping; it is a separate feature that happens to be
+ assigned as a second meaning to the same `\( ... \)' construct
+ because there is no conflict in practice between the two meanings.
+ Here is an explanation of this feature:
+
+`\DIGIT'
+ matches the same text that matched the DIGITth occurrence of a `\(
+ ... \)' construct.
+
+ In other words, after the end of a `\( ... \)' construct. the
+ matcher remembers the beginning and end of the text matched by that
+ construct. Then, later on in the regular expression, you can use
+ `\' followed by DIGIT to match that same text, whatever it may
+ have been.
+
+ The strings matching the first nine `\( ... \)' constructs
+ appearing in a regular expression are assigned numbers 1 through 9
+ in the order that the open parentheses appear in the regular
+ expression. So you can use `\1' through `\9' to refer to the text
+ matched by the corresponding `\( ... \)' constructs.
+
+ For example, `\(.*\)\1' matches any newline-free string that is
+ composed of two identical halves. The `\(.*\)' matches the first
+ half, which may be anything, but the `\1' that follows must match
+ the same exact text.
+
+`\(?: ... \)'
+ is called a "shy" grouping operator, and it is used just like `\(
+ ... \)', except that it does not cause the matched substring to be
+ recorded for future reference.
+
+ This is useful when you need a lot of grouping `\( ... \)'
+ constructs, but only want to remember one or two - or if you have
+ more than nine groupings and need to use backreferences to refer to
+ the groupings at the end.
+
+ Using `\(?: ... \)' rather than `\( ... \)' when you don't need
+ the captured substrings ought to speed up your programs some,
+ since it shortens the code path followed by the regular expression
+ engine, as well as the amount of memory allocation and string
+ copying it must do. The actual performance gain to be observed
+ has not been measured or quantified as of this writing.
+
+ The shy grouping operator has been borrowed from Perl, and has not
+ been available prior to XEmacs 20.3, nor is it available in FSF
+ Emacs.
+
+`\w'
+ matches any word-constituent character. The editor syntax table
+ determines which characters these are. *Note Syntax Tables::.
+
+`\W'
+ matches any character that is not a word constituent.
+
+`\sCODE'
+ matches any character whose syntax is CODE. Here CODE is a
+ character that represents a syntax code: thus, `w' for word
+ constituent, `-' for whitespace, `(' for open parenthesis, etc.
+ *Note Syntax Tables::, for a list of syntax codes and the
+ characters that stand for them.
+
+`\SCODE'
+ matches any character whose syntax is not CODE.
+
+ The following regular expression constructs match the empty
+string--that is, they don't use up any characters--but whether they
+match depends on the context.
+
+`\`'
+ matches the empty string, but only at the beginning of the buffer
+ or string being matched against.
+
+`\''
+ matches the empty string, but only at the end of the buffer or
+ string being matched against.
+
+`\='
+ matches the empty string, but only at point. (This construct is
+ not defined when matching against a string.)
+
+`\b'
+ matches the empty string, but only at the beginning or end of a
+ word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
+ separate word. `\bballs?\b' matches `ball' or `balls' as a
+ separate word.
+
+`\B'
+ matches the empty string, but _not_ at the beginning or end of a
+ word.
+
+`\<'
+ matches the empty string, but only at the beginning of a word.
+
+`\>'
+ matches the empty string, but only at the end of a word.
+
+ Not every string is a valid regular expression. For example, a
+string with unbalanced square brackets is invalid (with a few
+exceptions, such as `[]]'), and so is a string that ends with a single
+`\'. If an invalid regular expression is passed to any of the search
+functions, an `invalid-regexp' error is signaled.
+
+ - Function: regexp-quote string
+ This function returns a regular expression string that matches
+ exactly STRING and nothing else. This allows you to request an
+ exact string match when calling a function that wants a regular
+ expression.
+
+ (regexp-quote "^The cat$")
+ => "\\^The cat\\$"
+
+ One use of `regexp-quote' is to combine an exact string match with
+ context described as a regular expression. For example, this
+ searches for the string that is the value of `string', surrounded
+ by whitespace:
+
+ (re-search-forward
+ (concat "\\s-" (regexp-quote string) "\\s-"))
+
+\1f
File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
Complex Regexp Example
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
+`The XEmacs Lisp Reference Manual'. *Note Regular Expression Search:
+(xemacs)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
+ - Command: re-search-forward regexp &optional limit noerror count
+ buffer
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
`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
+ If COUNT 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
comes back" twice.
---------- Buffer: foo ----------
- - Command: re-search-backward regexp &optional limit noerror repeat
+ - Command: re-search-backward regexp &optional limit noerror count
+ buffer
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.
feature for matching regexps from end to beginning. It's not
worth the trouble of implementing that.
- - Function: string-match regexp string &optional start
+ - Function: string-match regexp string &optional start buffer
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.
+ Optional arg BUFFER controls how case folding is done (according
+ to the value of `case-fold-search' in BUFFER and BUFFER's case
+ tables) and defaults to the current buffer.
+
For example,
(string-match
`path-separator'. Under Unix, `path-separator' will normally be
`:', while under Windows, it will be `;'.
- - Function: looking-at regexp
+ - Function: looking-at regexp &optional buffer
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
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
+ - Command: posix-search-forward regexp &optional limit noerror count
+ buffer
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
+ - Command: posix-search-backward regexp &optional limit noerror count
+ buffer
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
+ - Function: posix-looking-at regexp &optional buffer
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
+ - Function: posix-string-match regexp string &optional start buffer
This is like `string-match' except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
+ Optional arg BUFFER controls how case folding is done (according
+ to the value of `case-fold-search' in BUFFER and BUFFER's case
+ tables) and defaults to the current buffer.
+
\1f
File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
(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
--------------------------------
-
- The functions `match-data' and `set-match-data' read or write the
-entire match data, all at once.
-
- - Function: match-data
- This function returns a newly constructed 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,
- and so on. 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: 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'.
-
- 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.
-
- `store-match-data' is an alias for `set-match-data'.
-
-\1f
-File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data
-
-Saving and Restoring the Match Data
------------------------------------
-
- When you call a function that may do a search, you may need to save
-and restore the match data around that call, if you want to preserve the
-match data from an earlier search for later use. Here is an example
-that shows the problem that arises if you fail to save the match data:
-
- (re-search-forward "The \\(cat \\)")
- => 48
- (foo) ; Perhaps `foo' does
- ; more searching.
- (match-end 0)
- => 61 ; Unexpected result--not 48!
-
- You can save and restore the match data with `save-match-data':
-
- - Macro: save-match-data body...
- This special form executes BODY, saving and restoring the match
- data around it.
-
- You can use `set-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.
- (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::).
-
-\1f
-File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, 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 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.
-
- Note that the user-level incremental search feature handles case
-distinctions differently. When given a lower case letter, it looks for
-a match of either case, but when given an upper case letter, it looks
-for an upper case letter only. But this has nothing to do with the
-searching functions Lisp functions use.
-
- - User Option: case-replace
- This variable determines whether the replacement functions should
- preserve case. If the variable is `nil', that means to use the
- replacement text verbatim. A non-`nil' value means to convert the
- case of the replacement text according to the text being replaced.
-
- The function `replace-match' is where this variable actually has
- its effect. *Note Replacing Match::.
-
- - 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)'.
-
-\1f
-File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching
-
-Standard Regular Expressions Used in Editing
-============================================
-
- This section describes some variables that hold regular expressions
-used for certain purposes 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"'); this
- matches a line that starts with a formfeed character.
-
- The following two regular expressions should _not_ assume the match
-always starts at the beginning of a line; they should not use `^' to
-anchor the match. Most often, the paragraph commands do check for a
-match only at the beginning of a line, which means that `^' would be
-superfluous. When there is a nonzero left margin, they accept matches
-that start after the left margin. In that case, a `^' would be
-incorrect. However, a `^' is harmless in modes where a left margin is
-never used.
-
- - 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 matches a line that consists entirely of
- spaces, tabs, and form feeds (after its left margin).
-
- - 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 (after its left margin).
-
- - 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
- optionally by a closing parenthetical character, followed by tabs,
- spaces or new lines.
-
- For a detailed explanation of this regular expression, see *Note
- Regexp Example::.
-
-\1f
-File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top
-
-Syntax Tables
-*************
-
- A "syntax table" specifies the syntactic textual function of each
-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
-functions in this chapter.
-
-* Menu:
-
-* Basics: Syntax Basics. Basic concepts of syntax tables.
-* Desc: Syntax Descriptors. How characters are classified.
-* Syntax Table Functions:: How to create, examine and alter syntax tables.
-* 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.
-
-\1f
-File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables
-
-Syntax Table Concepts
-=====================
-
- A "syntax table" provides Emacs with the information that determines
-the syntactic use of each character in a buffer. This information is
-used by the parsing commands, the complex movement commands, and others
-to determine where words, symbols, and other syntactic constructs begin
-and end. The current syntax table controls the meaning of the word
-motion functions (*note Word Motion::) and the list motion functions
-(*note List Motion::) as well as the functions in this chapter.
-
- 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
-question, or a cons of such an integer and a matching character (for
-characters with parenthesis syntax).
-
- Under XEmacs 19, a syntax table is a vector of 256 elements; it
-contains one entry for each of the 256 possible characters in an 8-bit
-byte. Each element is an integer that encodes the syntax of the
-character in question. (The matching character, if any, is embedded in
-the bits of this integer.)
-
- Syntax tables are used only for moving across text, not for the Emacs
-Lisp reader. XEmacs 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, XEmacs makes the choice of
-syntax table local to each buffer. Typically, each major mode has its
-own syntax table and installs that table in each buffer that uses that
-mode. Changing this table alters the syntax in all those buffers as
-well as in any buffers subsequently put in that mode. Occasionally
-several similar modes share one syntax table. *Note Example Major
-Modes::, for an example of how to set up a syntax table.
-
- A syntax table can inherit the data for some characters from the
-standard syntax table, while specifying other characters itself. The
-"inherit" syntax class means "inherit this character's syntax from the
-standard syntax table." Most major modes' syntax tables inherit the
-syntax of character codes 0 through 31 and 128 through 255. This is
-useful with character sets such as ISO Latin-1 that have additional
-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
- 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.
-
-\1f
-File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, 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.
-
- XEmacs defines a number of "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 that is frequently in that class; however,
-its meaning as a designator is unvarying and independent of what syntax
-that character currently has.
-
- A syntax descriptor is a Lisp string that specifies a syntax class, a
-matching character (used only for the parenthesis classes) and flags.
-The first character is the designator for a syntax class. The second
-character is the character to match; if it is unused, put a space there.
-Then come the characters for any desired flags. If no matching
-character or flags are needed, one character is sufficient.
-
- For example, the 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.
-
-\1f
-File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors
-
-Table of Syntax Classes
------------------------
-
- Here is a table of syntax classes, the characters that stand for
-them, their meanings, and examples of their use.
-
- - Syntax class: whitespace character
- "Whitespace characters" (designated with ` ' or `-') separate
- symbols and words from each other. Typically, whitespace
- characters have no other syntactic significance, and multiple
- whitespace characters are syntactically equivalent to a single
- one. Space, tab, newline and formfeed are almost always
- classified as 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, XEmacs 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 XEmacs Lisp, the delimiters for lists and
- vectors (`()' and `[]') are classified as parenthesis characters.
-
- - Syntax class: string quote
- "String quote characters" (designated with `"') are used in many
- languages, including Lisp and C, to delimit string constants. The
- same string quote character appears at the beginning and the end
- of a string. Such quoted strings do not nest.
-
- The parsing facilities of XEmacs 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 XEmacs 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 used for backslash in TeX mode.
-
- - 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 delimiter presently--the `$' that both enters
- and leaves 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. 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
- various 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.
-
- - Syntax class: inherit
- This syntax class does not specify a syntax. It says to look in
- the standard syntax table to find the syntax of this character.
- The designator for this syntax code is `@'.
-
-\1f
-File: lispref.info, 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 supports two comment styles simultaneously in any one syntax
- table. This is for the sake of C++. Each style of comment syntax
- has its own comment-start sequence and its own comment-end
- sequence. Each comment must stick to one style or the other;
- thus, if it starts with the comment-start sequence of style "b",
- it must also end with the comment-end sequence of style "b".
-
- The two comment-start sequences must begin with the same
- character; only the second character may differ. Mark the second
- character of the "b"-style comment-start sequence with the `b'
- flag.
-
- A comment-end sequence (one or two characters) applies to the "b"
- style if its first character has the `b' flag set; otherwise, it
- applies to the "a" style.
-
- The appropriate comment syntax settings for C++ are as follows:
-
- `/'
- `124b'
-
- `*'
- `23'
-
- newline
- `>b'
-
- This defines four comment-delimiting sequences:
-
- `/*'
- This is a comment-start sequence for "a" style because the
- second character, `*', does not have the `b' flag.
-
- `//'
- This is a comment-start sequence for "b" style because the
- second character, `/', does have the `b' flag.
-
- `*/'
- This is a comment-end sequence for "a" style because the first
- character, `*', does not have the `b' flag
-
- newline
- This is a comment-end sequence for "b" style, because the
- newline character has the `b' flag.
-
- * `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 (`''). *Note Motion and Syntax::.
-
-\1f
-File: lispref.info, 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 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
- copying what the standard syntax table says about them.
-
- Most major mode syntax tables are created in this way.
-
- - Function: copy-syntax-table &optional table
- This function constructs a copy of TABLE and returns it. If TABLE
- is not supplied (or is `nil'), it returns a copy of the current
- syntax table. Otherwise, an error is signaled if TABLE is not a
- syntax table.
-
- - Command: modify-syntax-entry char syntax-descriptor &optional table
- This function sets the syntax entry for CHAR according to
- SYNTAX-DESCRIPTOR. 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 ?/ ". 14")
- => 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 following examples apply to C mode. The first example shows
- that the syntax class of space is whitespace (represented by a
- space). The second example shows that the syntax of `/' is
- punctuation. This does not show the fact that it is also part of
- comment-start and -end sequences. The third example shows that
- open parenthesis is in the class of open parentheses. This does
- not show the fact that it has a matching character, `)'.
-
- (char-to-string (char-syntax ?\ ))
- => " "
-
- (char-to-string (char-syntax ?/))
- => "."
-
- (char-to-string (char-syntax ?\())
- => "("
-
- - 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
- This function returns the syntax table for BUFFER, which defaults
- to the current buffer if omitted.
-
-\1f
-File: lispref.info, 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 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
- This function moves point backward across characters whose syntax
- classes are mentioned in SYNTAXES. It stops when it encounters
- the beginning of the buffer, or position LIMIT (if specified), or a
- character it is not supposed to skip. Optional argument BUFFER
- defaults to the current buffer if omitted.
-
-
- - 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.
-
projects / chise / xemacs-chise.git / blobdiff