Re: improve AS_ESCAPE

[Ralf Wildenhues]

Hi Eric,

a couple of comments on this patch (thanks as always for all your work
on this!)

* Eric Blake wrote on Thu, Feb 19, 2009 at 11:10:29PM CET:
> * lib/m4sugar/m4sh.m4 (_AS_ESCAPE): Alter API to take first byte
> of set separately from rest.
> (AS_ESCAPE, _AS_QUOTE_MODERN, AS_TR_SH, AS_VAR_GET): Adjust
> callers.
> * lib/autoconf/autoheader.m4 (AH_VERBATIM): Avoid duplicate
> characters in translit request.
> * doc/autoconf.texi (Common Shell Constructs) <AS_ESCAPE>:
> Document the macro.
> * NEWS: Likewise.

> --- a/doc/autoconf.texi
> +++ b/doc/autoconf.texi
> @@ -12338,6 +12338,51 @@ Common Shell Constructs
>  Redirections can be placed outside the macro invocation.
>  @end defmac
> 
> address@hidden AS_ESCAPE (@var{string}, @dvar{chars, `\"$})
> address@hidden
> +Expands to @var{string}, with any characters in @var{chars} escaped with
> +a backslash (@samp{\}).  @var{chars} should be at most four bytes long,

I'm not too happy with this seemingly arbitrary limitation, and just for
the sake of optimization, but I guess in practice it will be one of the
less problematic ones.  Oh well.

> +and only contain characters from the set @samp{`\"$};

(and this limitation, of course; with it, the former isn't a problem)

> however,
> +characters may be safely listed more than once in @var{chars} for the
> +sake of syntax highlighting editors.  The current implementation expands
> address@hidden after adding escapes; if @var{string} contains macro calls
> +that have text that needs quoting, you can use

Does "quoting" refer to M4 or to shell quoting here?  This text is not
easy to read.

> address@hidden(m4_dquote(m4_expand([string])))}.
> +
> +The default for @var{chars} (@samp{\"$`}) is the set of characters
> +needing escapes when @var{string} will be used literally within double
> +quotes.  One common variant is the set of characters to protect when
> address@hidden will be used literally within back-ticks or an unquoted
> +here-doc (@samp{\$`}).  Another common variant is @samp{""}, which can
> +be used to form a double-quoted string containing the same expansions
> +that would have occurred if @var{string} were expanded in an unquoted
> +here-doc; however, when using this variant, care must be taken that
> address@hidden does not use double quotes within complex variable
> +expansions (such as @address@hidden "hi"address@hidden) that would be broken
> +with improper escapes.

> +This macro is often used with @code{AS_ECHO}.  For example, this snippet
> +will produce shell code that outputs the four lines @samp{"$foo" =
> +"bar"}, @samp{macro}, @samp{a, b}, and @samp{a, \b}:

The first @samp will be line-wrapped in the info page here, which is
unfortunate, given that it's valuable to see the verbatim results.  How
about making them a four-line result @example?

> address@hidden
> +foo=bar
> +AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"])
> +m4_define([macro], [a, [\b]])
> +AS_ECHO(["AS_ESCAPE([[macro]])"])
> +AS_ECHO(["AS_ESCAPE([macro])"])
> +AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"])
> address@hidden example


> address@hidden Should we add AS_ESCAPE_SINGLE?

What would it do?

> If we do, we can optimize in
> address@hidden the case of @var{string} that does not contain '.
> +To escape a string that will be placed within single quotes, use:
> +
> address@hidden
> +m4_bpatsubst(address@hidden, ['], ['\\''])
> address@hidden example
> address@hidden defmac


> --- a/lib/autoconf/autoheader.m4
> +++ b/lib/autoconf/autoheader.m4

> @@ -68,7 +68,7 @@ m4_define([AH_OUTPUT], [])
>  # Quote for Perl '' strings, which are those used by Autoheader.
>  m4_define([AH_VERBATIM],
>  [AS_LITERAL_IF([$1],
> -            [AH_OUTPUT([$1], AS_ESCAPE([[$2]], [\\'']))])])
> +            [AH_OUTPUT([$1], AS_ESCAPE([[$2]], [\']))])])

Why is this change needed?  Or is it a cosmetic fix only?

> --- a/lib/m4sugar/m4sh.m4
> +++ b/lib/m4sugar/m4sh.m4
> @@ -680,18 +680,33 @@ m4_define([AS_MESSAGE_LOG_FD])

> +# _AS_ESCAPE(STRING, KEY, SET)
> +# ----------------------------
> +# Backslash-escape all instances of the singly byte KEY or up to four

s/singly/single/

> +# bytes in SET occurring in STRING.  Although a character can occur
> +# multiple times, optimum efficiency occurs when KEY and SET are
> +# distinct, and when SET does not exceed two bytes.  These particular
> +# semantics allow for the fewest number of parses of STRING, as well
> +# as taking advantage of newer m4's optimizations when m4_translit is

s/newer m4's optimizations/optimizations in M4 versions XX and newer/
?

> +# passed SET of size 2 or smaller.
>  m4_define([_AS_ESCAPE],
> -[m4_if(m4_len([$1]),
> -       m4_len(m4_translit([[$1]], [$2])),
> -       [$1], [m4_bpatsubst([$1], [[$2]], [\\\&])])])
> +[m4_if(m4_index(m4_translit([[$1]], [$3], [$2$2$2$2]), [$2]), [-1],
> +       [$0_], [m4_bpatsubst])([$1], [[$2$3]], [\\\&])])
> +m4_define([_AS_ESCAPE_], [$1])

Cheers,
Ralf