Upgrade win_flex/win_bison to 2.5.5 (bison 3.0)
[mirror/qt/qt5.git] / gnuwin32 / bin / data / m4sugar / m4sugar.m4
1 divert(-1)#                                                  -*- Autoconf -*-
2 # This file is part of Autoconf.
3 # Base M4 layer.
4 # Requires GNU M4.
5 #
6 # Copyright (C) 1999-2013 Free Software Foundation, Inc.
7
8 # This file is part of Autoconf.  This program is free
9 # software; you can redistribute it and/or modify it under the
10 # terms of the GNU General Public License as published by the
11 # Free Software Foundation, either version 3 of the License, or
12 # (at your option) any later version.
13 #
14 # This program is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 # GNU General Public License for more details.
18 #
19 # Under Section 7 of GPL version 3, you are granted additional
20 # permissions described in the Autoconf Configure Script Exception,
21 # version 3.0, as published by the Free Software Foundation.
22 #
23 # You should have received a copy of the GNU General Public License
24 # and a copy of the Autoconf Configure Script Exception along with
25 # this program; see the files COPYINGv3 and COPYING.EXCEPTION
26 # respectively.  If not, see <http://www.gnu.org/licenses/>.
27
28 # Written by Akim Demaille.
29
30 # Set the quotes, whatever the current quoting system.
31 changequote()
32 changequote([, ])
33
34 # Some old m4's don't support m4exit.  But they provide
35 # equivalent functionality by core dumping because of the
36 # long macros we define.
37 ifdef([__gnu__], ,
38 [errprint(M4sugar requires GNU M4. Install it before installing M4sugar or
39 set the M4 environment variable to its absolute file name.)
40 m4exit(2)])
41
42
43 ## ------------------------------- ##
44 ## 1. Simulate --prefix-builtins.  ##
45 ## ------------------------------- ##
46
47 # m4_define
48 # m4_defn
49 # m4_undefine
50 define([m4_define],   defn([define]))
51 define([m4_defn],     defn([defn]))
52 define([m4_undefine], defn([undefine]))
53
54 m4_undefine([define])
55 m4_undefine([defn])
56 m4_undefine([undefine])
57
58
59 # m4_copy(SRC, DST)
60 # -----------------
61 # Define DST as the definition of SRC.
62 # What's the difference between:
63 # 1. m4_copy([from], [to])
64 # 2. m4_define([to], [from($@)])
65 # Well, obviously 1 is more expensive in space.  Maybe 2 is more expensive
66 # in time, but because of the space cost of 1, it's not that obvious.
67 # Nevertheless, one huge difference is the handling of `$0'.  If `from'
68 # uses `$0', then with 1, `to''s `$0' is `to', while it is `from' in 2.
69 # The user would certainly prefer to see `to'.
70 #
71 # This definition is in effect during m4sugar initialization, when
72 # there are no pushdef stacks; later on, we redefine it to something
73 # more powerful for all other clients to use.
74 m4_define([m4_copy],
75 [m4_define([$2], m4_defn([$1]))])
76
77
78 # m4_rename(SRC, DST)
79 # -------------------
80 # Rename the macro SRC to DST.
81 m4_define([m4_rename],
82 [m4_copy([$1], [$2])m4_undefine([$1])])
83
84
85 # m4_rename_m4(MACRO-NAME)
86 # ------------------------
87 # Rename MACRO-NAME to m4_MACRO-NAME.
88 m4_define([m4_rename_m4],
89 [m4_rename([$1], [m4_$1])])
90
91
92 # m4_copy_unm4(m4_MACRO-NAME)
93 # ---------------------------
94 # Copy m4_MACRO-NAME to MACRO-NAME.
95 m4_define([m4_copy_unm4],
96 [m4_copy([$1], m4_bpatsubst([$1], [^m4_\(.*\)], [[\1]]))])
97
98
99 # Some m4 internals have names colliding with tokens we might use.
100 # Rename them a` la `m4 --prefix-builtins'.  Conditionals first, since
101 # some subsequent renames are conditional.
102 m4_rename_m4([ifdef])
103 m4_rename([ifelse], [m4_if])
104
105 m4_rename_m4([builtin])
106 m4_rename_m4([changecom])
107 m4_rename_m4([changequote])
108 m4_ifdef([changeword],dnl conditionally available in 1.4.x
109 [m4_undefine([changeword])])
110 m4_rename_m4([debugfile])
111 m4_rename_m4([debugmode])
112 m4_rename_m4([decr])
113 m4_rename_m4([divnum])
114 m4_rename_m4([dumpdef])
115 m4_rename_m4([errprint])
116 m4_rename_m4([esyscmd])
117 m4_rename_m4([eval])
118 m4_rename_m4([format])
119 m4_undefine([include])
120 m4_rename_m4([incr])
121 m4_rename_m4([index])
122 m4_rename_m4([indir])
123 m4_rename_m4([len])
124 m4_rename([m4exit], [m4_exit])
125 m4_undefine([m4wrap])
126 m4_ifdef([mkstemp],dnl added in M4 1.4.8
127 [m4_rename_m4([mkstemp])
128 m4_copy([m4_mkstemp], [m4_maketemp])
129 m4_undefine([maketemp])],
130 [m4_rename_m4([maketemp])
131 m4_copy([m4_maketemp], [m4_mkstemp])])
132 m4_rename([patsubst], [m4_bpatsubst])
133 m4_rename_m4([popdef])
134 m4_rename_m4([pushdef])
135 m4_rename([regexp], [m4_bregexp])
136 m4_rename_m4([shift])
137 m4_undefine([sinclude])
138 m4_rename_m4([substr])
139 m4_ifdef([symbols],dnl present only in alpha-quality 1.4o
140 [m4_rename_m4([symbols])])
141 m4_rename_m4([syscmd])
142 m4_rename_m4([sysval])
143 m4_rename_m4([traceoff])
144 m4_rename_m4([traceon])
145 m4_rename_m4([translit])
146
147 # _m4_defn(ARG)
148 # -------------
149 # _m4_defn is for internal use only - it bypasses the wrapper, so it
150 # must only be used on one argument at a time, and only on macros
151 # known to be defined.  Make sure this still works if the user renames
152 # m4_defn but not _m4_defn.
153 m4_copy([m4_defn], [_m4_defn])
154
155 # _m4_divert_raw(NUM)
156 # -------------------
157 # _m4_divert_raw is for internal use only.  Use this instead of
158 # m4_builtin([divert], NUM), so that tracing diversion flow is easier.
159 m4_rename([divert], [_m4_divert_raw])
160
161 # _m4_popdef(ARG...)
162 # ------------------
163 # _m4_popdef is for internal use only - it bypasses the wrapper, so it
164 # must only be used on macros known to be defined.  Make sure this
165 # still works if the user renames m4_popdef but not _m4_popdef.
166 m4_copy([m4_popdef], [_m4_popdef])
167
168 # _m4_undefine(ARG...)
169 # --------------------
170 # _m4_undefine is for internal use only - it bypasses the wrapper, so
171 # it must only be used on macros known to be defined.  Make sure this
172 # still works if the user renames m4_undefine but not _m4_undefine.
173 m4_copy([m4_undefine], [_m4_undefine])
174
175 # _m4_undivert(NUM...)
176 # --------------------
177 # _m4_undivert is for internal use only, and should always be given
178 # arguments.  Use this instead of m4_builtin([undivert], NUM...), so
179 # that tracing diversion flow is easier.
180 m4_rename([undivert], [_m4_undivert])
181
182
183 ## ------------------- ##
184 ## 2. Error messages.  ##
185 ## ------------------- ##
186
187
188 # m4_location
189 # -----------
190 # Output the current file, colon, and the current line number.
191 m4_define([m4_location],
192 [__file__:__line__])
193
194
195 # m4_errprintn(MSG)
196 # -----------------
197 # Same as `errprint', but with the missing end of line.
198 m4_define([m4_errprintn],
199 [m4_errprint([$1
200 ])])
201
202
203 # m4_warning(MSG)
204 # ---------------
205 # Warn the user.
206 m4_define([m4_warning],
207 [m4_errprintn(m4_location[: warning: $1])])
208
209
210 # m4_fatal(MSG, [EXIT-STATUS])
211 # ----------------------------
212 # Fatal the user.                                                      :)
213 m4_define([m4_fatal],
214 [m4_errprintn(m4_location[: error: $1]
215 m4_expansion_stack)m4_exit(m4_if([$2],, 1, [$2]))])
216
217
218 # m4_assert(EXPRESSION, [EXIT-STATUS = 1])
219 # ----------------------------------------
220 # This macro ensures that EXPRESSION evaluates to true, and exits if
221 # EXPRESSION evaluates to false.
222 m4_define([m4_assert],
223 [m4_if(m4_eval([$1]), 0,
224        [m4_fatal([assert failed: $1], [$2])])])
225
226
227
228 ## ------------- ##
229 ## 3. Warnings.  ##
230 ## ------------- ##
231
232
233 # _m4_warn(CATEGORY, MESSAGE, [STACK-TRACE])
234 # ------------------------------------------
235 # Report a MESSAGE to the user if the CATEGORY of warnings is enabled.
236 # This is for traces only.
237 # If present, STACK-TRACE is a \n-separated list of "LOCATION: MESSAGE",
238 # where the last line (and no other) ends with "the top level".
239 #
240 # Within m4, the macro is a no-op.  This macro really matters
241 # when autom4te post-processes the trace output.
242 m4_define([_m4_warn], [])
243
244
245 # m4_warn(CATEGORY, MESSAGE)
246 # --------------------------
247 # Report a MESSAGE to the user if the CATEGORY of warnings is enabled.
248 m4_define([m4_warn],
249 [_m4_warn([$1], [$2],
250 m4_ifdef([_m4_expansion_stack], [m4_expansion_stack]))])
251
252
253
254 ## ------------------- ##
255 ## 4. File inclusion.  ##
256 ## ------------------- ##
257
258
259 # We also want to neutralize include (and sinclude for symmetry),
260 # but we want to extend them slightly: warn when a file is included
261 # several times.  This is, in general, a dangerous operation, because
262 # too many people forget to quote the first argument of m4_define.
263 #
264 # For instance in the following case:
265 #   m4_define(foo, [bar])
266 # then a second reading will turn into
267 #   m4_define(bar, [bar])
268 # which is certainly not what was meant.
269
270 # m4_include_unique(FILE)
271 # -----------------------
272 # Declare that the FILE was loading; and warn if it has already
273 # been included.
274 m4_define([m4_include_unique],
275 [m4_ifdef([m4_include($1)],
276           [m4_warn([syntax], [file `$1' included several times])])dnl
277 m4_define([m4_include($1)])])
278
279
280 # m4_include(FILE)
281 # ----------------
282 # Like the builtin include, but warns against multiple inclusions.
283 m4_define([m4_include],
284 [m4_include_unique([$1])dnl
285 m4_builtin([include], [$1])])
286
287
288 # m4_sinclude(FILE)
289 # -----------------
290 # Like the builtin sinclude, but warns against multiple inclusions.
291 m4_define([m4_sinclude],
292 [m4_include_unique([$1])dnl
293 m4_builtin([sinclude], [$1])])
294
295
296
297 ## ------------------------------------ ##
298 ## 5. Additional branching constructs.  ##
299 ## ------------------------------------ ##
300
301 # Both `m4_ifval' and `m4_ifset' tests against the empty string.  The
302 # difference is that `m4_ifset' is specialized on macros.
303 #
304 # In case of arguments of macros, eg. $1, it makes little difference.
305 # In the case of a macro `FOO', you don't want to check `m4_ifval(FOO,
306 # TRUE)', because if `FOO' expands with commas, there is a shifting of
307 # the arguments.  So you want to run `m4_ifval([FOO])', but then you just
308 # compare the *string* `FOO' against `', which, of course fails.
309 #
310 # So you want the variation `m4_ifset' that expects a macro name as $1.
311 # If this macro is both defined and defined to a non empty value, then
312 # it runs TRUE, etc.
313
314
315 # m4_ifblank(COND, [IF-BLANK], [IF-TEXT])
316 # m4_ifnblank(COND, [IF-TEXT], [IF-BLANK])
317 # ----------------------------------------
318 # If COND is empty, or consists only of blanks (space, tab, newline),
319 # then expand IF-BLANK, otherwise expand IF-TEXT.  This differs from
320 # m4_ifval only if COND has just whitespace, but it helps optimize in
321 # spite of users who mistakenly leave trailing space after what they
322 # thought was an empty argument:
323 #   macro(
324 #         []
325 #        )
326 #
327 # Writing one macro in terms of the other causes extra overhead, so
328 # we inline both definitions.
329 m4_define([m4_ifblank],
330 [m4_if(m4_translit([[$1]],  [ ][        ][
331 ]), [], [$2], [$3])])
332
333 m4_define([m4_ifnblank],
334 [m4_if(m4_translit([[$1]],  [ ][        ][
335 ]), [], [$3], [$2])])
336
337
338 # m4_ifval(COND, [IF-TRUE], [IF-FALSE])
339 # -------------------------------------
340 # If COND is not the empty string, expand IF-TRUE, otherwise IF-FALSE.
341 # Comparable to m4_ifdef.
342 m4_define([m4_ifval],
343 [m4_if([$1], [], [$3], [$2])])
344
345
346 # m4_n(TEXT)
347 # ----------
348 # If TEXT is not empty, return TEXT and a new line, otherwise nothing.
349 m4_define([m4_n],
350 [m4_if([$1],
351        [], [],
352            [$1
353 ])])
354
355
356 # m4_ifvaln(COND, [IF-TRUE], [IF-FALSE])
357 # --------------------------------------
358 # Same as `m4_ifval', but add an extra newline to IF-TRUE or IF-FALSE
359 # unless that argument is empty.
360 m4_define([m4_ifvaln],
361 [m4_if([$1],
362        [],   [m4_n([$3])],
363              [m4_n([$2])])])
364
365
366 # m4_ifset(MACRO, [IF-TRUE], [IF-FALSE])
367 # --------------------------------------
368 # If MACRO has no definition, or of its definition is the empty string,
369 # expand IF-FALSE, otherwise IF-TRUE.
370 m4_define([m4_ifset],
371 [m4_ifdef([$1],
372           [m4_ifval(_m4_defn([$1]), [$2], [$3])],
373           [$3])])
374
375
376 # m4_ifndef(NAME, [IF-NOT-DEFINED], [IF-DEFINED])
377 # -----------------------------------------------
378 m4_define([m4_ifndef],
379 [m4_ifdef([$1], [$3], [$2])])
380
381
382 # m4_case(SWITCH, VAL1, IF-VAL1, VAL2, IF-VAL2, ..., DEFAULT)
383 # -----------------------------------------------------------
384 # m4 equivalent of
385 # switch (SWITCH)
386 # {
387 #   case VAL1:
388 #     IF-VAL1;
389 #     break;
390 #   case VAL2:
391 #     IF-VAL2;
392 #     break;
393 #   ...
394 #   default:
395 #     DEFAULT;
396 #     break;
397 # }.
398 # All the values are optional, and the macro is robust to active
399 # symbols properly quoted.
400 #
401 # Please keep foreach.m4 in sync with any adjustments made here.
402 m4_define([m4_case],
403 [m4_if([$#], 0, [],
404        [$#], 1, [],
405        [$#], 2, [$2],
406        [$1], [$2], [$3],
407        [$0([$1], m4_shift3($@))])])
408
409
410 # m4_bmatch(SWITCH, RE1, VAL1, RE2, VAL2, ..., DEFAULT)
411 # -----------------------------------------------------
412 # m4 equivalent of
413 #
414 # if (SWITCH =~ RE1)
415 #   VAL1;
416 # elif (SWITCH =~ RE2)
417 #   VAL2;
418 # elif ...
419 #   ...
420 # else
421 #   DEFAULT
422 #
423 # All the values are optional, and the macro is robust to active symbols
424 # properly quoted.
425 #
426 # Please keep foreach.m4 in sync with any adjustments made here.
427 m4_define([m4_bmatch],
428 [m4_if([$#], 0, [m4_fatal([$0: too few arguments: $#])],
429        [$#], 1, [m4_fatal([$0: too few arguments: $#: $1])],
430        [$#], 2, [$2],
431        [m4_if(m4_bregexp([$1], [$2]), -1, [$0([$1], m4_shift3($@))],
432               [$3])])])
433
434 # m4_argn(N, ARGS...)
435 # -------------------
436 # Extract argument N (greater than 0) from ARGS.  Example:
437 #   m4_define([b], [B])
438 #   m4_argn([2], [a], [b], [c]) => b
439 #
440 # Rather than using m4_car(m4_shiftn([$1], $@)), we exploit the fact that
441 # GNU m4 can directly reference any argument, through an indirect macro.
442 m4_define([m4_argn],
443 [m4_assert([0 < $1])]dnl
444 [m4_pushdef([_$0], [_m4_popdef([_$0])]m4_dquote([$]m4_incr([$1])))_$0($@)])
445
446
447 # m4_car(ARGS...)
448 # m4_cdr(ARGS...)
449 # ---------------
450 # Manipulate m4 lists.  m4_car returns the first argument.  m4_cdr
451 # bundles all but the first argument into a quoted list.  These two
452 # macros are generally used with list arguments, with quoting removed
453 # to break the list into multiple m4 ARGS.
454 m4_define([m4_car], [[$1]])
455 m4_define([m4_cdr],
456 [m4_if([$#], 0, [m4_fatal([$0: cannot be called without arguments])],
457        [$#], 1, [],
458        [m4_dquote(m4_shift($@))])])
459
460 # _m4_cdr(ARGS...)
461 # ----------------
462 # Like m4_cdr, except include a leading comma unless only one argument
463 # remains.  Why?  Because comparing a large list against [] is more
464 # expensive in expansion time than comparing the number of arguments; so
465 # _m4_cdr can be used to reduce the number of arguments when it is time
466 # to end recursion.
467 m4_define([_m4_cdr],
468 [m4_if([$#], 1, [],
469        [, m4_dquote(m4_shift($@))])])
470
471
472
473 # m4_cond(TEST1, VAL1, IF-VAL1, TEST2, VAL2, IF-VAL2, ..., [DEFAULT])
474 # -------------------------------------------------------------------
475 # Similar to m4_if, except that each TEST is expanded when encountered.
476 # If the expansion of TESTn matches the string VALn, the result is IF-VALn.
477 # The result is DEFAULT if no tests passed.  This macro allows
478 # short-circuiting of expensive tests, where it pays to arrange quick
479 # filter tests to run first.
480 #
481 # For an example, consider a previous implementation of _AS_QUOTE_IFELSE:
482 #
483 #    m4_if(m4_index([$1], [\]), [-1], [$2],
484 #          m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
485 #          m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
486 #          m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
487 #          m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
488 #          [$2])
489 #
490 # Here, m4_index is computed 5 times, and m4_eval 4, even if $1 contains
491 # no backslash.  It is more efficient to do:
492 #
493 #    m4_cond([m4_index([$1], [\])], [-1], [$2],
494 #            [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
495 #            [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
496 #            [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
497 #            [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
498 #            [$2])
499 #
500 # In the common case of $1 with no backslash, only one m4_index expansion
501 # occurs, and m4_eval is avoided altogether.
502 #
503 # Please keep foreach.m4 in sync with any adjustments made here.
504 m4_define([m4_cond],
505 [m4_if([$#], [0], [m4_fatal([$0: cannot be called without arguments])],
506        [$#], [1], [$1],
507        m4_eval([$# % 3]), [2], [m4_fatal([$0: missing an argument])],
508        [_$0($@)])])
509
510 m4_define([_m4_cond],
511 [m4_if(($1), [($2)], [$3],
512        [$#], [3], [],
513        [$#], [4], [$4],
514        [$0(m4_shift3($@))])])
515
516
517 ## ---------------------------------------- ##
518 ## 6. Enhanced version of some primitives.  ##
519 ## ---------------------------------------- ##
520
521 # m4_bpatsubsts(STRING, RE1, SUBST1, RE2, SUBST2, ...)
522 # ----------------------------------------------------
523 # m4 equivalent of
524 #
525 #   $_ = STRING;
526 #   s/RE1/SUBST1/g;
527 #   s/RE2/SUBST2/g;
528 #   ...
529 #
530 # All the values are optional, and the macro is robust to active symbols
531 # properly quoted.
532 #
533 # I would have liked to name this macro `m4_bpatsubst', unfortunately,
534 # due to quotation problems, I need to double quote $1 below, therefore
535 # the anchors are broken :(  I can't let users be trapped by that.
536 #
537 # Recall that m4_shift3 always results in an argument.  Hence, we need
538 # to distinguish between a final deletion vs. ending recursion.
539 #
540 # Please keep foreach.m4 in sync with any adjustments made here.
541 m4_define([m4_bpatsubsts],
542 [m4_if([$#], 0, [m4_fatal([$0: too few arguments: $#])],
543        [$#], 1, [m4_fatal([$0: too few arguments: $#: $1])],
544        [$#], 2, [m4_unquote(m4_builtin([patsubst], [[$1]], [$2]))],
545        [$#], 3, [m4_unquote(m4_builtin([patsubst], [[$1]], [$2], [$3]))],
546        [_$0($@m4_if(m4_eval($# & 1), 0, [,]))])])
547 m4_define([_m4_bpatsubsts],
548 [m4_if([$#], 2, [$1],
549        [$0(m4_builtin([patsubst], [[$1]], [$2], [$3]),
550            m4_shift3($@))])])
551
552
553 # m4_copy(SRC, DST)
554 # -----------------
555 # Define the pushdef stack DST as a copy of the pushdef stack SRC;
556 # give an error if DST is already defined.  This is particularly nice
557 # for copying self-modifying pushdef stacks, where the top definition
558 # includes one-shot initialization that is later popped to the normal
559 # definition.  This version intentionally does nothing if SRC is
560 # undefined.
561 #
562 # Some macros simply can't be renamed with this method: namely, anything
563 # involved in the implementation of m4_stack_foreach_sep.
564 m4_define([m4_copy],
565 [m4_ifdef([$2], [m4_fatal([$0: won't overwrite defined macro: $2])],
566           [m4_stack_foreach_sep([$1], [m4_pushdef([$2],], [)])])]dnl
567 [m4_ifdef([m4_location($1)], [m4_define([m4_location($2)], m4_location)])])
568
569
570 # m4_copy_force(SRC, DST)
571 # m4_rename_force(SRC, DST)
572 # -------------------------
573 # Like m4_copy/m4_rename, except blindly overwrite any existing DST.
574 # Note that m4_copy_force tolerates undefined SRC, while m4_rename_force
575 # does not.
576 m4_define([m4_copy_force],
577 [m4_ifdef([$2], [_m4_undefine([$2])])m4_copy($@)])
578
579 m4_define([m4_rename_force],
580 [m4_ifdef([$2], [_m4_undefine([$2])])m4_rename($@)])
581
582
583 # m4_define_default(MACRO, VALUE)
584 # -------------------------------
585 # If MACRO is undefined, set it to VALUE.
586 m4_define([m4_define_default],
587 [m4_ifndef([$1], [m4_define($@)])])
588
589
590 # m4_default(EXP1, EXP2)
591 # m4_default_nblank(EXP1, EXP2)
592 # -----------------------------
593 # Returns EXP1 if not empty/blank, otherwise EXP2.  Expand the result.
594 #
595 # m4_default is called on hot paths, so inline the contents of m4_ifval,
596 # for one less round of expansion.
597 m4_define([m4_default],
598 [m4_if([$1], [], [$2], [$1])])
599
600 m4_define([m4_default_nblank],
601 [m4_ifblank([$1], [$2], [$1])])
602
603
604 # m4_default_quoted(EXP1, EXP2)
605 # m4_default_nblank_quoted(EXP1, EXP2)
606 # ------------------------------------
607 # Returns EXP1 if non empty/blank, otherwise EXP2.  Leave the result quoted.
608 #
609 # For comparison:
610 #   m4_define([active], [ACTIVE])
611 #   m4_default([active], [default]) => ACTIVE
612 #   m4_default([], [active]) => ACTIVE
613 #   -m4_default([ ], [active])- => - -
614 #   -m4_default_nblank([ ], [active])- => -ACTIVE-
615 #   m4_default_quoted([active], [default]) => active
616 #   m4_default_quoted([], [active]) => active
617 #   -m4_default_quoted([ ], [active])- => - -
618 #   -m4_default_nblank_quoted([ ], [active])- => -active-
619 #
620 # m4_default macro is called on hot paths, so inline the contents of m4_ifval,
621 # for one less round of expansion.
622 m4_define([m4_default_quoted],
623 [m4_if([$1], [], [[$2]], [[$1]])])
624
625 m4_define([m4_default_nblank_quoted],
626 [m4_ifblank([$1], [[$2]], [[$1]])])
627
628
629 # m4_defn(NAME)
630 # -------------
631 # Like the original, except guarantee a warning when using something which is
632 # undefined (unlike M4 1.4.x).  This replacement is not a full-featured
633 # replacement: if any of the defined macros contain unbalanced quoting, but
634 # when pasted together result in a well-quoted string, then only native m4
635 # support is able to get it correct.  But that's where quadrigraphs come in
636 # handy, if you really need unbalanced quotes inside your macros.
637 #
638 # This macro is called frequently, so minimize the amount of additional
639 # expansions by skipping m4_ifndef.  Better yet, if __m4_version__ exists,
640 # (added in M4 1.6), then let m4 do the job for us (see m4_init).
641 m4_define([m4_defn],
642 [m4_if([$#], [0], [[$0]],
643        [$#], [1], [m4_ifdef([$1], [_m4_defn([$1])],
644                             [m4_fatal([$0: undefined macro: $1])])],
645        [m4_map_args([$0], $@)])])
646
647
648 # m4_dumpdef(NAME...)
649 # -------------------
650 # In m4 1.4.x, dumpdef writes to the current debugfile, rather than
651 # stderr.  This in turn royally confuses autom4te; so we follow the
652 # lead of newer m4 and always dump to stderr.  Unlike the original,
653 # this version requires an argument, since there is no convenient way
654 # in m4 1.4.x to grab the names of all defined macros.  Newer m4
655 # always dumps to stderr, regardless of the current debugfile; it also
656 # provides m4symbols as a way to grab all current macro names.  But
657 # dumpdefs is not frequently called, so we don't need to worry about
658 # conditionally using these newer features.  Also, this version
659 # doesn't sort multiple arguments.
660 #
661 # If we detect m4 1.6 or newer, then provide an alternate definition,
662 # installed during m4_init, that allows builtins through.
663 # Unfortunately, there is no nice way in m4 1.4.x to dump builtins.
664 m4_define([m4_dumpdef],
665 [m4_if([$#], [0], [m4_fatal([$0: missing argument])],
666        [$#], [1], [m4_ifdef([$1], [m4_errprintn(
667   [$1:  ]m4_dquote(_m4_defn([$1])))], [m4_fatal([$0: undefined macro: $1])])],
668        [m4_map_args([$0], $@)])])
669
670 m4_define([_m4_dumpdef],
671 [m4_if([$#], [0], [m4_fatal([$0: missing argument])],
672        [$#], [1], [m4_builtin([dumpdef], [$1])],
673        [m4_map_args_sep([m4_builtin([dumpdef],], [)], [], $@)])])
674
675
676 # m4_dumpdefs(NAME...)
677 # --------------------
678 # Similar to `m4_dumpdef(NAME)', but if NAME was m4_pushdef'ed, display its
679 # value stack (most recent displayed first).  Also, this version silently
680 # ignores undefined macros, rather than erroring out.
681 #
682 # This macro cheats, because it relies on the current definition of NAME
683 # while the second argument of m4_stack_foreach_lifo is evaluated (which
684 # would be undefined according to the API).
685 m4_define([m4_dumpdefs],
686 [m4_if([$#], [0], [m4_fatal([$0: missing argument])],
687        [$#], [1], [m4_stack_foreach_lifo([$1], [m4_dumpdef([$1])m4_ignore])],
688        [m4_map_args([$0], $@)])])
689
690 # m4_esyscmd_s(COMMAND)
691 # ---------------------
692 # Like m4_esyscmd, except strip any trailing newlines, thus behaving
693 # more like shell command substitution.
694 m4_define([m4_esyscmd_s],
695 [m4_chomp_all(m4_esyscmd([$1]))])
696
697
698 # m4_popdef(NAME)
699 # ---------------
700 # Like the original, except guarantee a warning when using something which is
701 # undefined (unlike M4 1.4.x).
702 #
703 # This macro is called frequently, so minimize the amount of additional
704 # expansions by skipping m4_ifndef.  Better yet, if __m4_version__ exists,
705 # (added in M4 1.6), then let m4 do the job for us (see m4_init).
706 m4_define([m4_popdef],
707 [m4_if([$#], [0], [[$0]],
708        [$#], [1], [m4_ifdef([$1], [_m4_popdef([$1])],
709                             [m4_fatal([$0: undefined macro: $1])])],
710        [m4_map_args([$0], $@)])])
711
712
713 # m4_shiftn(N, ...)
714 # -----------------
715 # Returns ... shifted N times.  Useful for recursive "varargs" constructs.
716 #
717 # Autoconf does not use this macro, because it is inherently slower than
718 # calling the common cases of m4_shift2 or m4_shift3 directly.  But it
719 # might as well be fast for other clients, such as Libtool.  One way to
720 # do this is to expand $@ only once in _m4_shiftn (otherwise, for long
721 # lists, the expansion of m4_if takes twice as much memory as what the
722 # list itself occupies, only to throw away the unused branch).  The end
723 # result is strictly equivalent to
724 #   m4_if([$1], 1, [m4_shift(,m4_shift(m4_shift($@)))],
725 #         [_m4_shiftn(m4_decr([$1]), m4_shift(m4_shift($@)))])
726 # but with the final `m4_shift(m4_shift($@)))' shared between the two
727 # paths.  The first leg uses a no-op m4_shift(,$@) to balance out the ().
728 #
729 # Please keep foreach.m4 in sync with any adjustments made here.
730 m4_define([m4_shiftn],
731 [m4_assert(0 < $1 && $1 < $#)_$0($@)])
732
733 m4_define([_m4_shiftn],
734 [m4_if([$1], 1, [m4_shift(],
735        [$0(m4_decr([$1])]), m4_shift(m4_shift($@)))])
736
737 # m4_shift2(...)
738 # m4_shift3(...)
739 # --------------
740 # Returns ... shifted twice, and three times.  Faster than m4_shiftn.
741 m4_define([m4_shift2], [m4_shift(m4_shift($@))])
742 m4_define([m4_shift3], [m4_shift(m4_shift(m4_shift($@)))])
743
744 # _m4_shift2(...)
745 # _m4_shift3(...)
746 # ---------------
747 # Like m4_shift2 or m4_shift3, except include a leading comma unless shifting
748 # consumes all arguments.  Why?  Because in recursion, it is nice to
749 # distinguish between 1 element left and 0 elements left, based on how many
750 # arguments this shift expands to.
751 m4_define([_m4_shift2],
752 [m4_if([$#], [2], [],
753        [, m4_shift(m4_shift($@))])])
754 m4_define([_m4_shift3],
755 [m4_if([$#], [3], [],
756        [, m4_shift(m4_shift(m4_shift($@)))])])
757
758
759 # m4_undefine(NAME)
760 # -----------------
761 # Like the original, except guarantee a warning when using something which is
762 # undefined (unlike M4 1.4.x).
763 #
764 # This macro is called frequently, so minimize the amount of additional
765 # expansions by skipping m4_ifndef.  Better yet, if __m4_version__ exists,
766 # (added in M4 1.6), then let m4 do the job for us (see m4_init).
767 m4_define([m4_undefine],
768 [m4_if([$#], [0], [[$0]],
769        [$#], [1], [m4_ifdef([$1], [_m4_undefine([$1])],
770                             [m4_fatal([$0: undefined macro: $1])])],
771        [m4_map_args([$0], $@)])])
772
773 # _m4_wrap(PRE, POST)
774 # -------------------
775 # Helper macro for m4_wrap and m4_wrap_lifo.  Allows nested calls to
776 # m4_wrap within wrapped text.  Use _m4_defn and _m4_popdef for speed.
777 m4_define([_m4_wrap],
778 [m4_ifdef([$0_text],
779           [m4_define([$0_text], [$1]_m4_defn([$0_text])[$2])],
780           [m4_builtin([m4wrap], [m4_unquote(
781   _m4_defn([$0_text])_m4_popdef([$0_text]))])m4_define([$0_text], [$1$2])])])
782
783 # m4_wrap(TEXT)
784 # -------------
785 # Append TEXT to the list of hooks to be executed at the end of input.
786 # Whereas the order of the original may be LIFO in the underlying m4,
787 # this version is always FIFO.
788 m4_define([m4_wrap],
789 [_m4_wrap([], [$1[]])])
790
791 # m4_wrap_lifo(TEXT)
792 # ------------------
793 # Prepend TEXT to the list of hooks to be executed at the end of input.
794 # Whereas the order of m4_wrap may be FIFO in the underlying m4, this
795 # version is always LIFO.
796 m4_define([m4_wrap_lifo],
797 [_m4_wrap([$1[]])])
798
799 ## ------------------------- ##
800 ## 7. Quoting manipulation.  ##
801 ## ------------------------- ##
802
803
804 # m4_apply(MACRO, LIST)
805 # ---------------------
806 # Invoke MACRO, with arguments provided from the quoted list of
807 # comma-separated quoted arguments.  If LIST is empty, invoke MACRO
808 # without arguments.  The expansion will not be concatenated with
809 # subsequent text.
810 m4_define([m4_apply],
811 [m4_if([$2], [], [$1], [$1($2)])[]])
812
813 # _m4_apply(MACRO, LIST)
814 # ----------------------
815 # Like m4_apply, except do nothing if LIST is empty.
816 m4_define([_m4_apply],
817 [m4_if([$2], [], [], [$1($2)[]])])
818
819
820 # m4_count(ARGS)
821 # --------------
822 # Return a count of how many ARGS are present.
823 m4_define([m4_count], [$#])
824
825
826 # m4_curry(MACRO, ARG...)
827 # -----------------------
828 # Perform argument currying.  The expansion of this macro is another
829 # macro that takes exactly one argument, appends it to the end of the
830 # original ARG list, then invokes MACRO.  For example:
831 #   m4_curry([m4_curry], [m4_reverse], [1])([2])([3]) => 3, 2, 1
832 # Not quite as practical as m4_incr, but you could also do:
833 #   m4_define([add], [m4_eval(([$1]) + ([$2]))])
834 #   m4_define([add_one], [m4_curry([add], [1])])
835 #   add_one()([2]) => 3
836 m4_define([m4_curry], [$1(m4_shift($@,)_$0])
837 m4_define([_m4_curry],               [[$1])])
838
839
840 # m4_do(STRING, ...)
841 # ------------------
842 # This macro invokes all its arguments (in sequence, of course).  It is
843 # useful for making your macros more structured and readable by dropping
844 # unnecessary dnl's and have the macros indented properly.  No concatenation
845 # occurs after a STRING; use m4_unquote(m4_join(,STRING)) for that.
846 #
847 # Please keep foreach.m4 in sync with any adjustments made here.
848 m4_define([m4_do],
849 [m4_if([$#], 0, [],
850        [$#], 1, [$1[]],
851        [$1[]$0(m4_shift($@))])])
852
853
854 # m4_dquote(ARGS)
855 # ---------------
856 # Return ARGS as a quoted list of quoted arguments.
857 m4_define([m4_dquote],  [[$@]])
858
859
860 # m4_dquote_elt(ARGS)
861 # -------------------
862 # Return ARGS as an unquoted list of double-quoted arguments.
863 #
864 # Please keep foreach.m4 in sync with any adjustments made here.
865 m4_define([m4_dquote_elt],
866 [m4_if([$#], [0], [],
867        [$#], [1], [[[$1]]],
868        [[[$1]],$0(m4_shift($@))])])
869
870
871 # m4_echo(ARGS)
872 # -------------
873 # Return the ARGS, with the same level of quoting.  Whitespace after
874 # unquoted commas are consumed.
875 m4_define([m4_echo], [$@])
876
877
878 # m4_expand(ARG)
879 # _m4_expand(ARG)
880 # ---------------
881 # Return the expansion of ARG as a single string.  Unlike
882 # m4_quote($1), this preserves whitespace following single-quoted
883 # commas that appear within ARG.  It also deals with shell case
884 # statements.
885 #
886 #   m4_define([active], [ACT, IVE])
887 #   m4_define([active2], [[ACT, IVE]])
888 #   m4_quote(active, active2)
889 #   => ACT,IVE,ACT, IVE
890 #   m4_expand([active, active2])
891 #   => ACT, IVE, ACT, IVE
892 #
893 # Unfortunately, due to limitations in m4, ARG must expand to
894 # something with balanced quotes (use quadrigraphs to get around
895 # this), and should not contain the unlikely delimiters -=<{( or
896 # )}>=-.  It is possible to have unbalanced quoted `(' or `)', as well
897 # as unbalanced unquoted `)'.  m4_expand can handle unterminated
898 # comments or dnl on the final line, at the expense of speed; it also
899 # aids in detecting attempts to incorrectly change the current
900 # diversion inside ARG.  Meanwhile, _m4_expand is faster but must be
901 # given a terminated expansion, and has no safety checks for
902 # mis-diverted text.
903 #
904 # Exploit that extra unquoted () will group unquoted commas and the
905 # following whitespace.  m4_bpatsubst can't handle newlines inside $1,
906 # and m4_substr strips quoting.  So we (ab)use m4_changequote, using
907 # temporary quotes to remove the delimiters that conveniently included
908 # the unquoted () that were added prior to the changequote.
909 #
910 # Thanks to shell case statements, too many people are prone to pass
911 # underquoted `)', so we try to detect that by passing a marker as a
912 # fourth argument; if the marker is not present, then we assume that
913 # we encountered an early `)', and re-expand the first argument, but
914 # this time with one more `(' in the second argument and in the
915 # open-quote delimiter.  We must also ignore the slop from the
916 # previous try.  The final macro is thus half line-noise, half art.
917 m4_define([m4_expand],
918 [m4_pushdef([m4_divert], _m4_defn([_m4_divert_unsafe]))]dnl
919 [m4_pushdef([m4_divert_push], _m4_defn([_m4_divert_unsafe]))]dnl
920 [m4_chomp(_$0([$1
921 ]))_m4_popdef([m4_divert], [m4_divert_push])])
922
923 m4_define([_m4_expand], [$0_([$1], [(], -=<{($1)}>=-, [}>=-])])
924
925 m4_define([_m4_expand_],
926 [m4_if([$4], [}>=-],
927        [m4_changequote([-=<{$2], [)}>=-])$3m4_changequote([, ])],
928        [$0([$1], [($2], -=<{($2$1)}>=-, [}>=-])m4_ignore$2])])
929
930
931 # m4_ignore(ARGS)
932 # ---------------
933 # Expands to nothing.  Useful for conditionally ignoring an arbitrary
934 # number of arguments (see _m4_list_cmp for an example).
935 m4_define([m4_ignore])
936
937
938 # m4_make_list(ARGS)
939 # ------------------
940 # Similar to m4_dquote, this creates a quoted list of quoted ARGS.  This
941 # version is less efficient than m4_dquote, but separates each argument
942 # with a comma and newline, rather than just comma, for readability.
943 # When developing an m4sugar algorithm, you could temporarily use
944 #   m4_pushdef([m4_dquote],m4_defn([m4_make_list]))
945 # around your code to make debugging easier.
946 m4_define([m4_make_list], [m4_join([,
947 ], m4_dquote_elt($@))])
948
949
950 # m4_noquote(STRING)
951 # ------------------
952 # Return the result of ignoring all quotes in STRING and invoking the
953 # macros it contains.  Among other things, this is useful for enabling
954 # macro invocations inside strings with [] blocks (for instance regexps
955 # and help-strings).  On the other hand, since all quotes are disabled,
956 # any macro expanded during this time that relies on nested [] quoting
957 # will likely crash and burn.  This macro is seldom useful; consider
958 # m4_unquote or m4_expand instead.
959 m4_define([m4_noquote],
960 [m4_changequote([-=<{(],[)}>=-])$1-=<{()}>=-m4_changequote([,])])
961
962
963 # m4_quote(ARGS)
964 # --------------
965 # Return ARGS as a single argument.  Any whitespace after unquoted commas
966 # is stripped.  There is always output, even when there were no arguments.
967 #
968 # It is important to realize the difference between `m4_quote(exp)' and
969 # `[exp]': in the first case you obtain the quoted *result* of the
970 # expansion of EXP, while in the latter you just obtain the string
971 # `exp'.
972 m4_define([m4_quote],  [[$*]])
973
974
975 # _m4_quote(ARGS)
976 # ---------------
977 # Like m4_quote, except that when there are no arguments, there is no
978 # output.  For conditional scenarios (such as passing _m4_quote as the
979 # macro name in m4_mapall), this feature can be used to distinguish between
980 # one argument of the empty string vs. no arguments.  However, in the
981 # normal case with arguments present, this is less efficient than m4_quote.
982 m4_define([_m4_quote],
983 [m4_if([$#], [0], [], [[$*]])])
984
985
986 # m4_reverse(ARGS)
987 # ----------------
988 # Output ARGS in reverse order.
989 #
990 # Please keep foreach.m4 in sync with any adjustments made here.
991 m4_define([m4_reverse],
992 [m4_if([$#], [0], [], [$#], [1], [[$1]],
993        [$0(m4_shift($@)), [$1]])])
994
995
996 # m4_unquote(ARGS)
997 # ----------------
998 # Remove one layer of quotes from each ARG, performing one level of
999 # expansion.  For one argument, m4_unquote([arg]) is more efficient than
1000 # m4_do([arg]), but for multiple arguments, the difference is that
1001 # m4_unquote separates arguments with commas while m4_do concatenates.
1002 # Follow this macro with [] if concatenation with subsequent text is
1003 # undesired.
1004 m4_define([m4_unquote], [$*])
1005
1006
1007 ## -------------------------- ##
1008 ## 8. Implementing m4 loops.  ##
1009 ## -------------------------- ##
1010
1011
1012 # m4_for(VARIABLE, FIRST, LAST, [STEP = +/-1], EXPRESSION)
1013 # --------------------------------------------------------
1014 # Expand EXPRESSION defining VARIABLE to FROM, FROM + 1, ..., TO with
1015 # increments of STEP.  Both limits are included, and bounds are
1016 # checked for consistency.  The algorithm is robust to indirect
1017 # VARIABLE names.  Changing VARIABLE inside EXPRESSION will not impact
1018 # the number of iterations.
1019 #
1020 # Uses _m4_defn for speed, and avoid dnl in the macro body.  Factor
1021 # the _m4_for call so that EXPRESSION is only parsed once.
1022 m4_define([m4_for],
1023 [m4_pushdef([$1], m4_eval([$2]))]dnl
1024 [m4_cond([m4_eval(([$3]) > ([$2]))], 1,
1025            [m4_pushdef([_m4_step], m4_eval(m4_default_quoted([$4],
1026               1)))m4_assert(_m4_step > 0)_$0(_m4_defn([$1]),
1027   m4_eval((([$3]) - ([$2])) / _m4_step * _m4_step + ([$2])), _m4_step,],
1028          [m4_eval(([$3]) < ([$2]))], 1,
1029            [m4_pushdef([_m4_step], m4_eval(m4_default_quoted([$4],
1030               -1)))m4_assert(_m4_step < 0)_$0(_m4_defn([$1]),
1031   m4_eval((([$2]) - ([$3])) / -(_m4_step) * _m4_step + ([$2])), _m4_step,],
1032          [m4_pushdef([_m4_step])_$0(_m4_defn([$1]), _m4_defn([$1]), 0,])]dnl
1033 [[m4_define([$1],], [)$5])m4_popdef([_m4_step], [$1])])
1034
1035 # _m4_for(COUNT, LAST, STEP, PRE, POST)
1036 # -------------------------------------
1037 # Core of the loop, no consistency checks, all arguments are plain
1038 # numbers.  Expand PRE[COUNT]POST, then alter COUNT by STEP and
1039 # iterate if COUNT is not LAST.
1040 m4_define([_m4_for],
1041 [$4[$1]$5[]m4_if([$1], [$2], [],
1042                  [$0(m4_eval([$1 + $3]), [$2], [$3], [$4], [$5])])])
1043
1044
1045 # Implementing `foreach' loops in m4 is much more tricky than it may
1046 # seem.  For example, the old M4 1.4.4 manual had an incorrect example,
1047 # which looked like this (when translated to m4sugar):
1048 #
1049 # | # foreach(VAR, (LIST), STMT)
1050 # | m4_define([foreach],
1051 # |   [m4_pushdef([$1])_foreach([$1], [$2], [$3])m4_popdef([$1])])
1052 # | m4_define([_arg1], [$1])
1053 # | m4_define([_foreach],
1054 # |   [m4_if([$2], [()], ,
1055 # |     [m4_define([$1], _arg1$2)$3[]_foreach([$1], (m4_shift$2), [$3])])])
1056 #
1057 # But then if you run
1058 #
1059 # | m4_define(a, 1)
1060 # | m4_define(b, 2)
1061 # | m4_define(c, 3)
1062 # | foreach([f], [([a], [(b], [c)])], [echo f
1063 # | ])
1064 #
1065 # it gives
1066 #
1067 #  => echo 1
1068 #  => echo (2,3)
1069 #
1070 # which is not what is expected.
1071 #
1072 # Of course the problem is that many quotes are missing.  So you add
1073 # plenty of quotes at random places, until you reach the expected
1074 # result.  Alternatively, if you are a quoting wizard, you directly
1075 # reach the following implementation (but if you really did, then
1076 # apply to the maintenance of m4sugar!).
1077 #
1078 # | # foreach(VAR, (LIST), STMT)
1079 # | m4_define([foreach], [m4_pushdef([$1])_foreach($@)m4_popdef([$1])])
1080 # | m4_define([_arg1], [[$1]])
1081 # | m4_define([_foreach],
1082 # |  [m4_if($2, [()], ,
1083 # |    [m4_define([$1], [_arg1$2])$3[]_foreach([$1], [(m4_shift$2)], [$3])])])
1084 #
1085 # which this time answers
1086 #
1087 #  => echo a
1088 #  => echo (b
1089 #  => echo c)
1090 #
1091 # Bingo!
1092 #
1093 # Well, not quite.
1094 #
1095 # With a better look, you realize that the parens are more a pain than
1096 # a help: since anyway you need to quote properly the list, you end up
1097 # with always using an outermost pair of parens and an outermost pair
1098 # of quotes.  Rejecting the parens both eases the implementation, and
1099 # simplifies the use:
1100 #
1101 # | # foreach(VAR, (LIST), STMT)
1102 # | m4_define([foreach], [m4_pushdef([$1])_foreach($@)m4_popdef([$1])])
1103 # | m4_define([_arg1], [$1])
1104 # | m4_define([_foreach],
1105 # |  [m4_if($2, [], ,
1106 # |    [m4_define([$1], [_arg1($2)])$3[]_foreach([$1], [m4_shift($2)], [$3])])])
1107 #
1108 #
1109 # Now, just replace the `$2' with `m4_quote($2)' in the outer `m4_if'
1110 # to improve robustness, and you come up with a nice implementation
1111 # that doesn't require extra parentheses in the user's LIST.
1112 #
1113 # But wait -  now the algorithm is quadratic, because every recursion of
1114 # the algorithm keeps the entire LIST and merely adds another m4_shift to
1115 # the quoted text.  If the user has a lot of elements in LIST, you can
1116 # bring the system to its knees with the memory m4 then requires, or trip
1117 # the m4 --nesting-limit recursion factor.  The only way to avoid
1118 # quadratic growth is ensure m4_shift is expanded prior to the recursion.
1119 # Hence the design below.
1120 #
1121 # The M4 manual now includes a chapter devoted to this issue, with
1122 # the lessons learned from m4sugar.  And still, this design is only
1123 # optimal for M4 1.6; see foreach.m4 for yet more comments on why
1124 # M4 1.4.x uses yet another implementation.
1125
1126
1127 # m4_foreach(VARIABLE, LIST, EXPRESSION)
1128 # --------------------------------------
1129 #
1130 # Expand EXPRESSION assigning each value of the LIST to VARIABLE.
1131 # LIST should have the form `item_1, item_2, ..., item_n', i.e. the
1132 # whole list must *quoted*.  Quote members too if you don't want them
1133 # to be expanded.
1134 #
1135 # This macro is robust to active symbols:
1136 #      | m4_define(active, [ACT, IVE])
1137 #      | m4_foreach(Var, [active, active], [-Var-])
1138 #     => -ACT--IVE--ACT--IVE-
1139 #
1140 #      | m4_foreach(Var, [[active], [active]], [-Var-])
1141 #     => -ACT, IVE--ACT, IVE-
1142 #
1143 #      | m4_foreach(Var, [[[active]], [[active]]], [-Var-])
1144 #     => -active--active-
1145 #
1146 # This macro is called frequently, so avoid extra expansions such as
1147 # m4_ifval and dnl.  Also, since $2 might be quite large, try to use it
1148 # as little as possible in _m4_foreach; each extra use requires that much
1149 # more memory for expansion.  So, rather than directly compare $2 against
1150 # [] and use m4_car/m4_cdr for recursion, we instead unbox the list (which
1151 # requires swapping the argument order in the helper), insert an ignored
1152 # third argument, and use m4_shift3 to detect when recursion is complete,
1153 # at which point this looks very much like m4_map_args.
1154 m4_define([m4_foreach],
1155 [m4_if([$2], [], [],
1156        [m4_pushdef([$1])_$0([m4_define([$1],], [)$3], [],
1157   $2)m4_popdef([$1])])])
1158
1159 # _m4_foreach(PRE, POST, IGNORED, ARG...)
1160 # ---------------------------------------
1161 # Form the common basis of the m4_foreach and m4_map macros.  For each
1162 # ARG, expand PRE[ARG]POST[].  The IGNORED argument makes recursion
1163 # easier, and must be supplied rather than implicit.
1164 #
1165 # Please keep foreach.m4 in sync with any adjustments made here.
1166 m4_define([_m4_foreach],
1167 [m4_if([$#], [3], [],
1168        [$1[$4]$2[]$0([$1], [$2], m4_shift3($@))])])
1169
1170
1171 # m4_foreach_w(VARIABLE, LIST, EXPRESSION)
1172 # ----------------------------------------
1173 # Like m4_foreach, but the list is whitespace separated.  Depending on
1174 # EXPRESSION, it may be more efficient to use m4_map_args_w.
1175 #
1176 # This macro is robust to active symbols:
1177 #    m4_foreach_w([Var], [ active
1178 #    b  act\
1179 #    ive  ], [-Var-])end
1180 #    => -active--b--active-end
1181 #
1182 # This used to use a slower implementation based on m4_foreach:
1183 #   m4_foreach([$1], m4_split(m4_normalize([$2]), [ ]), [$3])
1184 m4_define([m4_foreach_w],
1185 [m4_pushdef([$1])m4_map_args_w([$2],
1186   [m4_define([$1],], [)$3])m4_popdef([$1])])
1187
1188
1189 # m4_map(MACRO, LIST)
1190 # m4_mapall(MACRO, LIST)
1191 # ----------------------
1192 # Invoke MACRO($1), MACRO($2) etc. where $1, $2... are the elements of
1193 # LIST.  $1, $2... must in turn be lists, appropriate for m4_apply.
1194 # If LIST contains an empty sublist, m4_map skips the expansion of
1195 # MACRO, while m4_mapall expands MACRO with no arguments.
1196 #
1197 # Since LIST may be quite large, we want to minimize how often it
1198 # appears in the expansion.  Rather than use m4_car/m4_cdr iteration,
1199 # we unbox the list, and use _m4_foreach for iteration.  For m4_map,
1200 # an empty list behaves like an empty sublist and gets ignored; for
1201 # m4_mapall, we must special-case the empty list.
1202 m4_define([m4_map],
1203 [_m4_foreach([_m4_apply([$1],], [)], [], $2)])
1204
1205 m4_define([m4_mapall],
1206 [m4_if([$2], [], [],
1207        [_m4_foreach([m4_apply([$1],], [)], [], $2)])])
1208
1209
1210 # m4_map_sep(MACRO, [SEPARATOR], LIST)
1211 # m4_mapall_sep(MACRO, [SEPARATOR], LIST)
1212 # ---------------------------------------
1213 # Invoke MACRO($1), SEPARATOR, MACRO($2), ..., MACRO($N) where $1,
1214 # $2... $N are the elements of LIST, and are in turn lists appropriate
1215 # for m4_apply.  SEPARATOR is expanded, in order to allow the creation
1216 # of a list of arguments by using a single-quoted comma as the
1217 # separator.  For each empty sublist, m4_map_sep skips the expansion
1218 # of MACRO and SEPARATOR, while m4_mapall_sep expands MACRO with no
1219 # arguments.
1220 #
1221 # For m4_mapall_sep, merely expand the first iteration without the
1222 # separator, then include separator as part of subsequent recursion;
1223 # but avoid extra expansion of LIST's side-effects via a helper macro.
1224 # For m4_map_sep, things are trickier - we don't know if the first
1225 # list element is an empty sublist, so we must define a self-modifying
1226 # helper macro and use that as the separator instead.
1227 m4_define([m4_map_sep],
1228 [m4_pushdef([m4_Sep], [m4_define([m4_Sep], _m4_defn([m4_unquote]))])]dnl
1229 [_m4_foreach([_m4_apply([m4_Sep([$2])[]$1],], [)], [], $3)m4_popdef([m4_Sep])])
1230
1231 m4_define([m4_mapall_sep],
1232 [m4_if([$3], [], [], [_$0([$1], [$2], $3)])])
1233
1234 m4_define([_m4_mapall_sep],
1235 [m4_apply([$1], [$3])_m4_foreach([m4_apply([$2[]$1],], [)], m4_shift2($@))])
1236
1237 # m4_map_args(EXPRESSION, ARG...)
1238 # -------------------------------
1239 # Expand EXPRESSION([ARG]) for each argument.  More efficient than
1240 #   m4_foreach([var], [ARG...], [EXPRESSION(m4_defn([var]))])
1241 # Shorthand for m4_map_args_sep([EXPRESSION(], [)], [], ARG...).
1242 m4_define([m4_map_args],
1243 [m4_if([$#], [0], [m4_fatal([$0: too few arguments: $#])],
1244        [$#], [1], [],
1245        [$#], [2], [$1([$2])[]],
1246        [_m4_foreach([$1(], [)], $@)])])
1247
1248
1249 # m4_map_args_pair(EXPRESSION, [END-EXPR = EXPRESSION], ARG...)
1250 # -------------------------------------------------------------
1251 # Perform a pairwise grouping of consecutive ARGs, by expanding
1252 # EXPRESSION([ARG1], [ARG2]).  If there are an odd number of ARGs, the
1253 # final argument is expanded with END-EXPR([ARGn]).
1254 #
1255 # For example:
1256 #   m4_define([show], [($*)m4_newline])dnl
1257 #   m4_map_args_pair([show], [], [a], [b], [c], [d], [e])dnl
1258 #   => (a,b)
1259 #   => (c,d)
1260 #   => (e)
1261 #
1262 # Please keep foreach.m4 in sync with any adjustments made here.
1263 m4_define([m4_map_args_pair],
1264 [m4_if([$#], [0], [m4_fatal([$0: too few arguments: $#])],
1265        [$#], [1], [m4_fatal([$0: too few arguments: $#: $1])],
1266        [$#], [2], [],
1267        [$#], [3], [m4_default([$2], [$1])([$3])[]],
1268        [$#], [4], [$1([$3], [$4])[]],
1269        [$1([$3], [$4])[]$0([$1], [$2], m4_shift(m4_shift3($@)))])])
1270
1271
1272 # m4_map_args_sep([PRE], [POST], [SEP], ARG...)
1273 # ---------------------------------------------
1274 # Expand PRE[ARG]POST for each argument, with SEP between arguments.
1275 m4_define([m4_map_args_sep],
1276 [m4_if([$#], [0], [m4_fatal([$0: too few arguments: $#])],
1277        [$#], [1], [],
1278        [$#], [2], [],
1279        [$#], [3], [],
1280        [$#], [4], [$1[$4]$2[]],
1281        [$1[$4]$2[]_m4_foreach([$3[]$1], [$2], m4_shift3($@))])])
1282
1283
1284 # m4_map_args_w(STRING, [PRE], [POST], [SEP])
1285 # -------------------------------------------
1286 # Perform the expansion of PRE[word]POST[] for each word in STRING
1287 # separated by whitespace.  More efficient than:
1288 #   m4_foreach_w([var], [STRING], [PRE[]m4_defn([var])POST])
1289 # Additionally, expand SEP between words.
1290 #
1291 # As long as we have to use m4_bpatsubst to split the string, we might
1292 # as well make it also apply PRE and POST; this avoids iteration
1293 # altogether.  But we must be careful of any \ in PRE or POST.
1294 # _m4_strip returns a quoted string, but that's okay, since it also
1295 # supplies an empty leading and trailing argument due to our
1296 # intentional whitespace around STRING.  We use m4_substr to strip the
1297 # empty elements and remove the extra layer of quoting.
1298 m4_define([m4_map_args_w],
1299 [_$0(_m4_split([ ]m4_flatten([$1])[ ], [[        ]+],
1300                m4_if(m4_index([$2$3$4], [\]), [-1], [[$3[]$4[]$2]],
1301                      [m4_bpatsubst([[$3[]$4[]$2]], [\\], [\\\\])])),
1302      m4_len([[]$3[]$4]), m4_len([$4[]$2[]]))])
1303
1304 m4_define([_m4_map_args_w],
1305 [m4_substr([$1], [$2], m4_eval(m4_len([$1]) - [$2] - [$3]))])
1306
1307
1308 # m4_stack_foreach(MACRO, FUNC)
1309 # m4_stack_foreach_lifo(MACRO, FUNC)
1310 # ----------------------------------
1311 # Pass each stacked definition of MACRO to the one-argument macro FUNC.
1312 # m4_stack_foreach proceeds in FIFO order, while m4_stack_foreach_lifo
1313 # processes the topmost definitions first.  In addition, FUNC should
1314 # not push or pop definitions of MACRO, and should not expect anything about
1315 # the active definition of MACRO (it will not be the topmost, and may not
1316 # be the one passed to FUNC either).
1317 #
1318 # Some macros simply can't be examined with this method: namely,
1319 # anything involved in the implementation of _m4_stack_reverse.
1320 m4_define([m4_stack_foreach],
1321 [_m4_stack_reverse([$1], [m4_tmp-$1])]dnl
1322 [_m4_stack_reverse([m4_tmp-$1], [$1], [$2(_m4_defn([m4_tmp-$1]))])])
1323
1324 m4_define([m4_stack_foreach_lifo],
1325 [_m4_stack_reverse([$1], [m4_tmp-$1], [$2(_m4_defn([m4_tmp-$1]))])]dnl
1326 [_m4_stack_reverse([m4_tmp-$1], [$1])])
1327
1328 # m4_stack_foreach_sep(MACRO, [PRE], [POST], [SEP])
1329 # m4_stack_foreach_sep_lifo(MACRO, [PRE], [POST], [SEP])
1330 # ------------------------------------------------------
1331 # Similar to m4_stack_foreach and m4_stack_foreach_lifo, in that every
1332 # definition of a pushdef stack will be visited.  But rather than
1333 # passing the definition as a single argument to a macro, this variant
1334 # expands the concatenation of PRE[]definition[]POST, and expands SEP
1335 # between consecutive expansions.  Note that m4_stack_foreach([a], [b])
1336 # is equivalent to m4_stack_foreach_sep([a], [b(], [)]).
1337 m4_define([m4_stack_foreach_sep],
1338 [_m4_stack_reverse([$1], [m4_tmp-$1])]dnl
1339 [_m4_stack_reverse([m4_tmp-$1], [$1], [$2[]_m4_defn([m4_tmp-$1])$3], [$4[]])])
1340
1341 m4_define([m4_stack_foreach_sep_lifo],
1342 [_m4_stack_reverse([$1], [m4_tmp-$1], [$2[]_m4_defn([m4_tmp-$1])$3], [$4[]])]dnl
1343 [_m4_stack_reverse([m4_tmp-$1], [$1])])
1344
1345
1346 # _m4_stack_reverse(OLD, NEW, [ACTION], [SEP])
1347 # --------------------------------------------
1348 # A recursive worker for pushdef stack manipulation.  Destructively
1349 # copy the OLD stack into the NEW, and expanding ACTION for each
1350 # iteration.  After the first iteration, SEP is promoted to the front
1351 # of ACTION (note that SEP should include a trailing [] if it is to
1352 # avoid interfering with ACTION).  The current definition is examined
1353 # after the NEW has been pushed but before OLD has been popped; this
1354 # order is important, as ACTION is permitted to operate on either
1355 # _m4_defn([OLD]) or _m4_defn([NEW]).  Since the operation is
1356 # destructive, this macro is generally used twice, with a temporary
1357 # macro name holding the swapped copy.
1358 m4_define([_m4_stack_reverse],
1359 [m4_ifdef([$1], [m4_pushdef([$2],
1360   _m4_defn([$1]))$3[]_m4_popdef([$1])$0([$1], [$2], [$4$3])])])
1361
1362
1363
1364 ## --------------------------- ##
1365 ## 9. More diversion support.  ##
1366 ## --------------------------- ##
1367
1368
1369 # m4_cleardivert(DIVERSION-NAME...)
1370 # ---------------------------------
1371 # Discard any text in DIVERSION-NAME.
1372 #
1373 # This works even inside m4_expand.
1374 m4_define([m4_cleardivert],
1375 [m4_if([$#], [0], [m4_fatal([$0: missing argument])],
1376        [_m4_divert_raw([-1])m4_undivert($@)_m4_divert_raw(
1377          _m4_divert(_m4_defn([_m4_divert_diversion]), [-]))])])
1378
1379
1380 # _m4_divert(DIVERSION-NAME or NUMBER, [NOWARN])
1381 # ----------------------------------------------
1382 # If DIVERSION-NAME is the name of a diversion, return its number,
1383 # otherwise if it is a NUMBER return it.  Issue a warning about
1384 # the use of a number instead of a name, unless NOWARN is provided.
1385 m4_define([_m4_divert],
1386 [m4_ifdef([_m4_divert($1)],
1387           [m4_indir([_m4_divert($1)])],
1388           [m4_if([$2], [], [m4_warn([syntax],
1389              [prefer named diversions])])$1])])
1390
1391 # KILL is only used to suppress output.
1392 m4_define([_m4_divert(KILL)],           -1)
1393
1394 # The empty diversion name is a synonym for 0.
1395 m4_define([_m4_divert()],                0)
1396
1397
1398 # m4_divert_stack
1399 # ---------------
1400 # Print the diversion stack, if it's nonempty.  The caller is
1401 # responsible for any leading or trailing newline.
1402 m4_define([m4_divert_stack],
1403 [m4_stack_foreach_sep_lifo([_m4_divert_stack], [], [], [
1404 ])])
1405
1406
1407 # m4_divert_stack_push(MACRO-NAME, DIVERSION-NAME)
1408 # ------------------------------------------------
1409 # Form an entry of the diversion stack from caller MACRO-NAME and
1410 # entering DIVERSION-NAME and push it.
1411 m4_define([m4_divert_stack_push],
1412 [m4_pushdef([_m4_divert_stack], m4_location[: $1: $2])])
1413
1414
1415 # m4_divert(DIVERSION-NAME)
1416 # -------------------------
1417 # Change the diversion stream to DIVERSION-NAME.
1418 m4_define([m4_divert],
1419 [m4_popdef([_m4_divert_stack])]dnl
1420 [m4_define([_m4_divert_diversion], [$1])]dnl
1421 [m4_divert_stack_push([$0], [$1])]dnl
1422 [_m4_divert_raw(_m4_divert([$1]))])
1423
1424
1425 # m4_divert_push(DIVERSION-NAME, [NOWARN])
1426 # ----------------------------------------
1427 # Change the diversion stream to DIVERSION-NAME, while stacking old values.
1428 # For internal use only: if NOWARN is not empty, DIVERSION-NAME can be a
1429 # number instead of a name.
1430 m4_define([m4_divert_push],
1431 [m4_divert_stack_push([$0], [$1])]dnl
1432 [m4_pushdef([_m4_divert_diversion], [$1])]dnl
1433 [_m4_divert_raw(_m4_divert([$1], [$2]))])
1434
1435
1436 # m4_divert_pop([DIVERSION-NAME])
1437 # -------------------------------
1438 # Change the diversion stream to its previous value, unstacking it.
1439 # If specified, verify we left DIVERSION-NAME.
1440 # When we pop the last value from the stack, we divert to -1.
1441 m4_define([m4_divert_pop],
1442 [m4_if([$1], [], [],
1443        [$1], _m4_defn([_m4_divert_diversion]), [],
1444        [m4_fatal([$0($1): diversion mismatch:
1445 ]m4_divert_stack)])]dnl
1446 [_m4_popdef([_m4_divert_stack], [_m4_divert_diversion])]dnl
1447 [m4_ifdef([_m4_divert_diversion], [],
1448            [m4_fatal([too many m4_divert_pop])])]dnl
1449 [_m4_divert_raw(_m4_divert(_m4_defn([_m4_divert_diversion]), [-]))])
1450
1451
1452 # m4_divert_text(DIVERSION-NAME, CONTENT)
1453 # ---------------------------------------
1454 # Output CONTENT into DIVERSION-NAME (which may be a number actually).
1455 # An end of line is appended for free to CONTENT.
1456 m4_define([m4_divert_text],
1457 [m4_divert_push([$1])$2
1458 m4_divert_pop([$1])])
1459
1460
1461 # m4_divert_once(DIVERSION-NAME, CONTENT)
1462 # ---------------------------------------
1463 # Output CONTENT into DIVERSION-NAME once, if not already there.
1464 # An end of line is appended for free to CONTENT.
1465 m4_define([m4_divert_once],
1466 [m4_expand_once([m4_divert_text([$1], [$2])])])
1467
1468
1469 # _m4_divert_unsafe(DIVERSION-NAME)
1470 # ---------------------------------
1471 # Issue a warning that the attempt to change the current diversion to
1472 # DIVERSION-NAME is unsafe, because this macro is being expanded
1473 # during argument collection of m4_expand.
1474 m4_define([_m4_divert_unsafe],
1475 [m4_fatal([$0: cannot change diversion to `$1' inside m4_expand])])
1476
1477
1478 # m4_undivert(DIVERSION-NAME...)
1479 # ------------------------------
1480 # Undivert DIVERSION-NAME.  Unlike the M4 version, this requires at
1481 # least one DIVERSION-NAME; also, due to support for named diversions,
1482 # this should not be used to undivert files.
1483 m4_define([m4_undivert],
1484 [m4_if([$#], [0], [m4_fatal([$0: missing argument])],
1485        [$#], [1], [_m4_undivert(_m4_divert([$1]))],
1486        [m4_map_args([$0], $@)])])
1487
1488
1489 ## --------------------------------------------- ##
1490 ## 10. Defining macros with bells and whistles.  ##
1491 ## --------------------------------------------- ##
1492
1493 # `m4_defun' is basically `m4_define' but it equips the macro with the
1494 # needed machinery for `m4_require'.  A macro must be m4_defun'd if
1495 # either it is m4_require'd, or it m4_require's.
1496 #
1497 # Two things deserve attention and are detailed below:
1498 #  1. Implementation of m4_require
1499 #  2. Keeping track of the expansion stack
1500 #
1501 # 1. Implementation of m4_require
1502 # ===============================
1503 #
1504 # Of course m4_defun calls m4_provide, so that a macro which has
1505 # been expanded is not expanded again when m4_require'd, but the
1506 # difficult part is the proper expansion of macros when they are
1507 # m4_require'd.
1508 #
1509 # The implementation is based on three ideas, (i) using diversions to
1510 # prepare the expansion of the macro and its dependencies (by Franc,ois
1511 # Pinard), (ii) expand the most recently m4_require'd macros _after_
1512 # the previous macros (by Axel Thimm), and (iii) track instances of
1513 # provide before require (by Eric Blake).
1514 #
1515 #
1516 # The first idea: why use diversions?
1517 # -----------------------------------
1518 #
1519 # When a macro requires another, the other macro is expanded in new
1520 # diversion, GROW.  When the outer macro is fully expanded, we first
1521 # undivert the most nested diversions (GROW - 1...), and finally
1522 # undivert GROW.  To understand why we need several diversions,
1523 # consider the following example:
1524 #
1525 # | m4_defun([TEST1], [Test...m4_require([TEST2])1])
1526 # | m4_defun([TEST2], [Test...m4_require([TEST3])2])
1527 # | m4_defun([TEST3], [Test...3])
1528 #
1529 # Because m4_require is not required to be first in the outer macros, we
1530 # must keep the expansions of the various levels of m4_require separated.
1531 # Right before executing the epilogue of TEST1, we have:
1532 #
1533 #          GROW - 2: Test...3
1534 #          GROW - 1: Test...2
1535 #          GROW:     Test...1
1536 #          BODY:
1537 #
1538 # Finally the epilogue of TEST1 undiverts GROW - 2, GROW - 1, and
1539 # GROW into the regular flow, BODY.
1540 #
1541 #          GROW - 2:
1542 #          GROW - 1:
1543 #          GROW:
1544 #          BODY:        Test...3; Test...2; Test...1
1545 #
1546 # (The semicolons are here for clarification, but of course are not
1547 # emitted.)  This is what Autoconf 2.0 (I think) to 2.13 (I'm sure)
1548 # implement.
1549 #
1550 #
1551 # The second idea: first required first out
1552 # -----------------------------------------
1553 #
1554 # The natural implementation of the idea above is buggy and produces
1555 # very surprising results in some situations.  Let's consider the
1556 # following example to explain the bug:
1557 #
1558 # | m4_defun([TEST1],  [m4_require([TEST2a])m4_require([TEST2b])])
1559 # | m4_defun([TEST2a], [])
1560 # | m4_defun([TEST2b], [m4_require([TEST3])])
1561 # | m4_defun([TEST3],  [m4_require([TEST2a])])
1562 # |
1563 # | AC_INIT
1564 # | TEST1
1565 #
1566 # The dependencies between the macros are:
1567 #
1568 #                3 --- 2b
1569 #               /        \              is m4_require'd by
1570 #              /          \       left -------------------- right
1571 #           2a ------------ 1
1572 #
1573 # If you strictly apply the rules given in the previous section you get:
1574 #
1575 #          GROW - 2: TEST3
1576 #          GROW - 1: TEST2a; TEST2b
1577 #          GROW:     TEST1
1578 #          BODY:
1579 #
1580 # (TEST2a, although required by TEST3 is not expanded in GROW - 3
1581 # because is has already been expanded before in GROW - 1, so it has
1582 # been AC_PROVIDE'd, so it is not expanded again) so when you undivert
1583 # the stack of diversions, you get:
1584 #
1585 #          GROW - 2:
1586 #          GROW - 1:
1587 #          GROW:
1588 #          BODY:        TEST3; TEST2a; TEST2b; TEST1
1589 #
1590 # i.e., TEST2a is expanded after TEST3 although the latter required the
1591 # former.
1592 #
1593 # Starting from 2.50, we use an implementation provided by Axel Thimm.
1594 # The idea is simple: the order in which macros are emitted must be the
1595 # same as the one in which macros are expanded.  (The bug above can
1596 # indeed be described as: a macro has been m4_provide'd before its
1597 # dependent, but it is emitted after: the lack of correlation between
1598 # emission and expansion order is guilty).
1599 #
1600 # How to do that?  You keep the stack of diversions to elaborate the
1601 # macros, but each time a macro is fully expanded, emit it immediately.
1602 #
1603 # In the example above, when TEST2a is expanded, but it's epilogue is
1604 # not run yet, you have:
1605 #
1606 #          GROW - 2:
1607 #          GROW - 1: TEST2a
1608 #          GROW:     Elaboration of TEST1
1609 #          BODY:
1610 #
1611 # The epilogue of TEST2a emits it immediately:
1612 #
1613 #          GROW - 2:
1614 #          GROW - 1:
1615 #          GROW:     Elaboration of TEST1
1616 #          BODY:     TEST2a
1617 #
1618 # TEST2b then requires TEST3, so right before the epilogue of TEST3, you
1619 # have:
1620 #
1621 #          GROW - 2: TEST3
1622 #          GROW - 1: Elaboration of TEST2b
1623 #          GROW:     Elaboration of TEST1
1624 #          BODY:      TEST2a
1625 #
1626 # The epilogue of TEST3 emits it:
1627 #
1628 #          GROW - 2:
1629 #          GROW - 1: Elaboration of TEST2b
1630 #          GROW:     Elaboration of TEST1
1631 #          BODY:     TEST2a; TEST3
1632 #
1633 # TEST2b is now completely expanded, and emitted:
1634 #
1635 #          GROW - 2:
1636 #          GROW - 1:
1637 #          GROW:     Elaboration of TEST1
1638 #          BODY:     TEST2a; TEST3; TEST2b
1639 #
1640 # and finally, TEST1 is finished and emitted:
1641 #
1642 #          GROW - 2:
1643 #          GROW - 1:
1644 #          GROW:
1645 #          BODY:     TEST2a; TEST3; TEST2b: TEST1
1646 #
1647 # The idea is simple, but the implementation is a bit involved.  If
1648 # you are like me, you will want to see the actual functioning of this
1649 # implementation to be convinced.  The next section gives the full
1650 # details.
1651 #
1652 #
1653 # The Axel Thimm implementation at work
1654 # -------------------------------------
1655 #
1656 # We consider the macros above, and this configure.ac:
1657 #
1658 #           AC_INIT
1659 #           TEST1
1660 #
1661 # You should keep the definitions of _m4_defun_pro, _m4_defun_epi, and
1662 # m4_require at hand to follow the steps.
1663 #
1664 # This implementation tries not to assume that the current diversion is
1665 # BODY, so as soon as a macro (m4_defun'd) is expanded, we first
1666 # record the current diversion under the name _m4_divert_dump (denoted
1667 # DUMP below for short).  This introduces an important difference with
1668 # the previous versions of Autoconf: you cannot use m4_require if you
1669 # are not inside an m4_defun'd macro, and especially, you cannot
1670 # m4_require directly from the top level.
1671 #
1672 # We have not tried to simulate the old behavior (better yet, we
1673 # diagnose it), because it is too dangerous: a macro m4_require'd from
1674 # the top level is expanded before the body of `configure', i.e., before
1675 # any other test was run.  I let you imagine the result of requiring
1676 # AC_STDC_HEADERS for instance, before AC_PROG_CC was actually run....
1677 #
1678 # After AC_INIT was run, the current diversion is BODY.
1679 # * AC_INIT was run
1680 #   DUMP:                undefined
1681 #   diversion stack:     BODY |-
1682 #
1683 # * TEST1 is expanded
1684 # The prologue of TEST1 sets _m4_divert_dump, which is the diversion
1685 # where the current elaboration will be dumped, to the current
1686 # diversion.  It also m4_divert_push to GROW, where the full
1687 # expansion of TEST1 and its dependencies will be elaborated.
1688 #   DUMP:        BODY
1689 #   BODY:        empty
1690 #   diversions:  GROW, BODY |-
1691 #
1692 # * TEST1 requires TEST2a
1693 # _m4_require_call m4_divert_pushes another temporary diversion,
1694 # GROW - 1, and expands TEST2a in there.
1695 #   DUMP:        BODY
1696 #   BODY:        empty
1697 #   GROW - 1:    TEST2a
1698 #   diversions:  GROW - 1, GROW, BODY |-
1699 # Then the content of the temporary diversion is moved to DUMP and the
1700 # temporary diversion is popped.
1701 #   DUMP:        BODY
1702 #   BODY:        TEST2a
1703 #   diversions:  GROW, BODY |-
1704 #
1705 # * TEST1 requires TEST2b
1706 # Again, _m4_require_call pushes GROW - 1 and heads to expand TEST2b.
1707 #   DUMP:        BODY
1708 #   BODY:        TEST2a
1709 #   diversions:  GROW - 1, GROW, BODY |-
1710 #
1711 # * TEST2b requires TEST3
1712 # _m4_require_call pushes GROW - 2 and expands TEST3 here.
1713 # (TEST3 requires TEST2a, but TEST2a has already been m4_provide'd, so
1714 # nothing happens.)
1715 #   DUMP:        BODY
1716 #   BODY:        TEST2a
1717 #   GROW - 2:    TEST3
1718 #   diversions:  GROW - 2, GROW - 1, GROW, BODY |-
1719 # Then the diversion is appended to DUMP, and popped.
1720 #   DUMP:        BODY
1721 #   BODY:        TEST2a; TEST3
1722 #   diversions:  GROW - 1, GROW, BODY |-
1723 #
1724 # * TEST1 requires TEST2b (contd.)
1725 # The content of TEST2b is expanded...
1726 #   DUMP:        BODY
1727 #   BODY:        TEST2a; TEST3
1728 #   GROW - 1:    TEST2b,
1729 #   diversions:  GROW - 1, GROW, BODY |-
1730 # ... and moved to DUMP.
1731 #   DUMP:        BODY
1732 #   BODY:        TEST2a; TEST3; TEST2b
1733 #   diversions:  GROW, BODY |-
1734 #
1735 # * TEST1 is expanded: epilogue
1736 # TEST1's own content is in GROW...
1737 #   DUMP:        BODY
1738 #   BODY:        TEST2a; TEST3; TEST2b
1739 #   GROW:        TEST1
1740 #   diversions:  BODY |-
1741 # ... and it's epilogue moves it to DUMP and then undefines DUMP.
1742 #   DUMP:       undefined
1743 #   BODY:       TEST2a; TEST3; TEST2b; TEST1
1744 #   diversions: BODY |-
1745 #
1746 #
1747 # The third idea: track macros provided before they were required
1748 # ---------------------------------------------------------------
1749 #
1750 # Using just the first two ideas, Autoconf 2.50 through 2.63 still had
1751 # a subtle bug for more than seven years.  Let's consider the
1752 # following example to explain the bug:
1753 #
1754 # | m4_defun([TEST1], [1])
1755 # | m4_defun([TEST2], [2[]m4_require([TEST1])])
1756 # | m4_defun([TEST3], [3 TEST1 m4_require([TEST2])])
1757 # | TEST3
1758 #
1759 # After the prologue of TEST3, we are collecting text in GROW with the
1760 # intent of dumping it in BODY during the epilogue.  Next, we
1761 # encounter the direct invocation of TEST1, which provides the macro
1762 # in place in GROW.  From there, we encounter a requirement for TEST2,
1763 # which must be collected in a new diversion.  While expanding TEST2,
1764 # we encounter a requirement for TEST1, but since it has already been
1765 # expanded, the Axel Thimm algorithm states that we can treat it as a
1766 # no-op.  But that would lead to an end result of `2 3 1', meaning
1767 # that we have once again output a macro (TEST2) prior to its
1768 # requirements (TEST1).
1769 #
1770 # The problem can only occur if a single defun'd macro first provides,
1771 # then later indirectly requires, the same macro.  Note that directly
1772 # expanding then requiring a macro is okay: because the dependency was
1773 # met, the require phase can be a no-op.  For that matter, the outer
1774 # macro can even require two helpers, where the first helper expands
1775 # the macro, and the second helper indirectly requires the macro.
1776 # Out-of-order expansion is only present if the inner macro is
1777 # required by something that will be hoisted in front of where the
1778 # direct expansion occurred.  In other words, we must be careful not
1779 # to warn on:
1780 #
1781 # | m4_defun([TEST4], [4])
1782 # | m4_defun([TEST5], [5 TEST4 m4_require([TEST4])])
1783 # | TEST5 => 5 4
1784 #
1785 # or even the more complex:
1786 #
1787 # | m4_defun([TEST6], [6])
1788 # | m4_defun([TEST7], [7 TEST6])
1789 # | m4_defun([TEST8], [8 m4_require([TEST6])])
1790 # | m4_defun([TEST9], [9 m4_require([TEST8])])
1791 # | m4_defun([TEST10], [10 m4_require([TEST7]) m4_require([TEST9])])
1792 # | TEST10 => 7 6 8 9 10
1793 #
1794 # So, to detect whether a require was direct or indirect, m4_defun and
1795 # m4_require track the name of the macro that caused a diversion to be
1796 # created (using the stack _m4_diverting, coupled with an O(1) lookup
1797 # _m4_diverting([NAME])), and m4_provide stores the name associated
1798 # with the diversion at which a macro was provided.  A require call is
1799 # direct if it occurs within the same diversion where the macro was
1800 # provided, or if the diversion associated with the providing context
1801 # has been collected.
1802 #
1803 # The implementation of the warning involves tracking the set of
1804 # macros which have been provided since the start of the outermost
1805 # defun'd macro (the set is named _m4_provide).  When starting an
1806 # outermost macro, the set is emptied; when a macro is provided, it is
1807 # added to the set; when require expands the body of a macro, it is
1808 # removed from the set; and when a macro is indirectly required, the
1809 # set is checked.  If a macro is in the set, then it has been provided
1810 # before it was required, and we satisfy dependencies by expanding the
1811 # macro as if it had never been provided; in the example given above,
1812 # this means we now output `1 2 3 1'.  Meanwhile, a warning is issued
1813 # to inform the user that her macros trigger the bug in older autoconf
1814 # versions, and that her output file now contains redundant contents
1815 # (and possibly new problems, if the repeated macro was not
1816 # idempotent).  Meanwhile, macros defined by m4_defun_once instead of
1817 # m4_defun are idempotent, avoiding any warning or duplicate output.
1818 #
1819 #
1820 # 2. Keeping track of the expansion stack
1821 # =======================================
1822 #
1823 # When M4 expansion goes wrong it is often extremely hard to find the
1824 # path amongst macros that drove to the failure.  What is needed is
1825 # the stack of macro `calls'. One could imagine that GNU M4 would
1826 # maintain a stack of macro expansions, unfortunately it doesn't, so
1827 # we do it by hand.  This is of course extremely costly, but the help
1828 # this stack provides is worth it.  Nevertheless to limit the
1829 # performance penalty this is implemented only for m4_defun'd macros,
1830 # not for define'd macros.
1831 #
1832 # Each time we enter an m4_defun'd macros, we add a definition in
1833 # _m4_expansion_stack, and when we exit the macro, we remove it (thanks
1834 # to pushdef/popdef).  m4_stack_foreach is used to print the expansion
1835 # stack in the rare cases when it's needed.
1836 #
1837 # In addition, we want to detect circular m4_require dependencies.
1838 # Each time we expand a macro FOO we define _m4_expanding(FOO); and
1839 # m4_require(BAR) simply checks whether _m4_expanding(BAR) is defined.
1840
1841
1842 # m4_expansion_stack
1843 # ------------------
1844 # Expands to the entire contents of the expansion stack.  The caller
1845 # must supply a trailing newline.  This macro always prints a
1846 # location; check whether _m4_expansion_stack is defined to filter out
1847 # the case when no defun'd macro is in force.
1848 m4_define([m4_expansion_stack],
1849 [m4_stack_foreach_sep_lifo([_$0], [_$0_entry(], [)
1850 ])m4_location[: the top level]])
1851
1852 # _m4_expansion_stack_entry(MACRO)
1853 # --------------------------------
1854 # Format an entry for MACRO found on the expansion stack.
1855 m4_define([_m4_expansion_stack_entry],
1856 [_m4_defn([m4_location($1)])[: $1 is expanded from...]])
1857
1858 # m4_expansion_stack_push(MACRO)
1859 # ------------------------------
1860 # Form an entry of the expansion stack on entry to MACRO and push it.
1861 m4_define([m4_expansion_stack_push],
1862 [m4_pushdef([_m4_expansion_stack], [$1])])
1863
1864
1865 # _m4_divert(GROW)
1866 # ----------------
1867 # This diversion is used by the m4_defun/m4_require machinery.  It is
1868 # important to keep room before GROW because for each nested
1869 # AC_REQUIRE we use an additional diversion (i.e., two m4_require's
1870 # will use GROW - 2.  More than 3 levels has never seemed to be
1871 # needed.)
1872 #
1873 # ...
1874 # - GROW - 2
1875 #   m4_require'd code, 2 level deep
1876 # - GROW - 1
1877 #   m4_require'd code, 1 level deep
1878 # - GROW
1879 #   m4_defun'd macros are elaborated here.
1880
1881 m4_define([_m4_divert(GROW)],       10000)
1882
1883
1884 # _m4_defun_pro(MACRO-NAME)
1885 # -------------------------
1886 # The prologue for Autoconf macros.
1887 #
1888 # This is called frequently, so minimize the number of macro invocations
1889 # by avoiding dnl and m4_defn overhead.
1890 m4_define([_m4_defun_pro],
1891 [m4_ifdef([_m4_expansion_stack], [], [_m4_defun_pro_outer([$1])])]dnl
1892 [m4_expansion_stack_push([$1])m4_pushdef([_m4_expanding($1)])])
1893
1894 m4_define([_m4_defun_pro_outer],
1895 [m4_set_delete([_m4_provide])]dnl
1896 [m4_pushdef([_m4_diverting([$1])])m4_pushdef([_m4_diverting], [$1])]dnl
1897 [m4_pushdef([_m4_divert_dump], m4_divnum)m4_divert_push([GROW])])
1898
1899 # _m4_defun_epi(MACRO-NAME)
1900 # -------------------------
1901 # The Epilogue for Autoconf macros.  MACRO-NAME only helps tracing
1902 # the PRO/EPI pairs.
1903 #
1904 # This is called frequently, so minimize the number of macro invocations
1905 # by avoiding dnl and m4_popdef overhead.
1906 m4_define([_m4_defun_epi],
1907 [_m4_popdef([_m4_expanding($1)], [_m4_expansion_stack])]dnl
1908 [m4_ifdef([_m4_expansion_stack], [], [_m4_defun_epi_outer([$1])])]dnl
1909 [m4_provide([$1])])
1910
1911 m4_define([_m4_defun_epi_outer],
1912 [_m4_popdef([_m4_divert_dump], [_m4_diverting([$1])], [_m4_diverting])]dnl
1913 [m4_divert_pop([GROW])m4_undivert([GROW])])
1914
1915
1916 # _m4_divert_dump
1917 # ---------------
1918 # If blank, we are outside of any defun'd macro.  Otherwise, expands
1919 # to the diversion number (not name) where require'd macros should be
1920 # moved once completed.
1921 m4_define([_m4_divert_dump])
1922
1923
1924 # m4_divert_require(DIVERSION, NAME-TO-CHECK, [BODY-TO-EXPAND])
1925 # -------------------------------------------------------------
1926 # Same as m4_require, but BODY-TO-EXPAND goes into the named DIVERSION;
1927 # requirements still go in the current diversion though.
1928 #
1929 m4_define([m4_divert_require],
1930 [m4_ifdef([_m4_expanding($2)],
1931   [m4_fatal([$0: circular dependency of $2])])]dnl
1932 [m4_if(_m4_divert_dump, [],
1933   [m4_fatal([$0($2): cannot be used outside of an m4_defun'd macro])])]dnl
1934 [m4_provide_if([$2], [],
1935   [_m4_require_call([$2], [$3], _m4_divert([$1], [-]))])])
1936
1937
1938 # m4_defun(NAME, EXPANSION, [MACRO = m4_define])
1939 # ----------------------------------------------
1940 # Define a macro NAME which automatically provides itself.  Add
1941 # machinery so the macro automatically switches expansion to the
1942 # diversion stack if it is not already using it, prior to EXPANSION.
1943 # In this case, once finished, it will bring back all the code
1944 # accumulated in the diversion stack.  This, combined with m4_require,
1945 # achieves the topological ordering of macros.  We don't use this
1946 # macro to define some frequently called macros that are not involved
1947 # in ordering constraints, to save m4 processing.
1948 #
1949 # MACRO is an undocumented argument; when set to m4_pushdef, and NAME
1950 # is already defined, the new definition is added to the pushdef
1951 # stack, rather than overwriting the current definition.  It can thus
1952 # be used to write self-modifying macros, which pop themselves to a
1953 # previously m4_define'd definition so that subsequent use of the
1954 # macro is faster.
1955 m4_define([m4_defun],
1956 [m4_define([m4_location($1)], m4_location)]dnl
1957 [m4_default([$3], [m4_define])([$1],
1958   [_m4_defun_pro(]m4_dquote($[0])[)$2[]_m4_defun_epi(]m4_dquote($[0])[)])])
1959
1960
1961 # m4_defun_init(NAME, INIT, COMMON)
1962 # ---------------------------------
1963 # Like m4_defun, but split EXPANSION into two portions: INIT which is
1964 # done only the first time NAME is invoked, and COMMON which is
1965 # expanded every time.
1966 #
1967 # For now, the COMMON definition is always m4_define'd, giving an even
1968 # lighter-weight definition.  m4_defun allows self-providing, but once
1969 # a macro is provided, m4_require no longer cares if it is m4_define'd
1970 # or m4_defun'd.  m4_defun also provides location tracking to identify
1971 # dependency bugs, but once the INIT has been expanded, we know there
1972 # are no dependency bugs.  However, if a future use needs COMMON to be
1973 # m4_defun'd, we can add a parameter, similar to the third parameter
1974 # to m4_defun.
1975 m4_define([m4_defun_init],
1976 [m4_define([$1], [$3[]])m4_defun([$1],
1977    [$2[]_m4_popdef(]m4_dquote($[0])[)m4_indir(]m4_dquote($[0])dnl
1978 [m4_if(]m4_dquote($[#])[, [0], [], ]m4_dquote([,$]@)[))], [m4_pushdef])])
1979
1980
1981 # m4_defun_once(NAME, EXPANSION)
1982 # ------------------------------
1983 # Like m4_defun, but guarantee that EXPANSION only happens once
1984 # (thereafter, using NAME is a no-op).
1985 #
1986 # If _m4_divert_dump is empty, we are called at the top level;
1987 # otherwise, we must ensure that we are required in front of the
1988 # current defun'd macro.  Use a helper macro so that EXPANSION need
1989 # only occur once in the definition of NAME, since it might be large.
1990 m4_define([m4_defun_once],
1991 [m4_define([m4_location($1)], m4_location)]dnl
1992 [m4_define([$1], [_m4_defun_once([$1], [$2], m4_if(_m4_divert_dump, [],
1993   [[_m4_defun_pro([$1])m4_unquote(], [)_m4_defun_epi([$1])]],
1994 m4_ifdef([_m4_diverting([$1])], [-]), [-], [[m4_unquote(], [)]],
1995   [[_m4_require_call([$1],], [, _m4_divert_dump)]]))])])
1996
1997 m4_define([_m4_defun_once],
1998 [m4_pushdef([$1])$3[$2[]m4_provide([$1])]$4])
1999
2000
2001 # m4_pattern_forbid(ERE, [WHY])
2002 # -----------------------------
2003 # Declare that no token matching the forbidden extended regular
2004 # expression ERE should be seen in the output unless...
2005 m4_define([m4_pattern_forbid], [])
2006
2007
2008 # m4_pattern_allow(ERE)
2009 # ---------------------
2010 # ... that token also matches the allowed extended regular expression ERE.
2011 # Both used via traces.
2012 m4_define([m4_pattern_allow], [])
2013
2014
2015 ## --------------------------------- ##
2016 ## 11. Dependencies between macros.  ##
2017 ## --------------------------------- ##
2018
2019
2020 # m4_before(THIS-MACRO-NAME, CALLED-MACRO-NAME)
2021 # ---------------------------------------------
2022 # Issue a warning if CALLED-MACRO-NAME was called before THIS-MACRO-NAME.
2023 m4_define([m4_before],
2024 [m4_provide_if([$2],
2025                [m4_warn([syntax], [$2 was called before $1])])])
2026
2027
2028 # m4_require(NAME-TO-CHECK, [BODY-TO-EXPAND = NAME-TO-CHECK])
2029 # -----------------------------------------------------------
2030 # If NAME-TO-CHECK has never been expanded (actually, if it is not
2031 # m4_provide'd), expand BODY-TO-EXPAND *before* the current macro
2032 # expansion; follow the expansion with a newline.  Once expanded, emit
2033 # it in _m4_divert_dump.  Keep track of the m4_require chain in
2034 # _m4_expansion_stack.
2035 #
2036 # The normal cases are:
2037 #
2038 # - NAME-TO-CHECK == BODY-TO-EXPAND
2039 #   Which you can use for regular macros with or without arguments, e.g.,
2040 #     m4_require([AC_PROG_CC], [AC_PROG_CC])
2041 #     m4_require([AC_CHECK_HEADERS(threads.h)], [AC_CHECK_HEADERS(threads.h)])
2042 #   which is just the same as
2043 #     m4_require([AC_PROG_CC])
2044 #     m4_require([AC_CHECK_HEADERS(threads.h)])
2045 #
2046 # - BODY-TO-EXPAND == m4_indir([NAME-TO-CHECK])
2047 #   In the case of macros with irregular names.  For instance:
2048 #     m4_require([AC_LANG_COMPILER(C)], [indir([AC_LANG_COMPILER(C)])])
2049 #   which means `if the macro named `AC_LANG_COMPILER(C)' (the parens are
2050 #   part of the name, it is not an argument) has not been run, then
2051 #   call it.'
2052 #   Had you used
2053 #     m4_require([AC_LANG_COMPILER(C)], [AC_LANG_COMPILER(C)])
2054 #   then m4_require would have tried to expand `AC_LANG_COMPILER(C)', i.e.,
2055 #   call the macro `AC_LANG_COMPILER' with `C' as argument.
2056 #
2057 #   You could argue that `AC_LANG_COMPILER', when it receives an argument
2058 #   such as `C' should dispatch the call to `AC_LANG_COMPILER(C)'.  But this
2059 #   `extension' prevents `AC_LANG_COMPILER' from having actual arguments that
2060 #   it passes to `AC_LANG_COMPILER(C)'.
2061 #
2062 # This is called frequently, so minimize the number of macro invocations
2063 # by avoiding dnl and other overhead on the common path.
2064 m4_define([m4_require],
2065 [m4_ifdef([_m4_expanding($1)],
2066   [m4_fatal([$0: circular dependency of $1])])]dnl
2067 [m4_if(_m4_divert_dump, [],
2068   [m4_fatal([$0($1): cannot be used outside of an ]dnl
2069 m4_if([$0], [m4_require], [[m4_defun]], [[AC_DEFUN]])['d macro])])]dnl
2070 [m4_provide_if([$1], [m4_set_contains([_m4_provide], [$1],
2071     [_m4_require_check([$1], _m4_defn([m4_provide($1)]), [$0])], [m4_ignore])],
2072   [_m4_require_call])([$1], [$2], _m4_divert_dump)])
2073
2074
2075 # _m4_require_call(NAME-TO-CHECK, [BODY-TO-EXPAND = NAME-TO-CHECK],
2076 #                  DIVERSION-NUMBER)
2077 # -----------------------------------------------------------------
2078 # If m4_require decides to expand the body, it calls this macro.  The
2079 # expansion is placed in DIVERSION-NUMBER.
2080 #
2081 # This is called frequently, so minimize the number of macro invocations
2082 # by avoiding dnl and other overhead on the common path.
2083 # The use of a witness macro protecting the warning allows aclocal
2084 # to silence any warnings when probing for what macros are required
2085 # and must therefore be located, when using the Autoconf-without-aclocal-m4
2086 # autom4te language.  For more background, see:
2087 # https://lists.gnu.org/archive/html/automake-patches/2012-11/msg00035.html
2088 m4_define([_m4_require_call],
2089 [m4_pushdef([_m4_divert_grow], m4_decr(_m4_divert_grow))]dnl
2090 [m4_pushdef([_m4_diverting([$1])])m4_pushdef([_m4_diverting], [$1])]dnl
2091 [m4_divert_push(_m4_divert_grow, [-])]dnl
2092 [m4_if([$2], [], [$1], [$2])
2093 m4_provide_if([$1], [m4_set_remove([_m4_provide], [$1])],
2094   [m4_ifndef([m4_require_silent_probe],
2095     [m4_warn([syntax], [$1 is m4_require'd but not m4_defun'd])])])]dnl
2096 [_m4_divert_raw($3)_m4_undivert(_m4_divert_grow)]dnl
2097 [m4_divert_pop(_m4_divert_grow)_m4_popdef([_m4_divert_grow],
2098 [_m4_diverting([$1])], [_m4_diverting])])
2099
2100
2101 # _m4_require_check(NAME-TO-CHECK, OWNER, CALLER)
2102 # -----------------------------------------------
2103 # NAME-TO-CHECK has been identified as previously expanded in the
2104 # diversion owned by OWNER.  If this is a problem, warn on behalf of
2105 # CALLER and return _m4_require_call; otherwise return m4_ignore.
2106 m4_define([_m4_require_check],
2107 [m4_if(_m4_defn([_m4_diverting]), [$2], [m4_ignore],
2108        m4_ifdef([_m4_diverting([$2])], [-]), [-], [m4_warn([syntax],
2109    [$3: `$1' was expanded before it was required
2110 http://www.gnu.org/software/autoconf/manual/autoconf.html#Expanded-Before-Required])_m4_require_call],
2111        [m4_ignore])])
2112
2113
2114 # _m4_divert_grow
2115 # ---------------
2116 # The counter for _m4_require_call.
2117 m4_define([_m4_divert_grow], _m4_divert([GROW]))
2118
2119
2120 # m4_expand_once(TEXT, [WITNESS = TEXT])
2121 # --------------------------------------
2122 # If TEXT has never been expanded, expand it *here*.  Use WITNESS as
2123 # as a memory that TEXT has already been expanded.
2124 m4_define([m4_expand_once],
2125 [m4_provide_if(m4_default_quoted([$2], [$1]),
2126                [],
2127                [m4_provide(m4_default_quoted([$2], [$1]))[]$1])])
2128
2129
2130 # m4_provide(MACRO-NAME)
2131 # ----------------------
2132 m4_define([m4_provide],
2133 [m4_ifdef([m4_provide($1)], [],
2134 [m4_set_add([_m4_provide], [$1], [m4_define([m4_provide($1)],
2135   m4_ifdef([_m4_diverting], [_m4_defn([_m4_diverting])]))])])])
2136
2137
2138 # m4_provide_if(MACRO-NAME, IF-PROVIDED, IF-NOT-PROVIDED)
2139 # -------------------------------------------------------
2140 # If MACRO-NAME is provided do IF-PROVIDED, else IF-NOT-PROVIDED.
2141 # The purpose of this macro is to provide the user with a means to
2142 # check macros which are provided without letting her know how the
2143 # information is coded.
2144 m4_define([m4_provide_if],
2145 [m4_ifdef([m4_provide($1)],
2146           [$2], [$3])])
2147
2148
2149 ## --------------------- ##
2150 ## 12. Text processing.  ##
2151 ## --------------------- ##
2152
2153
2154 # m4_cr_letters
2155 # m4_cr_LETTERS
2156 # m4_cr_Letters
2157 # -------------
2158 m4_define([m4_cr_letters], [abcdefghijklmnopqrstuvwxyz])
2159 m4_define([m4_cr_LETTERS], [ABCDEFGHIJKLMNOPQRSTUVWXYZ])
2160 m4_define([m4_cr_Letters],
2161 m4_defn([m4_cr_letters])dnl
2162 m4_defn([m4_cr_LETTERS])dnl
2163 )
2164
2165
2166 # m4_cr_digits
2167 # ------------
2168 m4_define([m4_cr_digits], [0123456789])
2169
2170
2171 # m4_cr_alnum
2172 # -----------
2173 m4_define([m4_cr_alnum],
2174 m4_defn([m4_cr_Letters])dnl
2175 m4_defn([m4_cr_digits])dnl
2176 )
2177
2178
2179 # m4_cr_symbols1
2180 # m4_cr_symbols2
2181 # --------------
2182 m4_define([m4_cr_symbols1],
2183 m4_defn([m4_cr_Letters])dnl
2184 _)
2185
2186 m4_define([m4_cr_symbols2],
2187 m4_defn([m4_cr_symbols1])dnl
2188 m4_defn([m4_cr_digits])dnl
2189 )
2190
2191 # m4_cr_all
2192 # ---------
2193 # The character range representing everything, with `-' as the last
2194 # character, since it is special to m4_translit.  Use with care, because
2195 # it contains characters special to M4 (fortunately, both ASCII and EBCDIC
2196 # have [] in order, so m4_defn([m4_cr_all]) remains a valid string).  It
2197 # also contains characters special to terminals, so it should never be
2198 # displayed in an error message.  Also, attempts to map [ and ] to other
2199 # characters via m4_translit must deal with the fact that m4_translit does
2200 # not add quotes to the output.
2201 #
2202 # In EBCDIC, $ is immediately followed by *, which leads to problems
2203 # if m4_cr_all is inlined into a macro definition; so swap them.
2204 #
2205 # It is mainly useful in generating inverted character range maps, for use
2206 # in places where m4_translit is faster than an equivalent m4_bpatsubst;
2207 # the regex `[^a-z]' is equivalent to:
2208 #  m4_translit(m4_dquote(m4_defn([m4_cr_all])), [a-z])
2209 m4_define([m4_cr_all],
2210 m4_translit(m4_dquote(m4_format(m4_dquote(m4_for(
2211   ,1,255,,[[%c]]))m4_for([i],1,255,,[,i]))), [$*-], [*$])-)
2212
2213
2214 # _m4_define_cr_not(CATEGORY)
2215 # ---------------------------
2216 # Define m4_cr_not_CATEGORY as the inverse of m4_cr_CATEGORY.
2217 m4_define([_m4_define_cr_not],
2218 [m4_define([m4_cr_not_$1],
2219            m4_translit(m4_dquote(m4_defn([m4_cr_all])),
2220                        m4_defn([m4_cr_$1])))])
2221
2222
2223 # m4_cr_not_letters
2224 # m4_cr_not_LETTERS
2225 # m4_cr_not_Letters
2226 # m4_cr_not_digits
2227 # m4_cr_not_alnum
2228 # m4_cr_not_symbols1
2229 # m4_cr_not_symbols2
2230 # ------------------
2231 # Inverse character sets
2232 _m4_define_cr_not([letters])
2233 _m4_define_cr_not([LETTERS])
2234 _m4_define_cr_not([Letters])
2235 _m4_define_cr_not([digits])
2236 _m4_define_cr_not([alnum])
2237 _m4_define_cr_not([symbols1])
2238 _m4_define_cr_not([symbols2])
2239
2240
2241 # m4_newline([STRING])
2242 # --------------------
2243 # Expands to a newline, possibly followed by STRING.  Exists mostly for
2244 # formatting reasons.
2245 m4_define([m4_newline], [
2246 $1])
2247
2248
2249 # m4_re_escape(STRING)
2250 # --------------------
2251 # Escape RE active characters in STRING.
2252 m4_define([m4_re_escape],
2253 [m4_bpatsubst([$1],
2254               [[][*+.?\^$]], [\\\&])])
2255
2256
2257 # m4_re_string
2258 # ------------
2259 # Regexp for `[a-zA-Z_0-9]*'
2260 # m4_dquote provides literal [] for the character class.
2261 m4_define([m4_re_string],
2262 m4_dquote(m4_defn([m4_cr_symbols2]))dnl
2263 [*]dnl
2264 )
2265
2266
2267 # m4_re_word
2268 # ----------
2269 # Regexp for `[a-zA-Z_][a-zA-Z_0-9]*'
2270 m4_define([m4_re_word],
2271 m4_dquote(m4_defn([m4_cr_symbols1]))dnl
2272 m4_defn([m4_re_string])dnl
2273 )
2274
2275
2276 # m4_tolower(STRING)
2277 # m4_toupper(STRING)
2278 # ------------------
2279 # These macros convert STRING to lowercase or uppercase.
2280 #
2281 # Rather than expand the m4_defn each time, we inline them up front.
2282 m4_define([m4_tolower],
2283 [m4_translit([[$1]], ]m4_dquote(m4_defn([m4_cr_LETTERS]))[,
2284                      ]m4_dquote(m4_defn([m4_cr_letters]))[)])
2285 m4_define([m4_toupper],
2286 [m4_translit([[$1]], ]m4_dquote(m4_defn([m4_cr_letters]))[,
2287                      ]m4_dquote(m4_defn([m4_cr_LETTERS]))[)])
2288
2289
2290 # m4_split(STRING, [REGEXP])
2291 # --------------------------
2292 # Split STRING into an m4 list of quoted elements.  The elements are
2293 # quoted with [ and ].  Beginning spaces and end spaces *are kept*.
2294 # Use m4_strip to remove them.
2295 #
2296 # REGEXP specifies where to split.  Default is [\t ]+.
2297 #
2298 # If STRING is empty, the result is an empty list.
2299 #
2300 # Pay attention to the m4_changequotes.  When m4 reads the definition of
2301 # m4_split, it still has quotes set to [ and ].  Luckily, these are matched
2302 # in the macro body, so the definition is stored correctly.  Use the same
2303 # alternate quotes as m4_noquote; it must be unlikely to appear in $1.
2304 #
2305 # Also, notice that $1 is quoted twice, since we want the result to
2306 # be quoted.  Then you should understand that the argument of
2307 # patsubst is -=<{(STRING)}>=- (i.e., with additional -=<{( and )}>=-).
2308 #
2309 # This macro is safe on active symbols, i.e.:
2310 #   m4_define(active, ACTIVE)
2311 #   m4_split([active active ])end
2312 #   => [active], [active], []end
2313 #
2314 # Optimize on regex of ` ' (space), since m4_foreach_w already guarantees
2315 # that the list contains single space separators, and a common case is
2316 # splitting a single-element list.  This macro is called frequently,
2317 # so avoid unnecessary dnl inside the definition.
2318 m4_define([m4_split],
2319 [m4_if([$1], [], [],
2320        [$2], [ ], [m4_if(m4_index([$1], [ ]), [-1], [[[$1]]],
2321                          [_$0([$1], [$2], [, ])])],
2322        [$2], [], [_$0([$1], [[   ]+], [, ])],
2323        [_$0([$1], [$2], [, ])])])
2324
2325 m4_define([_m4_split],
2326 [m4_changequote([-=<{(],[)}>=-])]dnl
2327 [[m4_bpatsubst(-=<{(-=<{($1)}>=-)}>=-, -=<{($2)}>=-,
2328                -=<{(]$3[)}>=-)]m4_changequote([, ])])
2329
2330
2331 # m4_chomp(STRING)
2332 # m4_chomp_all(STRING)
2333 # --------------------
2334 # Return STRING quoted, but without a trailing newline.  m4_chomp
2335 # removes at most one newline, while m4_chomp_all removes all
2336 # consecutive trailing newlines.  Embedded newlines are not touched,
2337 # and a trailing backslash-newline leaves just a trailing backslash.
2338 #
2339 # m4_bregexp is slower than m4_index, and we don't always want to
2340 # remove all newlines; hence the two variants.  We massage characters
2341 # to give a nicer pattern to match, particularly since m4_bregexp is
2342 # line-oriented.  Both versions must guarantee a match, to avoid bugs
2343 # with precision -1 in m4_format in older m4.
2344 m4_define([m4_chomp],
2345 [m4_format([[%.*s]], m4_index(m4_translit([[$1]], [
2346 /.], [/  ])[./.], [/.]), [$1])])
2347
2348 m4_define([m4_chomp_all],
2349 [m4_format([[%.*s]], m4_bregexp(m4_translit([[$1]], [
2350 /], [/ ]), [/*$]), [$1])])
2351
2352
2353 # m4_flatten(STRING)
2354 # ------------------
2355 # If STRING contains end of lines, replace them with spaces.  If there
2356 # are backslashed end of lines, remove them.  This macro is safe with
2357 # active symbols.
2358 #    m4_define(active, ACTIVE)
2359 #    m4_flatten([active
2360 #    act\
2361 #    ive])end
2362 #    => active activeend
2363 #
2364 # In m4, m4_bpatsubst is expensive, so first check for a newline.
2365 m4_define([m4_flatten],
2366 [m4_if(m4_index([$1], [
2367 ]), [-1], [[$1]],
2368        [m4_translit(m4_bpatsubst([[[$1]]], [\\
2369 ]), [
2370 ], [ ])])])
2371
2372
2373 # m4_strip(STRING)
2374 # ----------------
2375 # Expands into STRING with tabs and spaces singled out into a single
2376 # space, and removing leading and trailing spaces.
2377 #
2378 # This macro is robust to active symbols.
2379 #    m4_define(active, ACTIVE)
2380 #    m4_strip([  active <tab> <tab>active ])end
2381 #    => active activeend
2382 #
2383 # First, notice that we guarantee trailing space.  Why?  Because regular
2384 # expressions are greedy, and `.* ?' would always group the space into the
2385 # .* portion.  The algorithm is simpler by avoiding `?' at the end.  The
2386 # algorithm correctly strips everything if STRING is just ` '.
2387 #
2388 # Then notice the second pattern: it is in charge of removing the
2389 # leading/trailing spaces.  Why not just `[^ ]'?  Because they are
2390 # applied to over-quoted strings, i.e. more or less [STRING], due
2391 # to the limitations of m4_bpatsubsts.  So the leading space in STRING
2392 # is the *second* character; equally for the trailing space.
2393 m4_define([m4_strip],
2394 [m4_bpatsubsts([$1 ],
2395                [[        ]+], [ ],
2396                [^. ?\(.*\) .$], [[[\1]]])])
2397
2398
2399 # m4_normalize(STRING)
2400 # --------------------
2401 # Apply m4_flatten and m4_strip to STRING.
2402 #
2403 # The argument is quoted, so that the macro is robust to active symbols:
2404 #
2405 #    m4_define(active, ACTIVE)
2406 #    m4_normalize([  act\
2407 #    ive
2408 #    active ])end
2409 #    => active activeend
2410
2411 m4_define([m4_normalize],
2412 [m4_strip(m4_flatten([$1]))])
2413
2414
2415
2416 # m4_join(SEP, ARG1, ARG2...)
2417 # ---------------------------
2418 # Produce ARG1SEPARG2...SEPARGn.  Avoid back-to-back SEP when a given ARG
2419 # is the empty string.  No expansion is performed on SEP or ARGs.
2420 #
2421 # Since the number of arguments to join can be arbitrarily long, we
2422 # want to avoid having more than one $@ in the macro definition;
2423 # otherwise, the expansion would require twice the memory of the already
2424 # long list.  Hence, m4_join merely looks for the first non-empty element,
2425 # and outputs just that element; while _m4_join looks for all non-empty
2426 # elements, and outputs them following a separator.  The final trick to
2427 # note is that we decide between recursing with $0 or _$0 based on the
2428 # nested m4_if ending with `_'.
2429 #
2430 # Please keep foreach.m4 in sync with any adjustments made here.
2431 m4_define([m4_join],
2432 [m4_if([$#], [1], [],
2433        [$#], [2], [[$2]],
2434        [m4_if([$2], [], [], [[$2]_])$0([$1], m4_shift2($@))])])
2435 m4_define([_m4_join],
2436 [m4_if([$#$2], [2], [],
2437        [m4_if([$2], [], [], [[$1$2]])$0([$1], m4_shift2($@))])])
2438
2439 # m4_joinall(SEP, ARG1, ARG2...)
2440 # ------------------------------
2441 # Produce ARG1SEPARG2...SEPARGn.  An empty ARG results in back-to-back SEP.
2442 # No expansion is performed on SEP or ARGs.
2443 #
2444 # Please keep foreach.m4 in sync with any adjustments made here.
2445 m4_define([m4_joinall], [[$2]_$0([$1], m4_shift($@))])
2446 m4_define([_m4_joinall],
2447 [m4_if([$#], [2], [], [[$1$3]$0([$1], m4_shift2($@))])])
2448
2449 # m4_combine([SEPARATOR], PREFIX-LIST, [INFIX], SUFFIX...)
2450 # --------------------------------------------------------
2451 # Produce the pairwise combination of every element in the quoted,
2452 # comma-separated PREFIX-LIST with every element from the SUFFIX arguments.
2453 # Each pair is joined with INFIX, and pairs are separated by SEPARATOR.
2454 # No expansion occurs on SEPARATOR, INFIX, or elements of either list.
2455 #
2456 # For example:
2457 #   m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
2458 #   => a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
2459 #
2460 # This definition is a bit hairy; the thing to realize is that we want
2461 # to construct m4_map_args_sep([[prefix$3]], [], [[$1]], m4_shift3($@))
2462 # as the inner loop, using each prefix generated by the outer loop,
2463 # and without recalculating m4_shift3 every outer iteration.
2464 m4_define([m4_combine],
2465 [m4_if([$2], [], [], m4_eval([$# > 3]), [1],
2466 [m4_map_args_sep([m4_map_args_sep(m4_dquote(], [)[[$3]], [], [[$1]],]]]dnl
2467 [m4_dquote(m4_dquote(m4_shift3($@)))[[)], [[$1]], $2)])])
2468
2469
2470 # m4_append(MACRO-NAME, STRING, [SEPARATOR])
2471 # ------------------------------------------
2472 # Redefine MACRO-NAME to hold its former content plus `SEPARATOR`'STRING'
2473 # at the end.  It is valid to use this macro with MACRO-NAME undefined,
2474 # in which case no SEPARATOR is added.  Be aware that the criterion is
2475 # `not being defined', and not `not being empty'.
2476 #
2477 # Note that neither STRING nor SEPARATOR are expanded here; rather, when
2478 # you expand MACRO-NAME, they will be expanded at that point in time.
2479 #
2480 # This macro is robust to active symbols.  It can be used to grow
2481 # strings.
2482 #
2483 #    | m4_define(active, ACTIVE)dnl
2484 #    | m4_append([sentence], [This is an])dnl
2485 #    | m4_append([sentence], [ active ])dnl
2486 #    | m4_append([sentence], [symbol.])dnl
2487 #    | sentence
2488 #    | m4_undefine([active])dnl
2489 #    | sentence
2490 #    => This is an ACTIVE symbol.
2491 #    => This is an active symbol.
2492 #
2493 # It can be used to define hooks.
2494 #
2495 #    | m4_define(active, ACTIVE)dnl
2496 #    | m4_append([hooks], [m4_define([act1], [act2])])dnl
2497 #    | m4_append([hooks], [m4_define([act2], [active])])dnl
2498 #    | m4_undefine([active])dnl
2499 #    | act1
2500 #    | hooks
2501 #    | act1
2502 #    => act1
2503 #    =>
2504 #    => active
2505 #
2506 # It can also be used to create lists, although this particular usage was
2507 # broken prior to autoconf 2.62.
2508 #    | m4_append([list], [one], [, ])dnl
2509 #    | m4_append([list], [two], [, ])dnl
2510 #    | m4_append([list], [three], [, ])dnl
2511 #    | list
2512 #    | m4_dquote(list)
2513 #    => one, two, three
2514 #    => [one],[two],[three]
2515 #
2516 # Note that m4_append can benefit from amortized O(n) m4 behavior, if
2517 # the underlying m4 implementation is smart enough to avoid copying existing
2518 # contents when enlarging a macro's definition into any pre-allocated storage
2519 # (m4 1.4.x unfortunately does not implement this optimization).  We do
2520 # not implement m4_prepend, since it is inherently O(n^2) (pre-allocated
2521 # storage only occurs at the end of a macro, so the existing contents must
2522 # always be moved).
2523 #
2524 # Use _m4_defn for speed.
2525 m4_define([m4_append],
2526 [m4_define([$1], m4_ifdef([$1], [_m4_defn([$1])[$3]])[$2])])
2527
2528
2529 # m4_append_uniq(MACRO-NAME, STRING, [SEPARATOR], [IF-UNIQ], [IF-DUP])
2530 # --------------------------------------------------------------------
2531 # Like `m4_append', but append only if not yet present.  Additionally,
2532 # expand IF-UNIQ if STRING was appended, or IF-DUP if STRING was already
2533 # present.  Also, warn if SEPARATOR is not empty and occurs within STRING,
2534 # as the algorithm no longer guarantees uniqueness.
2535 #
2536 # Note that while m4_append can be O(n) (depending on the quality of the
2537 # underlying M4 implementation), m4_append_uniq is inherently O(n^2)
2538 # because each append operation searches the entire string.
2539 m4_define([m4_append_uniq],
2540 [m4_ifval([$3], [m4_if(m4_index([$2], [$3]), [-1], [],
2541                        [m4_warn([syntax],
2542                                 [$0: `$2' contains `$3'])])])_$0($@)])
2543 m4_define([_m4_append_uniq],
2544 [m4_ifdef([$1],
2545           [m4_if(m4_index([$3]_m4_defn([$1])[$3], [$3$2$3]), [-1],
2546                  [m4_append([$1], [$2], [$3])$4], [$5])],
2547           [m4_define([$1], [$2])$4])])
2548
2549 # m4_append_uniq_w(MACRO-NAME, STRINGS)
2550 # -------------------------------------
2551 # For each of the words in the whitespace separated list STRINGS, append
2552 # only the unique strings to the definition of MACRO-NAME.
2553 #
2554 # Use _m4_defn for speed.
2555 m4_define([m4_append_uniq_w],
2556 [m4_map_args_w([$2], [_m4_append_uniq([$1],], [, [ ])])])
2557
2558
2559 # m4_escape(STRING)
2560 # -----------------
2561 # Output quoted STRING, but with embedded #, $, [ and ] turned into
2562 # quadrigraphs.
2563 #
2564 # It is faster to check if STRING is already good using m4_translit
2565 # than to blindly perform four m4_bpatsubst.
2566 #
2567 # Because the translit is stripping quotes, it must also neutralize
2568 # anything that might be in a macro name, as well as comments, commas,
2569 # and parentheses.  All the problem characters are unified so that a
2570 # single m4_index can scan the result.
2571 #
2572 # Rather than expand m4_defn every time m4_escape is expanded, we
2573 # inline its expansion up front.
2574 m4_define([m4_escape],
2575 [m4_if(m4_index(m4_translit([$1],
2576    [[]#,()]]m4_dquote(m4_defn([m4_cr_symbols2]))[, [$$$]), [$]),
2577   [-1], [m4_echo], [_$0])([$1])])
2578
2579 m4_define([_m4_escape],
2580 [m4_changequote([-=<{(],[)}>=-])]dnl
2581 [m4_bpatsubst(m4_bpatsubst(m4_bpatsubst(m4_bpatsubst(
2582           -=<{(-=<{(-=<{(-=<{(-=<{($1)}>=-)}>=-)}>=-)}>=-)}>=-,
2583         -=<{(#)}>=-, -=<{(@%:@)}>=-),
2584       -=<{(\[)}>=-, -=<{(@<:@)}>=-),
2585     -=<{(\])}>=-, -=<{(@:>@)}>=-),
2586   -=<{(\$)}>=-, -=<{(@S|@)}>=-)m4_changequote([,])])
2587
2588
2589 # m4_text_wrap(STRING, [PREFIX], [FIRST-PREFIX], [WIDTH])
2590 # -------------------------------------------------------
2591 # Expands into STRING wrapped to hold in WIDTH columns (default = 79).
2592 # If PREFIX is given, each line is prefixed with it.  If FIRST-PREFIX is
2593 # specified, then the first line is prefixed with it.  As a special case,
2594 # if the length of FIRST-PREFIX is greater than that of PREFIX, then
2595 # FIRST-PREFIX will be left alone on the first line.
2596 #
2597 # No expansion occurs on the contents STRING, PREFIX, or FIRST-PREFIX,
2598 # although quadrigraphs are correctly recognized.  More precisely,
2599 # you may redefine m4_qlen to recognize whatever escape sequences that
2600 # you will post-process.
2601 #
2602 # Typical outputs are:
2603 #
2604 # m4_text_wrap([Short string */], [   ], [/* ], 20)
2605 #  => /* Short string */
2606 #
2607 # m4_text_wrap([Much longer string */], [   ], [/* ], 20)
2608 #  => /* Much longer
2609 #  =>    string */
2610 #
2611 # m4_text_wrap([Short doc.], [          ], [  --short ], 30)
2612 #  =>   --short Short doc.
2613 #
2614 # m4_text_wrap([Short doc.], [          ], [  --too-wide ], 30)
2615 #  =>   --too-wide
2616 #  =>           Short doc.
2617 #
2618 # m4_text_wrap([Super long documentation.], [          ], [  --too-wide ], 30)
2619 #  =>   --too-wide
2620 #  =>      Super long
2621 #  =>      documentation.
2622 #
2623 # FIXME: there is no checking of a longer PREFIX than WIDTH, but do
2624 # we really want to bother with people trying each single corner
2625 # of a software?
2626 #
2627 # This macro does not leave a trailing space behind the last word of a line,
2628 # which complicates it a bit.  The algorithm is otherwise stupid and simple:
2629 # all the words are preceded by m4_Separator which is defined to empty for
2630 # the first word, and then ` ' (single space) for all the others.
2631 #
2632 # The algorithm uses a helper that uses $2 through $4 directly, rather than
2633 # using local variables, to avoid m4_defn overhead, or expansion swallowing
2634 # any $.  It also bypasses m4_popdef overhead with _m4_popdef since no user
2635 # macro expansion occurs in the meantime.  Also, the definition is written
2636 # with m4_do, to avoid time wasted on dnl during expansion (since this is
2637 # already a time-consuming macro).
2638 m4_define([m4_text_wrap],
2639 [_$0(m4_escape([$1]), [$2], m4_default_quoted([$3], [$2]),
2640      m4_default_quoted([$4], [79]))])
2641
2642 m4_define([_m4_text_wrap],
2643 m4_do(dnl set up local variables, to avoid repeated calculations
2644 [[m4_pushdef([m4_Indent], m4_qlen([$2]))]],
2645 [[m4_pushdef([m4_Cursor], m4_qlen([$3]))]],
2646 [[m4_pushdef([m4_Separator], [m4_define([m4_Separator], [ ])])]],
2647 dnl expand the first prefix, then check its length vs. regular prefix
2648 dnl same length: nothing special
2649 dnl prefix1 longer: output on line by itself, and reset cursor
2650 dnl prefix1 shorter: pad to length of prefix, and reset cursor
2651 [[[$3]m4_cond([m4_Cursor], m4_Indent, [],
2652               [m4_eval(m4_Cursor > m4_Indent)], [1], [
2653 [$2]m4_define([m4_Cursor], m4_Indent)],
2654               [m4_format([%*s], m4_max([0],
2655   m4_eval(m4_Indent - m4_Cursor)), [])m4_define([m4_Cursor], m4_Indent)])]],
2656 dnl now, for each word, compute the cursor after the word is output, then
2657 dnl check if the cursor would exceed the wrap column
2658 dnl if so, reset cursor, and insert newline and prefix
2659 dnl if not, insert the separator (usually a space)
2660 dnl either way, insert the word
2661 [[m4_map_args_w([$1], [$0_word(], [, [$2], [$4])])]],
2662 dnl finally, clean up the local variables
2663 [[_m4_popdef([m4_Separator], [m4_Cursor], [m4_Indent])]]))
2664
2665 m4_define([_m4_text_wrap_word],
2666 [m4_define([m4_Cursor], m4_eval(m4_Cursor + m4_qlen([$1]) + 1))]dnl
2667 [m4_if(m4_eval(m4_Cursor > ([$3])),
2668       [1], [m4_define([m4_Cursor], m4_eval(m4_Indent + m4_qlen([$1]) + 1))
2669 [$2]],
2670       [m4_Separator[]])[$1]])
2671
2672 # m4_text_box(MESSAGE, [FRAME-CHARACTER = `-'])
2673 # ---------------------------------------------
2674 # Turn MESSAGE into:
2675 #  ## ------- ##
2676 #  ## MESSAGE ##
2677 #  ## ------- ##
2678 # using FRAME-CHARACTER in the border.
2679 #
2680 # Quadrigraphs are correctly recognized.  More precisely, you may
2681 # redefine m4_qlen to recognize whatever escape sequences that you
2682 # will post-process.
2683 m4_define([m4_text_box],
2684 [m4_pushdef([m4_Border],
2685             m4_translit(m4_format([[[%*s]]], m4_decr(m4_qlen(_m4_expand([$1
2686 ]))), []), [ ], m4_default_quoted([$2], [-])))]dnl
2687 [[##] _m4_defn([m4_Border]) [##]
2688 [##] $1 [##]
2689 [##] _m4_defn([m4_Border]) [##]_m4_popdef([m4_Border])])
2690
2691
2692 # m4_qlen(STRING)
2693 # ---------------
2694 # Expands to the length of STRING after autom4te converts all quadrigraphs.
2695 #
2696 # If you use some other means of post-processing m4 output rather than
2697 # autom4te, then you may redefine this macro to recognize whatever
2698 # escape sequences your post-processor will handle.  For that matter,
2699 # m4_define([m4_qlen], m4_defn([m4_len])) is sufficient if you don't
2700 # do any post-processing.
2701 #
2702 # Avoid bpatsubsts for the common case of no quadrigraphs.  Cache
2703 # results, as configure scripts tend to ask about lengths of common
2704 # strings like `/*' and `*/' rather frequently.  Minimize the number
2705 # of times that $1 occurs in m4_qlen, so there is less text to parse
2706 # on a cache hit.
2707 m4_define([m4_qlen],
2708 [m4_ifdef([$0-$1], [_m4_defn([$0-]], [_$0(])[$1])])
2709 m4_define([_m4_qlen],
2710 [m4_define([m4_qlen-$1],
2711 m4_if(m4_index([$1], [@]), [-1], [m4_len([$1])],
2712       [m4_len(m4_bpatsubst([[$1]],
2713                            [@\(\(<:\|:>\|S|\|%:\|\{:\|:\}\)\(@\)\|&t@\)],
2714                            [\3]))]))_m4_defn([m4_qlen-$1])])
2715
2716 # m4_copyright_condense(TEXT)
2717 # ---------------------------
2718 # Condense the copyright notice in TEXT to only display the final
2719 # year, wrapping the results to fit in 80 columns.
2720 m4_define([m4_copyright_condense],
2721 [m4_text_wrap(m4_bpatsubst(m4_flatten([[$1]]),
2722 [(C)[-   ,0-9]*\([1-9][0-9][0-9][0-9]\)], [(C) \1]))])
2723
2724 ## ----------------------- ##
2725 ## 13. Number processing.  ##
2726 ## ----------------------- ##
2727
2728 # m4_cmp(A, B)
2729 # ------------
2730 # Compare two integer expressions.
2731 # A < B -> -1
2732 # A = B ->  0
2733 # A > B ->  1
2734 m4_define([m4_cmp],
2735 [m4_eval((([$1]) > ([$2])) - (([$1]) < ([$2])))])
2736
2737
2738 # m4_list_cmp(A, B)
2739 # -----------------
2740 #
2741 # Compare the two lists of integer expressions A and B.  For instance:
2742 #   m4_list_cmp([1, 0],     [1])    ->  0
2743 #   m4_list_cmp([1, 0],     [1, 0]) ->  0
2744 #   m4_list_cmp([1, 2],     [1, 0]) ->  1
2745 #   m4_list_cmp([1, 2, 3],  [1, 2]) ->  1
2746 #   m4_list_cmp([1, 2, -3], [1, 2]) -> -1
2747 #   m4_list_cmp([1, 0],     [1, 2]) -> -1
2748 #   m4_list_cmp([1],        [1, 2]) -> -1
2749 #   m4_define([xa], [oops])dnl
2750 #   m4_list_cmp([[0xa]],    [5+5])  -> 0
2751 #
2752 # Rather than face the overhead of m4_case, we use a helper function whose
2753 # expansion includes the name of the macro to invoke on the tail, either
2754 # m4_ignore or m4_unquote.  This is particularly useful when comparing
2755 # long lists, since less text is being expanded for deciding when to end
2756 # recursion.  The recursion is between a pair of macros that alternate
2757 # which list is trimmed by one element; this is more efficient than
2758 # calling m4_cdr on both lists from a single macro.  Guarantee exactly
2759 # one expansion of both lists' side effects.
2760 #
2761 # Please keep foreach.m4 in sync with any adjustments made here.
2762 m4_define([m4_list_cmp],
2763 [_$0_raw(m4_dquote($1), m4_dquote($2))])
2764
2765 m4_define([_m4_list_cmp_raw],
2766 [m4_if([$1], [$2], [0], [_m4_list_cmp_1([$1], $2)])])
2767
2768 m4_define([_m4_list_cmp],
2769 [m4_if([$1], [], [0m4_ignore], [$2], [0], [m4_unquote], [$2m4_ignore])])
2770
2771 m4_define([_m4_list_cmp_1],
2772 [_m4_list_cmp_2([$2], [m4_shift2($@)], $1)])
2773
2774 m4_define([_m4_list_cmp_2],
2775 [_m4_list_cmp([$1$3], m4_cmp([$3+0], [$1+0]))(
2776   [_m4_list_cmp_1(m4_dquote(m4_shift3($@)), $2)])])
2777
2778 # m4_max(EXPR, ...)
2779 # m4_min(EXPR, ...)
2780 # -----------------
2781 # Return the decimal value of the maximum (or minimum) in a series of
2782 # integer expressions.
2783 #
2784 # M4 1.4.x doesn't provide ?:.  Hence this huge m4_eval.  Avoid m4_eval
2785 # if both arguments are identical, but be aware of m4_max(0xa, 10) (hence
2786 # the use of <=, not just <, in the second multiply).
2787 #
2788 # Please keep foreach.m4 in sync with any adjustments made here.
2789 m4_define([m4_max],
2790 [m4_if([$#], [0], [m4_fatal([too few arguments to $0])],
2791        [$#], [1], [m4_eval([$1])],
2792        [$#$1], [2$2], [m4_eval([$1])],
2793        [$#], [2], [_$0($@)],
2794        [_m4_minmax([_$0], $@)])])
2795
2796 m4_define([_m4_max],
2797 [m4_eval((([$1]) > ([$2])) * ([$1]) + (([$1]) <= ([$2])) * ([$2]))])
2798
2799 m4_define([m4_min],
2800 [m4_if([$#], [0], [m4_fatal([too few arguments to $0])],
2801        [$#], [1], [m4_eval([$1])],
2802        [$#$1], [2$2], [m4_eval([$1])],
2803        [$#], [2], [_$0($@)],
2804        [_m4_minmax([_$0], $@)])])
2805
2806 m4_define([_m4_min],
2807 [m4_eval((([$1]) < ([$2])) * ([$1]) + (([$1]) >= ([$2])) * ([$2]))])
2808
2809 # _m4_minmax(METHOD, ARG1, ARG2...)
2810 # ---------------------------------
2811 # Common recursion code for m4_max and m4_min.  METHOD must be _m4_max
2812 # or _m4_min, and there must be at least two arguments to combine.
2813 #
2814 # Please keep foreach.m4 in sync with any adjustments made here.
2815 m4_define([_m4_minmax],
2816 [m4_if([$#], [3], [$1([$2], [$3])],
2817        [$0([$1], $1([$2], [$3]), m4_shift3($@))])])
2818
2819
2820 # m4_sign(A)
2821 # ----------
2822 # The sign of the integer expression A.
2823 m4_define([m4_sign],
2824 [m4_eval((([$1]) > 0) - (([$1]) < 0))])
2825
2826
2827
2828 ## ------------------------ ##
2829 ## 14. Version processing.  ##
2830 ## ------------------------ ##
2831
2832
2833 # m4_version_unletter(VERSION)
2834 # ----------------------------
2835 # Normalize beta version numbers with letters to numeric expressions, which
2836 # can then be handed to m4_eval for the purpose of comparison.
2837 #
2838 #   Nl -> (N+1).-1.(l#)
2839 #
2840 # for example:
2841 #   [2.14a] -> [0,2,14+1,-1,[0r36:a]] -> 2.15.-1.10
2842 #   [2.14b] -> [0,2,15+1,-1,[0r36:b]] -> 2.15.-1.11
2843 #   [2.61aa.b] -> [0,2.61,1,-1,[0r36:aa],+1,-1,[0r36:b]] -> 2.62.-1.370.1.-1.11
2844 #   [08] -> [0,[0r10:0]8] -> 8
2845 #
2846 # This macro expects reasonable version numbers, but can handle double
2847 # letters and does not expand any macros.  Original version strings can
2848 # use both `.' and `-' separators.
2849 #
2850 # Inline constant expansions, to avoid m4_defn overhead.
2851 # _m4_version_unletter is the real workhorse used by m4_version_compare,
2852 # but since [0r36:a] and commas are less readable than 10 and dots, we
2853 # provide a wrapper for human use.
2854 m4_define([m4_version_unletter],
2855 [m4_substr(m4_map_args([.m4_eval], m4_unquote(_$0([$1]))), [3])])
2856 m4_define([_m4_version_unletter],
2857 [m4_bpatsubst(m4_bpatsubst(m4_translit([[[[0,$1]]]], [.-], [,,]),]dnl
2858 m4_dquote(m4_dquote(m4_defn([m4_cr_Letters])))[[+],
2859               [+1,-1,[0r36:\&]]), [,0], [,[0r10:0]])])
2860
2861
2862 # m4_version_compare(VERSION-1, VERSION-2)
2863 # ----------------------------------------
2864 # Compare the two version numbers and expand into
2865 #  -1 if VERSION-1 < VERSION-2
2866 #   0 if           =
2867 #   1 if           >
2868 #
2869 # Since _m4_version_unletter does not output side effects, we can
2870 # safely bypass the overhead of m4_version_cmp.
2871 m4_define([m4_version_compare],
2872 [_m4_list_cmp_raw(_m4_version_unletter([$1]), _m4_version_unletter([$2]))])
2873
2874
2875 # m4_PACKAGE_NAME
2876 # m4_PACKAGE_TARNAME
2877 # m4_PACKAGE_VERSION
2878 # m4_PACKAGE_STRING
2879 # m4_PACKAGE_BUGREPORT
2880 # --------------------
2881 # If m4sugar/version.m4 is present, then define version strings.  This
2882 # file is optional, provided by Autoconf but absent in Bison.
2883 m4_sinclude([m4sugar/version.m4])
2884
2885
2886 # m4_version_prereq(VERSION, [IF-OK], [IF-NOT = FAIL])
2887 # ----------------------------------------------------
2888 # Check this Autoconf version against VERSION.
2889 m4_define([m4_version_prereq],
2890 m4_ifdef([m4_PACKAGE_VERSION],
2891 [[m4_if(m4_version_compare(]m4_dquote(m4_defn([m4_PACKAGE_VERSION]))[, [$1]),
2892         [-1],
2893         [m4_default([$3],
2894                     [m4_fatal([Autoconf version $1 or higher is required],
2895                               [63])])],
2896         [$2])]],
2897 [[m4_fatal([m4sugar/version.m4 not found])]]))
2898
2899
2900 ## ------------------ ##
2901 ## 15. Set handling.  ##
2902 ## ------------------ ##
2903
2904 # Autoconf likes to create arbitrarily large sets; for example, as of
2905 # this writing, the configure.ac for coreutils tracks a set of more
2906 # than 400 AC_SUBST.  How do we track all of these set members,
2907 # without introducing duplicates?  We could use m4_append_uniq, with
2908 # the set NAME residing in the contents of the macro NAME.
2909 # Unfortunately, m4_append_uniq is quadratic for set creation, because
2910 # it costs O(n) to search the string for each of O(n) insertions; not
2911 # to mention that with m4 1.4.x, even using m4_append is slow, costing
2912 # O(n) rather than O(1) per insertion.  Other set operations, not used
2913 # by Autoconf but still possible by manipulation of the definition
2914 # tracked in macro NAME, include O(n) deletion of one element and O(n)
2915 # computation of set size.  Because the set is exposed to the user via
2916 # the definition of a single macro, we cannot cache any data about the
2917 # set without risking the cache being invalidated by the user
2918 # redefining NAME.
2919 #
2920 # Can we do better?  Yes, because m4 gives us an O(1) search function
2921 # for free: ifdef.  Additionally, even m4 1.4.x gives us an O(1)
2922 # insert operation for free: pushdef.  But to use these, we must
2923 # represent the set via a group of macros; to keep the set consistent,
2924 # we must hide the set so that the user can only manipulate it through
2925 # accessor macros.  The contents of the set are maintained through two
2926 # access points; _m4_set([name]) is a pushdef stack of values in the
2927 # set, useful for O(n) traversal of the set contents; while the
2928 # existence of _m4_set([name],value) with no particular value is
2929 # useful for O(1) querying of set membership.  And since the user
2930 # cannot externally manipulate the set, we are free to add additional
2931 # caching macros for other performance improvements.  Deletion can be
2932 # O(1) per element rather than O(n), by reworking the definition of
2933 # _m4_set([name],value) to be 0 or 1 based on current membership, and
2934 # adding _m4_set_cleanup(name) to defer the O(n) cleanup of
2935 # _m4_set([name]) until we have another reason to do an O(n)
2936 # traversal.  The existence of _m4_set_cleanup(name) can then be used
2937 # elsewhere to determine if we must dereference _m4_set([name],value),
2938 # or assume that definition implies set membership.  Finally, size can
2939 # be tracked in an O(1) fashion with _m4_set_size(name).
2940 #
2941 # The quoting in _m4_set([name],value) is chosen so that there is no
2942 # ambiguity with a set whose name contains a comma, and so that we can
2943 # supply the value via _m4_defn([_m4_set([name])]) without needing any
2944 # quote manipulation.
2945
2946 # m4_set_add(SET, VALUE, [IF-UNIQ], [IF-DUP])
2947 # -------------------------------------------
2948 # Add VALUE as an element of SET.  Expand IF-UNIQ on the first
2949 # addition, and IF-DUP if it is already in the set.  Addition of one
2950 # element is O(1), such that overall set creation is O(n).
2951 #
2952 # We do not want to add a duplicate for a previously deleted but
2953 # unpruned element, but it is just as easy to check existence directly
2954 # as it is to query _m4_set_cleanup($1).
2955 m4_define([m4_set_add],
2956 [m4_ifdef([_m4_set([$1],$2)],
2957           [m4_if(m4_indir([_m4_set([$1],$2)]), [0],
2958                  [m4_define([_m4_set([$1],$2)],
2959                             [1])_m4_set_size([$1], [m4_incr])$3], [$4])],
2960           [m4_define([_m4_set([$1],$2)],
2961                      [1])m4_pushdef([_m4_set([$1])],
2962                                     [$2])_m4_set_size([$1], [m4_incr])$3])])
2963
2964 # m4_set_add_all(SET, VALUE...)
2965 # -----------------------------
2966 # Add each VALUE into SET.  This is O(n) in the number of VALUEs, and
2967 # can be faster than calling m4_set_add for each VALUE.
2968 #
2969 # Implement two recursion helpers; the check variant is slower but
2970 # handles the case where an element has previously been removed but
2971 # not pruned.  The recursion helpers ignore their second argument, so
2972 # that we can use the faster m4_shift2 and 2 arguments, rather than
2973 # _m4_shift2 and one argument, as the signal to end recursion.
2974 #
2975 # Please keep foreach.m4 in sync with any adjustments made here.
2976 m4_define([m4_set_add_all],
2977 [m4_define([_m4_set_size($1)], m4_eval(m4_set_size([$1])
2978   + m4_len(m4_ifdef([_m4_set_cleanup($1)], [_$0_check], [_$0])([$1], $@))))])
2979
2980 m4_define([_m4_set_add_all],
2981 [m4_if([$#], [2], [],
2982        [m4_ifdef([_m4_set([$1],$3)], [],
2983                  [m4_define([_m4_set([$1],$3)], [1])m4_pushdef([_m4_set([$1])],
2984            [$3])-])$0([$1], m4_shift2($@))])])
2985
2986 m4_define([_m4_set_add_all_check],
2987 [m4_if([$#], [2], [],
2988        [m4_set_add([$1], [$3])$0([$1], m4_shift2($@))])])
2989
2990 # m4_set_contains(SET, VALUE, [IF-PRESENT], [IF-ABSENT])
2991 # ------------------------------------------------------
2992 # Expand IF-PRESENT if SET contains VALUE, otherwise expand IF-ABSENT.
2993 # This is always O(1).
2994 m4_define([m4_set_contains],
2995 [m4_ifdef([_m4_set_cleanup($1)],
2996           [m4_if(m4_ifdef([_m4_set([$1],$2)],
2997                     [m4_indir([_m4_set([$1],$2)])], [0]), [1], [$3], [$4])],
2998           [m4_ifdef([_m4_set([$1],$2)], [$3], [$4])])])
2999
3000 # m4_set_contents(SET, [SEP])
3001 # ---------------------------
3002 # Expand to a single string containing all the elements in SET,
3003 # separated by SEP, without modifying SET.  No provision is made for
3004 # disambiguating set elements that contain non-empty SEP as a
3005 # sub-string, or for recognizing a set that contains only the empty
3006 # string.  Order of the output is not guaranteed.  If any elements
3007 # have been previously removed from the set, this action will prune
3008 # the unused memory.  This is O(n) in the size of the set before
3009 # pruning.
3010 #
3011 # Use _m4_popdef for speed.  The existence of _m4_set_cleanup($1)
3012 # determines which version of _1 helper we use.
3013 m4_define([m4_set_contents],
3014 [m4_set_map_sep([$1], [], [], [[$2]])])
3015
3016 # _m4_set_contents_1(SET)
3017 # _m4_set_contents_1c(SET)
3018 # _m4_set_contents_2(SET, [PRE], [POST], [SEP])
3019 # ---------------------------------------------
3020 # Expand to a list of quoted elements currently in the set, each
3021 # surrounded by PRE and POST, and moving SEP in front of PRE on
3022 # recursion.  To avoid nesting limit restrictions, the algorithm must
3023 # be broken into two parts; _1 destructively copies the stack in
3024 # reverse into _m4_set_($1), producing no output; then _2
3025 # destructively copies _m4_set_($1) back into the stack in reverse.
3026 # If no elements were deleted, then this visits the set in the order
3027 # that elements were inserted.  Behavior is undefined if PRE/POST/SEP
3028 # tries to recursively list or modify SET in any way other than
3029 # calling m4_set_remove on the current element.  Use _1 if all entries
3030 # in the stack are guaranteed to be in the set, and _1c to prune
3031 # removed entries.  Uses _m4_defn and _m4_popdef for speed.
3032 m4_define([_m4_set_contents_1],
3033 [_m4_stack_reverse([_m4_set([$1])], [_m4_set_($1)])])
3034
3035 m4_define([_m4_set_contents_1c],
3036 [m4_ifdef([_m4_set([$1])],
3037           [m4_set_contains([$1], _m4_defn([_m4_set([$1])]),
3038                    [m4_pushdef([_m4_set_($1)], _m4_defn([_m4_set([$1])]))],
3039                    [_m4_popdef([_m4_set([$1],]_m4_defn(
3040       [_m4_set([$1])])[)])])_m4_popdef([_m4_set([$1])])$0([$1])],
3041           [_m4_popdef([_m4_set_cleanup($1)])])])
3042
3043 m4_define([_m4_set_contents_2],
3044 [_m4_stack_reverse([_m4_set_($1)], [_m4_set([$1])],
3045   [$2[]_m4_defn([_m4_set_($1)])$3], [$4[]])])
3046
3047 # m4_set_delete(SET)
3048 # ------------------
3049 # Delete all elements in SET, and reclaim any memory occupied by the
3050 # set.  This is O(n) in the set size.
3051 #
3052 # Use _m4_defn and _m4_popdef for speed.
3053 m4_define([m4_set_delete],
3054 [m4_ifdef([_m4_set([$1])],
3055           [_m4_popdef([_m4_set([$1],]_m4_defn([_m4_set([$1])])[)],
3056                       [_m4_set([$1])])$0([$1])],
3057           [m4_ifdef([_m4_set_cleanup($1)],
3058                     [_m4_popdef([_m4_set_cleanup($1)])])m4_ifdef(
3059                     [_m4_set_size($1)],
3060                     [_m4_popdef([_m4_set_size($1)])])])])
3061
3062 # m4_set_difference(SET1, SET2)
3063 # -----------------------------
3064 # Produce a LIST of quoted elements that occur in SET1 but not SET2.
3065 # Output a comma prior to any elements, to distinguish the empty
3066 # string from no elements.  This can be directly used as a series of
3067 # arguments, such as for m4_join, or wrapped inside quotes for use in
3068 # m4_foreach.  Order of the output is not guaranteed.
3069 #
3070 # Short-circuit the idempotence relation.
3071 m4_define([m4_set_difference],
3072 [m4_if([$1], [$2], [], [m4_set_map_sep([$1], [_$0([$2],], [)])])])
3073
3074 m4_define([_m4_set_difference],
3075 [m4_set_contains([$1], [$2], [], [,[$2]])])
3076
3077 # m4_set_dump(SET, [SEP])
3078 # -----------------------
3079 # Expand to a single string containing all the elements in SET,
3080 # separated by SEP, then delete SET.  In general, if you only need to
3081 # list the contents once, this is faster than m4_set_contents.  No
3082 # provision is made for disambiguating set elements that contain
3083 # non-empty SEP as a sub-string.  Order of the output is not
3084 # guaranteed.  This is O(n) in the size of the set before pruning.
3085 #
3086 # Use _m4_popdef for speed.  Use existence of _m4_set_cleanup($1) to
3087 # decide if more expensive recursion is needed.
3088 m4_define([m4_set_dump],
3089 [m4_ifdef([_m4_set_size($1)],
3090           [_m4_popdef([_m4_set_size($1)])])m4_ifdef([_m4_set_cleanup($1)],
3091     [_$0_check], [_$0])([$1], [], [$2])])
3092
3093 # _m4_set_dump(SET, [SEP], [PREP])
3094 # _m4_set_dump_check(SET, [SEP], [PREP])
3095 # --------------------------------------
3096 # Print SEP and the current element, then delete the element and
3097 # recurse with empty SEP changed to PREP.  The check variant checks
3098 # whether the element has been previously removed.  Use _m4_defn and
3099 # _m4_popdef for speed.
3100 m4_define([_m4_set_dump],
3101 [m4_ifdef([_m4_set([$1])],
3102           [[$2]_m4_defn([_m4_set([$1])])_m4_popdef([_m4_set([$1],]_m4_defn(
3103                 [_m4_set([$1])])[)], [_m4_set([$1])])$0([$1], [$2$3])])])
3104
3105 m4_define([_m4_set_dump_check],
3106 [m4_ifdef([_m4_set([$1])],
3107           [m4_set_contains([$1], _m4_defn([_m4_set([$1])]),
3108                            [[$2]_m4_defn([_m4_set([$1])])])_m4_popdef(
3109     [_m4_set([$1],]_m4_defn([_m4_set([$1])])[)],
3110     [_m4_set([$1])])$0([$1], [$2$3])],
3111           [_m4_popdef([_m4_set_cleanup($1)])])])
3112
3113 # m4_set_empty(SET, [IF-EMPTY], [IF-ELEMENTS])
3114 # --------------------------------------------
3115 # Expand IF-EMPTY if SET has no elements, otherwise IF-ELEMENTS.
3116 m4_define([m4_set_empty],
3117 [m4_ifdef([_m4_set_size($1)],
3118           [m4_if(m4_indir([_m4_set_size($1)]), [0], [$2], [$3])], [$2])])
3119
3120 # m4_set_foreach(SET, VAR, ACTION)
3121 # --------------------------------
3122 # For each element of SET, define VAR to the element and expand
3123 # ACTION.  ACTION should not recursively list SET's contents, add
3124 # elements to SET, nor delete any element from SET except the one
3125 # currently in VAR.  The order that the elements are visited in is not
3126 # guaranteed.  This is faster than the corresponding m4_foreach([VAR],
3127 #   m4_indir([m4_dquote]m4_set_listc([SET])), [ACTION])
3128 m4_define([m4_set_foreach],
3129 [m4_pushdef([$2])m4_set_map_sep([$1], [m4_define([$2],], [)$3])])
3130
3131 # m4_set_intersection(SET1, SET2)
3132 # -------------------------------
3133 # Produce a LIST of quoted elements that occur in both SET1 or SET2.
3134 # Output a comma prior to any elements, to distinguish the empty
3135 # string from no elements.  This can be directly used as a series of
3136 # arguments, such as for m4_join, or wrapped inside quotes for use in
3137 # m4_foreach.  Order of the output is not guaranteed.
3138 #
3139 # Iterate over the smaller set, and short-circuit the idempotence
3140 # relation.
3141 m4_define([m4_set_intersection],
3142 [m4_if([$1], [$2], [m4_set_listc([$1])],
3143        m4_eval(m4_set_size([$2]) < m4_set_size([$1])), [1], [$0([$2], [$1])],
3144        [m4_set_map_sep([$1], [_$0([$2],], [)])])])
3145
3146 m4_define([_m4_set_intersection],
3147 [m4_set_contains([$1], [$2], [,[$2]])])
3148
3149 # m4_set_list(SET)
3150 # m4_set_listc(SET)
3151 # -----------------
3152 # Produce a LIST of quoted elements of SET.  This can be directly used
3153 # as a series of arguments, such as for m4_join or m4_set_add_all, or
3154 # wrapped inside quotes for use in m4_foreach or m4_map.  With
3155 # m4_set_list, there is no way to distinguish an empty set from a set
3156 # containing only the empty string; with m4_set_listc, a leading comma
3157 # is output if there are any elements.
3158 m4_define([m4_set_list],
3159 [m4_set_map_sep([$1], [], [], [,])])
3160
3161 m4_define([m4_set_listc],
3162 [m4_set_map_sep([$1], [,])])
3163
3164 # m4_set_map(SET, ACTION)
3165 # -----------------------
3166 # For each element of SET, expand ACTION with a single argument of the
3167 # current element.  ACTION should not recursively list SET's contents,
3168 # add elements to SET, nor delete any element from SET except the one
3169 # passed as an argument.  The order that the elements are visited in
3170 # is not guaranteed.  This is faster than either of the corresponding
3171 #   m4_map_args([ACTION]m4_set_listc([SET]))
3172 #   m4_set_foreach([SET], [VAR], [ACTION(m4_defn([VAR]))])
3173 m4_define([m4_set_map],
3174 [m4_set_map_sep([$1], [$2(], [)])])
3175
3176 # m4_set_map_sep(SET, [PRE], [POST], [SEP])
3177 # -----------------------------------------
3178 # For each element of SET, expand PRE[value]POST[], and expand SEP
3179 # between elements.
3180 m4_define([m4_set_map_sep],
3181 [m4_ifdef([_m4_set_cleanup($1)], [_m4_set_contents_1c],
3182           [_m4_set_contents_1])([$1])_m4_set_contents_2($@)])
3183
3184 # m4_set_remove(SET, VALUE, [IF-PRESENT], [IF-ABSENT])
3185 # ----------------------------------------------------
3186 # If VALUE is an element of SET, delete it and expand IF-PRESENT.
3187 # Otherwise expand IF-ABSENT.  Deleting a single value is O(1),
3188 # although it leaves memory occupied until the next O(n) traversal of
3189 # the set which will compact the set.
3190 #
3191 # Optimize if the element being removed is the most recently added,
3192 # since defining _m4_set_cleanup($1) slows down so many other macros.
3193 # In particular, this plays well with m4_set_foreach and m4_set_map.
3194 m4_define([m4_set_remove],
3195 [m4_set_contains([$1], [$2], [_m4_set_size([$1],
3196     [m4_decr])m4_if(_m4_defn([_m4_set([$1])]), [$2],
3197                     [_m4_popdef([_m4_set([$1],$2)], [_m4_set([$1])])],
3198                     [m4_define([_m4_set_cleanup($1)])m4_define(
3199                       [_m4_set([$1],$2)], [0])])$3], [$4])])
3200
3201 # m4_set_size(SET)
3202 # ----------------
3203 # Expand to the number of elements currently in SET.  This operation
3204 # is O(1), and thus more efficient than m4_count(m4_set_list([SET])).
3205 m4_define([m4_set_size],
3206 [m4_ifdef([_m4_set_size($1)], [m4_indir([_m4_set_size($1)])], [0])])
3207
3208 # _m4_set_size(SET, ACTION)
3209 # -------------------------
3210 # ACTION must be either m4_incr or m4_decr, and the size of SET is
3211 # changed accordingly.  If the set is empty, ACTION must not be
3212 # m4_decr.
3213 m4_define([_m4_set_size],
3214 [m4_define([_m4_set_size($1)],
3215            m4_ifdef([_m4_set_size($1)], [$2(m4_indir([_m4_set_size($1)]))],
3216                     [1]))])
3217
3218 # m4_set_union(SET1, SET2)
3219 # ------------------------
3220 # Produce a LIST of double quoted elements that occur in either SET1
3221 # or SET2, without duplicates.  Output a comma prior to any elements,
3222 # to distinguish the empty string from no elements.  This can be
3223 # directly used as a series of arguments, such as for m4_join, or
3224 # wrapped inside quotes for use in m4_foreach.  Order of the output is
3225 # not guaranteed.
3226 #
3227 # We can rely on the fact that m4_set_listc prunes SET1, so we don't
3228 # need to check _m4_set([$1],element) for 0.  Short-circuit the
3229 # idempotence relation.
3230 m4_define([m4_set_union],
3231 [m4_set_listc([$1])m4_if([$1], [$2], [],
3232   [m4_set_map_sep([$2], [_$0([$1],], [)])])])
3233
3234 m4_define([_m4_set_union],
3235 [m4_ifdef([_m4_set([$1],$2)], [], [,[$2]])])
3236
3237
3238 ## ------------------- ##
3239 ## 16. File handling.  ##
3240 ## ------------------- ##
3241
3242
3243 # It is a real pity that M4 comes with no macros to bind a diversion
3244 # to a file.  So we have to deal without, which makes us a lot more
3245 # fragile than we should.
3246
3247
3248 # m4_file_append(FILE-NAME, CONTENT)
3249 # ----------------------------------
3250 m4_define([m4_file_append],
3251 [m4_syscmd([cat >>$1 <<_m4eof
3252 $2
3253 _m4eof
3254 ])
3255 m4_if(m4_sysval, [0], [],
3256       [m4_fatal([$0: cannot write: $1])])])
3257
3258
3259
3260 ## ------------------------ ##
3261 ## 17. Setting M4sugar up.  ##
3262 ## ------------------------ ##
3263
3264 # _m4_divert_diversion should be defined.
3265 m4_divert_push([KILL])
3266
3267 # m4_init
3268 # -------
3269 # Initialize the m4sugar language.
3270 m4_define([m4_init],
3271 [# All the M4sugar macros start with `m4_', except `dnl' kept as is
3272 # for sake of simplicity.
3273 m4_pattern_forbid([^_?m4_])
3274 m4_pattern_forbid([^dnl$])
3275
3276 # If __m4_version__ is defined, we assume that we are being run by M4
3277 # 1.6 or newer, thus $@ recursion is linear, and debugmode(+do)
3278 # is available for faster checks of dereferencing undefined macros
3279 # and forcing dumpdef to print to stderr regardless of debugfile.
3280 # But if it is missing, we assume we are being run by M4 1.4.x, that
3281 # $@ recursion is quadratic, and that we need foreach-based
3282 # replacement macros.  Also, m4 prior to 1.4.8 loses track of location
3283 # during m4wrap text; __line__ should never be 0.
3284 #
3285 # Use the raw builtin to avoid tripping up include tracing.
3286 # Meanwhile, avoid m4_copy, since it temporarily undefines m4_defn.
3287 m4_ifdef([__m4_version__],
3288 [m4_debugmode([+do])
3289 m4_define([m4_defn], _m4_defn([_m4_defn]))
3290 m4_define([m4_dumpdef], _m4_defn([_m4_dumpdef]))
3291 m4_define([m4_popdef], _m4_defn([_m4_popdef]))
3292 m4_define([m4_undefine], _m4_defn([_m4_undefine]))],
3293 [m4_builtin([include], [m4sugar/foreach.m4])
3294 m4_wrap_lifo([m4_if(__line__, [0], [m4_pushdef([m4_location],
3295 ]]m4_dquote(m4_dquote(m4_dquote(__file__:__line__)))[[)])])])
3296
3297 # Rewrite the first entry of the diversion stack.
3298 m4_divert([KILL])
3299
3300 # Check the divert push/pop perfect balance.
3301 # Some users are prone to also use m4_wrap to register last-minute
3302 # m4_divert_text; so after our diversion cleanups, we restore
3303 # KILL as the bottom of the diversion stack.
3304 m4_wrap([m4_popdef([_m4_divert_diversion])m4_ifdef(
3305   [_m4_divert_diversion], [m4_fatal([$0: unbalanced m4_divert_push:
3306 ]m4_divert_stack)])_m4_popdef([_m4_divert_stack])m4_divert_push([KILL])])
3307 ])