AS_FUNCTION_DESCRIBE [was: [CFT] Shell functionization patch]

[Eric Blake]

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

According to Eric Blake on 10/16/2008 2:24 PM:
> # AS_REQUIRE_SHELL_FN(name, [comment], body, [diversion])
> # --------
> m4_define(...)
> 
> And define a helper function:
> 
> # AS_FUNCTION_DESCRIBE(name, [args], description)
> # -----------------------------------------------
> # Output a shell comment that looks like:
> #   # NAME ARGS
> #   # ---------
> #   # DESCRIPTION
> # where the second line sizes itself according to the first, and where
> # DESCRIPTION is treated as a whitespace separated list of words
> # to be wrapped at 76 columns.

Done in two steps; I'm committing this patch series.  I didn't really
write a testsuite, but did visually inspect the testsuite before and after
the patch.

- --
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

iEYEARECAAYFAkj3+vYACgkQ84KuGfSFAYAlbQCfT0GdTbk6mNWK30+HFu+tU3AP
4JMAnROnn35x5xH3koSKNS4zzbyASMlk
=Fc2q
-----END PGP SIGNATURE-----

>From d99fef0e1e8e7a4c04b97fc4c6e0ffb01463622c Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Thu, 16 Oct 2008 19:59:11 -0600
Subject: [PATCH] Add AS_FUNCTION_DESCRIBE.

* lib/m4sugar/m4sh.m4 (AS_FUNCTION_DESCRIBE): New macro.
* lib/autotest/general.m4 (AT_INIT): Use it.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog               |    6 +++
 lib/autotest/general.m4 |   87 ++++++++++++++++++++--------------------------
 lib/m4sugar/m4sh.m4     |   18 ++++++++++
 3 files changed, 62 insertions(+), 49 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index dfbbdfd..b36b295 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2008-10-16  Eric Blake  <address@hidden>
 
+       Add AS_FUNCTION_DESCRIBE.
+       * lib/m4sugar/m4sh.m4 (AS_FUNCTION_DESCRIBE): New macro.
+       * lib/autotest/general.m4 (AT_INIT): Use it.
+
+2008-10-16  Eric Blake  <address@hidden>
+
        Speed up m4_qlen with caching.
        * lib/m4sugar/m4sugar.m4 (_m4_qlen): Renamed from old m4_qlen.
        (m4_qlen): Cache results for speed.
diff --git a/lib/autotest/general.m4 b/lib/autotest/general.m4
index e39aee1..f7ded36 100644
--- a/lib/autotest/general.m4
+++ b/lib/autotest/general.m4
@@ -247,10 +247,9 @@ m4_divert_push([PREPARE_TESTS])dnl
 ## Shell functions ##
 ## --------------- ##
 
-# at_func_banner NUMBER
-# ---------------------
-# Output banner NUMBER, provided the testsuite is running multiple groups
-# and this particular banner has not yet been printed.
+AS_FUNCTION_DESCRIBE([at_func_banner], [NUMBER],
+[Output banner NUMBER, provided the testsuite is running multiple groups
+and this particular banner has not yet been printed.])
 at_func_banner ()
 {
   $at_print_banners || return 0
@@ -260,10 +259,9 @@ at_func_banner ()
   AS_ECHO(["$as_nl$at_banner_text$as_nl"])
 } # at_func_banner
 
-# at_func_check_newline COMMAND
-# -----------------------------
-# Test if COMMAND includes a newline and, if so, print a message and return
-# exit code 1
+AS_FUNCTION_DESCRIBE([at_func_check_newline], [COMMAND],
+[Test if COMMAND includes a newline and, if so, print a message and return
+exit code 1.])
 at_func_check_newline ()
 {
   case "$[1]" in
@@ -274,10 +272,10 @@ at_func_check_newline ()
   esac
 }
 
-# at_func_filter_trace EXIT-CODE
-# ------------------------------
-# Split the contents of file "$at_stder1" into the "set -x" trace (on stderr)
-# and the other lines (on file "$at_stderr").  Return the exit code EXIT-CODE.
+AS_FUNCTION_DESCRIBE([at_func_filter_trace], [EXIT-CODE],
+[Split the contents of file "$at_stder1" into the "set -x" trace (on
+stderr) and the other lines (on file "$at_stderr").  Return the exit
+code EXIT-CODE.])
 at_func_filter_trace ()
 {
   grep '^ *+' "$at_stder1" >&2
@@ -285,10 +283,9 @@ at_func_filter_trace ()
   return $[1]
 }
 
-# at_func_log_failure FILE-LIST
-# -----------------------------
-# Copy the files in the list on stdout with a "> " prefix, and exit the shell
-# with a failure exit code.
+AS_FUNCTION_DESCRIBE([at_func_log_failure], [FILE-LIST],
+[Copy the files in the list on stdout with a "> " prefix, and exit the shell
+with a failure exit code.])
 at_func_log_failure ()
 {
   for file
@@ -297,10 +294,9 @@ at_func_log_failure ()
   exit 1
 }
 
-# at_func_check_skip EXIT-CODE
-# ----------------------------
-# Check whether EXIT-CODE is the special exit code 77, and if so exit the shell
-# with that same exit code.
+AS_FUNCTION_DESCRIBE([at_func_check_skip], [EXIT-CODE],
+[Check whether EXIT-CODE is the special exit code 77, and if so exit the shell
+with that same exit code.])
 at_func_check_skip ()
 {
   case $[1] in
@@ -308,11 +304,10 @@ at_func_check_skip ()
   esac
 }
 
-# at_func_check_status EXPECTED EXIT-CODE LINE
-# --------------------------------------------
-# Check whether EXIT-CODE is the expected exit code, and if so do nothing.
-# Otherwise, if it is 77 exit the shell with that same exit code; if it is
-# anything else print an error message and fail the test.
+AS_FUNCTION_DESCRIBE([at_func_check_status], [EXPECTED EXIT-CODE LINE],
+[Check whether EXIT-CODE is the expected exit code, and if so do nothing.
+Otherwise, if it is 77 exit the shell with that same exit code; if it is
+anything else print an error message and fail the test.])
 at_func_check_status ()
 {
 dnl This order ensures that we don't `skip' if we are precisely checking
@@ -325,29 +320,26 @@ dnl $? = 77.
   esac
 }
 
-# at_func_diff_devnull FILE
-# -------------------------
-# Emit a diff between /dev/null and FILE.  Uses "test -s" to avoid useless
-# diff invocations.
+AS_FUNCTION_DESCRIBE([at_func_diff_devnull], [FILE],
+[Emit a diff between /dev/null and FILE.  Uses "test -s" to avoid useless
+diff invocations.])
 at_func_diff_devnull ()
 {
   test -s "$[1]" || return 0
   $at_diff "$at_devnull" "$[1]"
 }
 
-# at_func_test NUMBER
-# -------------------
-# Parse out test NUMBER from the tail of this file.
+AS_FUNCTION_DESCRIBE([at_func_test], [NUMBER],
+[Parse out test NUMBER from the tail of this file.])
 at_func_test ()
 {
   eval at_sed=\$at_sed$[1]
   sed "$at_sed" "$at_myself" > "$at_test_source"
 }
 
-# at_func_create_debugging_script
-# -------------------------------
-# Create the debugging script $at_group_dir/run which will reproduce the
-# current test group.
+AS_FUNCTION_DESCRIBE([at_func_create_debugging_script], [],
+[Create the debugging script $at_group_dir/run which will reproduce the
+current test group.])
 at_func_create_debugging_script ()
 {
   {
@@ -362,10 +354,9 @@ at_func_create_debugging_script ()
   chmod +x "$at_group_dir/run"
 }
 
-# at_func_arith
-# -------------
-# Arithmetic evaluation, avoids expr if the shell is sane.  The
-# interpretation of leading zeroes is unspecified.
+AS_FUNCTION_DESCRIBE([at_func_arith], [ARG...],
+[Arithmetic evaluation, avoids expr if the shell is sane.  The
+interpretation of leading zeroes is unspecified.])
 #
 # subshell and eval are needed to keep Solaris sh from bailing out:
 if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then
@@ -444,10 +435,9 @@ at_format='m4_bpatsubst(m4_defn([AT_ordinal]), [.], [?])'
 # Description of all the test groups.
 at_help_all="AS_ESCAPE(m4_dquote(m4_defn([AT_help_all])))"
 
-# at_func_validate_ranges [NAME...]
-# ---------------------------------
-# Validate and normalize the test group number contained in each
-# variable NAME.  Leading zeroes are treated as decimal.
+AS_FUNCTION_DESCRIBE([at_func_validate_ranges], [NAME...],
+[Validate and normalize the test group number contained in each
+variable NAME.  Leading zeroes are treated as decimal.])
 at_func_validate_ranges ()
 {
   for at_grp
@@ -1042,9 +1032,8 @@ AS_ERROR([testsuite directory setup failed])
 # test group execution outside of a shell function in order
 # to avoid hitting zsh 4.x exit status bugs.
 
-# at_func_group_prepare
-# ---------------------
-# Prepare running a test group
+AS_FUNCTION_DESCRIBE([at_func_group_prepare], [],
+[Prepare running a test group.])
 at_func_group_prepare ()
 {
   # The directory for additional per-group helper files.
@@ -1093,8 +1082,8 @@ at_func_group_prepare ()
   fi
 }
 
-# at_func_group_postprocess
-# -------------------------
+AS_FUNCTION_DESCRIBE([at_func_group_postprocess], [],
+[Perform cleanup after running a test group.])
 at_func_group_postprocess ()
 {
   # Be sure to come back to the suite directory, in particular
diff --git a/lib/m4sugar/m4sh.m4 b/lib/m4sugar/m4sh.m4
index 5e6245d..566d27c 100644
--- a/lib/m4sugar/m4sh.m4
+++ b/lib/m4sugar/m4sh.m4
@@ -1226,6 +1226,24 @@ m4_define([_AS_BOX_INDIR],
 _ASBOX])
 
 
+# AS_FUNCTION_DESCRIBE(NAME, [ARGS], DESCRIPTION, [WRAP-COLUMN = 79])
+# -------------------------------------------------------------------
+# Output a shell comment describing NAME and its arguments ARGS, then
+# a separator line, then the DESCRIPTION wrapped at a decimal
+# WRAP-COLUMN.  The output resembles:
+#  # NAME ARGS
+#  # ---------
+#  # Wrapped DESCRIPTION text
+# NAME and ARGS are expanded, while DESCRIPTION is treated as a
+# whitespace-separated list of strings that are not expanded.
+m4_define([AS_FUNCTION_DESCRIBE],
address@hidden:@ $1[]m4_ifval([$2], [ $2])
address@hidden:@ m4_translit(m4_format([%*s],
+                  m4_qlen(m4_expand([$1[]m4_ifval([$2], [ $2])])), []),
+                [ ], [-])
+m4_text_wrap([$3], address@hidden:@ ], [], [$4])])
+
+
 # AS_HELP_STRING(LHS, RHS, [INDENT-COLUMN = 26], [WRAP-COLUMN = 79])
 # ------------------------------------------------------------------
 #
-- 
1.6.0.2


>From 29f8f14acdea1c7ebc2f739dceca962c84ba8c56 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Thu, 16 Oct 2008 20:08:06 -0600
Subject: [PATCH] Allow comments before functions emitted by m4sh.

* lib/m4sugar/m4sh.m4 (AS_REQUIRE_SHELL_FN): Add comment
argument.  Supply closing comment, to ease readability.
(_AS_MKDIR_P_PREPARE): Adjust caller.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog           |    6 ++++++
 lib/m4sugar/m4sh.m4 |   27 ++++++++++++++++++---------
 2 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b36b295..1ba9686 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2008-10-16  Eric Blake  <address@hidden>
 
+       Allow comments before functions emitted by m4sh.
+       * lib/m4sugar/m4sh.m4 (AS_REQUIRE_SHELL_FN): Add comment
+       argument.  Supply closing comment, to ease readability.
+       (_AS_MKDIR_P_PREPARE): Adjust caller.
+       (_AS_UNSET_PREPARE): Add comment.
+
        Add AS_FUNCTION_DESCRIBE.
        * lib/m4sugar/m4sh.m4 (AS_FUNCTION_DESCRIBE): New macro.
        * lib/autotest/general.m4 (AT_INIT): Use it.
diff --git a/lib/m4sugar/m4sh.m4 b/lib/m4sugar/m4sh.m4
index 566d27c..c387864 100644
--- a/lib/m4sugar/m4sh.m4
+++ b/lib/m4sugar/m4sh.m4
@@ -258,6 +258,8 @@ fi
 # important not to forget some: config.status needs them.
 m4_defun([_AS_PREPARE],
 [m4_pushdef([AS_REQUIRE], [])dnl
+AS_FUNCTION_DESCRIBE([as_func_mkdir_p], [],
+[Create "$as_dir" as a directory, including parents if necessary.])
 as_func_mkdir_p ()
 {
   _AS_MKDIR_P
@@ -314,18 +316,21 @@ m4_if(m4_eval(_m4_divert(_m4_divert_dump) <= 
_m4_divert(_m4_divert_desired)), 1,
       [m4_divert_require([_m4_divert_desired], [$1], [$2])])])
 
 
-# AS_REQUIRE_SHELL_FN(NAME-TO-CHECK, BODY-TO-EXPAND,
+# AS_REQUIRE_SHELL_FN(NAME-TO-CHECK, COMMENT, BODY-TO-EXPAND,
 #                     [DIVERSION = M4SH-INIT-FN])
-# --------------------------------------------------
+# -----------------------------------------------------------
 # BODY-TO-EXPAND is the body of a shell function to be emitted in the
 # given diversion when expanded (required or not).  Unlike other
-# xx_REQUIRE macros, BODY-TO-EXPAND is mandatory.
-#
+# xx_REQUIRE macros, BODY-TO-EXPAND is mandatory.  If COMMENT is
+# provided (often via AS_FUNCTION_DESCRIBE), it is listed with a
+# newline before the function name.
 m4_define([AS_REQUIRE_SHELL_FN],
-[AS_REQUIRE([AS_SHELL_FN_$1], [m4_provide([AS_SHELL_FN_$1])$1 ()
+[AS_REQUIRE([AS_SHELL_FN_$1],
+[m4_provide([AS_SHELL_FN_$1])m4_n([$2])$1 ()
 {
-$2
-}], m4_default_quoted([$3], [M4SH-INIT-FN]))])
+$3
+} [#] $1
+], m4_default_quoted([$4], [M4SH-INIT-FN]))])
 
 
 # _AS_RUN(TEST, [SHELL])
@@ -539,7 +544,8 @@ fi
 # Define $as_unset to execute AS_UNSET, for backwards compatibility
 # with older versions of M4sh.
 m4_defun([_AS_UNSET_PREPARE],
-[as_func_unset ()
+[AS_FUNCTION_DESCRIBE([as_func_unset], [VAR], [Portably unset VAR.])
+as_func_unset ()
 {
   AS_UNSET([$[1]])
 }
@@ -1080,7 +1086,10 @@ as_dir=$1; as_func_mkdir_p])# AS_MKDIR_P
 # _AS_MKDIR_P_PREPARE
 # -------------------
 m4_defun([_AS_MKDIR_P_PREPARE],
-[AS_REQUIRE_SHELL_FN([as_func_mkdir_p], [
+[AS_REQUIRE_SHELL_FN([as_func_mkdir_p],
+  [AS_FUNCTION_DESCRIBE([as_func_mkdir_p], [],
+    [Create "$as_dir" as a directory, including parents if necessary.])],
+[
   _AS_MKDIR_P
 ])
 if mkdir -p . 2>/dev/null; then
-- 
1.6.0.2