comparison lisp/progmodes/cc-engine.el @ 98693:69a04789c5f0

Amend several doc strings and comments.

98692:51d93fabb7cf

  "Move to the start of the current statement or declaration, or to
the previous one if already at the beginning of one.  Only
statements/declarations on the same level are considered, i.e. don't
move into or out of sexps (not even normal expression parentheses).

Stop at statement continuation tokens like \"else\", \"catch\",
\"finally\" and the \"while\" in \"do ... while\" if the start point
is within the continuation.  If starting at such a token, move to the
corresponding statement start.  If at the beginning of a statement,
move to the closest containing statement if there is any.  This might

from any normal statement starts found in it, stop at the first token
of the content in the macro, i.e. the expression of an \"#if\" or the
start of the definition in a \"#define\".  Also stop at start of
macros before leaving them.

Return 'label if stopped at a label, 'same if stopped at the beginning
of the current statement, 'up if stepped to a containing statement,
'previous if stepped to a preceding statement, 'beginning if stepped
from a statement continuation clause to its start clause, or 'macro if
stepped to a macro start.  Note that 'same and not 'label is returned
if stopped at the same label without crossing the colon character.

LIM may be given to limit the search.  If the search hits the limit,
point will be left at the closest following token, or at the start
position if that is less ('same is returned in this case).

(defun c-beginning-of-current-token (&optional back-limit)
  ;; Move to the beginning of the current token.  Do not move if not
  ;; in the middle of one.  BACK-LIMIT may be used to bound the
  ;; backward search; if given it's assumed to be at the boundary
  ;; between two tokens.  Return non-nil if the point is move, nil
  ;; otherwise.
  ;;
  ;; This function might do hidden buffer changes.
    (let ((start (point)))
      (if (looking-at "\\w\\|\\s_")

to start parsing from.  If NEAR is non-nil, then the limits of any
literal next to point is returned.  \"Next to\" means there's only
spaces and tabs between point and the literal.  The search for such a
literal is done first in forward direction.  If NOT-IN-DELIMITER is
non-nil, the case when point is inside a starting delimiter won't be
recognized.  This only has effect for comments, which have starting
delimiters with more than one character.

Note that this function might do hidden buffer changes.  See the
comment at the start of cc-engine.el for more info."

	  range)
      (error range))))

(defun c-literal-type (range)
  "Convenience function that given the result of `c-literal-limits',
returns nil or the type of literal that the range surrounds.  It's
much faster than using `c-in-literal' and is intended to be used when
you need both the type of a literal and its limits.

Note that this function might do hidden buffer changes.  See the
comment at the start of cc-engine.el for more info."

  (if (consp range)

				  (min cfd-prop-match (point))
				(point))))))

(defun c-find-decl-spots (cfd-limit cfd-decl-re cfd-face-checklist cfd-fun)
  ;; Call CFD-FUN for each possible spot for a declaration, cast or
  ;; label from the point to CFD-LIMIT.  Such a spot is:
  ;;
  ;; o  The first token after bob.
  ;; o  The first token after the end of submatch 1 in
  ;;    `c-decl-prefix-or-start-re' when that submatch matches.
  ;; o  The start of each `c-decl-prefix-or-start-re' match when
  ;;    submatch 1 doesn't match.

  ;; If the match is inside a macro then the buffer is narrowed to the
  ;; end of it, so that CFD-FUN can investigate the following tokens
  ;; without matching something that begins inside a macro and ends
  ;; outside it.  It's to avoid this work that the CFD-DECL-RE and
  ;; CFD-FACE-CHECKLIST checks exist.
  ;;
  ;; CFD-FUN is called with point at the start of the spot.  It's
  ;; passed two arguments: The first is the end position of the token
  ;; preceding the spot, or 0 for the implicit match at bob.  The
  ;; second is a flag that is t when the match is inside a macro.  If
  ;; CFD-FUN adds `c-decl-end' properties somewhere below the current
  ;; spot, it should return non-nil to ensure that the next search
  ;; will find them.
  ;;
  ;; The spots are visited approximately in order from top to bottom.
  ;; It's however the positions where `c-decl-prefix-or-start-re'
  ;; matches and where `c-decl-end' properties are found that are in
  ;; order.  Since the spots often are at the following token, they

  ;; CONTEXT is a symbol that describes the context at the point:
  ;; 'decl     In a comma-separated declaration context (typically
  ;;           inside a function declaration arglist).
  ;; '<>       In an angle bracket arglist.
  ;; 'arglist  Some other type of arglist.
  ;; nil       Some other context or unknown context.
  ;;
  ;; LAST-CAST-END is the first token after the closing paren of a
  ;; preceding cast, or nil if none is known.  If
  ;; `c-forward-decl-or-cast-1' is used in succession, it should be
  ;; the position after the closest preceding call where a cast was

      (setq
       at-decl-or-cast
       (catch 'at-decl-or-cast

	(when (> paren-depth 0)
	  ;; Encountered something inside parens that isn't matched by
	  ;; the `c-type-decl-*' regexps, so it's not a type decl
	  ;; expression.  Try to skip out to the same paren depth to
	  ;; not confuse the cast check below.

	;; signs before less certain ones.

	(if got-identifier
	    (progn

	      (when (and (or at-type maybe-typeless)
			 (not (or got-prefix got-parens)))
		;; Got another identifier directly after the type, so it's a
		;; declaration.
		(throw 'at-decl-or-cast t))

	  ;; Found no identifier.

	  (if backup-at-type
	      (progn

		(when (= (point) start)
		  ;; Got a plain list of identifiers.  If a colon follows it's
		  ;; a valid label.  Otherwise the last one probably is the
		  ;; declared identifier and we should back up to the previous
		  ;; type, providing it isn't a cast.

		      ;; declaration regardless.
		      (throw 'at-decl-or-cast (eq at-decl-or-cast t))
		    (setq backup-if-not-cast t)
		    (throw 'at-decl-or-cast t)))

		(when (and got-suffix
			   (not got-prefix)
			   (not got-parens))
		  ;; Got a plain list of identifiers followed by some suffix.
		  ;; If this isn't a cast then the last identifier probably is
		  ;; the declared one and we should back up to the previous
		  ;; type.
		  (setq backup-if-not-cast t)
		  (throw 'at-decl-or-cast t)))

	    (when (eq at-type t)
	      ;; If the type is known we know that there can't be any
	      ;; identifier somewhere else, and it's only in declarations in
	      ;; e.g. function prototypes and in casts that the identifier may
	      ;; be left out.
	      (throw 'at-decl-or-cast t))

	    (when (= (point) start)
	      ;; Only got a single identifier (parsed as a type so far).
	      (if (and
		   ;; Check that the identifier isn't at the start of an
		   ;; expression.
		   at-decl-end
		   (cond

		     ;; Inside a template arglist.  Accept known and found
		     ;; types; other identifiers could just as well be
		     ;; constants in C++.
		     (memq at-type '(known found)))))
		  (throw 'at-decl-or-cast t)
		;; Can't be a valid declaration or cast, but if we've found a
		;; specifier it can't be anything else either, so treat it as
		;; an invalid/unfinished declaration or cast.
		(throw 'at-decl-or-cast at-decl-or-cast))))

	      ;; recognize it at all, so it's better to try it as an abstract
	      ;; declarator instead.
	      (c-fdoc-shift-type-backward)

	    ;; Still no identifier.

	    (when (and got-prefix (or got-parens got-suffix))
	      ;; Require `got-prefix' together with either `got-parens' or
	      ;; `got-suffix' to recognize it as an abstract declarator:
	      ;; `got-parens' only is probably an empty function call.
	      ;; `got-suffix' only can build an ordinary expression together

	      ;; easily occur temporarily while writing an expression so we
	      ;; avoid that case anyway.  We could do a better job if we knew
	      ;; the point when the fontification was invoked.
	      (throw 'at-decl-or-cast t))

	    (when (and at-type
		       (not got-prefix)
		       (not got-parens)
		       got-suffix-after-parens
		       (eq (char-after got-suffix-after-parens) ?\())
	      ;; Got a type, no declarator but a paren suffix. I.e. it's a
	      ;; normal function call afterall (or perhaps a C++ style object
	      ;; instantiation expression).
	      (throw 'at-decl-or-cast nil))))

	(when at-decl-or-cast
	  ;; By now we've located the type in the declaration that we know
	  ;; we're in.
	  (throw 'at-decl-or-cast t))

	(when (and got-identifier
		   (not context)
		   (looking-at c-after-suffixed-type-decl-key)
		   (if (and got-parens
			    (not got-prefix)

		       (progn (c-fdoc-shift-type-backward) t)
		     got-suffix-after-parens))
	  ;; A declaration according to `c-after-suffixed-type-decl-key'.
	  (throw 'at-decl-or-cast t))

	(when (and (or got-prefix (not got-parens))
		   (memq at-type '(t known)))
	  ;; It's a declaration if a known type precedes it and it can't be a
	  ;; function call.
	  (throw 'at-decl-or-cast t))

	  (throw 'at-decl-or-cast at-decl-or-cast))

	;; Below are tests that only should be applied when we're certain to
	;; not have parsed halfway through an expression.

	(when (memq at-type '(t known))
	  ;; The expression starts with a known type so treat it as a
	  ;; declaration.
	  (throw 'at-decl-or-cast t))

	(when (and (c-major-mode-is 'c++-mode)
		   ;; In C++ we check if the identifier is a known type, since
		   ;; (con|de)structors use the class name as identifier.
		   ;; We've always shifted over the identifier as a type and
		   ;; then backed up again in this case.

						       (point))))))))
	  (throw 'at-decl-or-cast t))

	(if got-identifier
	    (progn
	      (when (and got-prefix-before-parens
			 at-type
			 (or at-decl-end (looking-at "=[^=]"))
			 (not context)
			 (not got-suffix))

		;; result isn't used.  We therefore choose to recognize it as
		;; a declaration.  Do not allow a suffix since it could then
		;; be a function call.
		(throw 'at-decl-or-cast t))

	      (when (and (or got-suffix-after-parens
			     (looking-at "=[^=]"))
			 (eq at-type 'found)
			 (not (eq context 'arglist)))
		;; Got something like "a (*b) (c);" or "a (b) = c;".  It could
		;; be an odd expression or it could be a declaration.  Treat
		;; it as a declaration if "a" has been used as a type
		;; somewhere else (if it's a known type we won't get here).
		(throw 'at-decl-or-cast t)))

	  (when (and context
		     (or got-prefix
			 (and (eq context 'decl)
			      (not c-recognize-paren-inits)
			      (or got-parens got-suffix))))

	 (backward-up-list 1)
	 (c-beginning-of-statement-1 (point-min) nil t)
	 (looking-at c-opt-asm-stmt-key))))

(defun c-at-toplevel-p ()
  "Return a determination as to whether point is at the `top-level'.
Being at the top-level means that point is either outside any
enclosing block (such function definition), or only inside a class,
namespace or other block that contains another declaration level.

If point is not at the top-level (e.g. it is inside a method
definition), then nil is returned.  Otherwise, if point is at a
top-level not enclosed within a class definition, t is returned.
Otherwise, a 2-vector is returned where the zeroth element is the

	   ;; CASE 5D: this could be a top-level initialization, a
	   ;; member init list continuation, or a template argument
	   ;; list continuation.
	   ((save-excursion
	      ;; Note: We use the fact that lim always is after any
	      ;; preceding brace sexp.
	      (if c-recognize-<>-arglists
		  (while (and
			  (progn
			    (c-syntactic-skip-backward "^;,=<>" lim t)

98693:69a04789c5f0

  "Move to the start of the current statement or declaration, or to
the previous one if already at the beginning of one.  Only
statements/declarations on the same level are considered, i.e. don't
move into or out of sexps (not even normal expression parentheses).

If point is already at the earliest statment within braces or parens,
this function doesn't move back into any whitespace preceding it; it
returns 'same in this case.

Stop at statement continuation tokens like \"else\", \"catch\",
\"finally\" and the \"while\" in \"do ... while\" if the start point
is within the continuation.  If starting at such a token, move to the
corresponding statement start.  If at the beginning of a statement,
move to the closest containing statement if there is any.  This might

from any normal statement starts found in it, stop at the first token
of the content in the macro, i.e. the expression of an \"#if\" or the
start of the definition in a \"#define\".  Also stop at start of
macros before leaving them.

Return:
'label          if stopped at a label;
'same           if stopped at the beginning of the current statement;
'up             if stepped to a containing statement;
'previous       if stepped to a preceding statement;
'beginning      if stepped from a statement continuation clause to
                its start clause; or
'macro          if stepped to a macro start.
Note that 'same and not 'label is returned if stopped at the same
label without crossing the colon character.

LIM may be given to limit the search.  If the search hits the limit,
point will be left at the closest following token, or at the start
position if that is less ('same is returned in this case).

(defun c-beginning-of-current-token (&optional back-limit)
  ;; Move to the beginning of the current token.  Do not move if not
  ;; in the middle of one.  BACK-LIMIT may be used to bound the
  ;; backward search; if given it's assumed to be at the boundary
  ;; between two tokens.  Return non-nil if the point is moved, nil
  ;; otherwise.
  ;;
  ;; This function might do hidden buffer changes.
    (let ((start (point)))
      (if (looking-at "\\w\\|\\s_")

to start parsing from.  If NEAR is non-nil, then the limits of any
literal next to point is returned.  \"Next to\" means there's only
spaces and tabs between point and the literal.  The search for such a
literal is done first in forward direction.  If NOT-IN-DELIMITER is
non-nil, the case when point is inside a starting delimiter won't be
recognized.  This only has effect for comments which have starting
delimiters with more than one character.

Note that this function might do hidden buffer changes.  See the
comment at the start of cc-engine.el for more info."

	  range)
      (error range))))

(defun c-literal-type (range)
  "Convenience function that given the result of `c-literal-limits',
returns nil or the type of literal that the range surrounds, one
of the symbols 'c, 'c++ or 'string.  It's much faster than using
`c-in-literal' and is intended to be used when you need both the
type of a literal and its limits.

Note that this function might do hidden buffer changes.  See the
comment at the start of cc-engine.el for more info."

  (if (consp range)

				  (min cfd-prop-match (point))
				(point))))))

(defun c-find-decl-spots (cfd-limit cfd-decl-re cfd-face-checklist cfd-fun)
  ;; Call CFD-FUN for each possible spot for a declaration, cast or
  ;; label from the point to CFD-LIMIT.
  ;;
  ;; CFD-FUN is called with point at the start of the spot.  It's
  ;; passed two arguments: The first is the end position of the token
  ;; preceding the spot, or 0 for the implicit match at bob.  The
  ;; second is a flag that is t when the match is inside a macro.  If
  ;; CFD-FUN adds `c-decl-end' properties somewhere below the current
  ;; spot, it should return non-nil to ensure that the next search
  ;; will find them.
  ;;
  ;; Such a spot is:
  ;; o  The first token after bob.
  ;; o  The first token after the end of submatch 1 in
  ;;    `c-decl-prefix-or-start-re' when that submatch matches.
  ;; o  The start of each `c-decl-prefix-or-start-re' match when
  ;;    submatch 1 doesn't match.

  ;; If the match is inside a macro then the buffer is narrowed to the
  ;; end of it, so that CFD-FUN can investigate the following tokens
  ;; without matching something that begins inside a macro and ends
  ;; outside it.  It's to avoid this work that the CFD-DECL-RE and
  ;; CFD-FACE-CHECKLIST checks exist.
  ;;
  ;; The spots are visited approximately in order from top to bottom.
  ;; It's however the positions where `c-decl-prefix-or-start-re'
  ;; matches and where `c-decl-end' properties are found that are in
  ;; order.  Since the spots often are at the following token, they

  ;; CONTEXT is a symbol that describes the context at the point:
  ;; 'decl     In a comma-separated declaration context (typically
  ;;           inside a function declaration arglist).
  ;; '<>       In an angle bracket arglist.
  ;; 'arglist  Some other type of arglist.
  ;; nil       Some other context or unknown context.  Includes
  ;;           within the parens of an if, for, ... construct.
  ;;
  ;; LAST-CAST-END is the first token after the closing paren of a
  ;; preceding cast, or nil if none is known.  If
  ;; `c-forward-decl-or-cast-1' is used in succession, it should be
  ;; the position after the closest preceding call where a cast was

      (setq
       at-decl-or-cast
       (catch 'at-decl-or-cast

	 ;; CASE 1
	(when (> paren-depth 0)
	  ;; Encountered something inside parens that isn't matched by
	  ;; the `c-type-decl-*' regexps, so it's not a type decl
	  ;; expression.  Try to skip out to the same paren depth to
	  ;; not confuse the cast check below.

	;; signs before less certain ones.

	(if got-identifier
	    (progn

	      ;; CASE 2
	      (when (and (or at-type maybe-typeless)
			 (not (or got-prefix got-parens)))
		;; Got another identifier directly after the type, so it's a
		;; declaration.
		(throw 'at-decl-or-cast t))

	  ;; Found no identifier.

	  (if backup-at-type
	      (progn

		;; CASE 3
		(when (= (point) start)
		  ;; Got a plain list of identifiers.  If a colon follows it's
		  ;; a valid label.  Otherwise the last one probably is the
		  ;; declared identifier and we should back up to the previous
		  ;; type, providing it isn't a cast.

		      ;; declaration regardless.
		      (throw 'at-decl-or-cast (eq at-decl-or-cast t))
		    (setq backup-if-not-cast t)
		    (throw 'at-decl-or-cast t)))

		;; CASE 4
		(when (and got-suffix
			   (not got-prefix)
			   (not got-parens))
		  ;; Got a plain list of identifiers followed by some suffix.
		  ;; If this isn't a cast then the last identifier probably is
		  ;; the declared one and we should back up to the previous
		  ;; type.
		  (setq backup-if-not-cast t)
		  (throw 'at-decl-or-cast t)))

	    ;; CASE 5
	    (when (eq at-type t)
	      ;; If the type is known we know that there can't be any
	      ;; identifier somewhere else, and it's only in declarations in
	      ;; e.g. function prototypes and in casts that the identifier may
	      ;; be left out.
	      (throw 'at-decl-or-cast t))

	    (when (= (point) start)
	      ;; Only got a single identifier (parsed as a type so far).
	      ;; CASE 6
	      (if (and
		   ;; Check that the identifier isn't at the start of an
		   ;; expression.
		   at-decl-end
		   (cond

		     ;; Inside a template arglist.  Accept known and found
		     ;; types; other identifiers could just as well be
		     ;; constants in C++.
		     (memq at-type '(known found)))))
		  (throw 'at-decl-or-cast t)
		;; CASE 7
		;; Can't be a valid declaration or cast, but if we've found a
		;; specifier it can't be anything else either, so treat it as
		;; an invalid/unfinished declaration or cast.
		(throw 'at-decl-or-cast at-decl-or-cast))))

	      ;; recognize it at all, so it's better to try it as an abstract
	      ;; declarator instead.
	      (c-fdoc-shift-type-backward)

	    ;; Still no identifier.
	    ;; CASE 8
	    (when (and got-prefix (or got-parens got-suffix))
	      ;; Require `got-prefix' together with either `got-parens' or
	      ;; `got-suffix' to recognize it as an abstract declarator:
	      ;; `got-parens' only is probably an empty function call.
	      ;; `got-suffix' only can build an ordinary expression together

	      ;; easily occur temporarily while writing an expression so we
	      ;; avoid that case anyway.  We could do a better job if we knew
	      ;; the point when the fontification was invoked.
	      (throw 'at-decl-or-cast t))

	    ;; CASE 9
	    (when (and at-type
		       (not got-prefix)
		       (not got-parens)
		       got-suffix-after-parens
		       (eq (char-after got-suffix-after-parens) ?\())
	      ;; Got a type, no declarator but a paren suffix. I.e. it's a
	      ;; normal function call afterall (or perhaps a C++ style object
	      ;; instantiation expression).
	      (throw 'at-decl-or-cast nil))))

	;; CASE 10
	(when at-decl-or-cast
	  ;; By now we've located the type in the declaration that we know
	  ;; we're in.
	  (throw 'at-decl-or-cast t))

	;; CASE 11
	(when (and got-identifier
		   (not context)
		   (looking-at c-after-suffixed-type-decl-key)
		   (if (and got-parens
			    (not got-prefix)

		       (progn (c-fdoc-shift-type-backward) t)
		     got-suffix-after-parens))
	  ;; A declaration according to `c-after-suffixed-type-decl-key'.
	  (throw 'at-decl-or-cast t))

	;; CASE 12
	(when (and (or got-prefix (not got-parens))
		   (memq at-type '(t known)))
	  ;; It's a declaration if a known type precedes it and it can't be a
	  ;; function call.
	  (throw 'at-decl-or-cast t))

	  (throw 'at-decl-or-cast at-decl-or-cast))

	;; Below are tests that only should be applied when we're certain to
	;; not have parsed halfway through an expression.

	;; CASE 14
	(when (memq at-type '(t known))
	  ;; The expression starts with a known type so treat it as a
	  ;; declaration.
	  (throw 'at-decl-or-cast t))

	;; CASE 15
	(when (and (c-major-mode-is 'c++-mode)
		   ;; In C++ we check if the identifier is a known type, since
		   ;; (con|de)structors use the class name as identifier.
		   ;; We've always shifted over the identifier as a type and
		   ;; then backed up again in this case.

						       (point))))))))
	  (throw 'at-decl-or-cast t))

	(if got-identifier
	    (progn
	      ;; CASE 16
	      (when (and got-prefix-before-parens
			 at-type
			 (or at-decl-end (looking-at "=[^=]"))
			 (not context)
			 (not got-suffix))

		;; result isn't used.  We therefore choose to recognize it as
		;; a declaration.  Do not allow a suffix since it could then
		;; be a function call.
		(throw 'at-decl-or-cast t))

	      ;; CASE 17
	      (when (and (or got-suffix-after-parens
			     (looking-at "=[^=]"))
			 (eq at-type 'found)
			 (not (eq context 'arglist)))
		;; Got something like "a (*b) (c);" or "a (b) = c;".  It could
		;; be an odd expression or it could be a declaration.  Treat
		;; it as a declaration if "a" has been used as a type
		;; somewhere else (if it's a known type we won't get here).
		(throw 'at-decl-or-cast t)))

	  ;; CASE 18
	  (when (and context
		     (or got-prefix
			 (and (eq context 'decl)
			      (not c-recognize-paren-inits)
			      (or got-parens got-suffix))))

	 (backward-up-list 1)
	 (c-beginning-of-statement-1 (point-min) nil t)
	 (looking-at c-opt-asm-stmt-key))))

(defun c-at-toplevel-p ()
  "Return a determination as to whether point is \"at the top level\".
Informally, \"at the top level\" is anywhere where you can write
a function.

More precisely, being at the top-level means that point is either
outside any enclosing block (such as a function definition), or
directly inside a class, namespace or other block that contains
another declaration level.

If point is not at the top-level (e.g. it is inside a method
definition), then nil is returned.  Otherwise, if point is at a
top-level not enclosed within a class definition, t is returned.
Otherwise, a 2-vector is returned where the zeroth element is the

	   ;; CASE 5D: this could be a top-level initialization, a
	   ;; member init list continuation, or a template argument
	   ;; list continuation.
	   ((save-excursion
	      ;; Note: We use the fact that lim is always after any
	      ;; preceding brace sexp.
	      (if c-recognize-<>-arglists
		  (while (and
			  (progn
			    (c-syntactic-skip-backward "^;,=<>" lim t)