1#! @PERL@ -w
2# -*- perl -*-
3# @configure_input@
4
5# autoupdate - modernize an Autoconf file.
6# Copyright (C) 1994, 1999-2012 Free Software Foundation, Inc.
7
8# This program is free software: you can redistribute it and/or modify
9# it under the terms of the GNU General Public License as published by
10# the Free Software Foundation, either version 3 of the License, or
11# (at your option) any later version.
12
13# This program is distributed in the hope that it will be useful,
14# but WITHOUT ANY WARRANTY; without even the implied warranty of
15# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16# GNU General Public License for more details.
17
18# You should have received a copy of the GNU General Public License
19# along with this program.  If not, see <http://www.gnu.org/licenses/>.
20
21# Originally written by David MacKenzie <djm@gnu.ai.mit.edu>.
22# Rewritten by Akim Demaille <akim@freefriends.org>.
23
24eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S "$0" "$@";; esac'
25    if 0;
26
27BEGIN
28{
29  my $pkgdatadir = $ENV{'autom4te_perllibdir'} || '@pkgdatadir@';
30  unshift @INC, $pkgdatadir;
31
32  # Override SHELL.  On DJGPP SHELL may not be set to a shell
33  # that can handle redirection and quote arguments correctly,
34  # e.g.: COMMAND.COM.  For DJGPP always use the shell that configure
35  # has detected.
36  $ENV{'SHELL'} = '@SHELL@' if ($^O eq 'dos');
37}
38
39use Autom4te::ChannelDefs;
40use Autom4te::Channels;
41use Autom4te::Configure_ac;
42use Autom4te::FileUtils;
43use Autom4te::General;
44use Autom4te::XFile;
45use File::Basename;
46use strict;
47
48# Lib files.
49my $autom4te = $ENV{'AUTOM4TE'} || '@bindir@/@autom4te-name@';
50my $autoconf = "$autom4te --language=autoconf";
51# We need to find m4sugar.
52my @prepend_include;
53my @include = ('@pkgdatadir@');
54my $force = 0;
55# m4.
56my $m4 = $ENV{"M4"} || '@M4@';
57
58
59# $HELP
60# -----
61$help = "Usage: $0 [OPTION]... [TEMPLATE-FILE]...
62
63Update each TEMPLATE-FILE if given, or `configure.ac' if present,
64or else `configure.in', to the syntax of the current version of
65Autoconf.  The original files are backed up.
66
67Operation modes:
68  -h, --help                 print this help, then exit
69  -V, --version              print version number, then exit
70  -v, --verbose              verbosely report processing
71  -d, --debug                don't remove temporary files
72  -f, --force                consider all files obsolete
73
74Library directories:
75  -B, --prepend-include=DIR  prepend directory DIR to search path
76  -I, --include=DIR          append directory DIR to search path
77
78Report bugs to <bug-autoconf\@gnu.org>.
79GNU Autoconf home page: <http://www.gnu.org/software/autoconf/>.
80General help using GNU software: <http://www.gnu.org/gethelp/>.
81";
82
83# $VERSION
84# --------
85$version = "autoupdate (@PACKAGE_NAME@) @VERSION@
86Copyright (C) @RELEASE_YEAR@ Free Software Foundation, Inc.
87License GPLv3+/Autoconf: GNU GPL version 3 or later
88<http://gnu.org/licenses/gpl.html>, <http://gnu.org/licenses/exceptions.html>
89This is free software: you are free to change and redistribute it.
90There is NO WARRANTY, to the extent permitted by law.
91
92Written by David J. MacKenzie and Akim Demaille.
93";
94
95## ---------- ##
96## Routines.  ##
97## ---------- ##
98
99
100# parse_args ()
101# -------------
102# Process any command line arguments.
103sub parse_args ()
104{
105  my $srcdir;
106
107  getopt ('I|include=s'         => \@include,
108	  'B|prepend-include=s' => \@prepend_include,
109	  'f|force'             => \$force);
110
111  if (! @ARGV)
112    {
113      my $configure_ac = require_configure_ac;
114      push @ARGV, $configure_ac;
115    }
116}
117
118
119
120# ----------------- #
121# Autoconf macros.  #
122# ----------------- #
123
124my (%ac_macros, %au_macros, %m4_builtins);
125
126# HANDLE_AUTOCONF_MACROS ()
127# -------------------------
128# @M4_BUILTINS -- M4 builtins and a useful comment.
129sub handle_autoconf_macros ()
130{
131  # Get the builtins.
132  xsystem ("echo dumpdef | $m4 2>" . shell_quote ("$tmp/m4.defs") . " >/dev/null");
133  my $m4_defs = new Autom4te::XFile "< " . open_quote ("$tmp/m4.defs");
134  while ($_ = $m4_defs->getline)
135    {
136      $m4_builtins{$1} = 1
137	if /^(\w+):/;
138    }
139  $m4_defs->close;
140
141  my $macros = new Autom4te::XFile ("$autoconf"
142				    . " --trace AU_DEFINE:'AU:\$f:\$1'"
143				    . " --trace define:'AC:\$f:\$1'"
144				    . " --melt /dev/null |");
145  while ($_ = $macros->getline)
146    {
147      chomp;
148      my ($domain, $file, $macro) = /^(AC|AU):(.*):([^:]*)$/ or next;
149      if ($domain eq "AU")
150	{
151	  $au_macros{$macro} = 1;
152	}
153      elsif ($file =~ /(^|\/)m4sugar\/(m4sugar|version)\.m4$/)
154	{
155	  # Add the m4sugar macros to m4_builtins.
156	  $m4_builtins{$macro} = 1;
157	}
158      else
159	{
160	  # Autoconf, aclocal, and m4sh macros.
161	  $ac_macros{$macro} = 1;
162	}
163    }
164  $macros->close;
165
166
167  # Don't keep AU macros in @AC_MACROS.
168  delete $ac_macros{$_}
169    foreach (keys %au_macros);
170  # Don't keep M4sugar macros which are redefined by Autoconf,
171  # such as `builtin', `changequote' etc.  See autoconf/autoconf.m4.
172  delete $ac_macros{$_}
173    foreach (keys %m4_builtins);
174  error "no current Autoconf macros found"
175    unless keys %ac_macros;
176  error "no obsolete Autoconf macros found"
177    unless keys %au_macros;
178
179  if ($debug)
180    {
181      print STDERR "Current Autoconf macros:\n";
182      print STDERR join (' ', sort keys %ac_macros) . "\n\n";
183      print STDERR "Obsolete Autoconf macros:\n";
184      print STDERR join (' ', sort keys %au_macros) . "\n\n";
185    }
186
187  # ac.m4 -- autoquoting definitions of the AC macros (M4sugar excluded).
188  # unac.m4 -- undefine the AC macros.
189  my $ac_m4 = new Autom4te::XFile "> " . open_quote ("$tmp/ac.m4");
190  print $ac_m4 "# ac.m4 -- autoquoting definitions of the AC macros.\n";
191  my $unac_m4 = new Autom4te::XFile "> " . open_quote ("$tmp/unac.m4");
192  print $unac_m4 "# unac.m4 -- undefine the AC macros.\n";
193  foreach (sort keys %ac_macros)
194    {
195      print $ac_m4   "_au_m4_define([$_], [m4_if(\$#, 0, [[\$0]], [[\$0(\$\@)]])])\n";
196      print $unac_m4 "_au_m4_undefine([$_])\n";
197    }
198
199  # m4save.m4 -- save the m4 builtins.
200  # unm4.m4 -- disable the m4 builtins.
201  # m4.m4 -- enable the m4 builtins.
202  my $m4save_m4 = new Autom4te::XFile "> " . open_quote ("$tmp/m4save.m4");
203  print $m4save_m4 "# m4save.m4 -- save the m4 builtins.\n";
204  my $unm4_m4 = new Autom4te::XFile "> " . open_quote ("$tmp/unm4.m4");
205  print $unm4_m4 "# unm4.m4 -- disable the m4 builtins.\n";
206  my $m4_m4 = new Autom4te::XFile "> " . open_quote ("$tmp/m4.m4");
207  print $m4_m4 "# m4.m4 -- enable the m4 builtins.\n";
208  foreach (sort keys %m4_builtins)
209    {
210      print $m4save_m4 "_au__save([$_])\n";
211      print $unm4_m4   "_au__undefine([$_])\n";
212      print $m4_m4     "_au__restore([$_])\n";
213    }
214}
215
216
217## -------------- ##
218## Main program.  ##
219## -------------- ##
220
221parse_args;
222$autoconf .= " --debug" if $debug;
223$autoconf .= " --force" if $force;
224$autoconf .= " --verbose" if $verbose;
225$autoconf .= join (' --include=', '', map { shell_quote ($_) } @include);
226$autoconf .= join (' --prepend-include=', '', map { shell_quote ($_) } @prepend_include);
227
228mktmpdir ('au');
229handle_autoconf_macros;
230
231# $au_changequote -- enable the quote `[', `]' right before any AU macro.
232my $au_changequote =
233  's/\b(' . join ('|', keys %au_macros) . ')\b/_au_m4_changequote([,])$1/g';
234
235# au.m4 -- definitions the AU macros.
236xsystem ("$autoconf --trace AU_DEFINE:'_au_defun(\@<:\@\$1\@:>\@,
237\@<:\@\$2\@:>\@)' --melt /dev/null "
238	. ">" . shell_quote ("$tmp/au.m4"));
239
240
241
242## ------------------- ##
243## Process the files.  ##
244## ------------------- ##
245
246foreach my $file (@ARGV)
247  {
248    # We need an actual file.
249    if ($file eq '-')
250      {
251	$file = "$tmp/stdin";
252	system "cat >" . shell_quote ($file);
253      }
254    elsif (! -r "$file")
255      {
256	die "$me: $file: No such file or directory";
257      }
258
259    # input.m4 -- m4 program to produce the updated file.
260    # Load the values, the dispatcher, neutralize m4, and the prepared
261    # input file.
262    my $input_m4 = <<\EOF;
263      divert(-1)                                            -*- Autoconf -*-
264      changequote([,])
265
266      # Define our special macros:
267      define([_au__defn], defn([defn]))
268      define([_au__divert], defn([divert]))
269      define([_au__ifdef], defn([ifdef]))
270      define([_au__include], defn([include]))
271      define([_au___undefine], defn([undefine]))
272      define([_au__undefine], [_au__ifdef([$1], [_au___undefine([$1])])])
273      define([_au__save], [m4_ifdef([$1],
274	[m4_define([_au_$1], _m4_defn([$1]))])])
275      define([_au__restore],
276	[_au_m4_ifdef([_au_$1],
277	  [_au_m4_define([$1], _au__defn([_au_$1]))])])
278
279      # Set up m4sugar.
280      include(m4sugar/m4sugar.m4)
281
282      # Redefine __file__ to make warnings nicer; $file is replaced below.
283      m4_define([__file__], [$file])
284
285      # Redefine m4_location to fix the line number.
286      m4_define([m4_location], [__file__:m4_eval(__line__ - _au__first_line)])
287
288      # Move all the builtins into the `_au_' pseudo namespace
289      m4_include([m4save.m4])
290
291      # _au_defun(NAME, BODY)
292      # ---------------------
293      # Define NAME to BODY, plus AU activation/deactivation.
294      _au_m4_define([_au_defun],
295      [_au_m4_define([$1],
296      [_au_enable()dnl
297      $2[]dnl
298      _au_disable()])])
299
300      # Import the definition of the obsolete macros.
301      _au__include([au.m4])
302
303
304      ## ------------------------ ##
305      ## _au_enable/_au_disable.  ##
306      ## ------------------------ ##
307
308      # They work by pair: each time an AU macro is activated, it runs
309      # _au_enable, and at its end its runs _au_disable (see _au_defun
310      # above).  AU macros might use AU macros, which should
311      # enable/disable only for the outer AU macros.
312      #
313      # `_au_enabled' is used to this end, determining whether we really
314      # enable/disable.
315
316
317      # __au_enable
318      # -----------
319      # Reenable the builtins, m4sugar, and the autoquoting AC macros.
320      _au_m4_define([__au_enable],
321      [_au__divert(-1)
322      # Enable special characters.
323      _au_m4_changecom([#])
324
325      _au__include([m4.m4])
326      _au__include([ac.m4])
327
328      _au__divert(0)])
329
330      # _au_enable
331      # ----------
332      # Called at the beginning of all the obsolete macros.  If this is the
333      # outermost level, call __au_enable.
334      _au_m4_define([_au_enable],
335      [_au_m4_ifdef([_au_enabled],
336		 [],
337		 [__au_enable()])_au_dnl
338      _au_m4_pushdef([_au_enabled])])
339
340
341      # __au_disable
342      # ------------
343      # Disable the AC autoquoting macros, m4sugar, and m4.
344      _au_m4_define([__au_disable],
345      [_au__divert(-1)
346      _au__include([unac.m4])
347      _au__include([unm4.m4])
348
349      # Disable special characters.
350      _au_m4_changequote()
351      _au_m4_changecom()
352
353      _au__divert(0)])
354
355      # _au_disable
356      # -----------
357      # Called at the end of all the obsolete macros.  If we are at the
358      # outermost level, call __au_disable.
359      _au_m4_define([_au_disable],
360      [_au_m4_popdef([_au_enabled])_au_dnl
361      _au_m4_ifdef([_au_enabled],
362		[],
363		[__au_disable()])])
364
365
366      ## ------------------------------- ##
367      ## Disable, and process the file.  ##
368      ## ------------------------------- ##
369      # The AC autoquoting macros are not loaded yet, hence invoking
370      # `_au_disable' would be wrong.
371      _au__include([unm4.m4])
372
373      # Disable special characters, and set the first line number.
374      _au_m4_changequote()
375      _au_m4_changecom()
376
377      _au_m4_define(_au__first_line, _au___line__)_au__divert(0)_au_dnl
378EOF
379
380    $input_m4 =~ s/^      //mg;
381    $input_m4 =~ s/\$file/$file/g;
382
383    # prepared input -- input, but reenables the quote before each AU macro.
384    open INPUT_M4, "> " . open_quote ("$tmp/input.m4")
385       or error "cannot open: $!";
386    open FILE, "< " . open_quote ($file)
387       or error "cannot open: $!";
388    print INPUT_M4 "$input_m4";
389    while (<FILE>)
390       {
391	 eval $au_changequote;
392	 print INPUT_M4;
393       }
394    close FILE
395       or error "cannot close $file: $!";
396    close INPUT_M4
397       or error "cannot close $tmp/input.m4: $!";
398
399    # Now ask m4 to perform the update.
400    xsystem ("$m4 --include=" . shell_quote ($tmp)
401	     . join (' --include=', '', map { shell_quote ($_) } reverse (@prepend_include))
402	     . join (' --include=', '', map { shell_quote ($_) } @include)
403	     . " " . shell_quote ("$tmp/input.m4") . " > " . shell_quote ("$tmp/updated"));
404    update_file ("$tmp/updated",
405		 "$file" eq "$tmp/stdin" ? '-' : "$file");
406  }
407exit 0;
408
409
410#		  ## ---------------------------- ##
411#		  ## How `autoupdate' functions.  ##
412#		  ## ---------------------------- ##
413#
414# The task of `autoupdate' is not trivial: the biggest difficulty being
415# that you must limit the changes to the parts that really need to be
416# updated.  Finding a satisfying implementation proved to be quite hard,
417# as this is the fifth implementation of `autoupdate'.
418#
419# Below, we will use a simple example of an obsolete macro:
420#
421#     AU_DEFUN([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))])
422#     AC_DEFUN([NEW], [echo "sum($1) = $2"])
423#
424# the input file contains
425#
426#     dnl The Unbelievable Truth
427#     OLD(1, 2)
428#     NEW([0, 0], [0])
429#
430# Of course the expected output is
431#
432#     dnl The Unbelievable Truth
433#     NEW([1, 2], [3])
434#     NEW([0, 0], [0])
435#
436#
437# # First implementation: sed
438# # =========================
439#
440# The first implementation was only able to change the name of obsolete
441# macros.
442#
443# The file `acoldnames.m4' defined the old names based on the new names.
444# It was simple then to produce a sed script such as:
445#
446#     s/OLD/NEW/g
447#
448# Updating merely consisted in running this script on the file to
449# update.
450#
451# This scheme suffers from an obvious limitation: that `autoupdate' was
452# unable to cope with new macros that just swap some of its arguments
453# compared to the old macro.  Fortunately, that was enough to upgrade
454# from Autoconf 1 to Autoconf 2.  (But I have no idea whether the
455# changes in Autoconf 2 were precisely limited by this constraint.)
456#
457#
458# # Second implementation: hooks
459# # ============================
460#
461# The version 2.15 of Autoconf brought a vast number of changes compared
462# to 2.13, so a solution was needed.  One could think of extending the
463# `sed' scripts with specialized code for complex macros.  However, this
464# approach is of course full of flaws:
465#
466# a. the Autoconf maintainers have to write these snippets, which we
467#    just don't want to,
468#
469# b. I really don't think you'll ever manage to handle the quoting of
470#    m4 with a sed script.
471#
472# To satisfy a., let's remark that the code which implements the old
473# features in term of the new feature is exactly the code which should
474# replace the old code.
475#
476# To answer point b, as usual in the history of Autoconf, the answer, at
477# least on the paper, is simple: m4 is the best tool to parse m4, so
478# let's use m4.
479#
480# Therefore the specification is:
481#
482#     I want to be able to tell Autoconf, well, m4, that the macro I
483#     am currently defining is an obsolete macro (so that the user is
484#     warned), and its code is the code to use when running autoconf,
485#     but that the very same code has to be used when running
486#     autoupdate.  To summarize, the interface I want is
487#     `AU_DEFUN(OLD-NAME, NEW-CODE)'.
488#
489#
490# Now for the technical details.
491#
492# When running autoconf, except for the warning, AU_DEFUN is basically
493# AC_DEFUN.
494#
495# When running autoupdate, we want *only* OLD-NAMEs to be expanded.
496# This obviously means that acgeneral.m4 and acspecific.m4 must not be
497# loaded.  Nonetheless, because we want to use a rich set of m4
498# features, m4sugar.m4 is needed.  Please note that the fact that
499# Autoconf's macros are not loaded is positive on two points:
500#
501# - we do get an updated `configure.ac', not a `configure'!
502#
503# - the old macros are replaced by *calls* to the new-macros, not the
504#   body of the new macros, since their body is not defined!!!
505#   (Whoa, that's really beautiful!).
506#
507# Additionally we need to disable the quotes when reading the input for
508# two reasons: first because otherwise `m4' will swallow the quotes of
509# other macros:
510#
511#     NEW([1, 2], 3)
512#     => NEW(1, 2, 3)
513#
514# and second, because we want to update the macro calls which are
515# quoted, i.e., we want
516#
517#     FOO([OLD(1, 2)])
518#     => FOO([NEW([1, 2], [3])])
519#
520# If we don't disable the quotes, only the macros called at the top
521# level would be updated.
522#
523# So, let's disable the quotes.
524#
525# Well, not quite: m4sugar.m4 still needs to use quotes for some macros.
526# Well, in this case, when running in autoupdate code, each macro first
527# reestablishes the quotes, expands itself, and disables the quotes.
528#
529# Thinking a bit more, you realize that in fact, people may use `define',
530# `ifelse' etc. in their files, and you certainly don't want to process
531# them.  Another example is `dnl': you don't want to remove the
532# comments.  You then realize you don't want exactly to import m4sugar:
533# you want to specify when it is enabled (macros active), and disabled.
534# m4sugar provides m4_disable/m4_enable to this end.
535#
536# You're getting close to it.  Now remains one task: how to handle
537# twofold definitions?
538#
539# Remember that the same AU_DEFUN must be understood in two different
540# ways, the AC way, and the AU way.
541#
542# One first solution is to check whether acgeneral.m4 was loaded.  But
543# that's definitely not cute.  Another is simply to install `hooks',
544# that is to say, to keep in some place m4 knows, late `define' to be
545# triggered *only* in AU mode.
546#
547# You first think of designing AU_DEFUN like this:
548#
549# 1. AC_DEFUN(OLD-NAME,
550#	      [Warn the user OLD-NAME is obsolete.
551#	       NEW-CODE])
552#
553# 2. Store for late AU binding([define(OLD_NAME,
554#				[Reestablish the quotes.
555#				 NEW-CODE
556#				 Disable the quotes.])])
557#
558# but this will not work: NEW-CODE probably uses $1, $2 etc. and these
559# guys will be replaced with the argument of `Store for late AU binding'
560# when you call it.
561#
562# I don't think there is a means to avoid this using this technology
563# (remember that $1 etc. are *always* expanded in m4).  You may also try
564# to replace them with $[1] to preserve them for a later evaluation, but
565# if `Store for late AU binding' is properly written, it will remain
566# quoted till the end...
567#
568# You have to change technology.  Since the problem is that `$1'
569# etc. should be `consumed' right away, one solution is to define now a
570# second macro, `AU_OLD-NAME', and to install a hook than binds OLD-NAME
571# to AU_OLD-NAME.  Then, autoupdate.m4 just need to run the hooks.  By
572# the way, the same method was used in autoheader.
573#
574#
575# # Third implementation: m4 namespaces by m4sugar
576# # ==============================================
577#
578# Actually, this implementation was just a clean up of the previous
579# implementation: instead of defining hooks by hand, m4sugar was equipped
580# with `namespaces'.  What are they?
581#
582# Sometimes we want to disable some *set* of macros, and restore them
583# later.  We provide support for this via namespaces.
584#
585# There are basically three characters playing this scene: defining a
586# macro in a namespace, disabling a namespace, and restoring a namespace
587# (i.e., all the definitions it holds).
588#
589# Technically, to define a MACRO in NAMESPACE means to define the macro
590# named `NAMESPACE::MACRO' to the VALUE.  At the same time, we append
591# `undefine(NAME)' in the macro named `m4_disable(NAMESPACE)', and
592# similarly a binding of NAME to the value of `NAMESPACE::MACRO' in
593# `m4_enable(NAMESPACE)'.  These mechanisms allow to bind the macro of
594# NAMESPACE and to unbind them at will.
595#
596# Of course this implementation is really inefficient: m4 has to grow
597# strings which can become quickly huge, which slows it significantly.
598#
599# In particular one should avoid as much as possible to use `define' for
600# temporaries.  Now that `define' has quite a complex meaning, it is an
601# expensive operations that should be limited to macros.  Use
602# `m4_define' for temporaries.
603#
604# Private copies of the macros we used in entering / exiting the m4sugar
605# namespace.  It is much more convenient than fighting with the renamed
606# version of define etc.
607#
608#
609#
610# Those two implementations suffered from serious problems:
611#
612# - namespaces were really expensive, and incurred a major performance
613#   loss on `autoconf' itself, not only `autoupdate'.  One solution
614#   would have been the limit the use of namespaces to `autoupdate', but
615#   that's again some complications on m4sugar, which really doesn't need
616#   this.  So we wanted to get rid of the namespaces.
617#
618# - since the quotes were disabled, autoupdate was sometimes making
619#   wrong guesses, for instance on:
620#
621#     foo([1, 2])
622#
623#   m4 saw 2 arguments: `[1'and `2]'.  A simple solution, somewhat
624#   fragile, is to reestablish the quotes right before all the obsolete
625#   macros, i.e., to use sed so that the previous text becomes
626#
627#     changequote([, ])foo([1, 2])
628#
629#   To this end, one wants to trace the definition of obsolete macros.
630#
631# It was there that the limitations of the namespace approach became
632# painful: because it was a complex machinery playing a lot with the
633# builtins of m4 (hence, quite fragile), tracing was almost impossible.
634#
635#
636# So this approach was dropped.
637#
638#
639# # The fourth implementation: two steps
640# # ====================================
641#
642# If you drop the uses of namespaces, you no longer can compute the
643# updated value, and replace the old call with it simultaneously.
644#
645# Obviously you will use m4 to compute the updated values, but you may
646# use some other tool to achieve the replacement.  Personally, I trust
647# nobody but m4 to parse m4, so below, m4 will perform the two tasks.
648#
649# How can m4 be used to replace *some* macros calls with newer values.
650# Well, that's dead simple: m4 should learn the definitions of obsolete
651# macros, forget its builtins, disable the quotes, and then run on the
652# input file, which amounts to doing this:
653#
654#     divert(-1)dnl
655#     changequote([, ])
656#     define([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))changequote()])
657#     undefine([dnl])
658#     undefine([m4_eval])
659#     # Some more undefines...
660#     changequote()
661#     divert(0)dnl
662#     dnl The Unbelievable Truth
663#     changequote([, ])OLD(1, 2)
664#     NEW([0, 0],
665#	  0)
666#
667# which will result in
668#
669#     dnl The Unbelievable Truth
670#     NEW(1, 2, m4_eval(1 + 2))
671#     NEW([0, 0],
672#	  0)
673#
674# Grpmh.  Two problems.  A minor problem: it would have been much better
675# to have the `m4_eval' computed, and a major problem: you lost the
676# quotation in the result.
677#
678# Let's address the big problem first.  One solution is to define any
679# modern macro to rewrite its calls with the proper quotation, thanks to
680# `$@'.  Again, tracing the `define's makes it possible to know which
681# are these macros, so you input is:
682#
683#     divert(-1)dnl
684#     changequote([, ])
685#     define([OLD], [NEW([$1, $2], m4_eval([$1 + $2]))changequote()])
686#     define([NEW], [[NEW($@)]changequote()])
687#     undefine([dnl])
688#     undefine([m4_eval])
689#     # Some more undefines...
690#     changequote()
691#     divert(0)dnl
692#     dnl The Unbelievable Truth
693#     changequote([, ])OLD(1, 2)
694#     changequote([, ])NEW([0, 0],
695#	  0)
696#
697# which results in
698#
699#     dnl The Unbelievable Truth
700#     NEW([1, 2],[m4_eval(1 + 2)])
701#     NEW([0, 0],[0])
702#
703# Our problem is solved, i.e., the first call to `NEW' is properly
704# quoted, but introduced another problem: we changed the layout of the
705# second calls, which can be a drama in the case of huge macro calls
706# (think of `AC_TRY_RUN' for instance).  This example didn't show it,
707# but we also introduced parens to macros which did not have some:
708#
709#     AC_INIT
710#     => AC_INIT()
711#
712# No big deal for the semantics (unless the macro depends upon $#, which
713# is bad), but the users would not be happy.
714#
715# Additionally, we introduced quotes that were not there before, which is
716# OK in most cases, but could change the semantics of the file.
717#
718# Cruel dilemma: we do want the auto-quoting definition of `NEW' when
719# evaluating `OLD', but we don't when we evaluate the second `NEW'.
720# Back to namespaces?
721#
722# No.
723#
724#
725# # Second step: replacement
726# # ------------------------
727#
728# No, as announced above, we will work in two steps: in a first step we
729# compute the updated values, and in a second step we replace them.  Our
730# goal is something like this:
731#
732#     divert(-1)dnl
733#     changequote([, ])
734#     define([OLD], [NEW([1, 2], [3])changequote()])
735#     undefine([dnl])
736#     undefine([m4_eval])
737#     # Some more undefines...
738#     changequote()
739#     divert(0)dnl
740#     dnl The Unbelievable Truth
741#     changequote([, ])OLD(1, 2)
742#     NEW([0, 0],
743#	  0)
744#
745# i.e., the new value of `OLD' is precomputed using the auto-quoting
746# definition of `NEW' and the m4 builtins.  We'll see how afterwards,
747# let's finish with the replacement.
748#
749# Of course the solution above is wrong: if there were other calls to
750# `OLD' with different values, we would smash them to the same value.
751# But it is quite easy to generalize the scheme above:
752#
753#     divert(-1)dnl
754#     changequote([, ])
755#     define([OLD([1],[2])], [NEW([1, 2], [3])])
756#     define([OLD], [defn([OLD($@)])changequote()])
757#     undefine([dnl])
758#     undefine([m4_eval])
759#     # Some more undefines...
760#     changequote()
761#     divert(0)dnl
762#     dnl The Unbelievable Truth
763#     changequote([, ])OLD(1, 2)
764#     NEW([0, 0],
765#	  0)
766#
767# i.e., for each call to obsolete macros, we build an array `call =>
768# value', and use a macro to dispatch these values.  This results in:
769#
770#     dnl The Unbelievable Truth
771#     NEW([1, 2], [3])
772#     NEW([0, 0],
773#	  0)
774#
775# In French, we say `Youpi !', which you might roughly translate as
776# `Yippee!'.
777#
778#
779# # First step: computation
780# # -----------------------
781#
782# Let's study the anatomy of the file, and name its sections:
783#
784# prologue
785#     divert(-1)dnl
786#     changequote([, ])
787# values
788#     define([OLD([1],[2])], [NEW([1, 2], [3])])
789# dispatcher
790#     define([OLD], [defn([OLD($@)])changequote()])
791# disabler
792#     undefine([dnl])
793#     undefine([m4_eval])
794#     # Some more undefines...
795#     changequote()
796#     divert(0)dnl
797# input
798#     dnl The Unbelievable Truth
799#     changequote([, ])OLD(1, 2)
800#     NEW([0, 0],
801#	  0)
802#
803#
804# # Computing the `values' section
805# # ..............................
806#
807# First we need to get the list of all the AU macro uses.  To this end,
808# first get the list of all the AU macros names by tracing `AU_DEFUN' in
809# the initialization of autoconf.  This list is computed in the file
810# `au.txt' below.
811#
812# Then use this list to trace all the AU macro uses in the input.  The
813# goal is obtain in the case of our example:
814#
815#     [define([OLD([1],[2])],]@<<@OLD([1],[2])@>>@[)]
816#
817# This is the file `values.in' below.
818#
819# We want to evaluate this with only the builtins (in fact m4sugar), the
820# auto-quoting definitions of the new macros (`new.m4'), and the
821# definition of the old macros (`old.m4').  Computing these last two
822# files is easy: it's just a matter of using the right `--trace' option.
823#
824# So the content of `values.in' is:
825#
826#     include($autoconf_dir/m4sugar.m4)
827#     m4_include(new.m4)
828#     m4_include(old.m4)
829#     divert(0)dnl
830#     [define([OLD([1],[2])],]@<<@OLD([1],[2])@>>@[)]
831#
832# We run m4 on it, which yields:
833#
834#     define([OLD([1],[2])],@<<@NEW([1, 2], [3])@>>@)
835#
836# Transform `@<<@' and `@>>@' into quotes and we get
837#
838#     define([OLD([1],[2])],[NEW([1, 2], [3])])
839#
840# This is `values.m4'.
841#
842#
843# # Computing the `dispatcher' section
844# # ..................................
845#
846# The `prologue', and the `disabler' are simple and need no commenting.
847#
848# To compute the `dispatcher' (`dispatch.m4'), again, it is a simple
849# matter of using the right `--trace'.
850#
851# Finally, the input is not exactly the input file, rather it is the
852# input file with the added `changequote'.  To this end, we build
853# `quote.sed'.
854#
855#
856# # Putting it all together
857# # .......................
858#
859# We build the file `input.m4' which contains:
860#
861#     divert(-1)dnl
862#     changequote([, ])
863#     include(values.m4)
864#     include(dispatch.m4)
865#     undefine([dnl])
866#     undefine([eval])
867#     # Some more undefines...
868#     changequote()
869#     divert(0)dnl
870#     dnl The Unbelievable Truth
871#     changequote([, ])OLD(1, 2)
872#     NEW([0, 0],
873#	  0)
874#
875# And we just run m4 on it.  Et voila`, Monsieur !  Mais oui, mais oui.
876#
877# Well, there are a few additional technicalities.  For instance, we
878# rely on `changequote', `ifelse' and `defn', but we don't want to
879# interpret the changequotes of the user, so we simply use another name:
880# `_au_changequote' etc.
881#
882#
883# # Failure of the fourth approach
884# # ------------------------------
885#
886# This approach is heavily based on traces, but then there is an obvious
887# problem: non expanded code will never be seen.  In particular, the body
888# of a `define' definition is not seen, so on the input
889#
890#	  define([idem], [OLD(0, [$1])])
891#
892# autoupdate would never see the `OLD', and wouldn't have updated it.
893# Worse yet, if `idem(0)' was used later, then autoupdate sees that
894# `OLD' is used, computes the result for `OLD(0, 0)' and sets up a
895# dispatcher for `OLD'.  Since there was no computed value for `OLD(0,
896# [$1])', the dispatcher would have replaced with... nothing, leading
897# to
898#
899#	  define([idem], [])
900#
901# With some more thinking, you see that the two step approach is wrong,
902# the namespace approach was much saner.
903#
904# But you learned a lot, in particular you realized that using traces
905# can make it possible to simulate namespaces!
906#
907#
908#
909# # The fifth implementation: m4 namespaces by files
910# # ================================================
911#
912# The fourth implementation demonstrated something unsurprising: you
913# cannot precompute, i.e., the namespace approach was the right one.
914# Still, we no longer want them, they're too expensive.  Let's have a
915# look at the way it worked.
916#
917# When updating
918#
919#     dnl The Unbelievable Truth
920#     OLD(1, 2)
921#     NEW([0, 0], [0])
922#
923# you evaluate `input.m4':
924#
925#     divert(-1)
926#     changequote([, ])
927#     define([OLD],
928#     [m4_enable()NEW([$1, $2], m4_eval([$1 + $2]))m4_disable()])
929#     ...
930#     m4_disable()
931#     dnl The Unbelievable Truth
932#     OLD(1, 2)
933#     NEW([0, 0], [0])
934#
935# where `m4_disable' undefines the m4 and m4sugar, and disables the quotes
936# and comments:
937#
938#     define([m4_disable],
939#     [undefine([__file__])
940#     ...
941#     changecom(#)
942#     changequote()])
943#
944# `m4_enable' does the converse: reestablish quotes and comments
945# --easy--, reestablish m4sugar --easy: just load `m4sugar.m4' again-- and
946# reenable the builtins.  This later task requires that you first save
947# the builtins.  And BTW, the definition above of `m4_disable' cannot
948# work: you undefined `changequote' before using it!  So you need to use
949# your privates copies of the builtins.  Let's introduce three files for
950# this:
951#
952#  `m4save.m4'
953#    moves the m4 builtins into the `_au_' pseudo namespace,
954#  `unm4.m4'
955#    undefines the builtins,
956#  `m4.m4'
957#    restores them.
958#
959# So `input.m4' is:
960#
961#     divert(-1)
962#     changequote([, ])
963#
964#     include([m4save.m4])
965#
966#     # Import AU.
967#     define([OLD],
968#     [m4_enable()NEW([$1, $2], m4_eval([$1 + $2]))m4_disable()])
969#
970#     define([_au_enable],
971#     [_au_changecom([#])
972#     _au_include([m4.m4])
973#     _au_include(m4sugar.m4)])
974#
975#     define([_au_disable],
976#     [# Disable m4sugar.
977#     # Disable the m4 builtins.
978#     _au_include([unm4.m4])
979#     # 1. Disable special characters.
980#     _au_changequote()
981#     _au_changecom()])
982#
983#     m4_disable()
984#     dnl The Unbelievable Truth
985#     OLD(1, 2)
986#     NEW([0, 0], [0])
987#
988# Based on what we learned in the fourth implementation we know that we
989# have to enable the quotes *before* any AU macro, and we know we need
990# to build autoquoting versions of the AC macros.  But the autoquoting
991# AC definitions must be disabled in the rest of the file, and enabled
992# inside AU macros.
993#
994# Using `autoconf --trace' it is easy to build the files
995#
996#   `ac.m4'
997#     define the autoquoting AC fake macros
998#   `disable.m4'
999#     undefine the m4sugar and AC autoquoting macros.
1000#   `au.m4'
1001#     definitions of the AU macros (such as `OLD' above).
1002#
1003# Now, `input.m4' is:
1004#
1005#     divert(-1)
1006#     changequote([, ])
1007#
1008#     include([m4save.m4])
1009#     # Import AU.
1010#     include([au.m4])
1011#
1012#     define([_au_enable],
1013#     [_au_changecom([#])
1014#     _au_include([m4.m4])
1015#     _au_include(m4sugar.m4)
1016#     _au_include(ac.m4)])
1017#
1018#     define([_au_disable],
1019#     [_au_include([disable.m4])
1020#     _au_include([unm4.m4])
1021#     # 1. Disable special characters.
1022#     _au_changequote()
1023#     _au_changecom()])
1024#
1025#     m4_disable()
1026#     dnl The Unbelievable Truth
1027#     _au_changequote([, ])OLD(1, 2)
1028#     NEW([0, 0], [0])
1029#
1030# Finally, version V is ready.
1031#
1032# Well... almost.
1033#
1034# There is a slight problem that remains: if an AU macro OUTER includes
1035# an AU macro INNER, then _au_enable will be run when entering OUTER
1036# and when entering INNER (not good, but not too bad yet).  But when
1037# getting out of INNER, _au_disable will disable everything while we
1038# were still in OUTER.  Badaboom.
1039#
1040# Therefore _au_enable and _au_disable have to be written to work by
1041# pairs: each _au_enable pushdef's _au_enabled, and each _au_disable
1042# popdef's _au_enabled.  And of course _au_enable and _au_disable are
1043# effective when _au_enabled is *not* defined.
1044#
1045# Finally, version V' is ready.  And there is much rejoicing.  (And I
1046# have free time again.  I think.  Yeah, right.)
1047
1048### Setup "GNU" style for perl-mode and cperl-mode.
1049## Local Variables:
1050## perl-indent-level: 2
1051## perl-continued-statement-offset: 2
1052## perl-continued-brace-offset: 0
1053## perl-brace-offset: 0
1054## perl-brace-imaginary-offset: 0
1055## perl-label-offset: -2
1056## cperl-indent-level: 2
1057## cperl-brace-offset: 0
1058## cperl-continued-brace-offset: 0
1059## cperl-label-offset: -2
1060## cperl-extra-newline-before-brace: t
1061## cperl-merge-trailing-else: nil
1062## cperl-continued-statement-offset: 2
1063## End:
1064