File: cc-engine.el.html
The functions which have docstring documentation can be considered part of an API which other packages can use in CC Mode buffers. Otoh, undocumented functions and functions with the documentation in comments are considered purely internal and can change semantics or even disappear in the future.
(This policy applies to CC Mode as a whole, not just this file. It
probably also applies to many other Emacs packages, but here it's
clearly spelled out.)
Hidden buffer changes
Various functions in CC Mode use text properties for caching and
syntactic markup purposes, and those of them that might modify such
properties but still don't modify the buffer in a visible way are
said to do "hidden buffer changes". They should be used within
c-save-buffer-state or a similar function that saves and restores
buffer modifiedness, disables buffer change hooks, etc.
Interactive functions are assumed to not do hidden buffer changes, except in the specific parts of them that do real changes.
Lineup functions are assumed to do hidden buffer changes. They must not do real changes, though.
All other functions that do hidden buffer changes have that noted in their doc string or comment.
The intention with this system is to avoid wrapping every leaf
function that do hidden buffer changes inside
c-save-buffer-state. It should be used as near the top of the
interactive functions as possible.
Functions called during font locking are allowed to do hidden
buffer changes since the font-lock package run them in a context
similar to c-save-buffer-state (in fact, that function is heavily
inspired by save-buffer-state in the font-lock package).
Use of text properties
CC Mode uses several text properties internally to mark up various positions, e.g. to improve speed and to eliminate glitches in interactive refontification.
Note: This doc is for internal use only. Other packages should not assume that these text properties are used as described here.
'category
Used for "indirection". With its help, some other property can
be cheaply and easily switched on or off everywhere it occurs.
'syntax-table
Used to modify the syntax of some characters. It is used to
mark the "<" and ">" of angle bracket parens with paren syntax, to
"hide" obtrusive characters in preprocessor lines, and to mark C++
raw strings to enable their fontification.
This property is used on single characters and is therefore
always treated as front and rear nonsticky (or start and end open
in XEmacs vocabulary). It's therefore installed on
text-property-default-nonsticky if that variable exists (Emacs
>= 21).
'c-fl-syn-tab
Saves the value of syntax-table properties which have been
temporarily removed from certain buffer positions. The syntax-table
properties are restored during c-before-change, c-after-change, and
font locking. The purpose of the temporary removal is to enable
C-M-* key sequences to operate over bogus pairs of string delimiters
which are "adjacent", yet do not delimit a string.
'c-is-sws and 'c-in-sws
Used by c-forward-syntactic-ws and c-backward-syntactic-ws to
speed them up. See the comment blurb before c-put-is-sws
below for further details.
'c-type
This property is used on single characters to mark positions with
special syntactic relevance of various sorts. Its primary use is
to avoid glitches when multiline constructs are refontified
interactively (on font lock decoration level 3). It's cleared in
a region before it's fontified and is then put on relevant chars
in that region as they are encountered during the fontification.
The value specifies the kind of position:
'c-decl-arg-start
Put on the last char of the token preceding each declaration
inside a declaration style arglist (typically in a function
prototype).
'c-decl-end
Put on the last char of the token preceding a declaration.
This is used in cases where declaration boundaries can't be
recognized simply by looking for a token like ";" or "}".
c-type-decl-end-used must be set if this is used (see also
c-find-decl-spots).
'c-<>-arg-sep
Put on the commas that separate arguments in angle bracket
arglists like C++ template arglists.
'c-decl-id-start and 'c-decl-type-start
Put on the last char of the token preceding each declarator
in the declarator list of a declaration. They are also used
between the identifiers cases like enum declarations.
'c-decl-type-start is used when the declarators are types,
'c-decl-id-start otherwise.
'c-not-decl
Put on the brace which introduces a brace list and on the commas
which separate the elements within it.
'c-typedef This property is applied to the first character of a
"typedef" keyword. It's value is a list of the identifiers that
the "typedef" declares as types.
'c-<>-c-types-set
This property is set on an opening angle bracket, and indicates that
any "," separators within the template/generic expression have been
marked with a 'c-type property value 'c-<>-arg-sep (see above).
'c-awk-NL-prop
Used in AWK mode to mark the various kinds of newlines. See
cc-awk.el.
Defined variables (78)
c-<-pseudo-digraph-cont-len | The maximum length of the main bit of a ‘c-<-pseudo-digraph-cont-regexp’ match. |
c-<-pseudo-digraph-cont-regexp | Regexp matching the continuation of a pseudo digraph starting "<". |
c-<>-notable-chars-re | A regexp matching any single character notable inside a <...> construct. |
c-anchored-cpp-prefix | Regexp matching the prefix of a cpp directive anchored to BOL, |
c-at-vsemi-p-fn | Contains a function "Is there a virtual semicolon at POS or point?". |
c-before-context-fontification-functions | If non-nil, a list of functions called just before context (or |
c-before-font-lock-functions | If non-nil, a list of functions called just before font locking. |
c-block-comment-awkward-chars | List of characters which, inside a block comment, could be the first |
c-block-comment-ender | String that ends block comments, or nil if such don’t exist. |
c-block-comment-is-default | Non-nil when the default comment style is block comment. |
c-block-comment-starter | String that starts block comments, or nil if such don’t exist. |
c-colon-type-list-re | Regexp matched after the keywords in ‘c-colon-type-list-kwds’ to skip |
c-cpp-expr-intro-re | Regexp which matches the start of a CPP directive which contains an |
c-decl-start-colon-kwd-re | Regexp matching a keyword that is followed by a colon, where |
c-decl-start-re | Regexp matching the start of any declaration, cast or label. |
c-doc-comment-start-regexp | Regexp to match the start of documentation comments. |
c-enums-contain-decls | Non-nil means that an enum structure can contain declarations. |
c-get-state-before-change-functions | If non-nil, a list of functions called from c-before-change-hook. |
c-has-bitfields | Whether the language has bitfield declarations. |
c-has-compound-literals | Whether literal initializers {...} are used other than in initializations. |
c-has-quoted-numbers | Whether the language has numbers quoted like 4’294’967’295. |
c-identifier-key | Regexp matching a fully qualified identifier, like "A::B::c" in |
c-identifier-start | Regexp that matches the start of an (optionally qualified) identifier. |
c-identifier-syntax-modifications | A list that describes the modifications that should be done to the |
c-identifier-syntax-table | Syntax table built on the mode syntax table but additionally |
c-label-prefix-re | Regexp like ‘c-decl-prefix-re’ that matches any token that can precede |
c-last-c-comment-end-on-line-re | Regexp which matches the last block comment ender on the |
c-line-comment-starter | String that starts line comments, or nil if such don’t exist. |
c-make-ml-string-closer-re-function | If non-nil, a function which creates a closer regexp matching an opener. |
c-make-ml-string-opener-re-function | If non-nil, a function which creates an opener regexp matching a closer. |
c-maybe-decl-faces | List of faces that might be put at the start of a type when |
c-maybe-typeless-specifier-re | Regexp matching keywords which might, but needn’t, declare variables with |
c-ml-string-any-closer-re | If non-nil, a regexp that matches any multi-line string closer. |
c-ml-string-back-closer-re | A regexp to move back out of a putative ml closer point is in. |
c-ml-string-max-closer-len | If non-nil, the maximum length of a multi-line string closer. |
c-ml-string-max-closer-len-no-leader | If non-nil, the maximum length of a ml string closer without its leader. |
c-ml-string-max-opener-len | If non-nil, the maximum length of a multi-line string opener. |
c-ml-string-opener-re | If non-nil, a regexp that matches a multi-line string opener. |
c-modified-constant | Regexp that matches a “modified” constant literal such as "L'a'", |
c-module-name-re | This regexp matches (a component of) a module name. |
c-multiline-string-start-char | Set if the language supports multiline string literals without escaped |
c-nonlabel-nonparen-token-key | Regexp matching things that can’t occur in generic colon labels, |
c-nonlabel-token-2-key | Regexp matching things that can’t occur two symbols before a colon in |
c-nonlabel-token-key | Regexp matching things that can’t occur in generic colon labels, |
c-nonsymbol-chars | This is the set of chars that can’t be part of a symbol, i.e. the |
c-nonsymbol-key | Regexp that matches any character that can’t be part of a symbol. |
c-opt-cpp-macro-define | Cpp directive (without the prefix) that is followed by a macro |
c-opt-cpp-prefix | Regexp matching the prefix of a cpp directive in the languages that |
c-opt-cpp-start | Regexp matching the prefix of a cpp directive including the directive |
c-opt-cpp-symbol | The symbol which starts preprocessor constructs when in the margin. |
c-opt-extra-label-key | Optional regexp matching labels. |
c-opt-op-identifier-prefix | Regexp matching the token before the ones in |
c-opt-type-suffix-key | Regexp matching operators that might follow after a type, or nil in |
c-other-decl-block-key-in-symbols-alist | Alist associating keywords in c-other-decl-block-decl-kwds with |
c-paragraph-separate | Regexp to append to ‘paragraph-separate’. |
c-paragraph-start | Regexp to append to ‘paragraph-start’. |
c-post-protection-token | The token which (may) follow a protection keyword, |
c-pre-brace-non-bracelist-key | A regexp matching tokens which, preceding a brace, make it a non-bracelist. |
c-pre-start-tokens | List of operators following which an apparent declaration (e.g. |
c-recognize-<>-arglists | Non-nil means C++ style template arglists should be handled. More |
c-recognize-bare-brace-inits | Non-nil means that brace initializers without "=" exist, |
c-recognize-colon-labels | Non-nil if generic labels ending with ":" should be recognized. |
c-recognize-knr-p | Non-nil means K&R style argument declarations are valid. |
c-recognize-paren-inexpr-blocks | Non-nil to recognize gcc style in-expression blocks, |
c-recognize-paren-inits | Non-nil means that parenthesis style initializers exist, |
c-recognize-post-brace-list-type-p | Set to t when we recognize a colon and then a type after an enum, |
c-recognize-typeless-decls | Non-nil means function declarations without return type should be |
c-single-quotes-quote-strings | Whether the language uses single quotes for multi-char strings. |
c-special-brace-lists | List of open- and close-chars that makes up a pike-style brace list, |
c-std-abbrev-keywords | List of keywords which may need to cause electric indentation. |
c-string-escaped-newlines | Set if the language support backslash escaped newlines inside string |
c-sub-colon-type-list-re | Regexp matching buffer content that may come between a keyword in |
c-symbol-char-key | Regexp matching a sequence of at least one identifier character. |
c-symbol-chars | Set of characters that can be part of a symbol. |
c-symbol-key | Regexp matching identifiers and keywords (with submatch 0). Assumed |
c-symbol-start | Regexp that matches the start of a symbol, i.e. any identifier or |
c-type-decl-operator-prefix-key | Regexp matching any declarator operator which isn’t a keyword, |
c-vsemi-status-unknown-p-fn | A function "are we unsure whether there is a virtual semicolon on this line?". |