autoconf: Text processing Macros
1
1 8.3.7 String manipulation in M4
1 -------------------------------
1
1 The following macros may be used to manipulate strings in M4. Many of
1 the macros in this section intentionally result in quoted strings as
1 output, rather than subjecting the arguments to further expansions. As
1 a result, if you are manipulating text that contains active M4
1 characters, the arguments are passed with single quoting rather than
1 double.
1
1 -- Macro: m4_append (MACRO-NAME, STRING, [SEPARATOR])
1 -- Macro: m4_append_uniq (MACRO-NAME, STRING, [SEPARATOR] [IF-UNIQ],
1 [IF-DUPLICATE])
1 Redefine MACRO-NAME to its former contents with SEPARATOR and
1 STRING added at the end. If MACRO-NAME was undefined before (but
1 not if it was defined but empty), then no SEPARATOR is added. As
1 of Autoconf 2.62, neither STRING nor SEPARATOR are expanded during
1 this macro; instead, they are expanded when MACRO-NAME is invoked.
1
1 `m4_append' can be used to grow strings, and `m4_append_uniq' to
1 grow strings without duplicating substrings. Additionally,
1 `m4_append_uniq' takes two optional parameters as of Autoconf 2.62;
1 IF-UNIQ is expanded if STRING was appended, and IF-DUPLICATE is
1 expanded if STRING was already present. Also, `m4_append_uniq'
1 warns if SEPARATOR is not empty, but occurs within STRING, since
1 that can lead to duplicates.
1
1 Note that `m4_append' can scale linearly in the length of the final
1 string, depending on the quality of the underlying M4
1 implementation, while `m4_append_uniq' has an inherent quadratic
1 scaling factor. If an algorithm can tolerate duplicates in the
1 final string, use the former for speed. If duplicates must be
11 avoided, consider using `m4_set_add' instead (⇒Set
manipulation Macros).
1
1 m4_define([active], [ACTIVE])dnl
1 m4_append([sentence], [This is an])dnl
1 m4_append([sentence], [ active ])dnl
1 m4_append([sentence], [symbol.])dnl
1 sentence
1 =>This is an ACTIVE symbol.
1 m4_undefine([active])dnl
1 =>This is an active symbol.
1 m4_append_uniq([list], [one], [, ], [new], [existing])
1 =>new
1 m4_append_uniq([list], [one], [, ], [new], [existing])
1 =>existing
1 m4_append_uniq([list], [two], [, ], [new], [existing])
1 =>new
1 m4_append_uniq([list], [three], [, ], [new], [existing])
1 =>new
1 m4_append_uniq([list], [two], [, ], [new], [existing])
1 =>existing
1 list
1 =>one, two, three
1 m4_dquote(list)
1 =>[one],[two],[three]
1 m4_append([list2], [one], [[, ]])dnl
1 m4_append_uniq([list2], [two], [[, ]])dnl
1 m4_append([list2], [three], [[, ]])dnl
1 list2
1 =>one, two, three
1 m4_dquote(list2)
1 =>[one, two, three]
1
1 -- Macro: m4_append_uniq_w (MACRO-NAME, STRINGS)
1 This macro was introduced in Autoconf 2.62. It is similar to
1 `m4_append_uniq', but treats STRINGS as a whitespace separated
1 list of words to append, and only appends unique words.
1 MACRO-NAME is updated with a single space between new words.
1 m4_append_uniq_w([numbers], [1 1 2])dnl
1 m4_append_uniq_w([numbers], [ 2 3 ])dnl
1 numbers
1 =>1 2 3
1
1 -- Macro: m4_chomp (STRING)
1 -- Macro: m4_chomp_all (STRING)
1 Output STRING in quotes, but without a trailing newline. The
1 macro `m4_chomp' is slightly faster, and removes at most one
1 newline; the macro `m4_chomp_all' removes all consecutive trailing
1 newlines. Unlike `m4_flatten', embedded newlines are left intact,
1 and backslash does not influence the result.
1
1 -- Macro: m4_combine ([SEPARATOR], PREFIX-LIST, [INFIX], SUFFIX-1,
1 [SUFFIX-2], ...)
1 This macro produces a quoted string containing the pairwise
1 combination of every element of the quoted, comma-separated
1 PREFIX-LIST, and every element from the SUFFIX arguments. Each
1 pairwise combination is joined with INFIX in the middle, and
1 successive pairs are joined by SEPARATOR. No expansion occurs on
1 any of the arguments. No output occurs if either the PREFIX or
1 SUFFIX list is empty, but the lists can contain empty elements.
1 m4_define([a], [oops])dnl
1 m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
1 =>a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
1 m4_combine([, ], [[a], [b]], [-])
1 =>
1 m4_combine([, ], [[a], [b]], [-], [])
1 =>a-, b-
1 m4_combine([, ], [], [-], [1], [2])
1 =>
1 m4_combine([, ], [[]], [-], [1], [2])
1 =>-1, -2
1
1 -- Macro: m4_escape (STRING)
1 Convert all instances of `[', `]', `#', and `$' within STRING into
1 their respective quadrigraphs. The result is still a quoted
1 string.
1
1 -- Macro: m4_flatten (STRING)
1 Flatten STRING into a single line. Delete all backslash-newline
1 pairs, and replace all remaining newlines with a space. The
1 result is still a quoted string.
1
1 -- Macro: m4_join ([SEPARATOR], ARGS...)
1 -- Macro: m4_joinall ([SEPARATOR], ARGS...)
1 Concatenate each ARG, separated by SEPARATOR. `joinall' uses
1 every argument, while `join' omits empty arguments so that there
1 are no back-to-back separators in the output. The result is a
1 quoted string.
1 m4_define([active], [ACTIVE])dnl
1 m4_join([|], [one], [], [active], [two])
1 =>one|active|two
1 m4_joinall([|], [one], [], [active], [two])
1 =>one||active|two
1
1 Note that if all you intend to do is join ARGS with commas between
1 them, to form a quoted list suitable for `m4_foreach', it is more
1 efficient to use `m4_dquote'.
1
1 -- Macro: m4_newline ([TEXT])
1 This macro was introduced in Autoconf 2.62, and expands to a
1 newline, followed by any TEXT. It is primarily useful for
1 maintaining macro formatting, and ensuring that M4 does not
1 discard leading whitespace during argument collection.
1
1 -- Macro: m4_normalize (STRING)
1 Remove leading and trailing spaces and tabs, sequences of
1 backslash-then-newline, and replace multiple spaces, tabs, and
1 newlines with a single space. This is a combination of
1 `m4_flatten' and `m4_strip'. To determine if STRING consists only
1 of bytes that would be removed by `m4_normalize', you can use
1 `m4_ifblank'.
1
1 -- Macro: m4_re_escape (STRING)
1 Backslash-escape all characters in STRING that are active in
1 regexps.
1
1 -- Macro: m4_split (STRING, [REGEXP = `[\t ]+'])
1 Split STRING into an M4 list of elements quoted by `[' and `]',
1 while keeping white space at the beginning and at the end. If
1 REGEXP is given, use it instead of `[\t ]+' for splitting. If
1 STRING is empty, the result is an empty list.
1
1 -- Macro: m4_strip (STRING)
1 Strip whitespace from STRING. Sequences of spaces and tabs are
1 reduced to a single space, then leading and trailing spaces are
1 removed. The result is still a quoted string. Note that this
1 does not interfere with newlines; if you want newlines stripped as
1 well, consider `m4_flatten', or do it all at once with
1 `m4_normalize'. To quickly test if STRING has only whitespace,
1 use `m4_ifblank'.
1
1 -- Macro: m4_text_box (MESSAGE, [FRAME = `-'])
1 Add a text box around MESSAGE, using FRAME as the border character
1 above and below the message. The FRAME argument must be a single
1 byte, and does not support quadrigraphs. The frame correctly
1 accounts for the subsequent expansion of MESSAGE. For example:
1 m4_define([macro], [abc])dnl
1 m4_text_box([macro])
1 =>## --- ##
1 =>## abc ##
1 =>## --- ##
1
1 The MESSAGE must contain balanced quotes and parentheses, although
1 quadrigraphs can be used to work around this.
1
1 -- Macro: m4_text_wrap (STRING, [PREFIX], [PREFIX1 = `PREFIX'], [WIDTH
1 = `79'])
1 Break STRING into a series of whitespace-separated words, then
1 output those words separated by spaces, and wrapping lines any
1 time the output would exceed WIDTH columns. If given, PREFIX1
1 begins the first line, and PREFIX begins all wrapped lines. If
1 PREFIX1 is longer than PREFIX, then the first line consists of
1 just PREFIX1. If PREFIX is longer than PREFIX1, padding is
1 inserted so that the first word of STRING begins at the same
1 indentation as all wrapped lines. Note that using literal tab
1 characters in any of the arguments will interfere with the
1 calculation of width. No expansions occur on PREFIX, PREFIX1, or
1 the words of STRING, although quadrigraphs are recognized.
1
1 For some examples:
1 m4_text_wrap([Short string */], [ ], [/* ], [20])
1 =>/* Short string */
1 m4_text_wrap([Much longer string */], [ ], [/* ], [20])
1 =>/* Much longer
1 => string */
1 m4_text_wrap([Short doc.], [ ], [ --short ], [30])
1 => --short Short doc.
1 m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30])
1 => --too-wide
1 => Short doc.
1 m4_text_wrap([Super long documentation.], [ ],
1 [ --too-wide ], 30)
1 => --too-wide
1 => Super long
1 => documentation.
1
1 -- Macro: m4_tolower (STRING)
1 -- Macro: m4_toupper (STRING)
1 Return STRING with letters converted to upper or lower case,
1 respectively.
1