info/lispref.info-33

   1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: Replacing Match,  Next: Entire Match Data,  Prev: Simple Match Data,  Up: Match Data
  54
  55 Replacing the Text That Matched
  56 -------------------------------
  57
  58    This function replaces the text matched by the last search with
  59 REPLACEMENT.
  60
  61  - Function: replace-match replacement &optional fixedcase literal
  62           string strbuffer
  63      This function replaces the text in the buffer (or in STRING) that
  64      was matched by the last search.  It replaces that text with
  65      REPLACEMENT.
  66
  67      If you did the last search in a buffer, you should specify `nil'
  68      for STRING.  Then `replace-match' does the replacement by editing
  69      the buffer; it leaves point at the end of the replacement text,
  70      and returns `t'.
  71
  72      If you did the search in a string, pass the same string as STRING.
  73      Then `replace-match' does the replacement by constructing and
  74      returning a new string.
  75
  76      If the fourth argument STRING is a string, fifth argument
  77      STRBUFFER specifies the buffer to be used for syntax-table and
  78      case-table lookup and defaults to the current buffer.  When STRING
  79      is not a string, the buffer that the match occurred in has
  80      automatically been remembered and you do not need to specify it.
  81
  82      If FIXEDCASE is non-`nil', then the case of the replacement text
  83      is not changed; otherwise, the replacement text is converted to a
  84      different case depending upon the capitalization of the text to be
  85      replaced.  If the original text is all upper case, the replacement
  86      text is converted to upper case.  If the first word of the
  87      original text is capitalized, then the first word of the
  88      replacement text is capitalized.  If the original text contains
  89      just one word, and that word is a capital letter, `replace-match'
  90      considers this a capitalized first word rather than all upper case.
  91
  92      If `case-replace' is `nil', then case conversion is not done,
  93      regardless of the value of FIXEDCASE.  *Note Searching and Case::.
  94
  95      If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
  96      it is, the only alterations being case changes as needed.  If it
  97      is `nil' (the default), then the character `\' is treated
  98      specially.  If a `\' appears in REPLACEMENT, then it must be part
  99      of one of the following sequences:
 100
 101     `\&'
 102           `\&' stands for the entire text being replaced.
 103
 104     `\N'
 105           `\N', where N is a digit, stands for the text that matched
 106           the Nth subexpression in the original regexp.  Subexpressions
 107           are those expressions grouped inside `\(...\)'.
 108
 109     `\\'
 110           `\\' stands for a single `\' in the replacement text.
 111
 112 \1f
 113 File: lispref.info,  Node: Entire Match Data,  Next: Saving Match Data,  Prev: Replacing Match,  Up: Match Data
 114
 115 Accessing the Entire Match Data
 116 -------------------------------
 117
 118    The functions `match-data' and `set-match-data' read or write the
 119 entire match data, all at once.
 120
 121  - Function: match-data &optional integers reuse
 122      This function returns a newly constructed list containing all the
 123      information on what text the last search matched.  Element zero is
 124      the position of the beginning of the match for the whole
 125      expression; element one is the position of the end of the match
 126      for the expression.  The next two elements are the positions of
 127      the beginning and end of the match for the first subexpression,
 128      and so on.  In general, element number 2N corresponds to
 129      `(match-beginning N)'; and element number 2N + 1 corresponds to
 130      `(match-end N)'.
 131
 132      All the elements are markers or `nil' if matching was done on a
 133      buffer, and all are integers or `nil' if matching was done on a
 134      string with `string-match'.  However, if the optional first
 135      argument INTEGERS is non-`nil', always use integers (rather than
 136      markers) to represent buffer positions.
 137
 138      If the optional second argument REUSE is a list, reuse it as part
 139      of the value.  If REUSE is long enough to hold all the values, and
 140      if INTEGERS is non-`nil', no new lisp objects are created.
 141
 142      As always, there must be no possibility of intervening searches
 143      between the call to a search function and the call to `match-data'
 144      that is intended to access the match data for that search.
 145
 146           (match-data)
 147                =>  (#<marker at 9 in foo>
 148                     #<marker at 17 in foo>
 149                     #<marker at 13 in foo>
 150                     #<marker at 17 in foo>)
 151
 152  - Function: set-match-data match-list
 153      This function sets the match data from the elements of MATCH-LIST,
 154      which should be a list that was the value of a previous call to
 155      `match-data'.
 156
 157      If MATCH-LIST refers to a buffer that doesn't exist, you don't get
 158      an error; that sets the match data in a meaningless but harmless
 159      way.
 160
 161      `store-match-data' is an alias for `set-match-data'.
 162
 163 \1f
 164 File: lispref.info,  Node: Saving Match Data,  Prev: Entire Match Data,  Up: Match Data
 165
 166 Saving and Restoring the Match Data
 167 -----------------------------------
 168
 169    When you call a function that may do a search, you may need to save
 170 and restore the match data around that call, if you want to preserve the
 171 match data from an earlier search for later use.  Here is an example
 172 that shows the problem that arises if you fail to save the match data:
 173
 174      (re-search-forward "The \\(cat \\)")
 175           => 48
 176      (foo)                   ; Perhaps `foo' does
 177                              ;   more searching.
 178      (match-end 0)
 179           => 61              ; Unexpected result--not 48!
 180
 181    You can save and restore the match data with `save-match-data':
 182
 183  - Special Form: save-match-data body...
 184      This special form executes BODY, saving and restoring the match
 185      data around it.
 186
 187    You can use `set-match-data' together with `match-data' to imitate
 188 the effect of the special form `save-match-data'.  This is useful for
 189 writing code that can run in Emacs 18.  Here is how:
 190
 191      (let ((data (match-data)))
 192        (unwind-protect
 193            ...   ; May change the original match data.
 194          (set-match-data data)))
 195
 196    Emacs automatically saves and restores the match data when it runs
 197 process filter functions (*note Filter Functions::) and process
 198 sentinels (*note Sentinels::).
 199
 200 \1f
 201 File: lispref.info,  Node: Searching and Case,  Next: Standard Regexps,  Prev: Match Data,  Up: Searching and Matching
 202
 203 Searching and Case
 204 ==================
 205
 206    By default, searches in Emacs ignore the case of the text they are
 207 searching through; if you specify searching for `FOO', then `Foo' or
 208 `foo' is also considered a match.  Regexps, and in particular character
 209 sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
 210
 211    If you do not want this feature, set the variable `case-fold-search'
 212 to `nil'.  Then all letters must match exactly, including case.  This
 213 is a buffer-local variable; altering the variable affects only the
 214 current buffer.  (*Note Intro to Buffer-Local::.)  Alternatively, you
 215 may change the value of `default-case-fold-search', which is the
 216 default value of `case-fold-search' for buffers that do not override it.
 217
 218    Note that the user-level incremental search feature handles case
 219 distinctions differently.  When given a lower case letter, it looks for
 220 a match of either case, but when given an upper case letter, it looks
 221 for an upper case letter only.  But this has nothing to do with the
 222 searching functions Lisp functions use.
 223
 224  - User Option: case-replace
 225      This variable determines whether the replacement functions should
 226      preserve case.  If the variable is `nil', that means to use the
 227      replacement text verbatim.  A non-`nil' value means to convert the
 228      case of the replacement text according to the text being replaced.
 229
 230      The function `replace-match' is where this variable actually has
 231      its effect.  *Note Replacing Match::.
 232
 233  - User Option: case-fold-search
 234      This buffer-local variable determines whether searches should
 235      ignore case.  If the variable is `nil' they do not ignore case;
 236      otherwise they do ignore case.
 237
 238  - Variable: default-case-fold-search
 239      The value of this variable is the default value for
 240      `case-fold-search' in buffers that do not override it.  This is the
 241      same as `(default-value 'case-fold-search)'.
 242
 243 \1f
 244 File: lispref.info,  Node: Standard Regexps,  Prev: Searching and Case,  Up: Searching and Matching
 245
 246 Standard Regular Expressions Used in Editing
 247 ============================================
 248
 249    This section describes some variables that hold regular expressions
 250 used for certain purposes in editing:
 251
 252  - Variable: page-delimiter
 253      This is the regexp describing line-beginnings that separate pages.
 254      The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
 255      matches a line that starts with a formfeed character.
 256
 257    The following two regular expressions should _not_ assume the match
 258 always starts at the beginning of a line; they should not use `^' to
 259 anchor the match.  Most often, the paragraph commands do check for a
 260 match only at the beginning of a line, which means that `^' would be
 261 superfluous.  When there is a nonzero left margin, they accept matches
 262 that start after the left margin.  In that case, a `^' would be
 263 incorrect.  However, a `^' is harmless in modes where a left margin is
 264 never used.
 265
 266  - Variable: paragraph-separate
 267      This is the regular expression for recognizing the beginning of a
 268      line that separates paragraphs.  (If you change this, you may have
 269      to change `paragraph-start' also.)  The default value is
 270      `"[ \t\f]*$"', which matches a line that consists entirely of
 271      spaces, tabs, and form feeds (after its left margin).
 272
 273  - Variable: paragraph-start
 274      This is the regular expression for recognizing the beginning of a
 275      line that starts _or_ separates paragraphs.  The default value is
 276      `"[ \t\n\f]"', which matches a line starting with a space, tab,
 277      newline, or form feed (after its left margin).
 278
 279  - Variable: sentence-end
 280      This is the regular expression describing the end of a sentence.
 281      (All paragraph boundaries also end sentences, regardless.)  The
 282      default value is:
 283
 284           "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
 285
 286      This means a period, question mark or exclamation mark, followed
 287      optionally by a closing parenthetical character, followed by tabs,
 288      spaces or new lines.
 289
 290      For a detailed explanation of this regular expression, see *Note
 291      Regexp Example::.
 292
 293 \1f
 294 File: lispref.info,  Node: Syntax Tables,  Next: Abbrevs,  Prev: Searching and Matching,  Up: Top
 295
 296 Syntax Tables
 297 *************
 298
 299    A "syntax table" specifies the syntactic textual function of each
 300 character.  This information is used by the parsing commands, the
 301 complex movement commands, and others to determine where words, symbols,
 302 and other syntactic constructs begin and end.  The current syntax table
 303 controls the meaning of the word motion functions (*note Word Motion::)
 304 and the list motion functions (*note List Motion::) as well as the
 305 functions in this chapter.
 306
 307 * Menu:
 308
 309 * Basics: Syntax Basics.     Basic concepts of syntax tables.
 310 * Desc: Syntax Descriptors.  How characters are classified.
 311 * Syntax Table Functions::   How to create, examine and alter syntax tables.
 312 * Motion and Syntax::        Moving over characters with certain syntaxes.
 313 * Parsing Expressions::      Parsing balanced expressions
 314                                 using the syntax table.
 315 * Standard Syntax Tables::   Syntax tables used by various major modes.
 316 * Syntax Table Internals::   How syntax table information is stored.
 317
 318 \1f
 319 File: lispref.info,  Node: Syntax Basics,  Next: Syntax Descriptors,  Up: Syntax Tables
 320
 321 Syntax Table Concepts
 322 =====================
 323
 324    A "syntax table" provides Emacs with the information that determines
 325 the syntactic use of each character in a buffer.  This information is
 326 used by the parsing commands, the complex movement commands, and others
 327 to determine where words, symbols, and other syntactic constructs begin
 328 and end.  The current syntax table controls the meaning of the word
 329 motion functions (*note Word Motion::) and the list motion functions
 330 (*note List Motion::) as well as the functions in this chapter.
 331
 332    Under XEmacs 20, a syntax table is a particular subtype of the
 333 primitive char table type (*note Char Tables::), and each element of the
 334 char table is an integer that encodes the syntax of the character in
 335 question, or a cons of such an integer and a matching character (for
 336 characters with parenthesis syntax).
 337
 338    Under XEmacs 19, a syntax table is a vector of 256 elements; it
 339 contains one entry for each of the 256 possible characters in an 8-bit
 340 byte.  Each element is an integer that encodes the syntax of the
 341 character in question. (The matching character, if any, is embedded in
 342 the bits of this integer.)
 343
 344    Syntax tables are used only for moving across text, not for the Emacs
 345 Lisp reader.  XEmacs Lisp uses built-in syntactic rules when reading
 346 Lisp expressions, and these rules cannot be changed.
 347
 348    Each buffer has its own major mode, and each major mode has its own
 349 idea of the syntactic class of various characters.  For example, in Lisp
 350 mode, the character `;' begins a comment, but in C mode, it terminates
 351 a statement.  To support these variations, XEmacs makes the choice of
 352 syntax table local to each buffer.  Typically, each major mode has its
 353 own syntax table and installs that table in each buffer that uses that
 354 mode.  Changing this table alters the syntax in all those buffers as
 355 well as in any buffers subsequently put in that mode.  Occasionally
 356 several similar modes share one syntax table.  *Note Example Major
 357 Modes::, for an example of how to set up a syntax table.
 358
 359    A syntax table can inherit the data for some characters from the
 360 standard syntax table, while specifying other characters itself.  The
 361 "inherit" syntax class means "inherit this character's syntax from the
 362 standard syntax table."  Most major modes' syntax tables inherit the
 363 syntax of character codes 0 through 31 and 128 through 255.  This is
 364 useful with character sets such as ISO Latin-1 that have additional
 365 alphabetic characters in the range 128 to 255.  Just changing the
 366 standard syntax for these characters affects all major modes.
 367
 368  - Function: syntax-table-p object
 369      This function returns `t' if OBJECT is a vector of length 256
 370      elements.  This means that the vector may be a syntax table.
 371      However, according to this test, any vector of length 256 is
 372      considered to be a syntax table, no matter what its contents.
 373
 374 \1f
 375 File: lispref.info,  Node: Syntax Descriptors,  Next: Syntax Table Functions,  Prev: Syntax Basics,  Up: Syntax Tables
 376
 377 Syntax Descriptors
 378 ==================
 379
 380    This section describes the syntax classes and flags that denote the
 381 syntax of a character, and how they are represented as a "syntax
 382 descriptor", which is a Lisp string that you pass to
 383 `modify-syntax-entry' to specify the desired syntax.
 384
 385    XEmacs defines a number of "syntax classes".  Each syntax table puts
 386 each character into one class.  There is no necessary relationship
 387 between the class of a character in one syntax table and its class in
 388 any other table.
 389
 390    Each class is designated by a mnemonic character, which serves as the
 391 name of the class when you need to specify a class.  Usually the
 392 designator character is one that is frequently in that class; however,
 393 its meaning as a designator is unvarying and independent of what syntax
 394 that character currently has.
 395
 396    A syntax descriptor is a Lisp string that specifies a syntax class, a
 397 matching character (used only for the parenthesis classes) and flags.
 398 The first character is the designator for a syntax class.  The second
 399 character is the character to match; if it is unused, put a space there.
 400 Then come the characters for any desired flags.  If no matching
 401 character or flags are needed, one character is sufficient.
 402
 403    For example, the descriptor for the character `*' in C mode is
 404 `. 23' (i.e., punctuation, matching character slot unused, second
 405 character of a comment-starter, first character of an comment-ender),
 406 and the entry for `/' is `. 14' (i.e., punctuation, matching character
 407 slot unused, first character of a comment-starter, second character of
 408 a comment-ender).
 409
 410 * Menu:
 411
 412 * Syntax Class Table::      Table of syntax classes.
 413 * Syntax Flags::            Additional flags each character can have.
 414
 415 \1f
 416 File: lispref.info,  Node: Syntax Class Table,  Next: Syntax Flags,  Up: Syntax Descriptors
 417
 418 Table of Syntax Classes
 419 -----------------------
 420
 421    Here is a table of syntax classes, the characters that stand for
 422 them, their meanings, and examples of their use.
 423
 424  - Syntax class: whitespace character
 425      "Whitespace characters" (designated with ` ' or `-') separate
 426      symbols and words from each other.  Typically, whitespace
 427      characters have no other syntactic significance, and multiple
 428      whitespace characters are syntactically equivalent to a single
 429      one.  Space, tab, newline and formfeed are almost always
 430      classified as whitespace.
 431
 432  - Syntax class: word constituent
 433      "Word constituents" (designated with `w') are parts of normal
 434      English words and are typically used in variable and command names
 435      in programs.  All upper- and lower-case letters, and the digits,
 436      are typically word constituents.
 437
 438  - Syntax class: symbol constituent
 439      "Symbol constituents" (designated with `_') are the extra
 440      characters that are used in variable and command names along with
 441      word constituents.  For example, the symbol constituents class is
 442      used in Lisp mode to indicate that certain characters may be part
 443      of symbol names even though they are not part of English words.
 444      These characters are `$&*+-_<>'.  In standard C, the only
 445      non-word-constituent character that is valid in symbols is
 446      underscore (`_').
 447
 448  - Syntax class: punctuation character
 449      "Punctuation characters" (`.') are those characters that are used
 450      as punctuation in English, or are used in some way in a programming
 451      language to separate symbols from one another.  Most programming
 452      language modes, including Emacs Lisp mode, have no characters in
 453      this class since the few characters that are not symbol or word
 454      constituents all have other uses.
 455
 456  - Syntax class: open parenthesis character
 457  - Syntax class: close parenthesis character
 458      Open and close "parenthesis characters" are characters used in
 459      dissimilar pairs to surround sentences or expressions.  Such a
 460      grouping is begun with an open parenthesis character and
 461      terminated with a close.  Each open parenthesis character matches
 462      a particular close parenthesis character, and vice versa.
 463      Normally, XEmacs indicates momentarily the matching open
 464      parenthesis when you insert a close parenthesis.  *Note Blinking::.
 465
 466      The class of open parentheses is designated with `(', and that of
 467      close parentheses with `)'.
 468
 469      In English text, and in C code, the parenthesis pairs are `()',
 470      `[]', and `{}'.  In XEmacs Lisp, the delimiters for lists and
 471      vectors (`()' and `[]') are classified as parenthesis characters.
 472
 473  - Syntax class: string quote
 474      "String quote characters" (designated with `"') are used in many
 475      languages, including Lisp and C, to delimit string constants.  The
 476      same string quote character appears at the beginning and the end
 477      of a string.  Such quoted strings do not nest.
 478
 479      The parsing facilities of XEmacs consider a string as a single
 480      token.  The usual syntactic meanings of the characters in the
 481      string are suppressed.
 482
 483      The Lisp modes have two string quote characters: double-quote (`"')
 484      and vertical bar (`|').  `|' is not used in XEmacs Lisp, but it is
 485      used in Common Lisp.  C also has two string quote characters:
 486      double-quote for strings, and single-quote (`'') for character
 487      constants.
 488
 489      English text has no string quote characters because English is not
 490      a programming language.  Although quotation marks are used in
 491      English, we do not want them to turn off the usual syntactic
 492      properties of other characters in the quotation.
 493
 494  - Syntax class: escape
 495      An "escape character" (designated with `\') starts an escape
 496      sequence such as is used in C string and character constants.  The
 497      character `\' belongs to this class in both C and Lisp.  (In C, it
 498      is used thus only inside strings, but it turns out to cause no
 499      trouble to treat it this way throughout C code.)
 500
 501      Characters in this class count as part of words if
 502      `words-include-escapes' is non-`nil'.  *Note Word Motion::.
 503
 504  - Syntax class: character quote
 505      A "character quote character" (designated with `/') quotes the
 506      following character so that it loses its normal syntactic meaning.
 507      This differs from an escape character in that only the character
 508      immediately following is ever affected.
 509
 510      Characters in this class count as part of words if
 511      `words-include-escapes' is non-`nil'.  *Note Word Motion::.
 512
 513      This class is used for backslash in TeX mode.
 514
 515  - Syntax class: paired delimiter
 516      "Paired delimiter characters" (designated with `$') are like
 517      string quote characters except that the syntactic properties of the
 518      characters between the delimiters are not suppressed.  Only TeX
 519      mode uses a paired delimiter presently--the `$' that both enters
 520      and leaves math mode.
 521
 522  - Syntax class: expression prefix
 523      An "expression prefix operator" (designated with `'') is used for
 524      syntactic operators that are part of an expression if they appear
 525      next to one.  These characters in Lisp include the apostrophe, `''
 526      (used for quoting), the comma, `,' (used in macros), and `#' (used
 527      in the read syntax for certain data types).
 528
 529  - Syntax class: comment starter
 530  - Syntax class: comment ender
 531      The "comment starter" and "comment ender" characters are used in
 532      various languages to delimit comments.  These classes are
 533      designated with `<' and `>', respectively.
 534
 535      English text has no comment characters.  In Lisp, the semicolon
 536      (`;') starts a comment and a newline or formfeed ends one.
 537
 538  - Syntax class: inherit
 539      This syntax class does not specify a syntax.  It says to look in
 540      the standard syntax table to find the syntax of this character.
 541      The designator for this syntax code is `@'.
 542
 543 \1f
 544 File: lispref.info,  Node: Syntax Flags,  Prev: Syntax Class Table,  Up: Syntax Descriptors
 545
 546 Syntax Flags
 547 ------------
 548
 549    In addition to the classes, entries for characters in a syntax table
 550 can include flags.  There are six possible flags, represented by the
 551 characters `1', `2', `3', `4', `b' and `p'.
 552
 553    All the flags except `p' are used to describe multi-character
 554 comment delimiters.  The digit flags indicate that a character can
 555 _also_ be part of a comment sequence, in addition to the syntactic
 556 properties associated with its character class.  The flags are
 557 independent of the class and each other for the sake of characters such
 558 as `*' in C mode, which is a punctuation character, _and_ the second
 559 character of a start-of-comment sequence (`/*'), _and_ the first
 560 character of an end-of-comment sequence (`*/').
 561
 562    The flags for a character C are:
 563
 564    * `1' means C is the start of a two-character comment-start sequence.
 565
 566    * `2' means C is the second character of such a sequence.
 567
 568    * `3' means C is the start of a two-character comment-end sequence.
 569
 570    * `4' means C is the second character of such a sequence.
 571
 572    * `b' means that C as a comment delimiter belongs to the alternative
 573      "b" comment style.
 574
 575      Emacs supports two comment styles simultaneously in any one syntax
 576      table.  This is for the sake of C++.  Each style of comment syntax
 577      has its own comment-start sequence and its own comment-end
 578      sequence.  Each comment must stick to one style or the other;
 579      thus, if it starts with the comment-start sequence of style "b",
 580      it must also end with the comment-end sequence of style "b".
 581
 582      The two comment-start sequences must begin with the same
 583      character; only the second character may differ.  Mark the second
 584      character of the "b"-style comment-start sequence with the `b'
 585      flag.
 586
 587      A comment-end sequence (one or two characters) applies to the "b"
 588      style if its first character has the `b' flag set; otherwise, it
 589      applies to the "a" style.
 590
 591      The appropriate comment syntax settings for C++ are as follows:
 592
 593     `/'
 594           `124b'
 595
 596     `*'
 597           `23'
 598
 599     newline
 600           `>b'
 601
 602      This defines four comment-delimiting sequences:
 603
 604     `/*'
 605           This is a comment-start sequence for "a" style because the
 606           second character, `*', does not have the `b' flag.
 607
 608     `//'
 609           This is a comment-start sequence for "b" style because the
 610           second character, `/', does have the `b' flag.
 611
 612     `*/'
 613           This is a comment-end sequence for "a" style because the first
 614           character, `*', does not have the `b' flag
 615
 616     newline
 617           This is a comment-end sequence for "b" style, because the
 618           newline character has the `b' flag.
 619
 620    * `p' identifies an additional "prefix character" for Lisp syntax.
 621      These characters are treated as whitespace when they appear between
 622      expressions.  When they appear within an expression, they are
 623      handled according to their usual syntax codes.
 624
 625      The function `backward-prefix-chars' moves back over these
 626      characters, as well as over characters whose primary syntax class
 627      is prefix (`'').  *Note Motion and Syntax::.
 628
 629 \1f
 630 File: lispref.info,  Node: Syntax Table Functions,  Next: Motion and Syntax,  Prev: Syntax Descriptors,  Up: Syntax Tables
 631
 632 Syntax Table Functions
 633 ======================
 634
 635    In this section we describe functions for creating, accessing and
 636 altering syntax tables.
 637
 638  - Function: make-syntax-table &optional oldtable
 639      This function creates a new syntax table.  Character codes 0
 640      through 31 and 128 through 255 are set up to inherit from the
 641      standard syntax table.  The other character codes are set up by
 642      copying what the standard syntax table says about them.
 643
 644      Most major mode syntax tables are created in this way.
 645
 646  - Function: copy-syntax-table &optional syntax-table
 647      This function constructs a copy of SYNTAX-TABLE and returns it.
 648      If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy
 649      of the current syntax table.  Otherwise, an error is signaled if
 650      SYNTAX-TABLE is not a syntax table.
 651
 652  - Command: modify-syntax-entry char-range syntax-descriptor &optional
 653           syntax-table
 654      This function sets the syntax entry for CHAR-RANGE according to
 655      SYNTAX-DESCRIPTOR.  CHAR-RANGE is either a single character or a
 656      range of characters, as used with `put-char-table'. The syntax is
 657      changed only for SYNTAX-TABLE, which defaults to the current
 658      buffer's syntax table, and not in any other syntax table.  The
 659      argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a
 660      string beginning with a class designator character, and optionally
 661      containing a matching character and flags as well.  *Note Syntax
 662      Descriptors::.
 663
 664      This function always returns `nil'.  The old syntax information in
 665      the table for CHAR-RANGE is discarded.
 666
 667      An error is signaled if the first character of the syntax
 668      descriptor is not one of the twelve syntax class designator
 669      characters.
 670
 671      Examples:
 672
 673           ;; Put the space character in class whitespace.
 674           (modify-syntax-entry ?\  " ")
 675                => nil
 676
 677           ;; Make `$' an open parenthesis character,
 678           ;;   with `^' as its matching close.
 679           (modify-syntax-entry ?$ "(^")
 680                => nil
 681
 682           ;; Make `^' a close parenthesis character,
 683           ;;   with `$' as its matching open.
 684           (modify-syntax-entry ?^ ")$")
 685                => nil
 686
 687           ;; Make `/' a punctuation character,
 688           ;;   the first character of a start-comment sequence,
 689           ;;   and the second character of an end-comment sequence.
 690           ;;   This is used in C mode.
 691           (modify-syntax-entry ?/ ". 14")
 692                => nil
 693
 694  - Function: char-syntax character &optional syntax-table
 695      This function returns the syntax class of CHARACTER, represented
 696      by its mnemonic designator character.  This _only_ returns the
 697      class, not any matching parenthesis or flags.
 698
 699      An error is signaled if CHARACTER is not a character.
 700
 701      The characters that correspond to various syntax codes are listed
 702      in the documentation of `modify-syntax-entry'.
 703
 704      Optional second argument SYNTAX-TABLE is the syntax table to be
 705      used, and defaults to the current buffer's syntax table.
 706
 707      The following examples apply to C mode.  The first example shows
 708      that the syntax class of space is whitespace (represented by a
 709      space).  The second example shows that the syntax of `/' is
 710      punctuation.  This does not show the fact that it is also part of
 711      comment-start and -end sequences.  The third example shows that
 712      open parenthesis is in the class of open parentheses.  This does
 713      not show the fact that it has a matching character, `)'.
 714
 715           (char-to-string (char-syntax ?\ ))
 716                => " "
 717
 718           (char-to-string (char-syntax ?/))
 719                => "."
 720
 721           (char-to-string (char-syntax ?\())
 722                => "("
 723
 724  - Function: set-syntax-table syntax-table &optional buffer
 725      This function makes SYNTAX-TABLE the syntax table for BUFFER, which
 726      defaults to the current buffer if omitted.  It returns
 727      SYNTAX-TABLE.
 728
 729  - Function: syntax-table &optional buffer
 730      This function returns the syntax table for BUFFER, which defaults
 731      to the current buffer if omitted.
 732
 733 \1f
 734 File: lispref.info,  Node: Motion and Syntax,  Next: Parsing Expressions,  Prev: Syntax Table Functions,  Up: Syntax Tables
 735
 736 Motion and Syntax
 737 =================
 738
 739    This section describes functions for moving across characters in
 740 certain syntax classes.  None of these functions exists in Emacs
 741 version 18 or earlier.
 742
 743  - Function: skip-syntax-forward syntaxes &optional limit buffer
 744      This function moves point forward across characters having syntax
 745      classes mentioned in SYNTAXES.  It stops when it encounters the
 746      end of the buffer, or position LIMIT (if specified), or a
 747      character it is not supposed to skip.  Optional argument BUFFER
 748      defaults to the current buffer if omitted.
 749
 750  - Function: skip-syntax-backward syntaxes &optional limit buffer
 751      This function moves point backward across characters whose syntax
 752      classes are mentioned in SYNTAXES.  It stops when it encounters
 753      the beginning of the buffer, or position LIMIT (if specified), or a
 754      character it is not supposed to skip.  Optional argument BUFFER
 755      defaults to the current buffer if omitted.
 756
 757
 758  - Function: backward-prefix-chars &optional buffer
 759      This function moves point backward over any number of characters
 760      with expression prefix syntax.  This includes both characters in
 761      the expression prefix syntax class, and characters with the `p'
 762      flag.  Optional argument BUFFER defaults to the current buffer if
 763      omitted.
 764
 765 \1f
 766 File: lispref.info,  Node: Parsing Expressions,  Next: Standard Syntax Tables,  Prev: Motion and Syntax,  Up: Syntax Tables
 767
 768 Parsing Balanced Expressions
 769 ============================
 770
 771    Here are several functions for parsing and scanning balanced
 772 expressions, also known as "sexps", in which parentheses match in
 773 pairs.  The syntax table controls the interpretation of characters, so
 774 these functions can be used for Lisp expressions when in Lisp mode and
 775 for C expressions when in C mode.  *Note List Motion::, for convenient
 776 higher-level functions for moving over balanced expressions.
 777
 778  - Function: parse-partial-sexp start limit &optional target-depth
 779           stop-before state stop-comment buffer
 780      This function parses a sexp in the current buffer starting at
 781      START, not scanning past LIMIT.  It stops at position LIMIT or
 782      when certain criteria described below are met, and sets point to
 783      the location where parsing stops.  It returns a value describing
 784      the status of the parse at the point where it stops.
 785
 786      If STATE is `nil', START is assumed to be at the top level of
 787      parenthesis structure, such as the beginning of a function
 788      definition.  Alternatively, you might wish to resume parsing in the
 789      middle of the structure.  To do this, you must provide a STATE
 790      argument that describes the initial status of parsing.
 791
 792      If the third argument TARGET-DEPTH is non-`nil', parsing stops if
 793      the depth in parentheses becomes equal to TARGET-DEPTH.  The depth
 794      starts at 0, or at whatever is given in STATE.
 795
 796      If the fourth argument STOP-BEFORE is non-`nil', parsing stops
 797      when it comes to any character that starts a sexp.  If
 798      STOP-COMMENT is non-`nil', parsing stops when it comes to the
 799      start of a comment.
 800
 801      The fifth argument STATE is an eight-element list of the same form
 802      as the value of this function, described below.  The return value
 803      of one call may be used to initialize the state of the parse on
 804      another call to `parse-partial-sexp'.
 805
 806      The result is a list of eight elements describing the final state
 807      of the parse:
 808
 809        0. The depth in parentheses, counting from 0.
 810
 811        1. The character position of the start of the innermost
 812           parenthetical grouping containing the stopping point; `nil'
 813           if none.
 814
 815        2. The character position of the start of the last complete
 816           subexpression terminated; `nil' if none.
 817
 818        3. Non-`nil' if inside a string.  More precisely, this is the
 819           character that will terminate the string.
 820
 821        4. `t' if inside a comment (of either style).
 822
 823        5. `t' if point is just after a quote character.
 824
 825        6. The minimum parenthesis depth encountered during this scan.
 826
 827        7. `t' if inside a comment of style "b".
 828
 829      Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
 830
 831      This function is most often used to compute indentation for
 832      languages that have nested parentheses.
 833
 834  - Function: scan-lists from count depth &optional buffer noerror
 835      This function scans forward COUNT balanced parenthetical groupings
 836      from character number FROM.  It returns the character position
 837      where the scan stops.
 838
 839      If DEPTH is nonzero, parenthesis depth counting begins from that
 840      value.  The only candidates for stopping are places where the
 841      depth in parentheses becomes zero; `scan-lists' counts COUNT such
 842      places and then stops.  Thus, a positive value for DEPTH means go
 843      out DEPTH levels of parenthesis.
 844
 845      Scanning ignores comments if `parse-sexp-ignore-comments' is
 846      non-`nil'.
 847
 848      If the scan reaches the beginning or end of the buffer (or its
 849      accessible portion), and the depth is not zero, an error is
 850      signaled.  If the depth is zero but the count is not used up,
 851      `nil' is returned.
 852
 853      If optional arg BUFFER is non-`nil', scanning occurs in that
 854      buffer instead of in the current buffer.
 855
 856      If optional arg NOERROR is non-`nil', `scan-lists' will return
 857      `nil' instead of signalling an error.
 858
 859  - Function: scan-sexps from count &optional buffer noerror
 860      This function scans forward COUNT sexps from character position
 861      FROM.  It returns the character position where the scan stops.
 862
 863      Scanning ignores comments if `parse-sexp-ignore-comments' is
 864      non-`nil'.
 865
 866      If the scan reaches the beginning or end of (the accessible part
 867      of) the buffer in the middle of a parenthetical grouping, an error
 868      is signaled.  If it reaches the beginning or end between groupings
 869      but before count is used up, `nil' is returned.
 870
 871      If optional arg BUFFER is non-`nil', scanning occurs in that
 872      buffer instead of in the current buffer.
 873
 874      If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
 875      instead of signalling an error.
 876
 877  - Variable: parse-sexp-ignore-comments
 878      If the value is non-`nil', then comments are treated as whitespace
 879      by the functions in this section and by `forward-sexp'.
 880
 881      In older Emacs versions, this feature worked only when the comment
 882      terminator is something like `*/', and appears only to end a
 883      comment.  In languages where newlines terminate comments, it was
 884      necessary make this variable `nil', since not every newline is the
 885      end of a comment.  This limitation no longer exists.
 886
 887    You can use `forward-comment' to move forward or backward over one
 888 comment or several comments.
 889
 890  - Function: forward-comment &optional count buffer
 891      This function moves point forward across COUNT comments (backward,
 892      if COUNT is negative).  If it finds anything other than a comment
 893      or whitespace, it stops, leaving point at the place where it
 894      stopped.  It also stops after satisfying COUNT.  COUNT defaults to
 895      `1'.
 896
 897      Optional argument BUFFER defaults to the current buffer.
 898
 899    To move forward over all comments and whitespace following point, use
 900 `(forward-comment (buffer-size))'.  `(buffer-size)' is a good argument
 901 to use, because the number of comments in the buffer cannot exceed that
 902 many.
 903
 904 \1f
 905 File: lispref.info,  Node: Standard Syntax Tables,  Next: Syntax Table Internals,  Prev: Parsing Expressions,  Up: Syntax Tables
 906
 907 Some Standard Syntax Tables
 908 ===========================
 909
 910    Most of the major modes in XEmacs have their own syntax tables.  Here
 911 are several of them:
 912
 913  - Function: standard-syntax-table
 914      This function returns the standard syntax table, which is the
 915      syntax table used in Fundamental mode.
 916
 917  - Variable: text-mode-syntax-table
 918      The value of this variable is the syntax table used in Text mode.
 919
 920  - Variable: c-mode-syntax-table
 921      The value of this variable is the syntax table for C-mode buffers.
 922
 923  - Variable: emacs-lisp-mode-syntax-table
 924      The value of this variable is the syntax table used in Emacs Lisp
 925      mode by editing commands.  (It has no effect on the Lisp `read'
 926      function.)
 927
 928 \1f
 929 File: lispref.info,  Node: Syntax Table Internals,  Prev: Standard Syntax Tables,  Up: Syntax Tables
 930
 931 Syntax Table Internals
 932 ======================
 933
 934    Each element of a syntax table is an integer that encodes the syntax
 935 of one character: the syntax class, possible matching character, and
 936 flags.  Lisp programs don't usually work with the elements directly; the
 937 Lisp-level syntax table functions usually work with syntax descriptors
 938 (*note Syntax Descriptors::).
 939
 940    The low 8 bits of each element of a syntax table indicate the syntax
 941 class.
 942
 943 Integer
 944      Class
 945
 946 0
 947      whitespace
 948
 949 1
 950      punctuation
 951
 952 2
 953      word
 954
 955 3
 956      symbol
 957
 958 4
 959      open parenthesis
 960
 961 5
 962      close parenthesis
 963
 964 6
 965      expression prefix
 966
 967 7
 968      string quote
 969
 970 8
 971      paired delimiter
 972
 973 9
 974      escape
 975
 976 10
 977      character quote
 978
 979 11
 980      comment-start
 981
 982 12
 983      comment-end
 984
 985 13
 986      inherit
 987
 988    The next 8 bits are the matching opposite parenthesis (if the
 989 character has parenthesis syntax); otherwise, they are not meaningful.
 990 The next 6 bits are the flags.
 991
 992 \1f
 993 File: lispref.info,  Node: Abbrevs,  Next: Extents,  Prev: Syntax Tables,  Up: Top
 994
 995 Abbrevs And Abbrev Expansion
 996 ****************************
 997
 998    An abbreviation or "abbrev" is a string of characters that may be
 999 expanded to a longer string.  The user can insert the abbrev string and
1000 find it replaced automatically with the expansion of the abbrev.  This
1001 saves typing.
1002
1003    The set of abbrevs currently in effect is recorded in an "abbrev
1004 table".  Each buffer has a local abbrev table, but normally all buffers
1005 in the same major mode share one abbrev table.  There is also a global
1006 abbrev table.  Normally both are used.
1007
1008    An abbrev table is represented as an obarray containing a symbol for
1009 each abbreviation.  The symbol's name is the abbreviation; its value is
1010 the expansion; its function definition is the hook function to do the
1011 expansion (*note Defining Abbrevs::); its property list cell contains
1012 the use count, the number of times the abbreviation has been expanded.
1013 Because these symbols are not interned in the usual obarray, they will
1014 never appear as the result of reading a Lisp expression; in fact,
1015 normally they are never used except by the code that handles abbrevs.
1016 Therefore, it is safe to use them in an extremely nonstandard way.
1017 *Note Creating Symbols::.
1018
1019    For the user-level commands for abbrevs, see *Note Abbrev Mode:
1020 (xemacs)Abbrevs.
1021
1022 * Menu:
1023
1024 * Abbrev Mode::                 Setting up XEmacs for abbreviation.
1025 * Tables: Abbrev Tables.        Creating and working with abbrev tables.
1026 * Defining Abbrevs::            Specifying abbreviations and their expansions.
1027 * Files: Abbrev Files.          Saving abbrevs in files.
1028 * Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
1029 * Standard Abbrev Tables::      Abbrev tables used by various major modes.
1030
1031 \1f
1032 File: lispref.info,  Node: Abbrev Mode,  Next: Abbrev Tables,  Up: Abbrevs
1033
1034 Setting Up Abbrev Mode
1035 ======================
1036
1037    Abbrev mode is a minor mode controlled by the value of the variable
1038 `abbrev-mode'.
1039
1040  - Variable: abbrev-mode
1041      A non-`nil' value of this variable turns on the automatic expansion
1042      of abbrevs when their abbreviations are inserted into a buffer.
1043      If the value is `nil', abbrevs may be defined, but they are not
1044      expanded automatically.
1045
1046      This variable automatically becomes local when set in any fashion.
1047
1048  - Variable: default-abbrev-mode
1049      This is the value of `abbrev-mode' for buffers that do not
1050      override it.  This is the same as `(default-value 'abbrev-mode)'.
1051
1052 \1f
1053 File: lispref.info,  Node: Abbrev Tables,  Next: Defining Abbrevs,  Prev: Abbrev Mode,  Up: Abbrevs
1054
1055 Abbrev Tables
1056 =============
1057
1058    This section describes how to create and manipulate abbrev tables.
1059
1060  - Function: make-abbrev-table
1061      This function creates and returns a new, empty abbrev table--an
1062      obarray containing no symbols.  It is a vector filled with zeros.
1063
1064  - Function: clear-abbrev-table table
1065      This function undefines all the abbrevs in abbrev table TABLE,
1066      leaving it empty.  The function returns `nil'.
1067
1068  - Function: define-abbrev-table table-name definitions
1069      This function defines TABLE-NAME (a symbol) as an abbrev table
1070      name, i.e., as a variable whose value is an abbrev table.  It
1071      defines abbrevs in the table according to DEFINITIONS, a list of
1072      elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'.  The
1073      value is always `nil'.
1074
1075  - Variable: abbrev-table-name-list
1076      This is a list of symbols whose values are abbrev tables.
1077      `define-abbrev-table' adds the new abbrev table name to this list.
1078
1079  - Function: insert-abbrev-table-description name &optional human
1080      This function inserts before point a description of the abbrev
1081      table named NAME.  The argument NAME is a symbol whose value is an
1082      abbrev table.  The value is always `nil'.
1083
1084      If HUMAN is non-`nil', the description is human-oriented.
1085      Otherwise the description is a Lisp expression--a call to
1086      `define-abbrev-table' that would define NAME exactly as it is
1087      currently defined.
1088
1089 \1f
1090 File: lispref.info,  Node: Defining Abbrevs,  Next: Abbrev Files,  Prev: Abbrev Tables,  Up: Abbrevs
1091
1092 Defining Abbrevs
1093 ================
1094
1095    These functions define an abbrev in a specified abbrev table.
1096 `define-abbrev' is the low-level basic function, while `add-abbrev' is
1097 used by commands that ask for information from the user.
1098
1099  - Function: add-abbrev table type arg
1100      This function adds an abbreviation to abbrev table TABLE based on
1101      information from the user.  The argument TYPE is a string
1102      describing in English the kind of abbrev this will be (typically,
1103      `"global"' or `"mode-specific"'); this is used in prompting the
1104      user.  The argument ARG is the number of words in the expansion.
1105
1106      The return value is the symbol that internally represents the new
1107      abbrev, or `nil' if the user declines to confirm redefining an
1108      existing abbrev.
1109
1110  - Function: define-abbrev table name &optional expansion hook count
1111      This function defines an abbrev in TABLE named NAME, to expand to
1112      EXPANSION, and call HOOK.  The return value is an uninterned
1113      symbol that represents the abbrev inside XEmacs; its name is NAME.
1114
1115      The argument NAME should be a string.  The argument EXPANSION
1116      should be a string, or `nil' to undefine the abbrev.
1117
1118      The argument HOOK is a function or `nil'.  If HOOK is non-`nil',
1119      then it is called with no arguments after the abbrev is replaced
1120      with EXPANSION; point is located at the end of EXPANSION when HOOK
1121      is called.
1122
1123      The use count of the abbrev is initialized to zero.
1124
1125  - User Option: only-global-abbrevs
1126      If this variable is non-`nil', it means that the user plans to use
1127      global abbrevs only.  This tells the commands that define
1128      mode-specific abbrevs to define global ones instead.  This
1129      variable does not alter the behavior of the functions in this
1130      section; it is examined by their callers.
1131
1132 \1f
1133 File: lispref.info,  Node: Abbrev Files,  Next: Abbrev Expansion,  Prev: Defining Abbrevs,  Up: Abbrevs
1134
1135 Saving Abbrevs in Files
1136 =======================
1137
1138    A file of saved abbrev definitions is actually a file of Lisp code.
1139 The abbrevs are saved in the form of a Lisp program to define the same
1140 abbrev tables with the same contents.  Therefore, you can load the file
1141 with `load' (*note How Programs Do Loading::).  However, the function
1142 `quietly-read-abbrev-file' is provided as a more convenient interface.
1143
1144    User-level facilities such as `save-some-buffers' can save abbrevs
1145 in a file automatically, under the control of variables described here.
1146
1147  - User Option: abbrev-file-name
1148      This is the default file name for reading and saving abbrevs.
1149
1150  - Function: quietly-read-abbrev-file &optional filename
1151      This function reads abbrev definitions from a file named FILENAME,
1152      previously written with `write-abbrev-file'.  If FILENAME is
1153      `nil', the file specified in `abbrev-file-name' is used.
1154      `save-abbrevs' is set to `t' so that changes will be saved.
1155
1156      This function does not display any messages.  It returns `nil'.
1157
1158  - User Option: save-abbrevs
1159      A non-`nil' value for `save-abbrev' means that XEmacs should save
1160      abbrevs when files are saved.  `abbrev-file-name' specifies the
1161      file to save the abbrevs in.
1162
1163  - Variable: abbrevs-changed
1164      This variable is set non-`nil' by defining or altering any
1165      abbrevs.  This serves as a flag for various XEmacs commands to
1166      offer to save your abbrevs.
1167
1168  - Command: write-abbrev-file filename
1169      Save all abbrev definitions, in all abbrev tables, in the file
1170      FILENAME, in the form of a Lisp program that when loaded will
1171      define the same abbrevs.  This function returns `nil'.
1172