From 6dcef6eca79b118976211b05552880be2ddf014a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 8 Sep 2012 22:23:01 +0800 Subject: [PATCH] Introduce "raw syntax descriptor" terminology, and use it. * syntax.texi (Syntax Table Internals): Define "raw syntax descriptor" terminology. (Syntax Descriptors): Mention raw syntax descriptors. * lisp/subr.el (syntax-after, syntax-class): Doc fix. * syntax.c (Fstring_to_syntax): Doc fix. Fixes: debbugs:12383 --- doc/lispref/ChangeLog | 6 ++++ doc/lispref/syntax.texi | 61 ++++++++++++++++++++++++----------------- lisp/ChangeLog | 4 +++ lisp/subr.el | 9 ++++-- src/ChangeLog | 4 +++ src/syntax.c | 10 +++---- 6 files changed, 62 insertions(+), 32 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 4bd7210d7d6..57ee374af49 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2012-09-08 Chong Yidong + + * syntax.texi (Syntax Table Internals): Define "raw syntax + descriptor" terminology (Bug#12383). + (Syntax Descriptors): Mention raw syntax descriptors. + 2012-09-07 Chong Yidong * variables.texi (Creating Buffer-Local): Fix description of diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 91ae4359af7..624b5a92d6e 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -130,6 +130,10 @@ comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender). + Emacs also defines @dfn{raw syntax descriptors}, which are used to +describe syntax classes at a lower level. @xref{Syntax Table +Internals}. + @menu * Syntax Class Table:: Table of syntax classes. * Syntax Flags:: Additional flags each character can have. @@ -531,8 +535,9 @@ the current buffer's syntax table to determine the syntax for the underlying text character. @item @code{(@var{syntax-code} . @var{matching-char})} -A cons cell of this format specifies the syntax for the underlying -text character. (@pxref{Syntax Table Internals}) +A cons cell of this format is a raw syntax descriptor (@pxref{Syntax +Table Internals}), which directly specifies a syntax class for the +underlying text character. @item @code{nil} If the property is @code{nil}, the character's syntax is determined from @@ -940,16 +945,20 @@ documented in this section. This internal format can also be assigned as syntax properties (@pxref{Syntax Properties}). @cindex syntax code - Each entry in a syntax table is a cons cell of the form -@code{(@var{syntax-code} . @var{matching-char})}. @var{syntax-code} -is an integer that encodes the syntax class and syntax flags, -according to the table below. @var{matching-char}, if non-@code{nil}, -specifies a matching character (similar to the second character in a -syntax descriptor). +@cindex raw syntax descriptor + Each entry in a syntax table is a @dfn{raw syntax descriptor}: a +cons cell of the form @code{(@var{syntax-code} +. @var{matching-char})}. @var{syntax-code} is an integer which +encodes the syntax class and syntax flags, according to the table +below. @var{matching-char}, if non-@code{nil}, specifies a matching +character (similar to the second character in a syntax descriptor). + + Here are the syntax codes corresponding to the various syntax +classes: @multitable @columnfractions .2 .3 .2 .3 @item -@i{Syntax code} @tab @i{Class} @tab @i{Syntax code} @tab @i{Class} +@i{Code} @tab @i{Class} @tab @i{Code} @tab @i{Class} @item 0 @tab whitespace @tab 8 @tab paired delimiter @item @@ -970,7 +979,7 @@ syntax descriptor). @noindent For example, in the standard syntax table, the entry for @samp{(} is -@code{(4 . 41)}. (41 is the character code for @samp{)}.) +@code{(4 . 41)}. 41 is the character code for @samp{)}. Syntax flags are encoded in higher order bits, starting 16 bits from the least significant bit. This table gives the power of two which @@ -990,33 +999,35 @@ corresponds to each syntax flag. @end multitable @defun string-to-syntax @var{desc} -Given a syntax descriptor @var{desc}, this function returns the -corresponding internal form, a cons cell @code{(@var{syntax-code} -. @var{matching-char})}. +Given a syntax descriptor @var{desc} (a string), this function returns +the corresponding raw syntax descriptor. @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}. +This function returns the raw syntax descriptor for 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}), +the return value is @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 +This function returns the syntax code for the raw syntax descriptor +@var{syntax}. More precisely, it takes the raw syntax descriptor's +@var{syntax-code} component, masks off the high 16 bits which record +the syntax flags, and returns the resulting integer. + +If @var{syntax} is @code{nil}, the return value is returns @code{nil}. +This is so that 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. +evaluates to @code{nil} if @code{pos} is outside the buffer's +accessible portion, without throwing errors or returning an incorrect +code. @end defun @node Categories diff --git a/lisp/ChangeLog b/lisp/ChangeLog index e10fe9166e7..4d6210a16b9 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,7 @@ +2012-09-08 Chong Yidong + + * subr.el (syntax-after, syntax-class): Doc fix. + 2012-09-08 Martin Rudalics * window.el (display-buffer-in-previous-window): New buffer diff --git a/lisp/subr.el b/lisp/subr.el index a3e0897e9fe..4f273a92a62 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -3737,7 +3737,7 @@ from `standard-syntax-table' otherwise." table)) (defun syntax-after (pos) - "Return the raw syntax of the char after POS. + "Return the raw syntax descriptor for the char after POS. If POS is outside the buffer's accessible portion, return nil." (unless (or (< pos (point-min)) (>= pos (point-max))) (let ((st (if parse-sexp-lookup-properties @@ -3746,7 +3746,12 @@ If POS is outside the buffer's accessible portion, return nil." (aref (or st (syntax-table)) (char-after pos)))))) (defun syntax-class (syntax) - "Return the syntax class part of the syntax descriptor SYNTAX. + "Return the code for the syntax class described by SYNTAX. + +SYNTAX should be a raw syntax descriptor; the return value is a +integer which encodes the corresponding syntax class. See Info +node `(elisp)Syntax Table Internals' for a list of codes. + If SYNTAX is nil, return nil." (and syntax (logand (car syntax) 65535))) diff --git a/src/ChangeLog b/src/ChangeLog index 40647d79589..ec6e39ad0b5 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2012-09-08 Chong Yidong + + * syntax.c (Fstring_to_syntax): Doc fix. + 2012-09-08 Jan Djärv * nsterm.m (ns_clip_to_row): Remove code that deals with drawing fringe diff --git a/src/syntax.c b/src/syntax.c index f995b8f2cac..fdd9353bb87 100644 --- a/src/syntax.c +++ b/src/syntax.c @@ -921,11 +921,11 @@ DEFUN ("matching-paren", Fmatching_paren, Smatching_paren, 1, 1, 0, } DEFUN ("string-to-syntax", Fstring_to_syntax, Sstring_to_syntax, 1, 1, 0, - doc: /* Convert a syntax specification STRING into syntax cell form. -STRING should be a string as it is allowed as argument of -`modify-syntax-entry'. Value is the equivalent cons cell -\(CODE . MATCHING-CHAR) that can be used as value of a `syntax-table' -text property. */) + doc: /* Convert a syntax descriptor STRING into a raw syntax descriptor. +STRING should be a string of the form allowed as argument of +`modify-syntax-entry'. The return value is a raw syntax descriptor: a +cons cell \(CODE . MATCHING-CHAR) which can be used, for example, as +the value of a `syntax-table' text property. */) (Lisp_Object string) { register const unsigned char *p; -- 2.39.2