Re: case statement style

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 11/21/2008 6:01 AM:
>> Shouldn't this exposition be in the "Programming in M4*" chapters
>> somewhere, with a suitable pointer from the 'expr' description?
> 
> You meant a pointer from the 'case' description, but yes, your point makes
> sense.  I'll move the exposition closer to the "Quoting Rule Of Thumb" node.

Done as follows, plus a followup that makes the cross-references into the
two Limitations nodes a bit more direct.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkkmvjMACgkQ84KuGfSFAYAutQCff9wzCja6pemPgEDrtndkBydi
0X0AoL1u5ZnSB+OzZyRw3a1CPEAGxwMa
=lNdj
-----END PGP SIGNATURE-----

>From 54dd8a93795219ca8e51bb58963be5ea64e48d34 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Fri, 21 Nov 2008 06:35:35 -0700
Subject: [PATCH] Move case statement style discussion to m4 quoting section.

* doc/autoconf.texi (Limitations of Builtins): Move comparison of
quoting styles...
(Balancing Parentheses): ...to this new node.
Suggested by Ralf Wildenhues.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |    8 ++
 doc/autoconf.texi |  228 +++++++++++++++++++++++++++++------------------------
 2 files changed, 133 insertions(+), 103 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8381688..2ab1757 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2008-11-21  Eric Blake  <address@hidden>
+
+       Move case statement style discussion to m4 quoting section.
+       * doc/autoconf.texi (Limitations of Builtins): Move comparison of
+       quoting styles...
+       (Balancing Parentheses): ...to this new node.
+       Suggested by Ralf Wildenhues.
+
 2008-11-20  Eric Blake  <address@hidden>
 
        Factor more common code out of AT_CHECK into shell function.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 7a154b7..b3628fb 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -445,6 +445,7 @@ Top
 * Quotation and Nested Macros::  Macros calling macros
 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
 * Quadrigraphs::                Another way to escape special characters
+* Balancing Parentheses::       Dealing with unbalanced parentheses
 * Quotation Rule Of Thumb::     One parenthesis, one quote
 
 Using @command{autom4te}
@@ -9292,6 +9293,7 @@ M4 Quotation
 * Quotation and Nested Macros::  Macros calling macros
 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
 * Quadrigraphs::                Another way to escape special characters
+* Balancing Parentheses::       Dealing with unbalanced parentheses
 * Quotation Rule Of Thumb::     One parenthesis, one quote
 @end menu
 
@@ -9778,6 +9780,126 @@ Quadrigraphs
 Cambridge University computer lab at the time.
 @end quotation
 
+
address@hidden Balancing Parentheses
address@hidden Dealing with unbalanced parentheses
address@hidden balancing parentheses
address@hidden parentheses, balancing
address@hidden unbalanced parentheses, managing
+
+One of the pitfalls of portable shell programming is that @command{case}
+statements require unbalanced parentheses (@pxref{Limitations of
+Builtins, , Limitations of Shell Builtins}).  With syntax highlighting
+editors, the presence of unbalanced @samp{)} can interfere with editors
+that perform syntax highlighting of macro contents based on finding the
+matching @samp{(}.  Another concern is how much editing must be done
+when transferring code snippets between shell scripts and macro
+definitions.  But most importantly, the presence of unbalanced
+parentheses can introduce expansion bugs.
+
+For an example, here is an underquoted attempt to use the macro
address@hidden, which happens to expand to a portable @command{case}
+statement:
+
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in
+  *.c) echo "C source code";;
+esac])
+AS_IF(:, my_case)
address@hidden example
+
address@hidden
+In the above example, the @code{AS_IF} call underquotes its arguments.
+As a result, the unbalanced @samp{)} generated by 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
+
+If nothing else, this should emphasize the importance of the quoting
+arguments to macro calls.  On the other hand, there are several
+variations for defining @code{my_case} to be more robust, even when used
+without proper quoting, 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])
address@hidden 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 itemize
+
+
 @node Quotation Rule Of Thumb
 @subsection Quotation Rule Of Thumb
 
@@ -14901,113 +15023,13 @@ Limitations of Builtins
 @end example
 
 @noindent
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:
-
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in
-  *.c) echo "C source code";;
-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])
address@hidden 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
+underquoted argument to an Autoconf macro.  @xref{Balancing
+Parentheses}, for tradeoffs involved in various styles of dealing with
+unbalanced @samp{)}.
 
 Zsh handles pattern fragments derived from parameter expansions or
 command substitutions as though quoted:
-- 
1.6.0.4


>From 26ba3d53187631bd8febe617a957df5063ed2fe6 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Fri, 21 Nov 2008 06:54:51 -0700
Subject: [PATCH] Add @anchors within Builtins and Usual Tools lists.

* doc/autoconf.texi (Limitations of Builtins)
(Limitatations of Usual Tools): Add anchors for tools called out
by name.  Adjust callers to narrow in on tool of interest.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |    5 ++++
 doc/autoconf.texi |   58 +++++++++++++++++++++++++++++++++-------------------
 2 files changed, 42 insertions(+), 21 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 2ab1757..a1b8a46 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2008-11-21  Eric Blake  <address@hidden>
 
+       Add @anchors within Builtins and Usual Tools lists.
+       * doc/autoconf.texi (Limitations of Builtins)
+       (Limitatations of Usual Tools): Add anchors for tools called out
+       by name.  Adjust callers to narrow in on tool of interest.
+
        Move case statement style discussion to m4 quoting section.
        * doc/autoconf.texi (Limitations of Builtins): Move comparison of
        quoting styles...
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index b3628fb..e5e2b3a 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -2958,7 +2958,8 @@ Automatic Remaking
 recompilation.  You should include the file @file{stamp-h.in} your
 package's distribution, so that @command{make} considers
 @file{config.h.in} up to date.  Don't use @command{touch}
-(@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
+(@pxref{touch, , Limitations of Usual Tools}); instead, use
address@hidden (using
 @command{date} would cause needless differences, hence @acronym{CVS}
 conflicts, etc.).
 
@@ -3768,7 +3769,7 @@ Particular Programs
 Look for the best available @code{grep} or @code{ggrep} that accepts the
 longest input lines possible, and that supports multiple @option{-e} options.
 Set the output variable @code{GREP} to whatever is chosen.
address@hidden of Usual Tools}, for more information about
address@hidden, , Limitations of Usual Tools}, for more information about
 portability problems with the @command{grep} command family.
 @end defmac
 
@@ -3951,7 +3952,7 @@ Particular Programs
 @ovindex SED
 Set output variable @code{SED} to a Sed implementation that conforms to
 Posix and does not have arbitrary length limits.  Report an error if no
-acceptable Sed is found.  @xref{Limitations of Usual Tools}, for more
+acceptable Sed is found.  @xref{sed, , Limitations of Usual Tools}, for more
 information about portability problems with Sed.
 @end defmac
 
@@ -9788,8 +9789,8 @@ Balancing Parentheses
 @cindex unbalanced parentheses, managing
 
 One of the pitfalls of portable shell programming is that @command{case}
-statements require unbalanced parentheses (@pxref{Limitations of
-Builtins, , Limitations of Shell Builtins}).  With syntax highlighting
+statements require unbalanced parentheses (@pxref{case, , Limitations of
+Shell Builtins}).  With syntax highlighting
 editors, the presence of unbalanced @samp{)} can interfere with editors
 that perform syntax highlighting of macro contents based on finding the
 matching @samp{(}.  Another concern is how much editing must be done
@@ -12131,6 +12132,8 @@ Common Shell Constructs
 Expand into a shell @samp{case} statement, where @var{word} is matched
 against one or more patterns.  @var{if-matched} is run if the
 corresponding pattern matched @var{word}, else @var{default} is run.
+Avoids several portability issues (@pxref{case, , Limitations of Shell
+Builtins}).
 @end defmac
 
 @c Deprecated, to be replaced by a better API
@@ -12148,7 +12151,9 @@ Common Shell Constructs
 Emits @var{word} to the standard output, followed by a newline.  @var{word}
 must be a single shell word (typically a quoted string).  The bytes of
 @var{word} are output as-is, even if it starts with "-" or contains "\".
-Redirections can be placed outside the macro invocation.
+Redirections can be placed outside the macro invocation.  This is much
+more portable than using @command{echo} (@pxref{echo, , Limitations of
+Shell Builtins}).
 @end defmac
 
 @defmac AS_ECHO_N (@var{word})
@@ -12167,8 +12172,8 @@ Common Shell Constructs
 converted to @samp{1}.  To exit with successful status, it is necessary
 to supply an explicit @var{status} that expands to @samp{0}.  This macro
 works around shells that see the exit status of the command prior to
address@hidden inside a @samp{trap 0} handler (@pxref{Limitations of
-Builtins, , Limitations of Shell Builtins}).
address@hidden inside a @samp{trap 0} handler (@pxref{trap, , Limitations
+of Shell Builtins}).
 @end defmac
 
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
@@ -12196,7 +12201,8 @@ Common Shell Constructs
 as necessary.  This is equivalent to @samp{mkdir -p -- @var{file-name}},
 except that it is portable to older versions of @command{mkdir} that
 lack support for the @option{-p} option or for the @option{--}
-delimiter.  Also, @code{AS_MKDIR_P}
+delimiter (@pxref{mkdir, , Limitations of Usual Tools}).  Also,
address@hidden
 succeeds if @var{file-name} is a symbolic link to an existing directory,
 even though Posix is unclear whether @samp{mkdir -p} should
 succeed in that case.  If creation of @var{file-name} fails, exit the
@@ -12209,8 +12215,7 @@ Common Shell Constructs
 @asindex{SET_STATUS}
 Emit shell code to set the value of @samp{$?} to @var{status} without
 forking.  However, this is not guaranteed to abort a shell running with
address@hidden -e} (@pxref{Limitations of Builtins, , Limitations of Shell
-Builtins}).
address@hidden -e} (@pxref{set, , Limitations of Shell Builtins}).
 @end defmac
 
 @defmac AS_TR_CPP (@var{expression})
@@ -12247,7 +12252,7 @@ Common Shell Constructs
 @defmac AS_UNSET (@var{var})
 @asindex{UNSET}
 Unsets the shell variable @var{var}, working around bugs in older
-shells (@pxref{Limitations of Builtins, , Limitations of Shell
+shells (@pxref{unset, , Limitations of Shell
 Builtins}).  @var{var} can be a literal or indirect variable name.
 @end defmac
 
@@ -13804,8 +13809,7 @@ File System Conventions
 
 @noindent
 Make sure you quote the brackets if appropriate and keep the backslash as
-first character (@pxref{Limitations of Builtins, , Limitations of Shell
-Builtins}).
+first character (@pxref{case, , Limitations of Shell Builtins}).
 
 Also, because the colon is used as part of a drivespec, these systems don't
 use it as path separator.  When creating or accessing paths, you can use the
@@ -14535,7 +14539,7 @@ Special Shell Variables
 
 @noindent
 (actually, there is some complication due to bugs in @command{unset};
-see @pxref{Limitations of Builtins, , Limitations of Shell Builtins}).
+see @pxref{unset, , Limitations of Shell Builtins}).
 
 @item FPATH
 The Korn shell uses @env{FPATH} to find shell functions, so avoid
@@ -14870,8 +14874,8 @@ Shell Functions
 It is probably not worth worrying about these shells any more.
 
 With @acronym{AIX} sh, a @command{trap} on 0 installed in a shell function
-triggers at function exit rather than at script exit, see @xref{Limitations
-of Builtins}.
+triggers at function exit rather than at script exit, see @xref{trap, ,
+Limitations of Shell Builtins}.
 
 @node Limitations of Builtins
 @section Limitations of Shell Builtins
@@ -14995,6 +14999,7 @@ Limitations of Builtins
 The use of @samp{break 2} etc.@: is safe.
 
 
address@hidden
 @item @command{case}
 @c -----------------
 @prindex @command{case}
@@ -15137,6 +15142,7 @@ Limitations of Builtins
 Also please see the discussion of the @command{pwd} command.
 
 
address@hidden
 @item @command{echo}
 @c -----------------
 @prindex @command{echo}
@@ -15300,6 +15306,7 @@ Limitations of Builtins
 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
 
 
address@hidden
 @item @command{export}
 @c -------------------
 @prindex @command{export}
@@ -15518,6 +15525,7 @@ Limitations of Builtins
 @command{/bin/sh} for example).
 
 
address@hidden
 @item @command{set}
 @c ----------------
 @prindex @command{set}
@@ -15726,6 +15734,7 @@ Limitations of Builtins
 @address@hidden contains backslashes.
 
 
address@hidden
 @item @command{trap}
 @c -----------------
 @prindex @command{trap}
@@ -15802,6 +15811,7 @@ Limitations of Builtins
 @end quotation
 
 
address@hidden
 @item @command{unset}
 @c ------------------
 @prindex @command{unset}
@@ -15833,7 +15843,7 @@ Limitations of Builtins
 
 @noindent
 @xref{Special Shell Variables}, for some neutralizing values.  Also, see
address@hidden of Builtins}, documentation of @command{export}, for
address@hidden, , Limitations of Builtins}, for
 the case of environment variables.
 
 @item @command{wait}
@@ -16219,7 +16229,8 @@ Limitations of Usual Tools
 |bar
 @end example
 
address@hidden also suffers the limitations of @command{grep}.
address@hidden also suffers the limitations of @command{grep}
+(@pxref{grep, , Limitations of Usual Tools}).
 
 @item @command{expr}
 @c -----------------
@@ -16386,6 +16397,7 @@ Limitations of Usual Tools
 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
 
 
address@hidden
 @item @command{grep}
 @c -----------------
 @prindex @command{grep}
@@ -16512,6 +16524,7 @@ Limitations of Usual Tools
 @samp{.c} files.  This is no longer a practical problem, since current
 @command{ls} implementations send diagnostics to standard error.
 
address@hidden
 @item @command{mkdir}
 @c ------------------
 @prindex @command{mkdir}
@@ -16674,6 +16687,7 @@ Limitations of Usual Tools
 Just as with @command{rm}, some platforms refuse to remove a working
 directory.
 
address@hidden
 @item @command{sed}
 @c ----------------
 @prindex @command{sed}
@@ -16941,6 +16955,7 @@ Limitations of Usual Tools
 the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
 level of portability to use.
 
address@hidden
 @item @command{touch}
 @c ------------------
 @prindex @command{touch}
@@ -17050,7 +17065,8 @@ Failure in Make Rules
 T || :; rm -f U}.
 However, even this approach can run into common bugs in @acronym{BSD}
 implementations of the @option{-e} option of @command{sh} and
address@hidden (@pxref{Limitations of Builtins}), so if you are worried
address@hidden (@pxref{set, , Limitations of Shell Builtins}), so if you
+are worried
 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
 complicated @command{make} actions into separate scripts.
 
@@ -17923,7 +17939,7 @@ Timestamps and Make
 like @samp{sleep 1} to work around timestamp truncation bugs.
 
 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
-file timestamps to their full resolutions (@pxref{Limitations of Usual
+file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual
 Tools}).  Hence you should be wary of rules like this:
 
 @example
-- 
1.6.0.4