From 536610a433e6edc0b3f831272c4e0424ebebee46 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Thu, 27 Oct 2011 20:34:23 +0000 Subject: Amend to indent and fontify macros "which include their own semicolon" correctly, using the "virtual semicolon" mechanism. cc-defs.el: Update "virtual semicolon" comments. cc-engine.el (c-crosses-statement-barrier-p): Recoded to scan one line at at time rather than having \n and \r explicitly in c-stmt-delim-chars (for some modes, e.g. AWK). (c-forward-label): Amend for virtual semicolons. (c-at-macro-vsemi-p, c-macro-vsemi-status-unknown-p): New functions cc-fonts.el (c-font-lock-declarations): Take account of the new C macros. cc-langs.el (c-at-vsemi-p-fn, c-vsemi-status-unknown-p-fn): move to earlier in the file. (c-opt-cpp-symbol, c-line-comment-start-regexp): New language variables. (c-opt-cpp-macro-define): Make into a full language variable. (c-stmt-delim-chars, c-stmt-delim-chars-with-comma): Special value for AWK Mode (including \n, \r) removed, no longer needed. cc-mode.el (c-mode, c++-mode, objc-mode): Invoke c-make-macro-with-semi-re. cc-vars.el (c-macro-with-semi-re, c-macro-names-with-semicolon): New variables. (c-make-macro-with-semi-re): New function cc-mode.texi (Indentation Commands): Mention "macros with semicolons". (Other Special Indentations): Add an xref to "Macros with ;". (Customizing Macros): Add stuff about syntax in macros. Add an xref to "Macros with ;". (Macros with ;): New page. --- doc/misc/cc-mode.texi | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) (limited to 'doc/misc') diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index a9339162666..4cc7f351c2e 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -341,6 +341,11 @@ Line-Up Functions * Comment Line-Up:: * Misc Line-Up:: +Customizing Macros + +* Macro Backslashes:: +* Macros with ;:: + @end detailmenu @end menu @@ -655,6 +660,10 @@ expression, to some statements, or perhaps to whole functions, the syntactic recognition can be wrong. @ccmode{} manages to figure it out correctly most of the time, though. +Some macros, when invoked, ''have their own semicolon''. To get the +next line indented correctly, rather than as a continuation line, +@xref{Macros with ;}. + Reindenting large sections of code can take a long time. When @ccmode{} reindents a region of code, it is essentially equivalent to hitting @key{TAB} on every line of the region. @@ -6550,6 +6559,9 @@ custom line-up function associated with it. @section Other Special Indentations @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +To configure macros which you invoke without a terminating @samp{;}, +see @xref{Macros with ;}. + Here are the remaining odds and ends regarding indentation: @defopt c-label-minimum-indentation @@ -6601,6 +6613,13 @@ functions to this hook, not remove them. @xref{Style Variables}. @cindex preprocessor directives @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +Preprocessor macros in C, C++, and Objective C (introduced by +@code{#define}) have a syntax different from the main language---for +example, a macro declaration is not terminated by a semicolon, and if +it is more than a line long, line breaks in it must be escaped with +backslashes. @ccmode{} has some commands to manipulate these, see +@ref{Macro Backslashes}. + Normally, the lines in a multi-line macro are indented relative to each other as though they were code. You can suppress this behavior by setting the following user option: @@ -6612,6 +6631,28 @@ is @code{nil}, all lines inside macro definitions are analyzed as @code{cpp-macro-cont}. @end defopt +Because a macro can expand into anything at all, near where one is +invoked @ccmode{} can only indent and fontify code heuristically. +Sometimes it gets it wrong. Usually you should try to design your +macros so that they ''look like ordinary code'' when you invoke them. +However, one situation is so common that @ccmode{} handles it +specially: that is when certain macros needn't (or mustn't) be +followed by a @samp{;}. You need to configure @ccmode{} to handle +these macros properly, see @ref{Macros with ;}. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@menu +* Macro Backslashes:: +* Macros with ;:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros +@comment node-name, next, previous, up +@section Customizing Macro Backslashes +@cindex #define +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @ccmode{} provides some tools to help keep the line continuation backslashes in macros neat and tidy. Their precise action is customized with these variables: @@ -6653,6 +6694,62 @@ get aligned only when you explicitly invoke the command @code{c-backslash-region} (@kbd{C-c C-\}). @end defopt +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Macros with ;, , Macro Backslashes, Custom Macros +@comment node-name, next, previous, up +@section Macros with semicolons +@cindex macros with semicolons +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +Macros which needn't (or mustn't) be followed by a semicolon when you +invoke them, @dfn{macros with semicolons}, are very common. These can +cause @ccmode{} to parse the next line wrongly as a +@code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent +it. + +You can prevent this by specifying which macros have semicolons. It +doesn't matter whether or not such a macro has a parameter list: + +@defopt c-macro-names-with-semicolon +@vindex macro-names-with-semicolon (c-) +This buffer-local variable specifies which macros have semicolons. +After setting its value, you need to call +@code{c-make-macro-with-semi-re} for it to take effect. It should be +set to one of these values: + +@table @asis +@item nil +There are no macros with semicolons. +@item a list of strings +Each string is the name of a macro with a semicolon. Only valid +@code{#define} names are allowed here. For example, to set the +default value, you could write the following into your @file{.emacs}: + +@example +(setq c-macro-names-with-semicolon + '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS")) +@end example + +@item a regular expression +This matches each symbol which is a macro with a semicolon. It must +not match any string which isn't a valid @code{#define} name. For +example: + +@example +(setq c-macro-names-with-semicolon + "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>") +@end example +@end table +@end defopt + +@defun c-make-macro-with-semi-re +@findex make-macro-with-semi-re (c-) +Call this (non-interactive) function, which sets internal variables, +each time you change the value of +@code{c-macro-names-with-semicolon}. It takes no arguments, and its +return value has no meaning. This function is called by @ccmode{}'s +initialization code. +@end defun + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Odds and Ends, Sample .emacs File, Custom Macros, Top @comment node-name, next, previous, up -- cgit v1.2.1 From 020716e178cdae443a3630c4307023cb3fc4c350 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Fri, 28 Oct 2011 14:34:39 +0000 Subject: DTRT for c-beginning/end-of-defun in nested declaration scopes. --- doc/misc/cc-mode.texi | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'doc/misc') diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index a9339162666..8818904982b 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -882,6 +882,8 @@ lines. @itemx @kbd{C-M-e} (@code{c-end-of-defun}) @findex c-beginning-of-defun @findex c-end-of-defun +@vindex c-defun-tactic +@vindex defun-tactic (c-) Move to the beginning or end of the current or next function. Other constructs (such as a structs or classes) which have a brace block @@ -895,6 +897,15 @@ commands try to leave point at the beginning of a line near the actual start or end of the function. This occasionally causes point not to move at all. +By default, these commands will recognize functions contained within a +@dfn{declaration scope} such as a C++ @code{class} or @code{namespace} +construct, should the point start inside it. If @ccmode fails to find +function beginnings or ends inside the current declaration scope, it +will search the enclosing scopes. If you want @ccmode to recognize +functions only at the top level@footnote{this was @ccmode{}'s +behaviour prior to version 5.32.}, set @code{c-defun-tatic} to +@code{t}. + These functions are analogous to the Emacs built-in commands @code{beginning-of-defun} and @code{end-of-defun}, except they eliminate the constraint that the top-level opening brace of the defun -- cgit v1.2.1 From 52bedd34385bf6434d60d884b306e5883fb656d9 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Fri, 28 Oct 2011 16:16:02 +0000 Subject: Increment c-version to 5.32.2. --- doc/misc/ChangeLog | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc/misc') diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 6b0ef9c5d8b..10a0d5e7a91 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,15 @@ +2011-10-28 Alan Mackenzie + + * cc-mode.texi (Indentation Commands): Mention "macros with semicolons". + (Other Special Indentations): Add an xref to "Macros with ;". + (Customizing Macros): Add stuff about syntax in macros. Add an xref to + "Macros with ;". + (Macros with ;): New page. + + * progmodes/cc-mode.texi (Movement Commands): Document + `c-defun-tactic'. Document the new handling of nested scopes for + movement by defuns. + 2011-10-23 Michael Albinus Sync with Tramp 2.2.3. -- cgit v1.2.1