(m4.info.gz) Patsubst

 
 10.6 Substituting text by regular expression
 ============================================
 
 Global substitution in a string is done by `patsubst':
 
  -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT])
      Searches STRING for matches of REGEXP, and substitutes REPLACEMENT
      for each match.  The syntax for regular expressions is the same as
      in GNU Emacs ( Regexp).
 
      The parts of STRING that are not covered by any match of REGEXP
      are copied to the expansion.  Whenever a match is found, the
      search proceeds from the end of the match, so a character from
      STRING will never be substituted twice.  If REGEXP matches a
      string of zero length, the start position for the search is
      incremented, to avoid infinite loops.
 
      When a replacement is to be made, REPLACEMENT is inserted into the
      expansion, with `\N' substituted by the text matched by the Nth
      parenthesized sub-expression of PATSUBST, for up to nine
      sub-expressions.  The escape `\&' is replaced by the text of the
      entire regular expression matched.  For all other characters, `\'
      treats the next character literally.  A warning is issued if there
      were fewer sub-expressions than the `\N' requested, or if there is
      a trailing `\'.
 
      The REPLACEMENT argument can be omitted, in which case the text
      matched by REGEXP is deleted.
 
      The macro `patsubst' is recognized only with parameters.
 
      patsubst(`GNUs not Unix', `^', `OBS: ')
      =>OBS: GNUs not Unix
      patsubst(`GNUs not Unix', `\<', `OBS: ')
      =>OBS: GNUs OBS: not OBS: Unix
      patsubst(`GNUs not Unix', `\w*', `(\&)')
      =>(GNUs)() (not)() (Unix)()
      patsubst(`GNUs not Unix', `\w+', `(\&)')
      =>(GNUs) (not) (Unix)
      patsubst(`GNUs not Unix', `[A-Z][a-z]+')
      =>GN not patsubst(`GNUs not Unix', `not', `NOT\')
      error-->m4:stdin:6: Warning: trailing \ ignored in replacement
      =>GNUs NOT Unix
 
    Here is a slightly more realistic example, which capitalizes
 individual word or whole sentences, by substituting calls of the macros
 `upcase' and `downcase' into the strings.
 
  -- Composite: upcase (TEXT)
  -- Composite: downcase (TEXT)
  -- Composite: capitalize (TEXT)
      Expand to TEXT, but with capitalization changed: `upcase' changes
      all letters to upper case, `downcase' changes all letters to lower
      case, and `capitalize' changes the first character of each word to
      upper case and the remaining characters to lower case.
 
      define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
      define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
      define(`capitalize1',
             `regexp(`$1', `^\(\w\)\(\w*\)',
                     `upcase(`\1')`'downcase(`\2')')')dnl
      define(`capitalize',
             `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
      capitalize(`GNUs not Unix')
      =>Gnus Not Unix
 
    While `regexp' replaces the whole input with the replacement as soon
 as there is a match, `patsubst' replaces each _occurrence_ of a match
 and preserves non-matching pieces:
 
      define(`patreg',
      `patsubst($@)
      regexp($@)')dnl
      patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
      =>bar FOO baz FOO
      =>FOO
      patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
      =>bab abb 212
      =>bab
 
    Omitting REGEXP evokes a warning, but still produces output.
 
      patsubst(`abc')
      error-->m4:stdin:1: Warning: too few arguments to builtin `patsubst'
      =>abc
Info Catalog
(m4.info.gz) Translit
(m4.info.gz) Text handling
(m4.info.gz) Format
automatically generated byinfo2html