[SCM] GNU Autoconf source repository branch, master, updated. v2.63-210-g644adb9

[Eric Blake]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Autoconf source repository".

http://git.sv.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=644adb9065b1f2521bc46f8ee4b3c13021ddae51

The branch, master has been updated
       via  644adb9065b1f2521bc46f8ee4b3c13021ddae51 (commit)
      from  0a144bc25ecb4dba3d9ee3a7200257a91a059096 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 644adb9065b1f2521bc46f8ee4b3c13021ddae51
Author: Eric Blake <address@hidden>
Date:   Thu Nov 20 14:29:58 2008 -0700

    Describe different hacks for balancing ')' in case statements.
    
    * doc/autoconf.texi (Limitations of Builtins) <case>: Add an
    exposition on various quoting styles.
    
    Signed-off-by: Eric Blake <address@hidden>

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog         |    6 +++
 doc/autoconf.texi |  109 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 109 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 22c98d0..1d5fbf5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2008-11-20  Eric Blake  <address@hidden>
 
+       Describe different hacks for balancing ')' in case statements.
+       * doc/autoconf.texi (Limitations of Builtins) <case>: Add an
+       exposition on various quoting styles.
+
+2008-11-20  Eric Blake  <address@hidden>
+
        Speed up _AS_QUOTE.
        * lib/m4sugar/m4sh.m4 (_AS_QUOTE_IFELSE): Inline into...
        (_AS_QUOTE): ...here, delete unused second paramenter, and factor
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index f06a545..db3f7cc 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -14873,16 +14873,113 @@ $ @kbd{case foo in (foo) echo foo;; esac}
 @end example
 
 @noindent
-The leading @samp{(} can be omitted safely.  In contexts where
-unbalanced parentheses cause other problems, such as when using a case
-statement as an argument to an Autoconf macro, you can also resort to
-creative shell comments to supply the balance:
address@hidden balancing parentheses
address@hidden parentheses, balancing
+The leading @samp{(} can be omitted safely.  Unfortunately, there are
+contexts where unbalanced parentheses cause other problems, such as when
+using a syntax-highlighting editor that searches for the balancing
+counterpart, or more importantly, when using a case statement as an
+underquoted argument to an Autoconf macro:
 
 @example
-case $file_name in #(
+AC_DEFUN([my_case],
+[case $file_name in
   *.c) echo "C source code";;
-esac
+esac])
+AS_IF(:, my_case)
address@hidden example
+
address@hidden
+In the above example, the unbalanced @samp{)} in the premature expansion
+of @code{my_case} results in expanding @code{AS_IF} with a truncated
+parameter, and the expansion is syntactically invalid:
+
address@hidden
+if :; then
+  case $file_name in
+  *.c
+fi echo "C source code";;
+esac)
address@hidden example
+
address@hidden
+If nothing else, this should emphasize the importance of the quoting
+rule of thumb (@pxref{Quotation Rule Of Thumb}), that you should single
+quote all macro arguments that might be re-expanded, and double-quote
+macro arguments that are literal text.  On the other hand, there are
+several variations for defining @code{my_case} to be more robust, each
+with some benefits and some drawbacks.
+
address@hidden @asis
address@hidden Creative literal shell comment
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in #(
+  *.c) echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version provides balanced parentheses to several editors, and can
+be copied and pasted into a terminal as is.  Unfortunately, it is still
+unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
+that masks the normal properties of @samp{(}.
+
address@hidden Quadrigraph shell comment
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in @@%:@@(
+  *.c) echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version provides balanced parentheses to even more editors, and can
+be used as a balanced Autoconf argument.  Unfortunately, it requires
+some editing before it can be copied and pasted into a terminal, and the
+use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
+
address@hidden Quoting just the parenthesis
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in
+  *.c[)] echo "C source code";;
+esac])
 @end example
address@hidden
+This version quotes the @samp{)}, so that it can be used as a balanced
+Autoconf argument.  As written, this is not balanced to an editor, but
+it can be coupled with @samp{[#(]} to meet that need, too.  However, it
+still requires some edits before it can be copied and pasted into a
+terminal.
+
address@hidden Double-quoting the entire statement
address@hidden
+AC_DEFUN([my_case],
+[[case $file_name in #(
+  *.c) echo "C source code";;
+esac]])
address@hidden example
address@hidden
+Since the entire macro is double-quoted, there is no problem with using
+this as an Autoconf argument; and since the double-quoting is over the
+entire statement, this code can be easily copied and pasted into a
+terminal.  However, the double quoting prevents the expansion of any
+macros inside the case statement, which may cause its own set of
+problems.
+
address@hidden Using @code{AS_CASE}
address@hidden
+AC_DEFUN([my_case],
+[AS_CASE([$file_name],
+  [*.c], [echo "C source code"])])
address@hidden example
address@hidden
+This version avoids the balancing issue altogether, by relying on
address@hidden (@pxref{Common Shell Constructs}); it also allows for the
+expansion of @code{AC_REQUIRE} to occur prior to the entire case
+statement, rather than within a branch of the case statement that might
+not be taken.  However, the abstraction comes with a penalty that it is
+no longer a quick copy, paste, and edit to get back to shell code.
address@hidden table
 
 Zsh handles pattern fragments derived from parameter expansions or
 command substitutions as though quoted:


hooks/post-receive
--
GNU Autoconf source repository