File: autoconf.info,  Node: Forbidden Patterns,  Prev: Set manipulation Macros,  Up: Programming in M4sugar

8.3.10 Forbidden Patterns
-------------------------

M4sugar provides a means to define suspicious patterns, patterns
describing tokens which should not be found in the output.  For
instance, if an Autoconf ‘configure’ script includes tokens such as
‘AC_DEFINE’, or ‘dnl’, then most probably something went wrong
(typically a macro was not evaluated because of overquotation).

   M4sugar forbids all the tokens matching ‘^_?m4_’ and ‘^dnl$’.
Additional layers, such as M4sh and Autoconf, add additional forbidden
patterns to the list.

 -- Macro: m4_pattern_forbid (PATTERN)
     Declare that no token matching PATTERN must be found in the output.
     The output file is (temporarily) split into one word per line as
     part of the ‘autom4te’ post-processing, with each line (and
     therefore word) then being checked against the Perl regular
     expression PATTERN.  If the regular expression matches, and
     ‘m4_pattern_allow’ does not also match, then an error is raised.

     Comments are not checked; this can be a problem if, for instance,
     you have some macro left unexpanded after an ‘#include’.  No
     consensus is currently found in the Autoconf community, as some
     people consider it should be valid to name macros in comments
     (which doesn't make sense to the authors of this documentation:
     input, such as macros, should be documented by ‘dnl’ comments;
     reserving ‘#’-comments to document the output).

     As an example, if you define your own macros that begin with ‘M_’
     and are composed from capital letters and underscores, the
     specification of ‘m4_pattern_forbid([^M_[A-Z_]+])’ will ensure all
     your macros are expanded when not used in comments.

     As an example of a common use of this macro, consider what happens
     in packages that want to use the ‘pkg-config’ script via the
     third-party ‘PKG_CHECK_MODULES’ macro.  By default, if a developer
     checks out the development tree but has not yet installed the
     pkg-config macros locally, they can manage to successfully run
     ‘autoconf’ on the package, but the resulting ‘configure’ file will
     likely result in a confusing shell message about a syntax error on
     the line mentioning the unexpanded ‘PKG_CHECK_MODULES’ macro.  On
     the other hand, if ‘configure.ac’ includes
     ‘m4_pattern_forbid([^PKG_])’, the missing pkg-config macros will be
     detected immediately without allowing ‘autoconf’ to succeed.

   Of course, you might encounter exceptions to these generic rules, for
instance you might have to refer to ‘$m4_flags’.

 -- Macro: m4_pattern_allow (PATTERN)
     Any token matching PATTERN is allowed, including if it matches an
     ‘m4_pattern_forbid’ pattern.

     For example, Gnulib uses ‘m4_pattern_forbid([^gl_])’ to reserve the
     ‘gl_’ namespace for itself, but also uses
     ‘m4_pattern_allow([^gl_ES$])’ to avoid a false negative on the
     valid locale name.