/[m4]/m4/doc/m4.texinfo
ViewVC logotype

Diff of /m4/doc/m4.texinfo

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.11 by akim, Mon Sep 3 15:05:12 2001 UTC revision 1.12 by akim, Thu Oct 4 08:03:18 2001 UTC
# Line 9  Line 9 
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.
# Line 202  Macros for text handling Line 207  Macros for text handling
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
# Line 578  Description of @samp{regexp}. Line 583  Description of @samp{regexp}.
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
# Line 2808  various ways, extracting substrings, sea Line 2813  various ways, extracting substrings, sea
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    
# Line 2854  index(`gnus, gnats, and armadillos', `da Line 2859  index(`gnus, gnats, and armadillos', `da
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    
# Line 2886  matched by the @var{n}th parenthesized s Line 2891  matched by the @var{n}th parenthesized s
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
# Line 2953  lowercase to uppercase, and the third `m Line 2975  lowercase to uppercase, and the third `m
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
# Line 2963  most common. Line 2985  most common.
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
# Line 2981  being the text the entire regular expres Line 3003  being the text the entire regular expres
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
# Line 2994  patsubst(`GNUs not Unix', `[A-Z][a-z]+') Line 3076  patsubst(`GNUs not Unix', `[A-Z][a-z]+')
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
# Line 3684  Formatted output is supported through th Line 3759  Formatted output is supported through th
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

Legend:
Removed from v.1.11  
changed lines
  Added in v.1.12

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26