GNU Info

(m4.info)Patsubst

---

Next: Format Prev: Translit Up: Text handling

---

Enter node , (file) or (file)node

Substituting text by regular expression
=======================================

   Global substitution in a string is done by `patsubst':

     patsubst(STRING, REGEXP, opt REPLACEMENT)

which searches STRING for matches of REGEXP, and substitutes
REPLACEMENT for each match.  The syntax for regular expressions is the
same as in GNU Emacs.

   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 REGEXP, `\&' being the text the entire
regular expression matched.

   The REPLACEMENT argument can be omitted, in which case the text
matched by REGEXP is deleted.

     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

   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.

     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

   The builtin macro `patsubst' is recognized only when given arguments.