case statement style (was: fewer forks in AC_DEFINE)

[Eric Blake]

Eric Blake <ebb9 <at> byu.net> writes:

> 
> Just because m4_expand can handle #( doesn't mean that other macros can;
> you still have a bug if you do:
> 
> 
> So, I will reword this paragraph to mention all of the possibilities, each
> with their strengths and drawbacks.

I'm committing this independently from the patch that makes m4_expand tolerate 
unbalanced ')'.

Oh, and for the record, you can still do:

m4_expand([[(]])

to get unbalanced '(' without sending the parser off the deep end (and the 
bison test suite does just that).  It is only single-quoted '(' that the new 
m4_expand algorithm doesn't cater to.  Technically, I think I could even manage 
that: when $4 is not the marker, then m4_index([$3], [}>=-]) should determine 
whether the marker appears in $3 (excess '(', use m4_substr) or not 
(excess ')', recurse with one more '('), but I didn't the bulk-to-benefit ratio 
was nearly as high as it was for case statements.


From: Eric Blake <address@hidden>
Date: Thu, 20 Nov 2008 14:29:58 -0700
Subject: [PATCH] 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>
---
 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 @@ Limitations of Builtins
 @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:
-- 
1.6.0.4