(autoconf.info)Text processing Macros

Next: Number processing Macros Prev: Evaluation Macros Up: Programming in M4sugar

8.3.7 String manipulation in M4

The following macros may be used to manipulate strings in M4.  Many of
the macros in this section intentionally result in quoted strings as
output, rather than subjecting the arguments to further expansions.  As
a result, if you are manipulating text that contains active M4
characters, the arguments are passed with single quoting rather than

 -- Macro: m4_append (MACRO-NAME, STRING, [SEPARATOR])
 -- Macro: m4_append_uniq (MACRO-NAME, STRING, [SEPARATOR] [IF-UNIQ],
     Redefine MACRO-NAME to its former contents with SEPARATOR and
     STRING added at the end.  If MACRO-NAME was undefined before (but
     not if it was defined but empty), then no SEPARATOR is added.  As
     of Autoconf 2.62, neither STRING nor SEPARATOR are expanded during
     this macro; instead, they are expanded when MACRO-NAME is invoked.

     `m4_append' can be used to grow strings, and `m4_append_uniq' to
     grow strings without duplicating substrings.  Additionally,
     `m4_append_uniq' takes two optional parameters as of Autoconf 2.62;
     IF-UNIQ is expanded if STRING was appended, and IF-DUPLICATE is
     expanded if STRING was already present.  Also, `m4_append_uniq'
     warns if SEPARATOR is not empty, but occurs within STRING, since
     that can lead to duplicates.

          m4_define([active], [ACTIVE])dnl
          m4_append([sentence], [This is an])dnl
          m4_append([sentence], [ active ])dnl
          m4_append([sentence], [symbol.])dnl
          =>This is an ACTIVE symbol.
          =>This is an active symbol.
          m4_append_uniq([list], [one], [, ], [new], [existing])
          m4_append_uniq([list], [one], [, ], [new], [existing])
          m4_append_uniq([list], [two], [, ], [new], [existing])
          m4_append_uniq([list], [three], [, ], [new], [existing])
          m4_append_uniq([list], [two], [, ], [new], [existing])
          =>one, two, three
          m4_append([list2], [one], [[, ]])dnl
          m4_append_uniq([list2], [two], [[, ]])dnl
          m4_append([list2], [three], [[, ]])dnl
          =>one, two, three
          =>[one, two, three]

 -- Macro: m4_append_uniq_w (MACRO-NAME, STRINGS)
     This macro was introduced in Autoconf 2.62.  It is similar to
     `m4_append_uniq', but treats STRINGS as a whitespace separated
     list of words to append, and only appends unique words.
     MACRO-NAME is updated with a single space between new words.
          m4_append_uniq_w([numbers], [1 1 2])dnl
          m4_append_uniq_w([numbers], [ 2 3 ])dnl
          =>1 2 3

 -- Macro: m4_combine ([SEPARATOR], PREFIX-LIST, [INFIX], SUFFIX-1,
          [SUFFIX-2], ...)
     This macro produces a quoted string containing the pairwise
     combination of every element of the quoted, comma-separated
     PREFIX-LIST, and every element from the SUFFIX arguments.  Each
     pairwise combination is joined with INFIX in the middle, and
     successive pairs are joined by SEPARATOR.  No expansion occurs on
     any of the arguments.  No output occurs if either the PREFIX or
     SUFFIX list is empty, but the lists can contain empty elements.
          m4_define([a], [oops])dnl
          m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
          =>a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
          m4_combine([, ], [[a], [b]], [-])
          m4_combine([, ], [[a], [b]], [-], [])
          =>a-, b-
          m4_combine([, ], [], [-], [1], [2])
          m4_combine([, ], [[]], [-], [1], [2])
          =>-1, -2

 -- Macro: m4_flatten (STRING)
     Flatten STRING into a single line.  Delete all backslash-newline
     pairs, and replace all remaining newlines with a space.  The
     result is still a quoted string.

 -- Macro: m4_join ([SEPARATOR], ARGS...)
     Concatenate each ARG, separated by SEPARATOR, with the exception
     that no back-to-back separators are issued for empty arguments.
     The result is a quoted string.
          m4_define([active], [ACTIVE])dnl
          m4_join([|], [one], [], [active], [two])

     Note that if all you intend to do is join ARGS with commas between
     them, to form a quoted list suitable for `m4_foreach', it is more
     efficient to use `m4_dquote'.

 -- Macro: m4_newline
     This macro was introduced in Autoconf 2.62, and expands to a
     newline.  It is primarily useful for maintaining macro formatting,
     and ensuring that M4 does not discard leading whitespace during
     argument collection.

 -- Macro: m4_normalize (STRING)
     Remove leading and trailing spaces and tabs, sequences of
     backslash-then-newline, and replace multiple spaces, tabs, and
     newlines with a single space.  This is a combination of
     `m4_flatten' and `m4_strip'.

 -- Macro: m4_re_escape (STRING)
     Backslash-escape all characters in STRING that are active in

 -- Macro: m4_split (STRING, [REGEXP = `[t ]+'])
     Split STRING into an M4 list of elements quoted by `[' and `]',
     while keeping white space at the beginning and at the end.  If
     REGEXP is given, use it instead of `[\t ]+' for splitting.  If
     STRING is empty, the result is an empty list.

 -- Macro: m4_strip (STRING)
     Strip whitespace from STRING.  Sequences of spaces and tabs are
     reduced to a single space, then leading and trailing spaces are
     removed.  The result is still a quoted string.  Note that this
     does not interfere with newlines; if you want newlines stripped as
     well, consider `m4_flatten', or do it all at once with

 -- Macro: m4_text_box (MESSAGE, [FRAME = `-'])
     Add a text box around MESSAGE, using FRAME as the border character
     above and below the message.  The frame correctly accounts for the
     subsequent expansion of MESSAGE.  For example:
          m4_define([macro], [abc])dnl
          =>## --- ##
          =>## abc ##
          =>## --- ##

 -- Macro: m4_text_wrap (STRING, [PREFIX], [PREFIX1 = `PREFIX'], [WIDTH
          = `79'])
     Break STRING into a series of whitespace-separated words, then
     output those words separated by spaces, and wrapping lines any
     time the output would exceed WIDTH columns.  If given, PREFIX1
     begins the first line, and PREFIX begins all wrapped lines.  If
     PREFIX1 is longer than PREFIX, then the first line consists of
     just PREFIX1.  If PREFIX is longer than PREFIX1, padding is
     inserted so that the first word of STRING begins at the same
     indentation as all wrapped lines.  Note that using literal tab
     characters in any of the arguments will interfere with the
     calculation of width.  No expansions occur on PREFIX, PREFIX1, or
     the words of STRING, although quadrigraphs are recognized.

     For some examples:
          m4_text_wrap([Short string */], [   ], [/* ], [20])
          =>/* Short string */
          m4_text_wrap([Much longer string */], [   ], [/* ], [20])
          =>/* Much longer
          =>   string */
          m4_text_wrap([Short doc.], [          ], [  --short ], [30])
          =>  --short Short doc.
          m4_text_wrap([Short doc.], [          ], [  --too-wide ], [30])
          =>  --too-wide
          =>          Short doc.
          m4_text_wrap([Super long documentation.], [     ],
                       [  --too-wide ], 30)
          =>  --too-wide
          =>     Super long
          =>     documentation.

 -- Macro: m4_tolower (STRING)
 -- Macro: m4_toupper (STRING)
     Return STRING with letters converted to upper or lower case,

automatically generated by info2www