9 |
|
|
10 |
@set beta |
@set beta |
11 |
|
|
12 |
|
@c A simple macro for optional variables. |
13 |
|
@macro ovar{varname} |
14 |
|
@r{[}@var{\varname\}@r{]} |
15 |
|
@end macro |
16 |
|
|
17 |
@dircategory Text Processing Tools |
@dircategory Text Processing Tools |
18 |
@direntry |
@direntry |
19 |
* m4: (m4). A powerful macro processor. |
* m4: (m4). A powerful macro processor. |
207 |
|
|
208 |
* Len:: Calculating length of strings |
* Len:: Calculating length of strings |
209 |
* Index:: Searching for substrings |
* Index:: Searching for substrings |
210 |
* Regexp:: Searching for regular expressions |
* Eregexp and Regexp:: Searching for regular expressions |
211 |
* Substr:: Extracting substrings |
* Substr:: Extracting substrings |
212 |
* Translit:: Translating characters |
* Translit:: Translating characters |
213 |
* Patsubst:: Substituting text by regular expression |
* Epatsubst and Patsubst:: Substituting text by regular expression |
214 |
* Format:: Formatting strings (printf-like) |
* Format:: Formatting strings (printf-like) |
215 |
|
|
216 |
Macros for doing arithmetic |
Macros for doing arithmetic |
583 |
The @samp{Builtin} declaration declares that this macro is implemented |
The @samp{Builtin} declaration declares that this macro is implemented |
584 |
as an m4 builtin; any parenthesised word immediately following is the |
as an m4 builtin; any parenthesised word immediately following is the |
585 |
name of the module that must be loaded. The standards modules include |
name of the module that must be loaded. The standards modules include |
586 |
@samp{m4} (which is always available), @samp{gnu} (for gnu specific m4 |
@samp{m4} (which is always available), @samp{gnu} (for @sc{gnu} specific |
587 |
extensions) and @samp{traditional} (for compatibility with System V |
m4 extensions) and @samp{traditional} (for compatibility with System V |
588 |
m4). |
m4). |
589 |
|
|
590 |
@noindent |
@noindent |
2813 |
@menu |
@menu |
2814 |
* Len:: Calculating length of strings |
* Len:: Calculating length of strings |
2815 |
* Index:: Searching for substrings |
* Index:: Searching for substrings |
2816 |
* Regexp:: Searching for regular expressions |
* Eregexp and Regexp:: Searching for regular expressions |
2817 |
* Substr:: Extracting substrings |
* Substr:: Extracting substrings |
2818 |
* Translit:: Translating characters |
* Translit:: Translating characters |
2819 |
* Patsubst:: Substituting text by regular expression |
* Epatsubst and Patsubst:: Substituting text by regular expression |
2820 |
* Format:: Formatting strings (printf-like) |
* Format:: Formatting strings (printf-like) |
2821 |
@end menu |
@end menu |
2822 |
|
|
2859 |
@result{}-1 |
@result{}-1 |
2860 |
@end example |
@end example |
2861 |
|
|
2862 |
@node Regexp |
@node Eregexp and Regexp |
2863 |
@section Searching for regular expressions |
@section Searching for regular expressions |
2864 |
|
|
2865 |
@cindex regular expressions |
@cindex regular expressions |
2866 |
@cindex GNU extensions |
@cindex GNU extensions |
2867 |
@deffn {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt @var{replacement})} |
@deffn {Builtin (gnu)} eregexp (@var{string}, @var{regexp}, @w{opt @var{replacement})} |
2868 |
Searching for regular expressions is done with the builtin |
Searching for regular expressions is done with the builtin |
2869 |
@code{regexp}, which searches for @var{regexp} in @var{string}. The |
@code{regexp}, which searches for @var{regexp} in @var{string}. The |
2870 |
syntax for regular expressions is the same as in GNU Emacs. |
syntax of regular expressions is similar to that of Perl, @sc{gnu} Awk |
2871 |
@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs |
and Egrep: so called ``Extended Regular Expression''. |
|
Manual}. |
|
2872 |
|
|
2873 |
If @var{replacement} is omitted, @code{regexp} expands to the index of |
If @var{replacement} is omitted, @code{regexp} expands to the index of |
2874 |
the first match of @var{regexp} in @var{string}. If @var{regexp} does |
the first match of @var{regexp} in @var{string}. If @var{replacement} |
2875 |
not match anywhere in @var{string}, it expands to -1. |
is specified and matches, then it expands into @var{replacement}. If |
2876 |
|
@var{regexp} does not match anywhere in @var{string}, it expands to -1. |
2877 |
|
|
2878 |
The builtin macro @code{regexp} is recognized only when given arguments. |
The builtin macro @code{regexp} is recognized only when given arguments. |
2879 |
@end deffn |
@end deffn |
2880 |
|
|
2881 |
@example |
@example |
2882 |
regexp(`GNUs not Unix', `\<[a-z]\w+') |
eregexp(`GNUs not Unix', `\<[a-z]\w+') |
2883 |
@result{}5 |
@result{}5 |
2884 |
regexp(`GNUs not Unix', `\<Q\w*') |
eregexp(`GNUs not Unix', `\<Q\w*') |
2885 |
@result{}-1 |
@result{}-1 |
2886 |
@end example |
@end example |
2887 |
|
|
2891 |
@samp{\&} being the text the entire regular expression matched. |
@samp{\&} being the text the entire regular expression matched. |
2892 |
|
|
2893 |
@example |
@example |
2894 |
|
eregexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***') |
2895 |
|
@result{}*** Unix *** nix *** |
2896 |
|
@end example |
2897 |
|
|
2898 |
|
Originally, regular expressions were much less powerful (basically only |
2899 |
|
@samp{*} was available), but to keep backward compatibility, new |
2900 |
|
operators were implemented with previously invalid sequences, such as |
2901 |
|
@samp{\(}. The following macro is exactly equivalent to @code{eregexp}, |
2902 |
|
but using the old, clumsy syntax. |
2903 |
|
|
2904 |
|
@deffn {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt @var{replacement})} |
2905 |
|
Same as @code{eregexp}, but using the old and clumsy ``Basic Regular |
2906 |
|
Expression'' syntax, the same as in @sc{gnu} Emacs. @xref{Regexps, , |
2907 |
|
Syntax of Regular Expressions, emacs, The @sc{gnu} Emacs Manual}. |
2908 |
|
@end deffn |
2909 |
|
|
2910 |
|
@example |
2911 |
regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***') |
regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***') |
2912 |
@result{}*** Unix *** nix *** |
@result{}*** Unix *** nix *** |
2913 |
@end example |
@end example |
2975 |
while converting them to lowercase. The two first cases are by far the |
while converting them to lowercase. The two first cases are by far the |
2976 |
most common. |
most common. |
2977 |
|
|
2978 |
@node Patsubst |
@node Epatsubst and Patsubst |
2979 |
@section Substituting text by regular expression |
@section Substituting text by regular expression |
2980 |
|
|
2981 |
@cindex regular expressions |
@cindex regular expressions |
2985 |
@deffn {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @w{opt @var{replacement})} |
@deffn {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @w{opt @var{replacement})} |
2986 |
Global substitution in a string is done by @code{patsubst}, which |
Global substitution in a string is done by @code{patsubst}, which |
2987 |
searches @var{string} for matches of @var{regexp}, and substitutes |
searches @var{string} for matches of @var{regexp}, and substitutes |
2988 |
@var{replacement} for each match. The syntax for regular expressions is |
@var{replacement} for each match. It uses Extended Regular Expressions |
2989 |
the same as in GNU Emacs. |
syntax. |
2990 |
|
|
2991 |
The parts of @var{string} that are not covered by any match of |
The parts of @var{string} that are not covered by any match of |
2992 |
@var{regexp} are copied to the expansion. Whenever a match is found, the |
@var{regexp} are copied to the expansion. Whenever a match is found, the |
3003 |
The @var{replacement} argument can be omitted, in which case the text |
The @var{replacement} argument can be omitted, in which case the text |
3004 |
matched by @var{regexp} is deleted. |
matched by @var{regexp} is deleted. |
3005 |
|
|
3006 |
|
The builtin macro @code{patsubst} is recognized only when given |
3007 |
|
arguments. |
3008 |
|
@end deffn |
3009 |
|
|
3010 |
|
When used with two arguments, while @code{eregexp} returns the position |
3011 |
|
of the match, @code{epatsusbt} deletes it: |
3012 |
|
|
3013 |
|
@example |
3014 |
|
epatsubst(`GNUs not Unix', `^', `OBS: ') |
3015 |
|
@result{}OBS: GNUs not Unix |
3016 |
|
epatsubst(`GNUs not Unix', `\<', `OBS: ') |
3017 |
|
@result{}OBS: GNUs OBS: not OBS: Unix |
3018 |
|
epatsubst(`GNUs not Unix', `\w*', `(\&)') |
3019 |
|
@result{}(GNUs)() (not)() (Unix) |
3020 |
|
epatsubst(`GNUs not Unix', `\w+', `(\&)') |
3021 |
|
@result{}(GNUs) (not) (Unix) |
3022 |
|
epatsubst(`GNUs not Unix', `[A-Z][a-z]+') |
3023 |
|
@result{}GN not @comment |
3024 |
|
@end example |
3025 |
|
|
3026 |
|
Here is a slightly more realistic example, which capitalizes individual |
3027 |
|
words or whole sentences, by substituting calls of the macros |
3028 |
|
@code{upcase} and @code{downcase} into the strings. |
3029 |
|
|
3030 |
|
@example |
3031 |
|
define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl |
3032 |
|
define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl |
3033 |
|
define(`capitalize1', |
3034 |
|
`eregexp(`$1', `^(\w)(\w*)', `upcase(`\1')`'downcase(`\2')')')dnl |
3035 |
|
define(`capitalize', |
3036 |
|
`epatsubst(`$1', `\w+', `capitalize1(`\&')')')dnl |
3037 |
|
capitalize(`GNUs not Unix') |
3038 |
|
@result{}Gnus Not Unix |
3039 |
|
@end example |
3040 |
|
|
3041 |
|
While @code{eregexp} replaces the whole input with the replacement as |
3042 |
|
soon as there is a match, @code{epatsubst} replaces each |
3043 |
|
@emph{occurrence} of a match and preserves non matching pieces: |
3044 |
|
|
3045 |
|
@example |
3046 |
|
define(`patreg', |
3047 |
|
`epatsubst($@@) |
3048 |
|
eregexp($@@)')dnl |
3049 |
|
patreg(`bar foo baz Foo', `foo|Foo', `FOO') |
3050 |
|
@result{}bar FOO baz FOO |
3051 |
|
@result{}FOO |
3052 |
|
patreg(`aba abb 121', `(.)(.)\1', `\2\1\2') |
3053 |
|
@result{}bab abb 212 |
3054 |
|
@result{}bab |
3055 |
|
@end example |
3056 |
|
|
3057 |
|
|
3058 |
|
@deffn {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @w{opt @var{replacement})} |
3059 |
|
Same as @code{epatsubst}, but using Basic Regular Expression syntax, see |
3060 |
|
@xref{Eregexp and Regexp}, for more details. |
3061 |
|
@end deffn |
3062 |
|
|
3063 |
|
@c No longer interesting for the documentation per se, but good |
3064 |
|
@c for testing. |
3065 |
|
@ignore |
3066 |
@example |
@example |
3067 |
patsubst(`GNUs not Unix', `^', `OBS: ') |
patsubst(`GNUs not Unix', `^', `OBS: ') |
3068 |
@result{}OBS: GNUs not Unix |
@result{}OBS: GNUs not Unix |
3076 |
@result{}GN not @comment |
@result{}GN not @comment |
3077 |
@end example |
@end example |
3078 |
|
|
|
The builtin macro @code{patsubst} is recognized only when given |
|
|
arguments. |
|
|
@end deffn |
|
|
|
|
|
Here is a slightly more realistic example, which capitalizes individual |
|
|
word or whole sentences, by substituting calls of the macros |
|
|
@code{upcase} and @code{downcase} into the strings. |
|
|
|
|
3079 |
@example |
@example |
3080 |
define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl |
define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl |
3081 |
define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl |
define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl |
3082 |
define(`capitalize1', |
define(`capitalize1', |
3083 |
`regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl |
`regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl |
3084 |
define(`capitalize', |
define(`capitalize', |
3085 |
`patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl |
`patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl |
3086 |
capitalize(`GNUs not Unix') |
capitalize(`GNUs not Unix') |
3087 |
@result{}Gnus Not Unix |
@result{}Gnus Not Unix |
3088 |
@end example |
@end example |
3089 |
|
@end ignore |
3090 |
|
|
3091 |
@node Format |
@node Format |
3092 |
@section Formatted output |
@section Formatted output |
3759 |
is modeled after the C library function @code{printf} (@pxref{Format}). |
is modeled after the C library function @code{printf} (@pxref{Format}). |
3760 |
|
|
3761 |
@item |
@item |
3762 |
Searches and text substitution through regular expressions are |
Searches and text substitution through regular expressions are supported |
3763 |
supported by the @code{regexp} (@pxref{Regexp}) and @code{patsubst} |
by the @code{eregexp}, @code{regexp} (@pxref{Eregexp and Regexp}) and |
3764 |
(@pxref{Patsubst}) builtins. |
@code{epatsubst}, @code{patsubst} (@pxref{Epatsubst and Patsubst}) |
3765 |
|
builtins. |
3766 |
|
|
3767 |
|
@item |
3768 |
|
The syntax of regular expressions in M4 has never clearly formalized. |
3769 |
|
While Open BSD M4 uses extended regular expressions for @code{regexp} |
3770 |
|
and @code{patsubst}, @sc{gnu} M4 uses basic regular expression. Use |
3771 |
|
@code{eregexp} (@pxref{Eregexp and Regexp}) and @code{epatsubst} |
3772 |
|
(@pxref{Epatsubst and Patsubst}) for extended regular expressions. |
3773 |
|
|
3774 |
@item |
@item |
3775 |
The output of shell commands can be read into @code{m4} with |
The output of shell commands can be read into @code{m4} with |