bin/autom4te.in

   1 #! @PERL@ -w
   2 # -*- perl -*-
   3 # @configure_input@
   4
   5 eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S "$0" "$@";; esac'
   6     if 0;
   7
   8 # autom4te - Wrapper around M4 libraries.
   9 # Copyright (C) 2001, 2002, 2003, 2005, 2006, 2007, 2008 Free Software
  10 # Foundation, Inc.
  11
  12 # This program is free software: you can redistribute it and/or modify
  13 # it under the terms of the GNU General Public License as published by
  14 # the Free Software Foundation; either version 2, or (at your option)
  15 # any later version.
  16
  17 # This program is distributed in the hope that it will be useful,
  18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 # GNU General Public License for more details.
  21
  22 # You should have received a copy of the GNU General Public License
  23 # along with this program; if not, write to the Free Software
  24 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  25 # 02110-1301, USA.
  26
  27
  28 BEGIN
  29 {
  30   my $datadir = $ENV{'autom4te_perllibdir'} || '@datadir@';
  31   unshift @INC, $datadir;
  32
  33   # Override SHELL.  On DJGPP SHELL may not be set to a shell
  34   # that can handle redirection and quote arguments correctly,
  35   # e.g.: COMMAND.COM.  For DJGPP always use the shell that configure
  36   # has detected.
  37   $ENV{'SHELL'} = '@SHELL@' if ($^O eq 'dos');
  38 }
  39
  40 use Autom4te::C4che;
  41 use Autom4te::ChannelDefs;
  42 use Autom4te::Channels;
  43 use Autom4te::FileUtils;
  44 use Autom4te::General;
  45 use Autom4te::XFile;
  46 use File::Basename;
  47 use strict;
  48
  49 # Data directory.
  50 my $datadir = $ENV{'AC_MACRODIR'} || '@datadir@';
  51
  52 # $LANGUAGE{LANGUAGE} -- Automatic options for LANGUAGE.
  53 my %language;
  54
  55 my $output = '-';
  56
  57 # Mode of the output file except for traces.
  58 my $mode = "0666";
  59
  60 # If melt, don't use frozen files.
  61 my $melt = 0;
  62
  63 # Names of the cache directory, cache directory index, trace cache
  64 # prefix, and output cache prefix.  And the IO object for the index.
  65 my $cache;
  66 my $icache;
  67 my $tcache;
  68 my $ocache;
  69 my $icache_file;
  70
  71 # The macros to trace mapped to their format, as specified by the
  72 # user.
  73 my %trace;
  74
  75 # The macros the user will want to trace in the future.
  76 # We need `include' to get the included file, `m4_pattern_forbid' and
  77 # `m4_pattern_allow' to check the output.
  78 #
  79 # FIXME: What about `sinclude'?
  80 my @preselect = ('include',
  81                  'm4_pattern_allow', 'm4_pattern_forbid',
  82                  '_m4_warn');
  83
  84 # M4 include path.
  85 my @include;
  86
  87 # Do we freeze?
  88 my $freeze = 0;
  89
  90 # $M4.
  91 my $m4 = $ENV{"M4"} || '@M4@';
  92 # Some non-GNU m4's don't reject the --help option, so give them /dev/null.
  93 fatal "need GNU m4 1.4 or later: $m4"
  94   if system "$m4 --help </dev/null 2>&1 | grep reload-state >/dev/null";
  95
  96 # Set some high recursion limit as the default limit, 250, has already
  97 # been hit with AC_OUTPUT.  Don't override the user's choice.
  98 $m4 .= ' --nesting-limit=1024'
  99   if " $m4 " !~ / (--nesting-limit(=[0-9]+)?|-L[0-9]*) /;
 100
 101
 102 # @M4_BUILTIN -- M4 builtins and a useful comment.
 103 my @m4_builtin = `echo dumpdef | $m4 2>&1 >/dev/null`;
 104 map { s/:.*//;s/\W// } @m4_builtin;
 105
 106
 107 # %M4_BUILTIN_ALTERNATE_NAME
 108 # --------------------------
 109 # The builtins are renamed, e.g., `define' is renamed `m4_define'.
 110 # So map `define' to `m4_define' and conversely.
 111 # Some macros don't follow this scheme: be sure to properly map to their
 112 # alternate name too.
 113 #
 114 # This is because GNU M4 1.4's tracing of builtins is buggy.  When run on
 115 # this input:
 116 #
 117 # | divert(-1)
 118 # | changequote([, ])
 119 # | define([m4_eval], defn([eval]))
 120 # | eval(1)
 121 # | m4_eval(2)
 122 # | undefine([eval])
 123 # | m4_eval(3)
 124 #
 125 # it behaves this way:
 126 #
 127 # | % m4 input.m4 -da -t eval
 128 # | m4trace: -1- eval(1)
 129 # | m4trace: -1- m4_eval(2)
 130 # | m4trace: -1- m4_eval(3)
 131 # | %
 132 #
 133 # Conversely:
 134 #
 135 # | % m4 input.m4 -da -t m4_eval
 136 # | %
 137 #
 138 # So we will merge them, i.e., tracing `BUILTIN' or tracing
 139 # `m4_BUILTIN' will be the same: tracing both, but honoring the
 140 # *last* trace specification.
 141 #
 142 # FIXME: This is not enough: in the output `$0' will be `BUILTIN'
 143 # sometimes and `m4_BUILTIN' at others.  We should return a unique name,
 144 # the one specified by the user.
 145 #
 146 # FIXME: To be absolutely rigorous, I would say that given that we
 147 # _redefine_ divert (instead of _copying_ it), divert and the like
 148 # should not be part of this list.
 149 my %m4_builtin_alternate_name;
 150 @m4_builtin_alternate_name{"$_", "m4_$_"} = ("m4_$_", "$_")
 151   foreach (grep { !/m4wrap|m4exit|dnl|ifelse|__.*__/ } @m4_builtin);
 152 @m4_builtin_alternate_name{"ifelse", "m4_if"}   = ("m4_if", "ifelse");
 153 @m4_builtin_alternate_name{"m4exit", "m4_exit"} = ("m4_exit", "m4exit");
 154 @m4_builtin_alternate_name{"m4wrap", "m4_wrap"} = ("m4_wrap", "m4wrap");
 155
 156
 157 # $HELP
 158 # -----
 159 $help = "Usage: $0 [OPTION] ... [FILES]
 160
 161 Run GNU M4 on the FILES, avoiding useless runs.  Output the traces if tracing,
 162 the frozen file if freezing, otherwise the expansion of the FILES.
 163
 164 If some of the FILES are named \`FILE.m4f\' they are considered to be M4
 165 frozen files of all the previous files (which are therefore not loaded).
 166 If \`FILE.m4f\' is not found, then \`FILE.m4\' will be used, together with
 167 all the previous files.
 168
 169 Some files may be optional, i.e., will only be processed if found in the
 170 include path, but then must end in \`.m4?\';  the question mark is not part of
 171 the actual file name.
 172
 173 Operation modes:
 174   -h, --help               print this help, then exit
 175   -V, --version            print version number, then exit
 176   -v, --verbose            verbosely report processing
 177   -d, --debug              don\'t remove temporary files
 178   -o, --output=FILE        save output in FILE (defaults to \`-\', stdout)
 179   -f, --force              don\'t rely on cached values
 180   -W, --warnings=CATEGORY  report the warnings falling in CATEGORY
 181   -l, --language=LANG      specify the set of M4 macros to use
 182   -C, --cache=DIRECTORY    preserve results for future runs in DIRECTORY
 183       --no-cache           disable the cache
 184   -m, --mode=OCTAL         change the non trace output file mode (0666)
 185   -M, --melt               don\'t use M4 frozen files
 186
 187 Languages include:
 188   \`Autoconf\'   create Autoconf configure scripts
 189   \`Autotest\'   create Autotest test suites
 190   \`M4sh\'       create M4sh shell scripts
 191   \`M4sugar\'    create M4sugar output
 192
 193 " . Autom4te::ChannelDefs::usage . "
 194
 195 The environment variables \`M4\' and \`WARNINGS\' are honored.
 196
 197 Library directories:
 198   -B, --prepend-include=DIR  prepend directory DIR to search path
 199   -I, --include=DIR          append directory DIR to search path
 200
 201 Tracing:
 202   -t, --trace=MACRO[:FORMAT]  report the MACRO invocations
 203   -p, --preselect=MACRO       prepare to trace MACRO in a future run
 204
 205 Freezing:
 206   -F, --freeze   produce an M4 frozen state file for FILES
 207
 208 FORMAT defaults to \`\$f:\$l:\$n:\$%\', and can use the following escapes:
 209   \$\$     literal \$
 210   \$f     file where macro was called
 211   \$l     line where macro was called
 212   \$d     nesting depth of macro call
 213   \$n     name of the macro
 214   \$NUM   argument NUM, unquoted and with newlines
 215   \$SEP\@  all arguments, with newlines, quoted, and separated by SEP
 216   \$SEP*  all arguments, with newlines, unquoted, and separated by SEP
 217   \$SEP%  all arguments, without newlines, unquoted, and separated by SEP
 218 SEP can be empty for the default (comma for \@ and *, colon for %),
 219 a single character for that character, or {STRING} to use a string.
 220
 221 Report bugs to <bug-autoconf\@gnu.org>.
 222 ";
 223
 224 # $VERSION
 225 # --------
 226 $version =  <<"EOF";
 227 autom4te (@PACKAGE_NAME@) @VERSION@
 228 Copyright (C) @RELEASE_YEAR@ Free Software Foundation, Inc.
 229 License GPLv2+: GNU GPL version 2 or later
 230 <http://gnu.org/licenses/old-licenses/gpl-2.0.html>
 231 This is free software: you are free to change and redistribute it.
 232 There is NO WARRANTY, to the extent permitted by law.
 233
 234 Written by Akim Demaille.
 235 EOF
 236
 237
 238 ## ---------- ##
 239 ## Routines.  ##
 240 ## ---------- ##
 241
 242
 243 # $OPTION
 244 # files_to_options (@FILE)
 245 # ------------------------
 246 # Transform Autom4te conventions (e.g., using foo.m4f to designate a frozen
 247 # file) into a suitable command line for M4 (e.g., using --reload-state).
 248 sub files_to_options (@)
 249 {
 250   my (@file) = @_;
 251   my @res;
 252   foreach my $file (@file)
 253     {
 254       my $arg = shell_quote ($file);
 255       if ($file =~ /\.m4f$/)
 256         {
 257           $arg = "--reload-state=$arg";
 258         }
 259       push @res, $arg;
 260     }
 261   return join ' ', @res;
 262 }
 263
 264
 265 # load_configuration ($FILE)
 266 # --------------------------
 267 # Load the configuration $FILE.
 268 sub load_configuration ($)
 269 {
 270   my ($file) = @_;
 271   use Text::ParseWords;
 272
 273   my $cfg = new Autom4te::XFile ("< " . open_quote ($file));
 274   my $lang;
 275   while ($_ = $cfg->getline)
 276     {
 277       chomp;
 278       # Comments.
 279       next
 280         if /^\s*(\#.*)?$/;
 281
 282       my @words = shellwords ($_);
 283       my $type = shift @words;
 284       if ($type eq 'begin-language:')
 285         {
 286           fatal "$file:$.: end-language missing for: $lang"
 287             if defined $lang;
 288           $lang = lc $words[0];
 289         }
 290       elsif ($type eq 'end-language:')
 291         {
 292           error "$file:$.: end-language mismatch: $lang"
 293             if $lang ne lc $words[0];
 294           $lang = undef;
 295         }
 296       elsif ($type eq 'args:')
 297         {
 298           fatal "$file:$.: no current language"
 299             unless defined $lang;
 300           push @{$language{$lang}}, @words;
 301         }
 302       else
 303         {
 304           error "$file:$.: unknown directive: $type";
 305         }
 306     }
 307 }
 308
 309
 310 # parse_args ()
 311 # -------------
 312 # Process any command line arguments.
 313 sub parse_args ()
 314 {
 315   # We want to look for the early options, which should not be found
 316   # in the configuration file.  Prepend to the user arguments.
 317   # Perform this repeatedly so that we can use --language in language
 318   # definitions.  Beware that there can be several --language
 319   # invocations.
 320   my @language;
 321   do {
 322     @language = ();
 323     use Getopt::Long;
 324     Getopt::Long::Configure ("pass_through", "permute");
 325     GetOptions ("l|language=s" => \@language);
 326
 327     foreach (@language)
 328       {
 329         error "unknown language: $_"
 330           unless exists $language{lc $_};
 331         unshift @ARGV, @{$language{lc $_}};
 332       }
 333   } while @language;
 334
 335   # --debug is useless: it is parsed below.
 336   if (exists $ENV{'AUTOM4TE_DEBUG'})
 337     {
 338       print STDERR "$me: concrete arguments:\n";
 339       foreach my $arg (@ARGV)
 340         {
 341           print STDERR "| $arg\n";
 342         }
 343     }
 344
 345   # Process the arguments for real this time.
 346   my @trace;
 347   my @prepend_include;
 348   parse_WARNINGS;
 349   getopt
 350     (
 351      # Operation modes:
 352      "o|output=s"   => \$output,
 353      "W|warnings=s" => \&parse_warnings,
 354      "m|mode=s"     => \$mode,
 355      "M|melt"       => \$melt,
 356
 357      # Library directories:
 358      "B|prepend-include=s" => \@prepend_include,
 359      "I|include=s"         => \@include,
 360
 361      # Tracing:
 362      # Using a hash for traces is seducing.  Unfortunately, upon `-t FOO',
 363      # instead of mapping `FOO' to undef, Getopt maps it to `1', preventing
 364      # us from distinguishing `-t FOO' from `-t FOO=1'.  So let's do it
 365      # by hand.
 366      "t|trace=s"     => \@trace,
 367      "p|preselect=s" => \@preselect,
 368
 369      # Freezing.
 370      "F|freeze" => \$freeze,
 371
 372      # Caching.
 373      "C|cache=s" => \$cache,
 374      "no-cache"  => sub { $cache = undef; },
 375     );
 376
 377   fatal "too few arguments
 378 Try `$me --help' for more information."
 379     unless @ARGV;
 380
 381   # Freezing:
 382   # We cannot trace at the same time (well, we can, but it sounds insane).
 383   # And it implies melting: there is risk not to update properly using
 384   # old frozen files, and worse yet: we could load a frozen file and
 385   # refreeze it!  A sort of caching :)
 386   fatal "cannot freeze and trace"
 387     if $freeze && @trace;
 388   $melt = 1
 389     if $freeze;
 390
 391   # Names of the cache directory, cache directory index, trace cache
 392   # prefix, and output cache prefix.  If the cache is not to be
 393   # preserved, default to a temporary directory (automatically removed
 394   # on exit).
 395   $cache = $tmp
 396     unless $cache;
 397   $icache = "$cache/requests";
 398   $tcache = "$cache/traces.";
 399   $ocache = "$cache/output.";
 400
 401   # Normalize the includes: the first occurrence is enough, several is
 402   # a pain since it introduces a useless difference in the path which
 403   # invalidates the cache.  And strip `.' which is implicit and always
 404   # first.
 405   @include = grep { !/^\.$/ } uniq (reverse(@prepend_include), @include);
 406
 407   # Convert @trace to %trace, and work around the M4 builtins tracing
 408   # problem.
 409   # The default format is `$f:$l:$n:$%'.
 410   foreach (@trace)
 411     {
 412       /^([^:]+)(?::(.*))?$/ms;
 413       $trace{$1} = defined $2 ? $2 : '$f:$l:$n:$%';
 414       $trace{$m4_builtin_alternate_name{$1}} = $trace{$1}
 415         if exists $m4_builtin_alternate_name{$1};
 416     }
 417
 418   # Work around the M4 builtins tracing problem for @PRESELECT.
 419   push (@preselect,
 420         map { $m4_builtin_alternate_name{$_} }
 421         grep { exists $m4_builtin_alternate_name{$_} } @preselect);
 422
 423   # If we find frozen files, then all the files before it are
 424   # discarded: the frozen file is supposed to include them all.
 425   #
 426   # We don't want to depend upon m4's --include to find the top level
 427   # files, so we use `find_file' here.  Try to get a canonical name,
 428   # as it's part of the key for caching.  And some files are optional
 429   # (also handled by `find_file').
 430   my @argv;
 431   foreach (@ARGV)
 432     {
 433       if ($_ eq '-')
 434         {
 435           push @argv, $_;
 436         }
 437       elsif (/\.m4f$/)
 438         {
 439           # Frozen files are optional => pass a `?' to `find_file'.
 440           my $file = find_file ("$_?", @include);
 441           if (!$melt && $file)
 442             {
 443               @argv = ($file);
 444             }
 445           else
 446             {
 447               s/\.m4f$/.m4/;
 448               push @argv, find_file ($_, @include);
 449             }
 450         }
 451       else
 452         {
 453           my $file = find_file ($_, @include);
 454           push @argv, $file
 455             if $file;
 456         }
 457     }
 458   @ARGV = @argv;
 459 }
 460
 461
 462 # handle_m4 ($REQ, @MACRO)
 463 # ------------------------
 464 # Run m4 on the input files, and save the traces on the @MACRO.
 465 sub handle_m4 ($@)
 466 {
 467   my ($req, @macro) = @_;
 468
 469   # GNU m4 appends when using --debugfile/--error-output.
 470   unlink ($tcache . $req->id . "t");
 471
 472   # Run m4.
 473   #
 474   # We don't output directly to the cache files, to avoid problems
 475   # when we are interrupted (that leaves corrupted files).
 476   xsystem ("$m4"
 477            . join (' --include=', '', map { shell_quote ($_) } @include)
 478            . ' --debug=aflq'
 479            . (!exists $ENV{'AUTOM4TE_NO_FATAL'} ? ' --fatal-warning' : '')
 480            . " @M4_DEBUGFILE@=" . shell_quote ("$tcache" . $req->id . "t")
 481            . join (' --trace=',   '', sort @macro)
 482            . " " . files_to_options (@ARGV)
 483            . " > " . shell_quote ("$ocache" . $req->id . "t"));
 484
 485   # Everything went ok: preserve the outputs.
 486   foreach my $file (map { $_ . $req->id } ($tcache, $ocache))
 487     {
 488       use File::Copy;
 489       move ("${file}t", "$file")
 490         or fatal "cannot rename ${file}t as $file: $!";
 491     }
 492 }
 493
 494
 495 # warn_forbidden ($WHERE, $WORD, %FORBIDDEN)
 496 # ------------------------------------------
 497 # $WORD is forbidden.  Warn with a dedicated error message if in
 498 # %FORBIDDEN, otherwise a simple `error: possibly undefined macro'
 499 # will do.
 500 my $first_warn_forbidden = 1;
 501 sub warn_forbidden ($$%)
 502 {
 503   my ($where, $word, %forbidden) = @_;
 504   my $message;
 505
 506   for my $re (sort keys %forbidden)
 507     {
 508       if ($word =~ $re)
 509         {
 510           $message = $forbidden{$re};
 511           last;
 512         }
 513     }
 514   $message ||= "possibly undefined macro: $word";
 515   warn "$where: error: $message\n";
 516   if ($first_warn_forbidden)
 517     {
 518       warn <<EOF;
 519       If this token and others are legitimate, please use m4_pattern_allow.
 520       See the Autoconf documentation.
 521 EOF
 522       $first_warn_forbidden = 0;
 523     }
 524 }
 525
 526
 527 # handle_output ($REQ, $OUTPUT)
 528 # -----------------------------
 529 # Run m4 on the input files, perform quadrigraphs substitution, check for
 530 # forbidden tokens, and save into $OUTPUT.
 531 sub handle_output ($$)
 532 {
 533   my ($req, $output) = @_;
 534
 535   verb "creating $output";
 536
 537   # Load the forbidden/allowed patterns.
 538   handle_traces ($req, "$tmp/patterns",
 539                  ('m4_pattern_forbid' => 'forbid:$1:$2',
 540                   'm4_pattern_allow'  => 'allow:$1'));
 541   my @patterns = new Autom4te::XFile ("< " . open_quote ("$tmp/patterns"))->getlines;
 542   chomp @patterns;
 543   my %forbidden =
 544     map { /^forbid:([^:]+):.+$/ => /^forbid:[^:]+:(.+)$/ } @patterns;
 545   my $forbidden = join ('|', map { /^forbid:([^:]+)/ } @patterns) || "^\$";
 546   my $allowed   = join ('|', map { /^allow:([^:]+)/  } @patterns) || "^\$";
 547
 548   verb "forbidden tokens: $forbidden";
 549   verb "forbidden token : $_ => $forbidden{$_}"
 550     foreach (sort keys %forbidden);
 551   verb "allowed   tokens: $allowed";
 552
 553   # Read the (cached) raw M4 output, produce the actual result.  We
 554   # have to use the 2nd arg to have Autom4te::XFile honor the third, but then
 555   # stdout is to be handled by hand :(.  Don't use fdopen as it means
 556   # we will close STDOUT, which we already do in END.
 557   my $out = new Autom4te::XFile;
 558   if ($output eq '-')
 559     {
 560       $out->open (">$output");
 561     }
 562   else
 563     {
 564       $out->open($output, O_CREAT | O_WRONLY | O_TRUNC, oct ($mode));
 565     }
 566   fatal "cannot create $output: $!"
 567     unless $out;
 568   my $in = new Autom4te::XFile ("< " . open_quote ($ocache . $req->id));
 569
 570   my %prohibited;
 571   my $res;
 572   while ($_ = $in->getline)
 573     {
 574       s/\s+$//;
 575       s/__oline__/$./g;
 576       s/\@<:\@/[/g;
 577       s/\@:>\@/]/g;
 578       s/\@\{:\@/(/g;
 579       s/\@:\}\@/)/g;
 580       s/\@S\|\@/\$/g;
 581       s/\@%:\@/#/g;
 582
 583       $res = $_;
 584
 585       # Don't complain in comments.  Well, until we have something
 586       # better, don't consider `#include' etc. are comments.
 587       s/\#.*//
 588         unless /^\#\s*(if|include|endif|ifdef|ifndef|define)\b/;
 589       foreach (split (/\W+/))
 590         {
 591           $prohibited{$_} = $.
 592             if !/^$/ && /$forbidden/o && !/$allowed/o && ! exists $prohibited{$_};
 593         }
 594
 595       # Performed *last*: the empty quadrigraph.
 596       $res =~ s/\@&t\@//g;
 597
 598       print $out "$res\n";
 599     }
 600
 601   $out->close();
 602
 603   # If no forbidden words, we're done.
 604   return
 605     if ! %prohibited;
 606
 607   # Locate the forbidden words in the last input file.
 608   # This is unsatisfying but...
 609   $exit_code = 1;
 610   if ($ARGV[$#ARGV] ne '-')
 611     {
 612       my $prohibited = '\b(' . join ('|', keys %prohibited) . ')\b';
 613       my $file = new Autom4te::XFile ("< " . open_quote ($ARGV[$#ARGV]));
 614
 615       while ($_ = $file->getline)
 616         {
 617           # Don't complain in comments.  Well, until we have something
 618           # better, don't consider `#include' etc. to be comments.
 619           s/\#.*//
 620             unless /^\#(if|include|endif|ifdef|ifndef|define)\b/;
 621
 622           # Complain once per word, but possibly several times per line.
 623           while (/$prohibited/)
 624             {
 625               my $word = $1;
 626               warn_forbidden ("$ARGV[$#ARGV]:$.", $word, %forbidden);
 627               delete $prohibited{$word};
 628               # If we're done, exit.
 629               return
 630                 if ! %prohibited;
 631               $prohibited = '\b(' . join ('|', keys %prohibited) . ')\b';
 632             }
 633         }
 634     }
 635   warn_forbidden ("$output:$prohibited{$_}", $_, %forbidden)
 636     foreach (sort { $prohibited{$a} <=> $prohibited{$b} } keys %prohibited);
 637 }
 638
 639
 640 ## --------------------- ##
 641 ## Handling the traces.  ##
 642 ## --------------------- ##
 643
 644
 645 # $M4_MACRO
 646 # trace_format_to_m4 ($FORMAT)
 647 # ----------------------------
 648 # Convert a trace $FORMAT into a M4 trace processing macro's body.
 649 sub trace_format_to_m4 ($)
 650 {
 651   my ($format) = @_;
 652   my $underscore = $_;
 653   my %escape = (# File name.
 654                 'f' => '$1',
 655                 # Line number.
 656                 'l' => '$2',
 657                 # Depth.
 658                 'd' => '$3',
 659                 # Name (also available as $0).
 660                 'n' => '$4',
 661                 # Escaped dollar.
 662                 '$' => '$');
 663
 664   my $res = '';
 665   $_ = $format;
 666   while ($_)
 667     {
 668       # $n -> $(n + 4)
 669       if (s/^\$(\d+)//)
 670         {
 671           $res .= "\$" . ($1 + 4);
 672         }
 673       # $x, no separator given.
 674       elsif (s/^\$([fldn\$])//)
 675         {
 676           $res .= $escape{$1};
 677         }
 678       # $.x or ${sep}x.
 679       elsif (s/^\$\{([^}]*)\}([@*%])//
 680             || s/^\$(.?)([@*%])//)
 681         {
 682           # $@, list of quoted effective arguments.
 683           if ($2 eq '@')
 684             {
 685               $res .= ']at_at([' . ($1 ? $1 : ',') . '], $@)[';
 686             }
 687           # $*, list of unquoted effective arguments.
 688           elsif ($2 eq '*')
 689             {
 690               $res .= ']at_star([' . ($1 ? $1 : ',') . '], $@)[';
 691             }
 692           # $%, list of flattened unquoted effective arguments.
 693           elsif ($2 eq '%')
 694             {
 695               $res .= ']at_percent([' . ($1 ? $1 : ':') . '], $@)[';
 696             }
 697         }
 698       elsif (/^(\$.)/)
 699         {
 700           error "invalid escape: $1";
 701         }
 702       else
 703         {
 704           s/^([^\$]+)//;
 705           $res .= $1;
 706         }
 707     }
 708
 709   $_ = $underscore;
 710   return '[[' . $res . ']]';
 711 }
 712
 713
 714 # handle_traces($REQ, $OUTPUT, %TRACE)
 715 # ------------------------------------
 716 # We use M4 itself to process the traces.  But to avoid name clashes when
 717 # processing the traces, the builtins are disabled, and moved into `at_'.
 718 # Actually, all the low level processing macros are in `at_' (and `_at_').
 719 # To avoid clashes between user macros and `at_' macros, the macros which
 720 # implement tracing are in `AT_'.
 721 #
 722 # Having $REQ is needed to neutralize the macros which have been traced,
 723 # but are not wanted now.
 724 sub handle_traces ($$%)
 725 {
 726   my ($req, $output, %trace) = @_;
 727
 728   verb "formatting traces for `$output': " . join (', ', sort keys %trace);
 729
 730   # Processing the traces.
 731   my $trace_m4 = new Autom4te::XFile ("> " . open_quote ("$tmp/traces.m4"));
 732
 733   $_ = <<'EOF';
 734   divert(-1)
 735   changequote([, ])
 736   # _at_MODE(SEPARATOR, ELT1, ELT2...)
 737   # ----------------------------------
 738   # List the elements, separating then with SEPARATOR.
 739   # MODE can be:
 740   #  `at'       -- the elements are enclosed in brackets.
 741   #  `star'     -- the elements are listed as are.
 742   #  `percent'  -- the elements are `flattened': spaces are singled out,
 743   #                and no new line remains.
 744   define([_at_at],
 745   [at_ifelse([$#], [1], [],
 746              [$#], [2], [[[$2]]],
 747              [[[$2]][$1]$0([$1], at_shift(at_shift($@)))])])
 748
 749   define([_at_percent],
 750   [at_ifelse([$#], [1], [],
 751              [$#], [2], [at_flatten([$2])],
 752              [at_flatten([$2])[$1]$0([$1], at_shift(at_shift($@)))])])
 753
 754   define([_at_star],
 755   [at_ifelse([$#], [1], [],
 756              [$#], [2], [[$2]],
 757              [[$2][$1]$0([$1], at_shift(at_shift($@)))])])
 758
 759   # FLATTEN quotes its result.
 760   # Note that the second pattern is `newline, tab or space'.  Don't lose
 761   # the tab!
 762   define([at_flatten],
 763   [at_patsubst(at_patsubst(at_patsubst(at_patsubst([[[[$1]]]], [\\\n]),
 764                                        [[\n\t ]+], [ ]),
 765                            [ *\(.\)$], [\1]),
 766                [^ *\(.*\)], [[\1]])])
 767
 768   define([at_args],    [at_shift(at_shift(at_shift(at_shift(at_shift($@)))))])
 769   define([at_at],      [_$0([$1], at_args($@))])
 770   define([at_percent], [_$0([$1], at_args($@))])
 771   define([at_star],    [_$0([$1], at_args($@))])
 772
 773 EOF
 774   s/^  //mg;s/\\t/\t/mg;s/\\n/\n/mg;
 775   print $trace_m4 $_;
 776
 777   # If you trace `define', then on `define([m4_exit], defn([m4exit])' you
 778   # will produce
 779   #
 780   #    AT_define([m4sugar.m4], [115], [1], [define], [m4_exit], <m4exit>)
 781   #
 782   # Since `<m4exit>' is not quoted, the outer m4, when processing
 783   # `trace.m4' will exit prematurely.  Hence, move all the builtins to
 784   # the `at_' name space.
 785
 786   print $trace_m4 "# Copy the builtins.\n";
 787   map { print $trace_m4 "define([at_$_], defn([$_]))\n" } @m4_builtin;
 788   print $trace_m4 "\n";
 789
 790   print $trace_m4 "# Disable them.\n";
 791   map { print $trace_m4 "at_undefine([$_])\n" } @m4_builtin;
 792   print $trace_m4 "\n";
 793
 794
 795   # Neutralize traces: we don't want traces of cached requests (%REQUEST).
 796   print $trace_m4
 797    "## -------------------------------------- ##\n",
 798    "## By default neutralize all the traces.  ##\n",
 799    "## -------------------------------------- ##\n",
 800    "\n";
 801   print $trace_m4 "at_define([AT_$_], [at_dnl])\n"
 802     foreach (sort keys %{$req->macro});
 803   print $trace_m4 "\n";
 804
 805   # Implement traces for current requests (%TRACE).
 806   print $trace_m4
 807     "## ------------------------- ##\n",
 808     "## Trace processing macros.  ##\n",
 809     "## ------------------------- ##\n",
 810     "\n";
 811   foreach (sort keys %trace)
 812     {
 813       # Trace request can be embed \n.
 814       (my $comment = "Trace $_:$trace{$_}") =~ s/^/\# /;
 815       print $trace_m4 "$comment\n";
 816       print $trace_m4 "at_define([AT_$_],\n";
 817       print $trace_m4 trace_format_to_m4 ($trace{$_}) . ")\n\n";
 818     }
 819   print $trace_m4 "\n";
 820
 821   # Reenable output.
 822   print $trace_m4 "at_divert(0)at_dnl\n";
 823
 824   # Transform the traces from m4 into an m4 input file.
 825   # Typically, transform:
 826   #
 827   # | m4trace:configure.ac:3: -1- AC_SUBST([exec_prefix], [NONE])
 828   #
 829   # into
 830   #
 831   # | AT_AC_SUBST([configure.ac], [3], [1], [AC_SUBST], [exec_prefix], [NONE])
 832   #
 833   # Pay attention that the file name might include colons, if under DOS
 834   # for instance, so we don't use `[^:]+'.
 835   my $traces = new Autom4te::XFile ("< " . open_quote ($tcache . $req->id));
 836   while ($_ = $traces->getline)
 837     {
 838       # Trace with arguments, as the example above.  We don't try
 839       # to match the trailing parenthesis as it might be on a
 840       # separate line.
 841       s{^m4trace:(.+):(\d+): -(\d+)- ([^(]+)\((.*)$}
 842        {AT_$4([$1], [$2], [$3], [$4], $5};
 843       # Traces without arguments, always on a single line.
 844       s{^m4trace:(.+):(\d+): -(\d+)- ([^)]*)\n$}
 845        {AT_$4([$1], [$2], [$3], [$4])\n};
 846       print $trace_m4 "$_";
 847     }
 848   $trace_m4->close;
 849
 850   my $in = new Autom4te::XFile ("$m4 " . shell_quote ("$tmp/traces.m4") . " |");
 851   my $out = new Autom4te::XFile ("> " . open_quote ($output));
 852
 853   # This is dubious: should we really transform the quadrigraphs in
 854   # traces?  It might break balanced [ ] etc. in the output.  The
 855   # consensus seeems to be that traces are more useful this way.
 856   while ($_ = $in->getline)
 857     {
 858       # It makes no sense to try to transform __oline__.
 859       s/\@<:\@/[/g;
 860       s/\@:>\@/]/g;
 861       s/\@\{:\@/(/g;
 862       s/\@:\}\@/)/g;
 863       s/\@S\|\@/\$/g;
 864       s/\@%:\@/#/g;
 865       s/\@&t\@//g;
 866       print $out $_;
 867     }
 868 }
 869
 870
 871 # $BOOL
 872 # up_to_date ($REQ)
 873 # -----------------
 874 # Are the cache files of $REQ up to date?
 875 # $REQ is `valid' if it corresponds to the request and exists, which
 876 # does not mean it is up to date.  It is up to date if, in addition,
 877 # its files are younger than its dependencies.
 878 sub up_to_date ($)
 879 {
 880   my ($req) = @_;
 881
 882   return 0
 883     if ! $req->valid;
 884
 885   my $tfile = $tcache . $req->id;
 886   my $ofile = $ocache . $req->id;
 887
 888   # We can't answer properly if the traces are not computed since we
 889   # need to know what other files were included.  Actually, if any of
 890   # the cache files is missing, we are not up to date.
 891   return 0
 892     if ! -f $tfile || ! -f $ofile;
 893
 894   # The youngest of the cache files must be older than the oldest of
 895   # the dependencies.
 896   my $tmtime = mtime ($tfile);
 897   my $omtime = mtime ($ofile);
 898   my ($file, $mtime) = ($tmtime < $omtime
 899                         ? ($ofile, $omtime) : ($tfile, $tmtime));
 900
 901   # We depend at least upon the arguments.
 902   my @dep = @ARGV;
 903
 904   # stdin is always out of date.
 905   if (grep { $_ eq '-' } @dep)
 906     { return 0 }
 907
 908   # Files may include others.  We can use traces since we just checked
 909   # if they are available.
 910   handle_traces ($req, "$tmp/dependencies",
 911                  ('include'    => '$1',
 912                   'm4_include' => '$1'));
 913   my $deps = new Autom4te::XFile ("< " . open_quote ("$tmp/dependencies"));
 914   while ($_ = $deps->getline)
 915     {
 916       chomp;
 917       my $file = find_file ("$_?", @include);
 918       # If a file which used to be included is no longer there, then
 919       # don't say it's missing (it might no longer be included).  But
 920       # of course, that causes the output to be outdated (as if the
 921       # time stamp of that missing file was newer).
 922       return 0
 923         if ! $file;
 924       push @dep, $file;
 925     }
 926
 927   # If $FILE is younger than one of its dependencies, it is outdated.
 928   return up_to_date_p ($file, @dep);
 929 }
 930
 931
 932 ## ---------- ##
 933 ## Freezing.  ##
 934 ## ---------- ##
 935
 936 # freeze ($OUTPUT)
 937 # ----------------
 938 sub freeze ($)
 939 {
 940   my ($output) = @_;
 941
 942   # When processing the file with diversion disabled, there must be no
 943   # output but comments and empty lines.
 944   my $result = xqx ("$m4"
 945                     . ' --fatal-warning'
 946                     . join (' --include=', '', map { shell_quote ($_) } @include)
 947                     . ' --define=divert'
 948                     . " " . files_to_options (@ARGV)
 949                     . ' </dev/null');
 950   $result =~ s/#.*\n//g;
 951   $result =~ s/^\n//mg;
 952
 953   fatal "freezing produced output:\n$result"
 954     if $result;
 955
 956   # If freezing produces output, something went wrong: a bad `divert',
 957   # or an improper paren etc.
 958   xsystem ("$m4"
 959            . ' --fatal-warning'
 960            . join (' --include=', '', map { shell_quote ($_) } @include)
 961            . " --freeze-state=" . shell_quote ($output)
 962            . " " . files_to_options (@ARGV)
 963            . ' </dev/null');
 964 }
 965
 966 ## -------------- ##
 967 ## Main program.  ##
 968 ## -------------- ##
 969
 970 mktmpdir ('am4t');
 971 load_configuration ($ENV{'AUTOM4TE_CFG'} || "$datadir/autom4te.cfg");
 972 load_configuration ("$ENV{'HOME'}/.autom4te.cfg")
 973   if exists $ENV{'HOME'} && -f "$ENV{'HOME'}/.autom4te.cfg";
 974 load_configuration (".autom4te.cfg")
 975   if -f ".autom4te.cfg";
 976 parse_args;
 977
 978 # Freezing does not involve the cache.
 979 if ($freeze)
 980   {
 981     freeze ($output);
 982     exit $exit_code;
 983   }
 984
 985 # We need our cache directory.
 986 if (! -d "$cache")
 987   {
 988     mkdir "$cache", 0755
 989       or fatal "cannot create $cache: $!";
 990   }
 991
 992 # Open the index for update, and lock it.  autom4te handles several
 993 # files, but the index is the first and last file to be updated, so
 994 # locking it is sufficient.
 995 $icache_file = new Autom4te::XFile $icache, O_RDWR|O_CREAT;
 996 $icache_file->lock (LOCK_EX);
 997
 998 # Read the cache index if available and older than autom4te itself.
 999 # If autom4te is younger, then some structures such as C4che might
1000 # have changed, which would corrupt its processing.
1001 Autom4te::C4che->load ($icache_file)
1002   if -f $icache && mtime ($icache) > mtime ($0);
1003
1004 # Add the new trace requests.
1005 my $req = Autom4te::C4che->request ('input' => \@ARGV,
1006                                     'path'  => \@include,
1007                                     'macro' => [keys %trace, @preselect]);
1008
1009 # If $REQ's cache files are not up to date, or simply if the user
1010 # discarded them (-f), declare it invalid.
1011 $req->valid (0)
1012   if $force || ! up_to_date ($req);
1013
1014 # We now know whether we can trust the Request object.  Say it.
1015 verb "the trace request object is:\n" . $req->marshall;
1016
1017 # We need to run M4 if (i) the user wants it (--force), (ii) $REQ is
1018 # invalid.
1019 handle_m4 ($req, keys %{$req->macro})
1020   if $force || ! $req->valid;
1021
1022 # Issue the warnings each time autom4te was run.
1023 my $separator = "\n" . ('-' x 25) . " END OF WARNING " . ('-' x 25) . "\n\n";
1024 handle_traces ($req, "$tmp/warnings",
1025                ('_m4_warn' => "\$1::\$f:\$l::\$2::\$3$separator"));
1026 # Swallow excessive newlines.
1027 for (split (/\n*$separator\n*/o, contents ("$tmp/warnings")))
1028 {
1029   # The message looks like:
1030   # | syntax::input.as:5::ouch
1031   # | ::input.as:4: baz is expanded from...
1032   # | input.as:2: bar is expanded from...
1033   # | input.as:3: foo is expanded from...
1034   # | input.as:5: the top level
1035   my ($cat, $loc, $msg, $stacktrace) = split ('::', $_, 4);
1036   msg $cat, $loc, "warning: $msg";
1037   for (split /\n/, $stacktrace)
1038     {
1039       my ($loc, $trace) = split (': ', $_, 2);
1040       msg $cat, $loc, $trace;
1041     }
1042 }
1043
1044 # Now output...
1045 if (%trace)
1046   {
1047     # Always produce traces, since even if the output is young enough,
1048     # there is no guarantee that the traces use the same *format*
1049     # (e.g., `-t FOO:foo' and `-t FOO:bar' are both using the same M4
1050     # traces, hence the M4 traces cache is usable, but its formatting
1051     # will yield different results).
1052     handle_traces ($req, $output, %trace);
1053   }
1054 else
1055   {
1056     # Actual M4 expansion, if the user wants it, or if $output is old
1057     # (STDOUT is pretty old).
1058     handle_output ($req, $output)
1059       if $force || mtime ($output) < mtime ($ocache . $req->id);
1060   }
1061
1062 # If we ran up to here, the cache is valid.
1063 $req->valid (1);
1064 Autom4te::C4che->save ($icache_file);
1065
1066 exit $exit_code;
1067
1068 ### Setup "GNU" style for perl-mode and cperl-mode.
1069 ## Local Variables:
1070 ## perl-indent-level: 2
1071 ## perl-continued-statement-offset: 2
1072 ## perl-continued-brace-offset: 0
1073 ## perl-brace-offset: 0
1074 ## perl-brace-imaginary-offset: 0
1075 ## perl-label-offset: -2
1076 ## cperl-indent-level: 2
1077 ## cperl-brace-offset: 0
1078 ## cperl-continued-brace-offset: 0
1079 ## cperl-label-offset: -2
1080 ## cperl-extra-newline-before-brace: t
1081 ## cperl-merge-trailing-else: nil
1082 ## cperl-continued-statement-offset: 2
1083 ## End: