X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/ad800164c88de7d29471d1fac5035c23ad82245d..a85732e683f6e3b24426f36d4869135bad18d5af:/lispref/syntax.texi diff --git a/lispref/syntax.texi b/lispref/syntax.texi index a2153cee4f..a9df79e9f5 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004, 2005 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/syntax @@ -135,10 +135,10 @@ modes. @end deffn @deffn {Syntax class} @w{word constituent} -@dfn{Word constituents} (designated by @samp{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. +@dfn{Word constituents} (designated by @samp{w}) are parts of words in +human languages, and are typically used in variable and command names +in programs. All upper- and lower-case letters, and the digits, are +typically word constituents. @end deffn @deffn {Syntax class} @w{symbol constituent} @@ -155,9 +155,10 @@ character that is valid in symbols is underscore (@samp{_}). @dfn{Punctuation characters} (designated by @samp{.}) 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 +Some programming language modes, such as Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or -word constituents all have other uses. +word constituents all have other uses. Other programming language modes, +such as C mode, use punctuation syntax for operators. @end deffn @deffn {Syntax class} @w{open parenthesis character} @@ -397,10 +398,13 @@ prefix (@samp{'}). @xref{Motion and Syntax}. In this section we describe functions for creating, accessing and altering syntax tables. -@defun make-syntax-table -This function creates a new syntax table. It inherits the syntax for -letters and control characters from the standard syntax table. For -other characters, the syntax is copied from the standard syntax table. +@defun make-syntax-table &optional table +This function creates a new syntax table, with all values initialized +to @code{nil}. If @var{table} is non-@code{nil}, it becomes the +parent of the new syntax table, otherwise the standard syntax table is +the parent. Like all char-tables, a syntax table inherits from its +parent. Thus the original syntax of all characters in the returned +syntax table is determined by the parent. @xref{Char-Tables}. Most major mode syntax tables are created in this way. @end defun @@ -408,7 +412,7 @@ Most major mode syntax tables are created in this way. @defun copy-syntax-table &optional table This function constructs a copy of @var{table} and returns it. If @var{table} is not supplied (or is @code{nil}), it returns a copy of the -current syntax table. Otherwise, an error is signaled if @var{table} is +standard syntax table. Otherwise, an error is signaled if @var{table} is not a syntax table. @end defun @@ -425,7 +429,7 @@ This function always returns @code{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 +one of the seventeen syntax class designator characters. An error is also signaled if @var{char} is not a character. @example @@ -524,10 +528,12 @@ execution starts. Other buffers are not affected. @section Syntax Properties @kindex syntax-table @r{(text property)} -When the syntax table is not flexible enough to specify the syntax of a -language, you can use @code{syntax-table} text properties to override -the syntax table for specific character occurrences in the buffer. -@xref{Text Properties}. +When the syntax table is not flexible enough to specify the syntax of +a language, you can use @code{syntax-table} text properties to +override the syntax table for specific character occurrences in the +buffer. @xref{Text Properties}. You can use Font Lock mode to set +@code{syntax-table} text properties. @xref{Setting Syntax +Properties}. The valid values of @code{syntax-table} text property are: @@ -559,10 +565,11 @@ table. have certain syntax classes. @defun skip-syntax-forward syntaxes &optional limit -This function moves point forward across characters having syntax classes -mentioned in @var{syntaxes}. It stops when it encounters the end of -the buffer, or position @var{limit} (if specified), or a character it is -not supposed to skip. +This function moves point forward across characters having syntax +classes mentioned in @var{syntaxes} (a string of syntax code +characters). It stops when it encounters the end of the buffer, or +position @var{limit} (if specified), or a character it is not supposed +to skip. If @var{syntaxes} starts with @samp{^}, then the function skips characters whose syntax is @emph{not} in @var{syntaxes}. @@ -654,13 +661,13 @@ start of a comment. If @var{stop-comment} is the symbol string, or the end of a comment or a string, whichever comes first. @cindex parse state -The fifth argument @var{state} is a nine-element list of the same form +The fifth argument @var{state} is a ten-element list of the same form as the value of this function, described below. (It is OK to omit the -last element of the nine.) The return value of one call may be used to -initialize the state of the parse on another call to +last two elements of this list.) The return value of one call may be +used to initialize the state of the parse on another call to @code{parse-partial-sexp}. -The result is a list of nine elements describing the final state of +The result is a list of ten elements describing the final state of the parse: @enumerate 0 @@ -697,18 +704,26 @@ that can be nested. The minimum parenthesis depth encountered during this scan. @item -What kind of comment is active: @code{nil} for a comment of style ``a'', -@code{t} for a comment of style ``b'', and @code{syntax-table} for -a comment that should be ended by a generic comment delimiter character. +What kind of comment is active: @code{nil} for a comment of style +``a'' or when not inside a comment, @code{t} for a comment of style +``b'', and @code{syntax-table} for a comment that should be ended by a +generic comment delimiter character. @item The string or comment start position. While inside a comment, this is the position where the comment began; while inside a string, this is the position where the string began. When outside of strings and comments, this element is @code{nil}. + +@item +Internal data for continuing the parsing. The meaning of this +data is subject to change; it is used if you pass this list +as the @var{state} argument to another call. + @end enumerate -Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}. +Elements 0, 3, 4, 5, 7 and 9 are significant in the argument +@var{state}. @cindex indenting with parentheses This function is most often used to compute indentation for languages @@ -757,17 +772,11 @@ of what the syntax table says about them. (However, text properties can still override the syntax.) @end defvar -@defvar parse-sexp-ignore-comments +@defopt parse-sexp-ignore-comments @cindex skipping comments If the value is non-@code{nil}, then comments are treated as whitespace by the functions in this section and by @code{forward-sexp}. - -In older Emacs versions, this feature worked only when the comment -terminator is something like @samp{*/}, and appears only to end a -comment. In languages where newlines terminate comments, it was -necessary make this variable @code{nil}, since not every newline is the -end of a comment. This limitation no longer exists. -@end defvar +@end defopt @vindex parse-sexp-lookup-properties The behaviour of @code{parse-partial-sexp} is also affected by @@ -930,6 +939,30 @@ This function returns the internal form @code{(@var{syntax-code} . @var{matching-char})} corresponding to the syntax descriptor @var{desc}. @end defun +@defun syntax-after pos +This function returns the syntax code of the character in the buffer +after position @var{pos}, taking account of syntax properties as well +as the syntax table. If @var{pos} is outside the buffer's accessible +portion (@pxref{Narrowing, accessible portion}), this function returns +@code{nil}. +@end defun + +@defun syntax-class syntax +This function returns the syntax class of the syntax code +@var{syntax}. (It masks off the high 16 bits that hold the flags +encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it +returns @code{nil}; this is so evaluating the expression + +@example +(syntax-class (syntax-after pos)) +@end example + +@noindent +where @code{pos} is outside the buffer's accessible portion, will +yield @code{nil} without throwing errors or producing wrong syntax +class codes. +@end defun + @node Categories @section Categories @cindex categories of characters @@ -957,12 +990,12 @@ belongs to. In this category set, if the element at index @var{cat} is @code{t}, that means category @var{cat} is a member of the set, and that character @var{c} belongs to category @var{cat}. +For the next three functions, the optional argument @var{table} +defaults to the current buffer's category table. + @defun define-category char docstring &optional table This function defines a new category, with name @var{char} and -documentation @var{docstring}. - -The new category is defined for category table @var{table}, which -defaults to the current buffer's category table. +documentation @var{docstring}, for the category table @var{table}. @end defun @defun category-docstring category &optional table @@ -977,7 +1010,7 @@ in category table @var{table}. @end example @end defun -@defun get-unused-category table +@defun get-unused-category &optional table This function returns a category name (a character) which is not currently defined in @var{table}. If all possible categories are in use in @var{table}, it returns @code{nil}. @@ -999,7 +1032,7 @@ This function returns the standard category table. @defun copy-category-table &optional table This function constructs a copy of @var{table} and returns it. If @var{table} is not supplied (or is @code{nil}), it returns a copy of the -current category table. Otherwise, an error is signaled if @var{table} +standard category table. Otherwise, an error is signaled if @var{table} is not a category table. @end defun @@ -1029,11 +1062,11 @@ other categories. @end defun @defun char-category-set char -This function returns the category set for character @var{char}. This -is the bool-vector which records which categories the character -@var{char} belongs to. The function @code{char-category-set} does not -allocate storage, because it returns the same bool-vector that exists in -the category table. +This function returns the category set for character @var{char} in the +current buffer's category table. This is the bool-vector which +records which categories the character @var{char} belongs to. The +function @code{char-category-set} does not allocate storage, because +it returns the same bool-vector that exists in the category table. @example (char-category-set ?a) @@ -1062,10 +1095,11 @@ But if @var{reset} is non-@code{nil}, then it deletes @var{category} instead. @end defun -@deffn Command describe-categories +@deffn Command describe-categories &optional buffer-or-name This function describes the category specifications in the current -category table. The descriptions are inserted in a buffer, which is -then displayed. +category table. It inserts the descriptions in a buffer, and then +displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it +describes the category table of that buffer instead. @end deffn @ignore