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