comparison lispref/syntax.texi @ 54114:f309c4cf39a2

(Syntax Table Functions): Clarify and correct descriptions of make-syntax-table and copy-syntax-table. (Motion and Syntax): Clarify SYNTAXES argument to skip-syntax-forward. (Parsing Expressions): Mention that the return value of parse-partial-sexp is currently a list of ten rather than nine elements. (Categories): Various corrections and clarifications.

54113:a045d0873ac4

@section Syntax Table Functions

  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.

Most major mode syntax tables are created in this way.
@end defun

@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
not a syntax table.
@end defun

@deffn Command modify-syntax-entry char syntax-descriptor  &optional table
This function sets the syntax entry for @var{char} according to

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
signaled if @var{char} is not a character.

@example
@group
@exdent @r{Examples:}

  This section describes functions for moving across characters that
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.

If @var{syntaxes} starts with @samp{^}, then the function skips
characters whose syntax is @emph{not} in @var{syntaxes}.

The return value is the distance traveled, which is a nonnegative

@item
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.

@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}.
@end enumerate

Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.

@cindex indenting with parentheses
This function is most often used to compute indentation for languages
that have nested parentheses.
@end defun

non-@acronym{ASCII} characters as symbol constituents regardless
of what the syntax table says about them.  (However, text properties
can still override the syntax.)
@end defvar

@defvar 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}.
@end defvar

@vindex parse-sexp-lookup-properties
The behaviour of @code{parse-partial-sexp} is also affected by
@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).

set}---a bool-vector---that indicates which categories character @var{c}
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}.

@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.
@end defun

@defun category-docstring category &optional table
This function returns the documentation string of category @var{category}
in category table @var{table}.

(category-docstring ?l)
     @result{} "Latin"
@end example
@end defun

@defun get-unused-category 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}.
@end defun

@end defun

@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}
is not a category table.
@end defun

@defun set-category-table table
This function makes @var{table} the category table for the current

     @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example
@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.

@example
(char-category-set ?a)
     @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example

Normally, it modifies the category set by adding @var{category} to it.
But if @var{reset} is non-@code{nil}, then it deletes @var{category}
instead.
@end defun

@deffn Command describe-categories
This function describes the category specifications in the current
category table.  The descriptions are inserted in a buffer, which is
then displayed.
@end deffn

@ignore
   arch-tag: 4d914e96-0283-445c-9233-75d33662908c
@end ignore

54114:f309c4cf39a2

@section Syntax Table Functions

  In this section we describe functions for creating, accessing and
altering syntax tables.

@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

@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
standard syntax table.  Otherwise, an error is signaled if @var{table} is
not a syntax table.
@end defun

@deffn Command modify-syntax-entry char syntax-descriptor  &optional table
This function sets the syntax entry for @var{char} according to

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 seventeen syntax class designator characters.  An error is also
signaled if @var{char} is not a character.

@example
@group
@exdent @r{Examples:}

  This section describes functions for moving across characters that
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} (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}.

The return value is the distance traveled, which is a nonnegative

@item
The minimum parenthesis depth encountered during this scan.

@item
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}.
@end enumerate

Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.

Actually, the return value is currently a list of ten, rather than
nine, elements and @var{state} is allowed to be a list of ten elements
as well.  However, the meaning of the tenth element is subject to
change and only the first eight elements of @var{state} need to be
specified.

@cindex indenting with parentheses
This function is most often used to compute indentation for languages
that have nested parentheses.
@end defun

non-@acronym{ASCII} characters as symbol constituents regardless
of what the syntax table says about them.  (However, text properties
can still override the syntax.)
@end defvar

@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}.
@end defopt

@vindex parse-sexp-lookup-properties
The behaviour of @code{parse-partial-sexp} is also affected by
@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).

set}---a bool-vector---that indicates which categories character @var{c}
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}, for the category table @var{table},
@end defun

@defun category-docstring category &optional table
This function returns the documentation string of category @var{category}
in category table @var{table}.

(category-docstring ?l)
     @result{} "Latin"
@end example
@end defun

@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}.
@end defun

@end defun

@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
standard category table.  Otherwise, an error is signaled if @var{table}
is not a category table.
@end defun

@defun set-category-table table
This function makes @var{table} the category table for the current

     @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example
@end defun

@defun char-category-set char
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)
     @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example

Normally, it modifies the category set by adding @var{category} to it.
But if @var{reset} is non-@code{nil}, then it deletes @var{category}
instead.
@end defun

@deffn Command describe-categories &optional buffer-or-name
This function describes the category specifications in the current
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
   arch-tag: 4d914e96-0283-445c-9233-75d33662908c
@end ignore