Re: m4sugar speedups

[Ralf Wildenhues]

Hi Eric,

late review of an old patch:
<http://thread.gmane.org/gmane.comp.sysutils.autoconf.general/9586/focus=4902>

* Eric Blake wrote on Sat, Oct 13, 2007 at 04:36:47PM CEST:
> 
> 2007-10-13  Eric Blake  <address@hidden>
> 
>       Make AC_PREREQ faster and more robust.
[...]
> diff --git a/doc/autoconf.texi b/doc/autoconf.texi
> index 26ca6fd..f63dfa2 100644
> --- a/doc/autoconf.texi
> +++ b/doc/autoconf.texi
[...]
> @@ -10585,7 +10587,42 @@ Expand to @var{text}, and add a newline if 
> @var{text} is not empty.
>  @node Looping constructs
>  @subsection Looping constructs
>  
> -The following macros implement loops in M4.
> +The following macros are useful in implementing recursive algorithms in
> +M4, including loop operations.  An M4 list is formed by quoting a list
> +of quoted elements; generally the lists are comma-separated, although
> address@hidden is whitespace-separated.  For example, the list
> address@hidden, [b,c]]} contains two elements: @samp{[a]} and @samp{[b,c]}.
> +It is common to see lists with unquoted elements when those elements are
> +not likely to be macro names, as in @samp{[fputc_unlocked,
> +fgetc_unlocked]}.
> +
> address@hidden m4_car (@var{list})
> address@hidden
> +Expands to the quoted first element of the comma-separated quoted
> address@hidden  Often used with @code{m4_cdr} to recursively iterate
> +through a list.  Generally, when using quoted lists of quoted elements,
> address@hidden should be called without any extra quotes.
> address@hidden defmac
> +
> address@hidden m4_cdr (@var{list})
> address@hidden
> +Expands to a quoted list of all but the first element of the
> +comma-separated quoted @var{list}, or the empty string if @var{list} had
> +only one element.  Generally, when using quoted lists of quoted
> +elements, @code{m4_cdr} should be called without any extra quotes.
> +
> +For example, this is an implementation of @code{m4_map}; note how each
> +iteration of the helper macro @code{_m4_map} checks for the end of
> +recursion, then merely applies the first argument to the first element
> +of the list, then recurses with the rest of the list.

I know this is probably widely used, and hardly misunderstood by a
native computer-savvy speaker, but to me, "recurses" sounds like
someone repeating the act of swearing.

> @@ -10649,18 +10680,59 @@ for two and three shifts, respectively.
>  @subsection Evaluation Macros
>  
>  The following macros give some control over the order of the evaluation
> -by adding or removing levels of quotes.  They are meant for hard-core M4
> -programmers.
> +by adding or removing levels of quotes.
> +
> address@hidden m4_do (@var{arg1}, @dots{})

Please make that @var{arg}, which is what you're repeating below; it makes no
sense to not have identical metasyntactic variables.
(Several instances of this, not sure whether I got them all.)

> address@hidden
> +This macro loops over its arguments and expands each @var{arg} in
> +sequence.  Its main use is for readability; it allows the use of
> +indentation and fewer @code{dnl} to result in the same expansion.
> address@hidden defmac

>  @defmac m4_dquote (@var{arg1}, @dots{})

Likewise.

>  @msindex{dquote}
>  Return the arguments as a quoted list of quoted arguments.
> +Conveniently, if there is just one @var{arg}, this effectively adds a
> +level of quoting.
>  @end defmac


> address@hidden m4_ignore (@dots{})
> address@hidden
> +This macro was introduced in Autoconf 2.62.  Expands to nothing,
> +ignoring all of its arguments.  By itself, this isn't very useful.
> +However, it can be used to conditionally ignore an arbitrary number of
> +arguments, by making a decision about which macro name to apply to a
> +list of arguments.

The last sub-clause is a bit awkward.  How about "by deciding which macro
to apply ..."?

> address@hidden
> +dnl foo outputs a message only if [debug] is defined.
> +m4_define([foo],
> +[m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])])
> address@hidden example

> address@hidden m4_unquote (@var{arg1}, @dots{})

Likewise, see above.

> address@hidden
> +This macro was introduced in Autoconf 2.62.  Expand each argument,
> +separated by commas.  For a single @var{arg}, this effectively removes a
> +layer of quoting, and @code{m4_unquote(address@hidden)} is more efficient
> +than the equivalent @code{m4_do(address@hidden)}.  For multiple arguments,
> +this results in an unquoted list of expansions.  This is commonly used
> +with @code{m4_split}, in order to convert a single quoted list into a
> +series of quoted elements.
>  @end defmac


> @@ -10852,17 +10924,76 @@ Return @var{string} with letters converted to upper 
> or lower case,
>  respectively.
>  @end defmac
>  
> address@hidden Number processing Macros
> address@hidden Arithmetic computation in M4
> +
> +The following macros make it easier to deal with arithmetic operations.

s/make it easier/help/  or  s/make it easier to deal with/facilitate/  ?

s/arithmetic/integer &/  ?

> +Where a parameter is documented as taking an arithmetic expression, you
> +can use anything that can be parsed by @code{m4_eval}.

> address@hidden m4_list_cmp (@var{list-1}, @var{list-2})
> address@hidden
> +Compare the two M4 lists consisting of comma-separated arithmetic
> +expressions, left to right.  Expand to @samp{-1} for the first element
> +pairing where the value from @var{list-1} is smaller, @samp{1} where the
> +value from @var{list-2} is smaller, or @samp{0} if both lists have the
> +same values.  If one list is shorter than the other, the remaining
> +elements of the longer list are compared against 0.

0 vs. @samp{0}.

> --- a/lib/m4sugar/m4sugar.m4
> +++ b/lib/m4sugar/m4sugar.m4

>  # m4_list_cmp(A, B)
>  # -----------------
>  #
> -# Compare the two lists of integers A and B.  For instance:
> -#   m4_list_cmp((1, 0),     (1))    ->  0
> -#   m4_list_cmp((1, 0),     (1, 0)) ->  0
> -#   m4_list_cmp((1, 2),     (1, 0)) ->  1
> -#   m4_list_cmp((1, 2, 3),  (1, 2)) ->  1
> -#   m4_list_cmp((1, 2, -3), (1, 2)) -> -1
> -#   m4_list_cmp((1, 0),     (1, 2)) -> -1
> -#   m4_list_cmp((1),        (1, 2)) -> -1
> +# Compare the two lists of integer expressions A and B.  For instance:
> +#   m4_list_cmp([1, 0],     [1])    ->  0
> +#   m4_list_cmp([1, 0],     [1, 0]) ->  0
> +#   m4_list_cmp([1, 2],     [1, 0]) ->  1
> +#   m4_list_cmp([1, 2, 3],  [1, 2]) ->  1
> +#   m4_list_cmp([1, 2, -3], [1, 2]) -> -1
> +#   m4_list_cmp([1, 0],     [1, 2]) -> -1
> +#   m4_list_cmp([1],        [1, 2]) -> -1
> +#   m4_define([xa], [oops])dnl
> +#   m4_list_cmp([[0xa]],    [5+5])  -> 0

Curious: is this fixing implementation or just fixing the comments?
FWIW, I haven't bothered to review the code changes in this patch,
they are a bit over my head for this time of day.

> +# Rather than face the overhead of m4_case, we use a helper function whose
> +# expansion includes the name of the macro to invoke on the tail, either
> +# m4_ignore or m4_unquote.  This is particularly useful when comparing
> +# long lists, since less text is being expanded to determine when to recurse.

See above on recurse.

Cheers,
Ralf