m4: Translit

1 
1 11.5 Translating characters
1 ===========================
1 
1 Character translation is done with 'translit':
1 
1  -- Builtin: translit (STRING, CHARS, [REPLACEMENT])
1      Expands to STRING, with each character that occurs in CHARS
1      translated into the character from REPLACEMENT with the same index.
1 
1      If REPLACEMENT is shorter than CHARS, the excess characters of
1      CHARS are deleted from the expansion; if CHARS is shorter, the
1      excess characters in REPLACEMENT are silently ignored.  If
1      REPLACEMENT is omitted, all characters in STRING that are present
1      in CHARS are deleted from the expansion.  If a character appears
1      more than once in CHARS, only the first instance is used in making
1      the translation.  Only a single translation pass is made, even if
1      characters in REPLACEMENT also appear in CHARS.
1 
1      As a GNU extension, both CHARS and REPLACEMENT can contain
1      character-ranges, e.g., 'a-z' (meaning all lowercase letters) or
1      '0-9' (meaning all digits).  To include a dash '-' in CHARS or
1      REPLACEMENT, place it first or last in the entire string, or as the
1      last character of a range.  Back-to-back ranges can share a common
1      endpoint.  It is not an error for the last character in the range
1      to be 'larger' than the first.  In that case, the range runs
1      backwards, i.e., '9-0' means the string '9876543210'.  The
1      expansion of a range is dependent on the underlying encoding of
1      characters, so using ranges is not always portable between
1      machines.
1 
1      The macro 'translit' is recognized only with parameters.
1 
1      translit(`GNUs not Unix', `A-Z')
1      =>s not nix
1      translit(`GNUs not Unix', `a-z', `A-Z')
1      =>GNUS NOT UNIX
1      translit(`GNUs not Unix', `A-Z', `z-a')
1      =>tmfs not fnix
1      translit(`+,-12345', `+--1-5', `<;>a-c-a')
1      =><;>abcba
1      translit(`abcdef', `aabdef', `bcged')
1      =>bgced
1 
1    In the ASCII encoding, the first example deletes all uppercase
1 letters, the second converts lowercase to uppercase, and the third
1 'mirrors' all uppercase letters, while converting them to lowercase.
1 The two first cases are by far the most common, even though they are not
1 portable to EBCDIC or other encodings.  The fourth example shows a range
1 ending in '-', as well as back-to-back ranges.  The final example shows
1 that 'a' is mapped to 'b', not 'c'; the resulting 'b' is not further
1 remapped to 'g'; the 'd' and 'e' are swapped, and the 'f' is discarded.
1 
1    Omitting CHARS evokes a warning, but still produces output.
1 
1      translit(`abc')
1      error->m4:stdin:1: Warning: too few arguments to builtin `translit'
1      =>abc
1