diff options
author | Anas Nashif <anas.nashif@intel.com> | 2012-11-05 11:10:13 -0800 |
---|---|---|
committer | Anas Nashif <anas.nashif@intel.com> | 2012-11-05 11:10:13 -0800 |
commit | 7be93f2d05131d061bd4790ae33c8d50f50010d7 (patch) | |
tree | 72736c1606f803a92ffa07c9808ffea2521d009e /doc | |
download | m4-7be93f2d05131d061bd4790ae33c8d50f50010d7.tar.gz m4-7be93f2d05131d061bd4790ae33c8d50f50010d7.tar.bz2 m4-7be93f2d05131d061bd4790ae33c8d50f50010d7.zip |
Imported Upstream version 1.4.16upstream/1.4.16
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 43 | ||||
-rw-r--r-- | doc/Makefile.in | 1557 | ||||
-rw-r--r-- | doc/fdl-1.3.texi | 506 | ||||
-rw-r--r-- | doc/gendocs_template | 96 | ||||
-rw-r--r-- | doc/gpl-3.0.texi | 717 | ||||
-rw-r--r-- | doc/m4.1 | 151 | ||||
-rw-r--r-- | doc/m4.info | 134 | ||||
-rw-r--r-- | doc/m4.info-1 | 7858 | ||||
-rw-r--r-- | doc/m4.info-2 | 909 | ||||
-rw-r--r-- | doc/m4.texinfo | 8729 | ||||
-rw-r--r-- | doc/stamp-vti | 4 | ||||
-rw-r--r-- | doc/version.texi | 4 |
12 files changed, 20708 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..9d3391d --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,43 @@ +## Makefile.am - template for generating Makefile via Automake +## +## Copyright (C) 2006-2011 Free Software Foundation, Inc. +## +## This file is part of GNU M4. +## +## GNU M4 is free software: you can redistribute it and/or modify +## it under the terms of the GNU General Public License as published by +## the Free Software Foundation, either version 3 of the License, or +## (at your option) any later version. +## +## GNU M4 is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with this program. If not, see <http://www.gnu.org/licenses/>. +## +## This file written by Eric Blake <ebb9@byu.net> + +info_TEXINFOS = m4.texinfo +m4_TEXINFOS = fdl-1.3.texi gpl-3.0.texi +man_MANS = $(srcdir)/m4.1 +EXTRA_DIST = $(man_MANS) gendocs_template +MAINTAINERCLEANFILES = $(man_MANS) gendocs_template +SUFFIXES = .1 +HELP2MAN = $(SHELL) $(top_srcdir)/build-aux/missing --run help2man + +# Depend on ../.version for version, m4.c for usage text. Do not depend on +# built m4 executable, since not everyone has help2man or perl. +# Build the man page once in the srcdir, rather than in every VPATH build +# dir, to match how automake builds info pages. This is safe for 'make +# distcheck' since it is distributed pre-built. +$(srcdir)/m4.1: $(top_srcdir)/.version $(top_srcdir)/src/m4.c + @if test -x ../src/m4$(EXEEXT) ; then \ + echo "Updating man page m4.1" ; \ + $(HELP2MAN) --name="macro processor" --source='$(PACKAGE_STRING)' \ + --info-page=m4 --output=$@ ../src/m4$(EXEEXT) ; \ + else \ + echo "WARNING: The \`man' page \`$@' cannot be updated yet."; \ + echo " Retry once the program executable is ready."; \ + fi diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..25e44aa --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,1557 @@ +# Makefile.in generated by automake 1.11.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +DIST_COMMON = $(m4_TEXINFOS) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in $(srcdir)/stamp-vti \ + $(srcdir)/version.texi +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/00gnulib.m4 \ + $(top_srcdir)/m4/alloca.m4 $(top_srcdir)/m4/ansi-c++.m4 \ + $(top_srcdir)/m4/assert.m4 $(top_srcdir)/m4/autobuild.m4 \ + $(top_srcdir)/m4/btowc.m4 $(top_srcdir)/m4/c-stack.m4 \ + $(top_srcdir)/m4/canonicalize.m4 $(top_srcdir)/m4/cloexec.m4 \ + $(top_srcdir)/m4/close-stream.m4 $(top_srcdir)/m4/close.m4 \ + $(top_srcdir)/m4/closein.m4 $(top_srcdir)/m4/closeout.m4 \ + $(top_srcdir)/m4/codeset.m4 $(top_srcdir)/m4/config-h.m4 \ + $(top_srcdir)/m4/configmake.m4 $(top_srcdir)/m4/dirname.m4 \ + $(top_srcdir)/m4/double-slash-root.m4 $(top_srcdir)/m4/dup2.m4 \ + $(top_srcdir)/m4/eealloc.m4 $(top_srcdir)/m4/environ.m4 \ + $(top_srcdir)/m4/errno_h.m4 $(top_srcdir)/m4/error.m4 \ + $(top_srcdir)/m4/execute.m4 $(top_srcdir)/m4/exponentd.m4 \ + $(top_srcdir)/m4/exponentf.m4 $(top_srcdir)/m4/exponentl.m4 \ + $(top_srcdir)/m4/extensions.m4 \ + $(top_srcdir)/m4/fatal-signal.m4 $(top_srcdir)/m4/fclose.m4 \ + $(top_srcdir)/m4/fcntl-o.m4 $(top_srcdir)/m4/fcntl.m4 \ + $(top_srcdir)/m4/fcntl_h.m4 $(top_srcdir)/m4/fflush.m4 \ + $(top_srcdir)/m4/filenamecat.m4 $(top_srcdir)/m4/float_h.m4 \ + $(top_srcdir)/m4/fopen.m4 $(top_srcdir)/m4/fpending.m4 \ + $(top_srcdir)/m4/fpieee.m4 $(top_srcdir)/m4/fpurge.m4 \ + $(top_srcdir)/m4/freading.m4 $(top_srcdir)/m4/frexp.m4 \ + $(top_srcdir)/m4/frexpl.m4 $(top_srcdir)/m4/fseeko.m4 \ + $(top_srcdir)/m4/ftell.m4 $(top_srcdir)/m4/ftello.m4 \ + $(top_srcdir)/m4/getdtablesize.m4 $(top_srcdir)/m4/getopt.m4 \ + $(top_srcdir)/m4/getpagesize.m4 \ + $(top_srcdir)/m4/gettimeofday.m4 $(top_srcdir)/m4/gl_list.m4 \ + $(top_srcdir)/m4/glibc21.m4 $(top_srcdir)/m4/gnulib-common.m4 \ + $(top_srcdir)/m4/gnulib-comp.m4 \ + $(top_srcdir)/m4/include_next.m4 $(top_srcdir)/m4/inline.m4 \ + $(top_srcdir)/m4/intlmacosx.m4 $(top_srcdir)/m4/intmax_t.m4 \ + $(top_srcdir)/m4/inttypes_h.m4 $(top_srcdir)/m4/isnand.m4 \ + $(top_srcdir)/m4/isnanf.m4 $(top_srcdir)/m4/isnanl.m4 \ + $(top_srcdir)/m4/langinfo_h.m4 $(top_srcdir)/m4/lcmessage.m4 \ + $(top_srcdir)/m4/ldexp.m4 $(top_srcdir)/m4/ldexpl.m4 \ + $(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \ + $(top_srcdir)/m4/lib-prefix.m4 $(top_srcdir)/m4/libsigsegv.m4 \ + $(top_srcdir)/m4/link.m4 $(top_srcdir)/m4/localcharset.m4 \ + $(top_srcdir)/m4/locale-fr.m4 $(top_srcdir)/m4/locale-ja.m4 \ + $(top_srcdir)/m4/locale-tr.m4 $(top_srcdir)/m4/locale-zh.m4 \ + $(top_srcdir)/m4/locale_h.m4 $(top_srcdir)/m4/localename.m4 \ + $(top_srcdir)/m4/lock.m4 $(top_srcdir)/m4/longlong.m4 \ + $(top_srcdir)/m4/lseek.m4 $(top_srcdir)/m4/lstat.m4 \ + $(top_srcdir)/m4/malloc.m4 $(top_srcdir)/m4/malloca.m4 \ + $(top_srcdir)/m4/manywarnings.m4 $(top_srcdir)/m4/math_h.m4 \ + $(top_srcdir)/m4/mbrtowc.m4 $(top_srcdir)/m4/mbsinit.m4 \ + $(top_srcdir)/m4/mbstate_t.m4 $(top_srcdir)/m4/mbtowc.m4 \ + $(top_srcdir)/m4/memchr.m4 $(top_srcdir)/m4/mkdtemp.m4 \ + $(top_srcdir)/m4/mkstemp.m4 $(top_srcdir)/m4/mmap-anon.m4 \ + $(top_srcdir)/m4/mode_t.m4 $(top_srcdir)/m4/multiarch.m4 \ + $(top_srcdir)/m4/nl_langinfo.m4 $(top_srcdir)/m4/nocrash.m4 \ + $(top_srcdir)/m4/open.m4 $(top_srcdir)/m4/pathmax.m4 \ + $(top_srcdir)/m4/pipe2.m4 $(top_srcdir)/m4/posix_spawn.m4 \ + $(top_srcdir)/m4/printf-frexp.m4 \ + $(top_srcdir)/m4/printf-frexpl.m4 $(top_srcdir)/m4/printf.m4 \ + $(top_srcdir)/m4/putenv.m4 $(top_srcdir)/m4/quotearg.m4 \ + $(top_srcdir)/m4/rawmemchr.m4 $(top_srcdir)/m4/readlink.m4 \ + $(top_srcdir)/m4/regex.m4 $(top_srcdir)/m4/rename.m4 \ + $(top_srcdir)/m4/rmdir.m4 $(top_srcdir)/m4/sched_h.m4 \ + $(top_srcdir)/m4/setenv.m4 $(top_srcdir)/m4/setlocale.m4 \ + $(top_srcdir)/m4/sig_atomic_t.m4 $(top_srcdir)/m4/sigaction.m4 \ + $(top_srcdir)/m4/signal_h.m4 \ + $(top_srcdir)/m4/signalblocking.m4 $(top_srcdir)/m4/signbit.m4 \ + $(top_srcdir)/m4/size_max.m4 $(top_srcdir)/m4/snprintf.m4 \ + $(top_srcdir)/m4/spawn-pipe.m4 $(top_srcdir)/m4/spawn_h.m4 \ + $(top_srcdir)/m4/ssize_t.m4 $(top_srcdir)/m4/stat.m4 \ + $(top_srcdir)/m4/stdarg.m4 $(top_srcdir)/m4/stdbool.m4 \ + $(top_srcdir)/m4/stddef_h.m4 $(top_srcdir)/m4/stdint.m4 \ + $(top_srcdir)/m4/stdint_h.m4 $(top_srcdir)/m4/stdio-safer.m4 \ + $(top_srcdir)/m4/stdio_h.m4 $(top_srcdir)/m4/stdlib-safer.m4 \ + $(top_srcdir)/m4/stdlib_h.m4 $(top_srcdir)/m4/strchrnul.m4 \ + $(top_srcdir)/m4/strdup.m4 $(top_srcdir)/m4/strerror.m4 \ + $(top_srcdir)/m4/string_h.m4 $(top_srcdir)/m4/strndup.m4 \ + $(top_srcdir)/m4/strnlen.m4 $(top_srcdir)/m4/strsignal.m4 \ + $(top_srcdir)/m4/strstr.m4 $(top_srcdir)/m4/strtod.m4 \ + $(top_srcdir)/m4/strtol.m4 $(top_srcdir)/m4/symlink.m4 \ + $(top_srcdir)/m4/sys_stat_h.m4 $(top_srcdir)/m4/sys_time_h.m4 \ + $(top_srcdir)/m4/sys_wait_h.m4 $(top_srcdir)/m4/tempname.m4 \ + $(top_srcdir)/m4/threadlib.m4 $(top_srcdir)/m4/time_h.m4 \ + $(top_srcdir)/m4/tls.m4 $(top_srcdir)/m4/tmpdir.m4 \ + $(top_srcdir)/m4/ungetc.m4 $(top_srcdir)/m4/unistd-safer.m4 \ + $(top_srcdir)/m4/unistd_h.m4 $(top_srcdir)/m4/unlocked-io.m4 \ + $(top_srcdir)/m4/vasnprintf.m4 \ + $(top_srcdir)/m4/vasprintf-posix.m4 \ + $(top_srcdir)/m4/vasprintf.m4 $(top_srcdir)/m4/version-etc.m4 \ + $(top_srcdir)/m4/wait-process.m4 $(top_srcdir)/m4/waitpid.m4 \ + $(top_srcdir)/m4/warnings.m4 $(top_srcdir)/m4/wchar_h.m4 \ + $(top_srcdir)/m4/wchar_t.m4 $(top_srcdir)/m4/wcrtomb.m4 \ + $(top_srcdir)/m4/wctob.m4 $(top_srcdir)/m4/wctomb.m4 \ + $(top_srcdir)/m4/wctype_h.m4 $(top_srcdir)/m4/wint_t.m4 \ + $(top_srcdir)/m4/xalloc.m4 $(top_srcdir)/m4/xsize.m4 \ + $(top_srcdir)/m4/xstrndup.m4 $(top_srcdir)/m4/xvasprintf.m4 \ + $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/lib/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +INFO_DEPS = $(srcdir)/m4.info +TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux +DVIS = m4.dvi +PDFS = m4.pdf +PSS = m4.ps +HTMLS = m4.html +TEXINFOS = m4.texinfo +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +man1dir = $(mandir)/man1 +NROFF = nroff +MANS = $(man_MANS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +pkglibexecdir = @pkglibexecdir@ +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +ALLOCA_H = @ALLOCA_H@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APPLE_UNIVERSAL_BUILD = @APPLE_UNIVERSAL_BUILD@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@ +BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@ +BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@ +BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@ +BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CONFIG_INCLUDE = @CONFIG_INCLUDE@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CXX_CHOICE = @CXX_CHOICE@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EMULTIHOP_HIDDEN = @EMULTIHOP_HIDDEN@ +EMULTIHOP_VALUE = @EMULTIHOP_VALUE@ +ENOLINK_HIDDEN = @ENOLINK_HIDDEN@ +ENOLINK_VALUE = @ENOLINK_VALUE@ +EOVERFLOW_HIDDEN = @EOVERFLOW_HIDDEN@ +EOVERFLOW_VALUE = @EOVERFLOW_VALUE@ +ERRNO_H = @ERRNO_H@ +EXEEXT = @EXEEXT@ +FLOAT_H = @FLOAT_H@ +GETOPT_H = @GETOPT_H@ +GLIBC21 = @GLIBC21@ +GNULIB_ACOSL = @GNULIB_ACOSL@ +GNULIB_ASINL = @GNULIB_ASINL@ +GNULIB_ATANL = @GNULIB_ATANL@ +GNULIB_ATOLL = @GNULIB_ATOLL@ +GNULIB_BTOWC = @GNULIB_BTOWC@ +GNULIB_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@ +GNULIB_CANONICALIZE_FILE_NAME = @GNULIB_CANONICALIZE_FILE_NAME@ +GNULIB_CEIL = @GNULIB_CEIL@ +GNULIB_CEILF = @GNULIB_CEILF@ +GNULIB_CEILL = @GNULIB_CEILL@ +GNULIB_CHOWN = @GNULIB_CHOWN@ +GNULIB_CLOSE = @GNULIB_CLOSE@ +GNULIB_COSL = @GNULIB_COSL@ +GNULIB_DPRINTF = @GNULIB_DPRINTF@ +GNULIB_DUP2 = @GNULIB_DUP2@ +GNULIB_DUP3 = @GNULIB_DUP3@ +GNULIB_DUPLOCALE = @GNULIB_DUPLOCALE@ +GNULIB_ENVIRON = @GNULIB_ENVIRON@ +GNULIB_EUIDACCESS = @GNULIB_EUIDACCESS@ +GNULIB_EXPL = @GNULIB_EXPL@ +GNULIB_FACCESSAT = @GNULIB_FACCESSAT@ +GNULIB_FCHDIR = @GNULIB_FCHDIR@ +GNULIB_FCHMODAT = @GNULIB_FCHMODAT@ +GNULIB_FCHOWNAT = @GNULIB_FCHOWNAT@ +GNULIB_FCLOSE = @GNULIB_FCLOSE@ +GNULIB_FCNTL = @GNULIB_FCNTL@ +GNULIB_FFLUSH = @GNULIB_FFLUSH@ +GNULIB_FLOOR = @GNULIB_FLOOR@ +GNULIB_FLOORF = @GNULIB_FLOORF@ +GNULIB_FLOORL = @GNULIB_FLOORL@ +GNULIB_FOPEN = @GNULIB_FOPEN@ +GNULIB_FPRINTF = @GNULIB_FPRINTF@ +GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@ +GNULIB_FPURGE = @GNULIB_FPURGE@ +GNULIB_FPUTC = @GNULIB_FPUTC@ +GNULIB_FPUTS = @GNULIB_FPUTS@ +GNULIB_FREOPEN = @GNULIB_FREOPEN@ +GNULIB_FREXP = @GNULIB_FREXP@ +GNULIB_FREXPL = @GNULIB_FREXPL@ +GNULIB_FSEEK = @GNULIB_FSEEK@ +GNULIB_FSEEKO = @GNULIB_FSEEKO@ +GNULIB_FSTATAT = @GNULIB_FSTATAT@ +GNULIB_FSYNC = @GNULIB_FSYNC@ +GNULIB_FTELL = @GNULIB_FTELL@ +GNULIB_FTELLO = @GNULIB_FTELLO@ +GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@ +GNULIB_FUTIMENS = @GNULIB_FUTIMENS@ +GNULIB_FWRITE = @GNULIB_FWRITE@ +GNULIB_GETCWD = @GNULIB_GETCWD@ +GNULIB_GETDELIM = @GNULIB_GETDELIM@ +GNULIB_GETDOMAINNAME = @GNULIB_GETDOMAINNAME@ +GNULIB_GETDTABLESIZE = @GNULIB_GETDTABLESIZE@ +GNULIB_GETGROUPS = @GNULIB_GETGROUPS@ +GNULIB_GETHOSTNAME = @GNULIB_GETHOSTNAME@ +GNULIB_GETLINE = @GNULIB_GETLINE@ +GNULIB_GETLOADAVG = @GNULIB_GETLOADAVG@ +GNULIB_GETLOGIN = @GNULIB_GETLOGIN@ +GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@ +GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@ +GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@ +GNULIB_GETTIMEOFDAY = @GNULIB_GETTIMEOFDAY@ +GNULIB_GETUSERSHELL = @GNULIB_GETUSERSHELL@ +GNULIB_GRANTPT = @GNULIB_GRANTPT@ +GNULIB_ISFINITE = @GNULIB_ISFINITE@ +GNULIB_ISINF = @GNULIB_ISINF@ +GNULIB_ISNAN = @GNULIB_ISNAN@ +GNULIB_ISNAND = @GNULIB_ISNAND@ +GNULIB_ISNANF = @GNULIB_ISNANF@ +GNULIB_ISNANL = @GNULIB_ISNANL@ +GNULIB_ISWBLANK = @GNULIB_ISWBLANK@ +GNULIB_ISWCTYPE = @GNULIB_ISWCTYPE@ +GNULIB_LCHMOD = @GNULIB_LCHMOD@ +GNULIB_LCHOWN = @GNULIB_LCHOWN@ +GNULIB_LDEXPL = @GNULIB_LDEXPL@ +GNULIB_LINK = @GNULIB_LINK@ +GNULIB_LINKAT = @GNULIB_LINKAT@ +GNULIB_LOGB = @GNULIB_LOGB@ +GNULIB_LOGL = @GNULIB_LOGL@ +GNULIB_LSEEK = @GNULIB_LSEEK@ +GNULIB_LSTAT = @GNULIB_LSTAT@ +GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@ +GNULIB_MBRLEN = @GNULIB_MBRLEN@ +GNULIB_MBRTOWC = @GNULIB_MBRTOWC@ +GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@ +GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@ +GNULIB_MBSCHR = @GNULIB_MBSCHR@ +GNULIB_MBSCSPN = @GNULIB_MBSCSPN@ +GNULIB_MBSINIT = @GNULIB_MBSINIT@ +GNULIB_MBSLEN = @GNULIB_MBSLEN@ +GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@ +GNULIB_MBSNLEN = @GNULIB_MBSNLEN@ +GNULIB_MBSNRTOWCS = @GNULIB_MBSNRTOWCS@ +GNULIB_MBSPBRK = @GNULIB_MBSPBRK@ +GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@ +GNULIB_MBSRCHR = @GNULIB_MBSRCHR@ +GNULIB_MBSRTOWCS = @GNULIB_MBSRTOWCS@ +GNULIB_MBSSEP = @GNULIB_MBSSEP@ +GNULIB_MBSSPN = @GNULIB_MBSSPN@ +GNULIB_MBSSTR = @GNULIB_MBSSTR@ +GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@ +GNULIB_MBTOWC = @GNULIB_MBTOWC@ +GNULIB_MEMCHR = @GNULIB_MEMCHR@ +GNULIB_MEMMEM = @GNULIB_MEMMEM@ +GNULIB_MEMPCPY = @GNULIB_MEMPCPY@ +GNULIB_MEMRCHR = @GNULIB_MEMRCHR@ +GNULIB_MKDIRAT = @GNULIB_MKDIRAT@ +GNULIB_MKDTEMP = @GNULIB_MKDTEMP@ +GNULIB_MKFIFO = @GNULIB_MKFIFO@ +GNULIB_MKFIFOAT = @GNULIB_MKFIFOAT@ +GNULIB_MKNOD = @GNULIB_MKNOD@ +GNULIB_MKNODAT = @GNULIB_MKNODAT@ +GNULIB_MKOSTEMP = @GNULIB_MKOSTEMP@ +GNULIB_MKOSTEMPS = @GNULIB_MKOSTEMPS@ +GNULIB_MKSTEMP = @GNULIB_MKSTEMP@ +GNULIB_MKSTEMPS = @GNULIB_MKSTEMPS@ +GNULIB_MKTIME = @GNULIB_MKTIME@ +GNULIB_NANOSLEEP = @GNULIB_NANOSLEEP@ +GNULIB_NL_LANGINFO = @GNULIB_NL_LANGINFO@ +GNULIB_OBSTACK_PRINTF = @GNULIB_OBSTACK_PRINTF@ +GNULIB_OBSTACK_PRINTF_POSIX = @GNULIB_OBSTACK_PRINTF_POSIX@ +GNULIB_OPEN = @GNULIB_OPEN@ +GNULIB_OPENAT = @GNULIB_OPENAT@ +GNULIB_PERROR = @GNULIB_PERROR@ +GNULIB_PIPE = @GNULIB_PIPE@ +GNULIB_PIPE2 = @GNULIB_PIPE2@ +GNULIB_POPEN = @GNULIB_POPEN@ +GNULIB_POSIX_SPAWN = @GNULIB_POSIX_SPAWN@ +GNULIB_POSIX_SPAWNATTR_DESTROY = @GNULIB_POSIX_SPAWNATTR_DESTROY@ +GNULIB_POSIX_SPAWNATTR_GETFLAGS = @GNULIB_POSIX_SPAWNATTR_GETFLAGS@ +GNULIB_POSIX_SPAWNATTR_GETPGROUP = @GNULIB_POSIX_SPAWNATTR_GETPGROUP@ +GNULIB_POSIX_SPAWNATTR_GETSCHEDPARAM = @GNULIB_POSIX_SPAWNATTR_GETSCHEDPARAM@ +GNULIB_POSIX_SPAWNATTR_GETSCHEDPOLICY = @GNULIB_POSIX_SPAWNATTR_GETSCHEDPOLICY@ +GNULIB_POSIX_SPAWNATTR_GETSIGDEFAULT = @GNULIB_POSIX_SPAWNATTR_GETSIGDEFAULT@ +GNULIB_POSIX_SPAWNATTR_GETSIGMASK = @GNULIB_POSIX_SPAWNATTR_GETSIGMASK@ +GNULIB_POSIX_SPAWNATTR_INIT = @GNULIB_POSIX_SPAWNATTR_INIT@ +GNULIB_POSIX_SPAWNATTR_SETFLAGS = @GNULIB_POSIX_SPAWNATTR_SETFLAGS@ +GNULIB_POSIX_SPAWNATTR_SETPGROUP = @GNULIB_POSIX_SPAWNATTR_SETPGROUP@ +GNULIB_POSIX_SPAWNATTR_SETSCHEDPARAM = @GNULIB_POSIX_SPAWNATTR_SETSCHEDPARAM@ +GNULIB_POSIX_SPAWNATTR_SETSCHEDPOLICY = @GNULIB_POSIX_SPAWNATTR_SETSCHEDPOLICY@ +GNULIB_POSIX_SPAWNATTR_SETSIGDEFAULT = @GNULIB_POSIX_SPAWNATTR_SETSIGDEFAULT@ +GNULIB_POSIX_SPAWNATTR_SETSIGMASK = @GNULIB_POSIX_SPAWNATTR_SETSIGMASK@ +GNULIB_POSIX_SPAWNP = @GNULIB_POSIX_SPAWNP@ +GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE@ +GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDDUP2 = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDDUP2@ +GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDOPEN = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDOPEN@ +GNULIB_POSIX_SPAWN_FILE_ACTIONS_DESTROY = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_DESTROY@ +GNULIB_POSIX_SPAWN_FILE_ACTIONS_INIT = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_INIT@ +GNULIB_PREAD = @GNULIB_PREAD@ +GNULIB_PRINTF = @GNULIB_PRINTF@ +GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@ +GNULIB_PTSNAME = @GNULIB_PTSNAME@ +GNULIB_PUTC = @GNULIB_PUTC@ +GNULIB_PUTCHAR = @GNULIB_PUTCHAR@ +GNULIB_PUTENV = @GNULIB_PUTENV@ +GNULIB_PUTS = @GNULIB_PUTS@ +GNULIB_PWRITE = @GNULIB_PWRITE@ +GNULIB_RANDOM_R = @GNULIB_RANDOM_R@ +GNULIB_RAWMEMCHR = @GNULIB_RAWMEMCHR@ +GNULIB_READLINK = @GNULIB_READLINK@ +GNULIB_READLINKAT = @GNULIB_READLINKAT@ +GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@ +GNULIB_REALPATH = @GNULIB_REALPATH@ +GNULIB_REMOVE = @GNULIB_REMOVE@ +GNULIB_RENAME = @GNULIB_RENAME@ +GNULIB_RENAMEAT = @GNULIB_RENAMEAT@ +GNULIB_RMDIR = @GNULIB_RMDIR@ +GNULIB_ROUND = @GNULIB_ROUND@ +GNULIB_ROUNDF = @GNULIB_ROUNDF@ +GNULIB_ROUNDL = @GNULIB_ROUNDL@ +GNULIB_RPMATCH = @GNULIB_RPMATCH@ +GNULIB_SETENV = @GNULIB_SETENV@ +GNULIB_SETLOCALE = @GNULIB_SETLOCALE@ +GNULIB_SIGACTION = @GNULIB_SIGACTION@ +GNULIB_SIGNAL_H_SIGPIPE = @GNULIB_SIGNAL_H_SIGPIPE@ +GNULIB_SIGNBIT = @GNULIB_SIGNBIT@ +GNULIB_SIGPROCMASK = @GNULIB_SIGPROCMASK@ +GNULIB_SINL = @GNULIB_SINL@ +GNULIB_SLEEP = @GNULIB_SLEEP@ +GNULIB_SNPRINTF = @GNULIB_SNPRINTF@ +GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@ +GNULIB_SQRTL = @GNULIB_SQRTL@ +GNULIB_STAT = @GNULIB_STAT@ +GNULIB_STDIO_H_SIGPIPE = @GNULIB_STDIO_H_SIGPIPE@ +GNULIB_STPCPY = @GNULIB_STPCPY@ +GNULIB_STPNCPY = @GNULIB_STPNCPY@ +GNULIB_STRCASESTR = @GNULIB_STRCASESTR@ +GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@ +GNULIB_STRDUP = @GNULIB_STRDUP@ +GNULIB_STRERROR = @GNULIB_STRERROR@ +GNULIB_STRERROR_R = @GNULIB_STRERROR_R@ +GNULIB_STRNCAT = @GNULIB_STRNCAT@ +GNULIB_STRNDUP = @GNULIB_STRNDUP@ +GNULIB_STRNLEN = @GNULIB_STRNLEN@ +GNULIB_STRPBRK = @GNULIB_STRPBRK@ +GNULIB_STRPTIME = @GNULIB_STRPTIME@ +GNULIB_STRSEP = @GNULIB_STRSEP@ +GNULIB_STRSIGNAL = @GNULIB_STRSIGNAL@ +GNULIB_STRSTR = @GNULIB_STRSTR@ +GNULIB_STRTOD = @GNULIB_STRTOD@ +GNULIB_STRTOK_R = @GNULIB_STRTOK_R@ +GNULIB_STRTOLL = @GNULIB_STRTOLL@ +GNULIB_STRTOULL = @GNULIB_STRTOULL@ +GNULIB_STRVERSCMP = @GNULIB_STRVERSCMP@ +GNULIB_SYMLINK = @GNULIB_SYMLINK@ +GNULIB_SYMLINKAT = @GNULIB_SYMLINKAT@ +GNULIB_SYSTEM_POSIX = @GNULIB_SYSTEM_POSIX@ +GNULIB_TANL = @GNULIB_TANL@ +GNULIB_TIMEGM = @GNULIB_TIMEGM@ +GNULIB_TIME_R = @GNULIB_TIME_R@ +GNULIB_TMPFILE = @GNULIB_TMPFILE@ +GNULIB_TOWCTRANS = @GNULIB_TOWCTRANS@ +GNULIB_TRUNC = @GNULIB_TRUNC@ +GNULIB_TRUNCF = @GNULIB_TRUNCF@ +GNULIB_TRUNCL = @GNULIB_TRUNCL@ +GNULIB_TTYNAME_R = @GNULIB_TTYNAME_R@ +GNULIB_UNISTD_H_GETOPT = @GNULIB_UNISTD_H_GETOPT@ +GNULIB_UNISTD_H_SIGPIPE = @GNULIB_UNISTD_H_SIGPIPE@ +GNULIB_UNLINK = @GNULIB_UNLINK@ +GNULIB_UNLINKAT = @GNULIB_UNLINKAT@ +GNULIB_UNLOCKPT = @GNULIB_UNLOCKPT@ +GNULIB_UNSETENV = @GNULIB_UNSETENV@ +GNULIB_USLEEP = @GNULIB_USLEEP@ +GNULIB_UTIMENSAT = @GNULIB_UTIMENSAT@ +GNULIB_VASPRINTF = @GNULIB_VASPRINTF@ +GNULIB_VDPRINTF = @GNULIB_VDPRINTF@ +GNULIB_VFPRINTF = @GNULIB_VFPRINTF@ +GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@ +GNULIB_VPRINTF = @GNULIB_VPRINTF@ +GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@ +GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@ +GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@ +GNULIB_WAITPID = @GNULIB_WAITPID@ +GNULIB_WCPCPY = @GNULIB_WCPCPY@ +GNULIB_WCPNCPY = @GNULIB_WCPNCPY@ +GNULIB_WCRTOMB = @GNULIB_WCRTOMB@ +GNULIB_WCSCASECMP = @GNULIB_WCSCASECMP@ +GNULIB_WCSCAT = @GNULIB_WCSCAT@ +GNULIB_WCSCHR = @GNULIB_WCSCHR@ +GNULIB_WCSCMP = @GNULIB_WCSCMP@ +GNULIB_WCSCOLL = @GNULIB_WCSCOLL@ +GNULIB_WCSCPY = @GNULIB_WCSCPY@ +GNULIB_WCSCSPN = @GNULIB_WCSCSPN@ +GNULIB_WCSDUP = @GNULIB_WCSDUP@ +GNULIB_WCSLEN = @GNULIB_WCSLEN@ +GNULIB_WCSNCASECMP = @GNULIB_WCSNCASECMP@ +GNULIB_WCSNCAT = @GNULIB_WCSNCAT@ +GNULIB_WCSNCMP = @GNULIB_WCSNCMP@ +GNULIB_WCSNCPY = @GNULIB_WCSNCPY@ +GNULIB_WCSNLEN = @GNULIB_WCSNLEN@ +GNULIB_WCSNRTOMBS = @GNULIB_WCSNRTOMBS@ +GNULIB_WCSPBRK = @GNULIB_WCSPBRK@ +GNULIB_WCSRCHR = @GNULIB_WCSRCHR@ +GNULIB_WCSRTOMBS = @GNULIB_WCSRTOMBS@ +GNULIB_WCSSPN = @GNULIB_WCSSPN@ +GNULIB_WCSSTR = @GNULIB_WCSSTR@ +GNULIB_WCSTOK = @GNULIB_WCSTOK@ +GNULIB_WCSWIDTH = @GNULIB_WCSWIDTH@ +GNULIB_WCSXFRM = @GNULIB_WCSXFRM@ +GNULIB_WCTOB = @GNULIB_WCTOB@ +GNULIB_WCTOMB = @GNULIB_WCTOMB@ +GNULIB_WCTRANS = @GNULIB_WCTRANS@ +GNULIB_WCTYPE = @GNULIB_WCTYPE@ +GNULIB_WCWIDTH = @GNULIB_WCWIDTH@ +GNULIB_WMEMCHR = @GNULIB_WMEMCHR@ +GNULIB_WMEMCMP = @GNULIB_WMEMCMP@ +GNULIB_WMEMCPY = @GNULIB_WMEMCPY@ +GNULIB_WMEMMOVE = @GNULIB_WMEMMOVE@ +GNULIB_WMEMSET = @GNULIB_WMEMSET@ +GNULIB_WRITE = @GNULIB_WRITE@ +GNULIB__EXIT = @GNULIB__EXIT@ +GREP = @GREP@ +HAVE_ACOSL = @HAVE_ACOSL@ +HAVE_ASINL = @HAVE_ASINL@ +HAVE_ATANL = @HAVE_ATANL@ +HAVE_ATOLL = @HAVE_ATOLL@ +HAVE_BTOWC = @HAVE_BTOWC@ +HAVE_CANONICALIZE_FILE_NAME = @HAVE_CANONICALIZE_FILE_NAME@ +HAVE_CHOWN = @HAVE_CHOWN@ +HAVE_COSL = @HAVE_COSL@ +HAVE_DECL_ACOSL = @HAVE_DECL_ACOSL@ +HAVE_DECL_ASINL = @HAVE_DECL_ASINL@ +HAVE_DECL_ATANL = @HAVE_DECL_ATANL@ +HAVE_DECL_CEILF = @HAVE_DECL_CEILF@ +HAVE_DECL_CEILL = @HAVE_DECL_CEILL@ +HAVE_DECL_COSL = @HAVE_DECL_COSL@ +HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@ +HAVE_DECL_EXPL = @HAVE_DECL_EXPL@ +HAVE_DECL_FCHDIR = @HAVE_DECL_FCHDIR@ +HAVE_DECL_FLOORF = @HAVE_DECL_FLOORF@ +HAVE_DECL_FLOORL = @HAVE_DECL_FLOORL@ +HAVE_DECL_FPURGE = @HAVE_DECL_FPURGE@ +HAVE_DECL_FREXPL = @HAVE_DECL_FREXPL@ +HAVE_DECL_FSEEKO = @HAVE_DECL_FSEEKO@ +HAVE_DECL_FTELLO = @HAVE_DECL_FTELLO@ +HAVE_DECL_GETDELIM = @HAVE_DECL_GETDELIM@ +HAVE_DECL_GETDOMAINNAME = @HAVE_DECL_GETDOMAINNAME@ +HAVE_DECL_GETLINE = @HAVE_DECL_GETLINE@ +HAVE_DECL_GETLOADAVG = @HAVE_DECL_GETLOADAVG@ +HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@ +HAVE_DECL_GETPAGESIZE = @HAVE_DECL_GETPAGESIZE@ +HAVE_DECL_GETUSERSHELL = @HAVE_DECL_GETUSERSHELL@ +HAVE_DECL_LDEXPL = @HAVE_DECL_LDEXPL@ +HAVE_DECL_LOCALTIME_R = @HAVE_DECL_LOCALTIME_R@ +HAVE_DECL_LOGB = @HAVE_DECL_LOGB@ +HAVE_DECL_LOGL = @HAVE_DECL_LOGL@ +HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@ +HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@ +HAVE_DECL_OBSTACK_PRINTF = @HAVE_DECL_OBSTACK_PRINTF@ +HAVE_DECL_ROUND = @HAVE_DECL_ROUND@ +HAVE_DECL_ROUNDF = @HAVE_DECL_ROUNDF@ +HAVE_DECL_ROUNDL = @HAVE_DECL_ROUNDL@ +HAVE_DECL_SETENV = @HAVE_DECL_SETENV@ +HAVE_DECL_SINL = @HAVE_DECL_SINL@ +HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@ +HAVE_DECL_SQRTL = @HAVE_DECL_SQRTL@ +HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@ +HAVE_DECL_STRERROR_R = @HAVE_DECL_STRERROR_R@ +HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@ +HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@ +HAVE_DECL_STRSIGNAL = @HAVE_DECL_STRSIGNAL@ +HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@ +HAVE_DECL_TANL = @HAVE_DECL_TANL@ +HAVE_DECL_TRUNC = @HAVE_DECL_TRUNC@ +HAVE_DECL_TRUNCF = @HAVE_DECL_TRUNCF@ +HAVE_DECL_TRUNCL = @HAVE_DECL_TRUNCL@ +HAVE_DECL_TTYNAME_R = @HAVE_DECL_TTYNAME_R@ +HAVE_DECL_UNSETENV = @HAVE_DECL_UNSETENV@ +HAVE_DECL_VSNPRINTF = @HAVE_DECL_VSNPRINTF@ +HAVE_DECL_WCTOB = @HAVE_DECL_WCTOB@ +HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@ +HAVE_DPRINTF = @HAVE_DPRINTF@ +HAVE_DUP2 = @HAVE_DUP2@ +HAVE_DUP3 = @HAVE_DUP3@ +HAVE_DUPLOCALE = @HAVE_DUPLOCALE@ +HAVE_EUIDACCESS = @HAVE_EUIDACCESS@ +HAVE_EXPL = @HAVE_EXPL@ +HAVE_FACCESSAT = @HAVE_FACCESSAT@ +HAVE_FCHDIR = @HAVE_FCHDIR@ +HAVE_FCHMODAT = @HAVE_FCHMODAT@ +HAVE_FCHOWNAT = @HAVE_FCHOWNAT@ +HAVE_FCNTL = @HAVE_FCNTL@ +HAVE_FEATURES_H = @HAVE_FEATURES_H@ +HAVE_FSEEKO = @HAVE_FSEEKO@ +HAVE_FSTATAT = @HAVE_FSTATAT@ +HAVE_FSYNC = @HAVE_FSYNC@ +HAVE_FTELLO = @HAVE_FTELLO@ +HAVE_FTRUNCATE = @HAVE_FTRUNCATE@ +HAVE_FUTIMENS = @HAVE_FUTIMENS@ +HAVE_GETDTABLESIZE = @HAVE_GETDTABLESIZE@ +HAVE_GETGROUPS = @HAVE_GETGROUPS@ +HAVE_GETHOSTNAME = @HAVE_GETHOSTNAME@ +HAVE_GETLOGIN = @HAVE_GETLOGIN@ +HAVE_GETOPT_H = @HAVE_GETOPT_H@ +HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@ +HAVE_GETSUBOPT = @HAVE_GETSUBOPT@ +HAVE_GETTIMEOFDAY = @HAVE_GETTIMEOFDAY@ +HAVE_GRANTPT = @HAVE_GRANTPT@ +HAVE_INTTYPES_H = @HAVE_INTTYPES_H@ +HAVE_ISNAND = @HAVE_ISNAND@ +HAVE_ISNANF = @HAVE_ISNANF@ +HAVE_ISNANL = @HAVE_ISNANL@ +HAVE_ISWBLANK = @HAVE_ISWBLANK@ +HAVE_ISWCNTRL = @HAVE_ISWCNTRL@ +HAVE_LANGINFO_CODESET = @HAVE_LANGINFO_CODESET@ +HAVE_LANGINFO_ERA = @HAVE_LANGINFO_ERA@ +HAVE_LANGINFO_H = @HAVE_LANGINFO_H@ +HAVE_LANGINFO_T_FMT_AMPM = @HAVE_LANGINFO_T_FMT_AMPM@ +HAVE_LANGINFO_YESEXPR = @HAVE_LANGINFO_YESEXPR@ +HAVE_LCHMOD = @HAVE_LCHMOD@ +HAVE_LCHOWN = @HAVE_LCHOWN@ +HAVE_LIBSIGSEGV = @HAVE_LIBSIGSEGV@ +HAVE_LINK = @HAVE_LINK@ +HAVE_LINKAT = @HAVE_LINKAT@ +HAVE_LOGL = @HAVE_LOGL@ +HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@ +HAVE_LSTAT = @HAVE_LSTAT@ +HAVE_MBRLEN = @HAVE_MBRLEN@ +HAVE_MBRTOWC = @HAVE_MBRTOWC@ +HAVE_MBSINIT = @HAVE_MBSINIT@ +HAVE_MBSLEN = @HAVE_MBSLEN@ +HAVE_MBSNRTOWCS = @HAVE_MBSNRTOWCS@ +HAVE_MBSRTOWCS = @HAVE_MBSRTOWCS@ +HAVE_MEMCHR = @HAVE_MEMCHR@ +HAVE_MEMPCPY = @HAVE_MEMPCPY@ +HAVE_MKDIRAT = @HAVE_MKDIRAT@ +HAVE_MKDTEMP = @HAVE_MKDTEMP@ +HAVE_MKFIFO = @HAVE_MKFIFO@ +HAVE_MKFIFOAT = @HAVE_MKFIFOAT@ +HAVE_MKNOD = @HAVE_MKNOD@ +HAVE_MKNODAT = @HAVE_MKNODAT@ +HAVE_MKOSTEMP = @HAVE_MKOSTEMP@ +HAVE_MKOSTEMPS = @HAVE_MKOSTEMPS@ +HAVE_MKSTEMP = @HAVE_MKSTEMP@ +HAVE_MKSTEMPS = @HAVE_MKSTEMPS@ +HAVE_NANOSLEEP = @HAVE_NANOSLEEP@ +HAVE_NL_LANGINFO = @HAVE_NL_LANGINFO@ +HAVE_OPENAT = @HAVE_OPENAT@ +HAVE_OS_H = @HAVE_OS_H@ +HAVE_PIPE = @HAVE_PIPE@ +HAVE_PIPE2 = @HAVE_PIPE2@ +HAVE_POSIX_SIGNALBLOCKING = @HAVE_POSIX_SIGNALBLOCKING@ +HAVE_POSIX_SPAWN = @HAVE_POSIX_SPAWN@ +HAVE_POSIX_SPAWNATTR_T = @HAVE_POSIX_SPAWNATTR_T@ +HAVE_POSIX_SPAWN_FILE_ACTIONS_T = @HAVE_POSIX_SPAWN_FILE_ACTIONS_T@ +HAVE_PREAD = @HAVE_PREAD@ +HAVE_PTSNAME = @HAVE_PTSNAME@ +HAVE_PWRITE = @HAVE_PWRITE@ +HAVE_RANDOM_H = @HAVE_RANDOM_H@ +HAVE_RANDOM_R = @HAVE_RANDOM_R@ +HAVE_RAWMEMCHR = @HAVE_RAWMEMCHR@ +HAVE_READLINK = @HAVE_READLINK@ +HAVE_READLINKAT = @HAVE_READLINKAT@ +HAVE_REALPATH = @HAVE_REALPATH@ +HAVE_RENAMEAT = @HAVE_RENAMEAT@ +HAVE_RPMATCH = @HAVE_RPMATCH@ +HAVE_SCHED_H = @HAVE_SCHED_H@ +HAVE_SETENV = @HAVE_SETENV@ +HAVE_SIGACTION = @HAVE_SIGACTION@ +HAVE_SIGINFO_T = @HAVE_SIGINFO_T@ +HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@ +HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@ +HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@ +HAVE_SIGSET_T = @HAVE_SIGSET_T@ +HAVE_SINL = @HAVE_SINL@ +HAVE_SLEEP = @HAVE_SLEEP@ +HAVE_SPAWN_H = @HAVE_SPAWN_H@ +HAVE_SQRTL = @HAVE_SQRTL@ +HAVE_STDINT_H = @HAVE_STDINT_H@ +HAVE_STPCPY = @HAVE_STPCPY@ +HAVE_STPNCPY = @HAVE_STPNCPY@ +HAVE_STRCASESTR = @HAVE_STRCASESTR@ +HAVE_STRCHRNUL = @HAVE_STRCHRNUL@ +HAVE_STRPBRK = @HAVE_STRPBRK@ +HAVE_STRPTIME = @HAVE_STRPTIME@ +HAVE_STRSEP = @HAVE_STRSEP@ +HAVE_STRTOD = @HAVE_STRTOD@ +HAVE_STRTOLL = @HAVE_STRTOLL@ +HAVE_STRTOULL = @HAVE_STRTOULL@ +HAVE_STRUCT_RANDOM_DATA = @HAVE_STRUCT_RANDOM_DATA@ +HAVE_STRUCT_SCHED_PARAM = @HAVE_STRUCT_SCHED_PARAM@ +HAVE_STRUCT_SIGACTION_SA_SIGACTION = @HAVE_STRUCT_SIGACTION_SA_SIGACTION@ +HAVE_STRUCT_TIMEVAL = @HAVE_STRUCT_TIMEVAL@ +HAVE_STRVERSCMP = @HAVE_STRVERSCMP@ +HAVE_SYMLINK = @HAVE_SYMLINK@ +HAVE_SYMLINKAT = @HAVE_SYMLINKAT@ +HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@ +HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@ +HAVE_SYS_LOADAVG_H = @HAVE_SYS_LOADAVG_H@ +HAVE_SYS_PARAM_H = @HAVE_SYS_PARAM_H@ +HAVE_SYS_TIME_H = @HAVE_SYS_TIME_H@ +HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@ +HAVE_TANL = @HAVE_TANL@ +HAVE_TIMEGM = @HAVE_TIMEGM@ +HAVE_TYPE_VOLATILE_SIG_ATOMIC_T = @HAVE_TYPE_VOLATILE_SIG_ATOMIC_T@ +HAVE_UNISTD_H = @HAVE_UNISTD_H@ +HAVE_UNLINKAT = @HAVE_UNLINKAT@ +HAVE_UNLOCKPT = @HAVE_UNLOCKPT@ +HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@ +HAVE_USLEEP = @HAVE_USLEEP@ +HAVE_UTIMENSAT = @HAVE_UTIMENSAT@ +HAVE_VASPRINTF = @HAVE_VASPRINTF@ +HAVE_VDPRINTF = @HAVE_VDPRINTF@ +HAVE_WCHAR_H = @HAVE_WCHAR_H@ +HAVE_WCHAR_T = @HAVE_WCHAR_T@ +HAVE_WCPCPY = @HAVE_WCPCPY@ +HAVE_WCPNCPY = @HAVE_WCPNCPY@ +HAVE_WCRTOMB = @HAVE_WCRTOMB@ +HAVE_WCSCASECMP = @HAVE_WCSCASECMP@ +HAVE_WCSCAT = @HAVE_WCSCAT@ +HAVE_WCSCHR = @HAVE_WCSCHR@ +HAVE_WCSCMP = @HAVE_WCSCMP@ +HAVE_WCSCOLL = @HAVE_WCSCOLL@ +HAVE_WCSCPY = @HAVE_WCSCPY@ +HAVE_WCSCSPN = @HAVE_WCSCSPN@ +HAVE_WCSDUP = @HAVE_WCSDUP@ +HAVE_WCSLEN = @HAVE_WCSLEN@ +HAVE_WCSNCASECMP = @HAVE_WCSNCASECMP@ +HAVE_WCSNCAT = @HAVE_WCSNCAT@ +HAVE_WCSNCMP = @HAVE_WCSNCMP@ +HAVE_WCSNCPY = @HAVE_WCSNCPY@ +HAVE_WCSNLEN = @HAVE_WCSNLEN@ +HAVE_WCSNRTOMBS = @HAVE_WCSNRTOMBS@ +HAVE_WCSPBRK = @HAVE_WCSPBRK@ +HAVE_WCSRCHR = @HAVE_WCSRCHR@ +HAVE_WCSRTOMBS = @HAVE_WCSRTOMBS@ +HAVE_WCSSPN = @HAVE_WCSSPN@ +HAVE_WCSSTR = @HAVE_WCSSTR@ +HAVE_WCSTOK = @HAVE_WCSTOK@ +HAVE_WCSWIDTH = @HAVE_WCSWIDTH@ +HAVE_WCSXFRM = @HAVE_WCSXFRM@ +HAVE_WCTRANS_T = @HAVE_WCTRANS_T@ +HAVE_WCTYPE_H = @HAVE_WCTYPE_H@ +HAVE_WCTYPE_T = @HAVE_WCTYPE_T@ +HAVE_WINT_T = @HAVE_WINT_T@ +HAVE_WMEMCHR = @HAVE_WMEMCHR@ +HAVE_WMEMCMP = @HAVE_WMEMCMP@ +HAVE_WMEMCPY = @HAVE_WMEMCPY@ +HAVE_WMEMMOVE = @HAVE_WMEMMOVE@ +HAVE_WMEMSET = @HAVE_WMEMSET@ +HAVE_XLOCALE_H = @HAVE_XLOCALE_H@ +HAVE__BOOL = @HAVE__BOOL@ +HAVE__EXIT = @HAVE__EXIT@ +INCLUDE_NEXT = @INCLUDE_NEXT@ +INCLUDE_NEXT_AS_FIRST_DIRECTIVE = @INCLUDE_NEXT_AS_FIRST_DIRECTIVE@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ +LDFLAGS = @LDFLAGS@ +LIBCSTACK = @LIBCSTACK@ +LIBINTL = @LIBINTL@ +LIBM4_LIBDEPS = @LIBM4_LIBDEPS@ +LIBM4_LTLIBDEPS = @LIBM4_LTLIBDEPS@ +LIBMULTITHREAD = @LIBMULTITHREAD@ +LIBOBJS = @LIBOBJS@ +LIBPTH = @LIBPTH@ +LIBPTH_PREFIX = @LIBPTH_PREFIX@ +LIBS = @LIBS@ +LIBSIGSEGV = @LIBSIGSEGV@ +LIBSIGSEGV_PREFIX = @LIBSIGSEGV_PREFIX@ +LIBTESTS_LIBDEPS = @LIBTESTS_LIBDEPS@ +LIBTHREAD = @LIBTHREAD@ +LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@ +LOCALE_FR = @LOCALE_FR@ +LOCALE_FR_UTF8 = @LOCALE_FR_UTF8@ +LOCALE_JA = @LOCALE_JA@ +LOCALE_TR_UTF8 = @LOCALE_TR_UTF8@ +LOCALE_ZH_CN = @LOCALE_ZH_CN@ +LTLIBCSTACK = @LTLIBCSTACK@ +LTLIBINTL = @LTLIBINTL@ +LTLIBMULTITHREAD = @LTLIBMULTITHREAD@ +LTLIBOBJS = @LTLIBOBJS@ +LTLIBPTH = @LTLIBPTH@ +LTLIBSIGSEGV = @LTLIBSIGSEGV@ +LTLIBTHREAD = @LTLIBTHREAD@ +M4_LIBOBJS = @M4_LIBOBJS@ +M4_LTLIBOBJS = @M4_LTLIBOBJS@ +M4tests_LIBOBJS = @M4tests_LIBOBJS@ +M4tests_LTLIBOBJS = @M4tests_LTLIBOBJS@ +M4tests_WITNESS = @M4tests_WITNESS@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +NEXT_AS_FIRST_DIRECTIVE_ERRNO_H = @NEXT_AS_FIRST_DIRECTIVE_ERRNO_H@ +NEXT_AS_FIRST_DIRECTIVE_FCNTL_H = @NEXT_AS_FIRST_DIRECTIVE_FCNTL_H@ +NEXT_AS_FIRST_DIRECTIVE_FLOAT_H = @NEXT_AS_FIRST_DIRECTIVE_FLOAT_H@ +NEXT_AS_FIRST_DIRECTIVE_GETOPT_H = @NEXT_AS_FIRST_DIRECTIVE_GETOPT_H@ +NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H = @NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H@ +NEXT_AS_FIRST_DIRECTIVE_LOCALE_H = @NEXT_AS_FIRST_DIRECTIVE_LOCALE_H@ +NEXT_AS_FIRST_DIRECTIVE_MATH_H = @NEXT_AS_FIRST_DIRECTIVE_MATH_H@ +NEXT_AS_FIRST_DIRECTIVE_SCHED_H = @NEXT_AS_FIRST_DIRECTIVE_SCHED_H@ +NEXT_AS_FIRST_DIRECTIVE_SIGNAL_H = @NEXT_AS_FIRST_DIRECTIVE_SIGNAL_H@ +NEXT_AS_FIRST_DIRECTIVE_SPAWN_H = @NEXT_AS_FIRST_DIRECTIVE_SPAWN_H@ +NEXT_AS_FIRST_DIRECTIVE_STDARG_H = @NEXT_AS_FIRST_DIRECTIVE_STDARG_H@ +NEXT_AS_FIRST_DIRECTIVE_STDDEF_H = @NEXT_AS_FIRST_DIRECTIVE_STDDEF_H@ +NEXT_AS_FIRST_DIRECTIVE_STDINT_H = @NEXT_AS_FIRST_DIRECTIVE_STDINT_H@ +NEXT_AS_FIRST_DIRECTIVE_STDIO_H = @NEXT_AS_FIRST_DIRECTIVE_STDIO_H@ +NEXT_AS_FIRST_DIRECTIVE_STDLIB_H = @NEXT_AS_FIRST_DIRECTIVE_STDLIB_H@ +NEXT_AS_FIRST_DIRECTIVE_STRING_H = @NEXT_AS_FIRST_DIRECTIVE_STRING_H@ +NEXT_AS_FIRST_DIRECTIVE_SYS_STAT_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_STAT_H@ +NEXT_AS_FIRST_DIRECTIVE_SYS_TIME_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TIME_H@ +NEXT_AS_FIRST_DIRECTIVE_SYS_WAIT_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_WAIT_H@ +NEXT_AS_FIRST_DIRECTIVE_TIME_H = @NEXT_AS_FIRST_DIRECTIVE_TIME_H@ +NEXT_AS_FIRST_DIRECTIVE_UNISTD_H = @NEXT_AS_FIRST_DIRECTIVE_UNISTD_H@ +NEXT_AS_FIRST_DIRECTIVE_WCHAR_H = @NEXT_AS_FIRST_DIRECTIVE_WCHAR_H@ +NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H = @NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H@ +NEXT_ERRNO_H = @NEXT_ERRNO_H@ +NEXT_FCNTL_H = @NEXT_FCNTL_H@ +NEXT_FLOAT_H = @NEXT_FLOAT_H@ +NEXT_GETOPT_H = @NEXT_GETOPT_H@ +NEXT_LANGINFO_H = @NEXT_LANGINFO_H@ +NEXT_LOCALE_H = @NEXT_LOCALE_H@ +NEXT_MATH_H = @NEXT_MATH_H@ +NEXT_SCHED_H = @NEXT_SCHED_H@ +NEXT_SIGNAL_H = @NEXT_SIGNAL_H@ +NEXT_SPAWN_H = @NEXT_SPAWN_H@ +NEXT_STDARG_H = @NEXT_STDARG_H@ +NEXT_STDDEF_H = @NEXT_STDDEF_H@ +NEXT_STDINT_H = @NEXT_STDINT_H@ +NEXT_STDIO_H = @NEXT_STDIO_H@ +NEXT_STDLIB_H = @NEXT_STDLIB_H@ +NEXT_STRING_H = @NEXT_STRING_H@ +NEXT_SYS_STAT_H = @NEXT_SYS_STAT_H@ +NEXT_SYS_TIME_H = @NEXT_SYS_TIME_H@ +NEXT_SYS_WAIT_H = @NEXT_SYS_WAIT_H@ +NEXT_TIME_H = @NEXT_TIME_H@ +NEXT_UNISTD_H = @NEXT_UNISTD_H@ +NEXT_WCHAR_H = @NEXT_WCHAR_H@ +NEXT_WCTYPE_H = @NEXT_WCTYPE_H@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PRAGMA_COLUMNS = @PRAGMA_COLUMNS@ +PRAGMA_SYSTEM_HEADER = @PRAGMA_SYSTEM_HEADER@ +PTHREAD_H_DEFINES_STRUCT_TIMESPEC = @PTHREAD_H_DEFINES_STRUCT_TIMESPEC@ +PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@ +RANLIB = @RANLIB@ +REPLACE_BTOWC = @REPLACE_BTOWC@ +REPLACE_CALLOC = @REPLACE_CALLOC@ +REPLACE_CANONICALIZE_FILE_NAME = @REPLACE_CANONICALIZE_FILE_NAME@ +REPLACE_CEIL = @REPLACE_CEIL@ +REPLACE_CEILF = @REPLACE_CEILF@ +REPLACE_CEILL = @REPLACE_CEILL@ +REPLACE_CHOWN = @REPLACE_CHOWN@ +REPLACE_CLOSE = @REPLACE_CLOSE@ +REPLACE_DPRINTF = @REPLACE_DPRINTF@ +REPLACE_DUP = @REPLACE_DUP@ +REPLACE_DUP2 = @REPLACE_DUP2@ +REPLACE_DUPLOCALE = @REPLACE_DUPLOCALE@ +REPLACE_FCHOWNAT = @REPLACE_FCHOWNAT@ +REPLACE_FCLOSE = @REPLACE_FCLOSE@ +REPLACE_FCNTL = @REPLACE_FCNTL@ +REPLACE_FFLUSH = @REPLACE_FFLUSH@ +REPLACE_FLOOR = @REPLACE_FLOOR@ +REPLACE_FLOORF = @REPLACE_FLOORF@ +REPLACE_FLOORL = @REPLACE_FLOORL@ +REPLACE_FOPEN = @REPLACE_FOPEN@ +REPLACE_FPRINTF = @REPLACE_FPRINTF@ +REPLACE_FPURGE = @REPLACE_FPURGE@ +REPLACE_FREOPEN = @REPLACE_FREOPEN@ +REPLACE_FREXP = @REPLACE_FREXP@ +REPLACE_FREXPL = @REPLACE_FREXPL@ +REPLACE_FSEEK = @REPLACE_FSEEK@ +REPLACE_FSEEKO = @REPLACE_FSEEKO@ +REPLACE_FSTAT = @REPLACE_FSTAT@ +REPLACE_FSTATAT = @REPLACE_FSTATAT@ +REPLACE_FTELL = @REPLACE_FTELL@ +REPLACE_FTELLO = @REPLACE_FTELLO@ +REPLACE_FUTIMENS = @REPLACE_FUTIMENS@ +REPLACE_GETCWD = @REPLACE_GETCWD@ +REPLACE_GETDELIM = @REPLACE_GETDELIM@ +REPLACE_GETDOMAINNAME = @REPLACE_GETDOMAINNAME@ +REPLACE_GETGROUPS = @REPLACE_GETGROUPS@ +REPLACE_GETLINE = @REPLACE_GETLINE@ +REPLACE_GETLOGIN_R = @REPLACE_GETLOGIN_R@ +REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@ +REPLACE_GETTIMEOFDAY = @REPLACE_GETTIMEOFDAY@ +REPLACE_HUGE_VAL = @REPLACE_HUGE_VAL@ +REPLACE_ISFINITE = @REPLACE_ISFINITE@ +REPLACE_ISINF = @REPLACE_ISINF@ +REPLACE_ISNAN = @REPLACE_ISNAN@ +REPLACE_ISWBLANK = @REPLACE_ISWBLANK@ +REPLACE_ISWCNTRL = @REPLACE_ISWCNTRL@ +REPLACE_LCHOWN = @REPLACE_LCHOWN@ +REPLACE_LDEXPL = @REPLACE_LDEXPL@ +REPLACE_LINK = @REPLACE_LINK@ +REPLACE_LINKAT = @REPLACE_LINKAT@ +REPLACE_LOCALTIME_R = @REPLACE_LOCALTIME_R@ +REPLACE_LSEEK = @REPLACE_LSEEK@ +REPLACE_LSTAT = @REPLACE_LSTAT@ +REPLACE_MALLOC = @REPLACE_MALLOC@ +REPLACE_MBRLEN = @REPLACE_MBRLEN@ +REPLACE_MBRTOWC = @REPLACE_MBRTOWC@ +REPLACE_MBSINIT = @REPLACE_MBSINIT@ +REPLACE_MBSNRTOWCS = @REPLACE_MBSNRTOWCS@ +REPLACE_MBSRTOWCS = @REPLACE_MBSRTOWCS@ +REPLACE_MBSTATE_T = @REPLACE_MBSTATE_T@ +REPLACE_MBTOWC = @REPLACE_MBTOWC@ +REPLACE_MEMCHR = @REPLACE_MEMCHR@ +REPLACE_MEMMEM = @REPLACE_MEMMEM@ +REPLACE_MKDIR = @REPLACE_MKDIR@ +REPLACE_MKFIFO = @REPLACE_MKFIFO@ +REPLACE_MKNOD = @REPLACE_MKNOD@ +REPLACE_MKSTEMP = @REPLACE_MKSTEMP@ +REPLACE_MKTIME = @REPLACE_MKTIME@ +REPLACE_NAN = @REPLACE_NAN@ +REPLACE_NANOSLEEP = @REPLACE_NANOSLEEP@ +REPLACE_NL_LANGINFO = @REPLACE_NL_LANGINFO@ +REPLACE_NULL = @REPLACE_NULL@ +REPLACE_OBSTACK_PRINTF = @REPLACE_OBSTACK_PRINTF@ +REPLACE_OPEN = @REPLACE_OPEN@ +REPLACE_OPENAT = @REPLACE_OPENAT@ +REPLACE_PERROR = @REPLACE_PERROR@ +REPLACE_POPEN = @REPLACE_POPEN@ +REPLACE_POSIX_SPAWN = @REPLACE_POSIX_SPAWN@ +REPLACE_PREAD = @REPLACE_PREAD@ +REPLACE_PRINTF = @REPLACE_PRINTF@ +REPLACE_PUTENV = @REPLACE_PUTENV@ +REPLACE_PWRITE = @REPLACE_PWRITE@ +REPLACE_READLINK = @REPLACE_READLINK@ +REPLACE_REALLOC = @REPLACE_REALLOC@ +REPLACE_REALPATH = @REPLACE_REALPATH@ +REPLACE_REMOVE = @REPLACE_REMOVE@ +REPLACE_RENAME = @REPLACE_RENAME@ +REPLACE_RENAMEAT = @REPLACE_RENAMEAT@ +REPLACE_RMDIR = @REPLACE_RMDIR@ +REPLACE_ROUND = @REPLACE_ROUND@ +REPLACE_ROUNDF = @REPLACE_ROUNDF@ +REPLACE_ROUNDL = @REPLACE_ROUNDL@ +REPLACE_SETENV = @REPLACE_SETENV@ +REPLACE_SETLOCALE = @REPLACE_SETLOCALE@ +REPLACE_SIGNBIT = @REPLACE_SIGNBIT@ +REPLACE_SIGNBIT_USING_GCC = @REPLACE_SIGNBIT_USING_GCC@ +REPLACE_SLEEP = @REPLACE_SLEEP@ +REPLACE_SNPRINTF = @REPLACE_SNPRINTF@ +REPLACE_SPRINTF = @REPLACE_SPRINTF@ +REPLACE_STAT = @REPLACE_STAT@ +REPLACE_STDIO_WRITE_FUNCS = @REPLACE_STDIO_WRITE_FUNCS@ +REPLACE_STPNCPY = @REPLACE_STPNCPY@ +REPLACE_STRCASESTR = @REPLACE_STRCASESTR@ +REPLACE_STRDUP = @REPLACE_STRDUP@ +REPLACE_STRERROR = @REPLACE_STRERROR@ +REPLACE_STRERROR_R = @REPLACE_STRERROR_R@ +REPLACE_STRNCAT = @REPLACE_STRNCAT@ +REPLACE_STRNDUP = @REPLACE_STRNDUP@ +REPLACE_STRNLEN = @REPLACE_STRNLEN@ +REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@ +REPLACE_STRSTR = @REPLACE_STRSTR@ +REPLACE_STRTOD = @REPLACE_STRTOD@ +REPLACE_STRTOK_R = @REPLACE_STRTOK_R@ +REPLACE_SYMLINK = @REPLACE_SYMLINK@ +REPLACE_TIMEGM = @REPLACE_TIMEGM@ +REPLACE_TMPFILE = @REPLACE_TMPFILE@ +REPLACE_TRUNC = @REPLACE_TRUNC@ +REPLACE_TRUNCF = @REPLACE_TRUNCF@ +REPLACE_TRUNCL = @REPLACE_TRUNCL@ +REPLACE_TTYNAME_R = @REPLACE_TTYNAME_R@ +REPLACE_UNLINK = @REPLACE_UNLINK@ +REPLACE_UNLINKAT = @REPLACE_UNLINKAT@ +REPLACE_UNSETENV = @REPLACE_UNSETENV@ +REPLACE_USLEEP = @REPLACE_USLEEP@ +REPLACE_UTIMENSAT = @REPLACE_UTIMENSAT@ +REPLACE_VASPRINTF = @REPLACE_VASPRINTF@ +REPLACE_VDPRINTF = @REPLACE_VDPRINTF@ +REPLACE_VFPRINTF = @REPLACE_VFPRINTF@ +REPLACE_VPRINTF = @REPLACE_VPRINTF@ +REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@ +REPLACE_VSPRINTF = @REPLACE_VSPRINTF@ +REPLACE_WCRTOMB = @REPLACE_WCRTOMB@ +REPLACE_WCSNRTOMBS = @REPLACE_WCSNRTOMBS@ +REPLACE_WCSRTOMBS = @REPLACE_WCSRTOMBS@ +REPLACE_WCSWIDTH = @REPLACE_WCSWIDTH@ +REPLACE_WCTOB = @REPLACE_WCTOB@ +REPLACE_WCTOMB = @REPLACE_WCTOMB@ +REPLACE_WCWIDTH = @REPLACE_WCWIDTH@ +REPLACE_WRITE = @REPLACE_WRITE@ +SCHED_H = @SCHED_H@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@ +SIZE_T_SUFFIX = @SIZE_T_SUFFIX@ +STDARG_H = @STDARG_H@ +STDBOOL_H = @STDBOOL_H@ +STDDEF_H = @STDDEF_H@ +STDINT_H = @STDINT_H@ +STRIP = @STRIP@ +SYS_TIME_H_DEFINES_STRUCT_TIMESPEC = @SYS_TIME_H_DEFINES_STRUCT_TIMESPEC@ +TIME_H_DEFINES_STRUCT_TIMESPEC = @TIME_H_DEFINES_STRUCT_TIMESPEC@ +UNDEFINE_STRTOK_R = @UNDEFINE_STRTOK_R@ +UNISTD_H_HAVE_WINSOCK2_H = @UNISTD_H_HAVE_WINSOCK2_H@ +UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS = @UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS@ +VERSION = @VERSION@ +WARN_CFLAGS = @WARN_CFLAGS@ +WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@ +WERROR_CFLAGS = @WERROR_CFLAGS@ +WINT_T_SUFFIX = @WINT_T_SUFFIX@ +abs_aux_dir = @abs_aux_dir@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +lispdir = @lispdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +info_TEXINFOS = m4.texinfo +m4_TEXINFOS = fdl-1.3.texi gpl-3.0.texi +man_MANS = $(srcdir)/m4.1 +EXTRA_DIST = $(man_MANS) gendocs_template +MAINTAINERCLEANFILES = $(man_MANS) gendocs_template +SUFFIXES = .1 +HELP2MAN = $(SHELL) $(top_srcdir)/build-aux/missing --run help2man +all: all-am + +.SUFFIXES: +.SUFFIXES: .1 .dvi .html .info .pdf .ps .texinfo +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +.texinfo.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texinfo.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texinfo.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texinfo.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/m4.info: m4.texinfo $(srcdir)/version.texi $(m4_TEXINFOS) +m4.dvi: m4.texinfo $(srcdir)/version.texi $(m4_TEXINFOS) +m4.pdf: m4.texinfo $(srcdir)/version.texi $(m4_TEXINFOS) +m4.html: m4.texinfo $(srcdir)/version.texi $(m4_TEXINFOS) +$(srcdir)/version.texi: $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: m4.texinfo $(top_srcdir)/configure + @(dir=.; test -f ./m4.texinfo || dir=$(srcdir); \ + set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/m4.texinfo`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp + @cmp -s vti.tmp $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi"; \ + cp vti.tmp $(srcdir)/version.texi) + -@rm -f vti.tmp + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp + +maintainer-clean-vti: + -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf m4.aux m4.cp m4.cps m4.fn m4.fns m4.ky m4.kys m4.log m4.pg m4.pgs \ + m4.tmp m4.toc m4.tp m4.tps m4.vr m4.vrs + +clean-aminfo: + -test -z "m4.dvi m4.pdf m4.ps m4.html" \ + || rm -rf m4.dvi m4.pdf m4.ps m4.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +install-man1: $(man_MANS) + @$(NORMAL_INSTALL) + test -z "$(man1dir)" || $(MKDIR_P) "$(DESTDIR)$(man1dir)" + @list=''; test -n "$(man1dir)" || exit 0; \ + { for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.1[a-z]*$$/p'; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \ + done; } + +uninstall-man1: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man1dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.1[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + test -z "$$files" || { \ + echo " ( cd '$(DESTDIR)$(man1dir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(man1dir)" && rm -f $$files; } +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @list='$(MANS)'; if test -n "$$list"; then \ + list=`for p in $$list; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + if test -f "$$d$$p"; then echo "$$d$$p"; else :; fi; done`; \ + if test -n "$$list" && \ + grep 'ab help2man is required to generate this page' $$list >/dev/null; then \ + echo "error: found man pages containing the \`missing help2man' replacement text:" >&2; \ + grep -l 'ab help2man is required to generate this page' $$list | sed 's/^/ /' >&2; \ + echo " to fix them, install help2man, remove and regenerate the man pages;" >&2; \ + echo " typically \`make maintainer-clean' will remove them" >&2; \ + exit 1; \ + else :; fi; \ + else :; fi + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) $(MANS) +installdirs: + for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) +clean: clean-am + +clean-am: clean-aminfo clean-generic mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am install-man + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d$$p"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: install-man1 + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-man uninstall-pdf-am uninstall-ps-am + +uninstall-man: uninstall-man1 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + dist-info distclean distclean-generic distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-man1 install-pdf \ + install-pdf-am install-ps install-ps-am install-strip \ + installcheck installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti mostlyclean mostlyclean-aminfo \ + mostlyclean-generic mostlyclean-vti pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-dvi-am uninstall-html-am \ + uninstall-info-am uninstall-man uninstall-man1 \ + uninstall-pdf-am uninstall-ps-am + + +# Depend on ../.version for version, m4.c for usage text. Do not depend on +# built m4 executable, since not everyone has help2man or perl. +# Build the man page once in the srcdir, rather than in every VPATH build +# dir, to match how automake builds info pages. This is safe for 'make +# distcheck' since it is distributed pre-built. +$(srcdir)/m4.1: $(top_srcdir)/.version $(top_srcdir)/src/m4.c + @if test -x ../src/m4$(EXEEXT) ; then \ + echo "Updating man page m4.1" ; \ + $(HELP2MAN) --name="macro processor" --source='$(PACKAGE_STRING)' \ + --info-page=m4 --output=$@ ../src/m4$(EXEEXT) ; \ + else \ + echo "WARNING: The \`man' page \`$@' cannot be updated yet."; \ + echo " Retry once the program executable is ready."; \ + fi + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/fdl-1.3.texi b/doc/fdl-1.3.texi new file mode 100644 index 0000000..fc19ddd --- /dev/null +++ b/doc/fdl-1.3.texi @@ -0,0 +1,506 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, La@TeX{} input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/doc/gendocs_template b/doc/gendocs_template new file mode 100644 index 0000000..ccce0be --- /dev/null +++ b/doc/gendocs_template @@ -0,0 +1,96 @@ +<!--#include virtual="/server/header.html" --> +<title>%%TITLE%% - GNU Project - Free Software Foundation (FSF)</title> +<!--#include virtual="/server/banner.html" --> +<h2>%%TITLE%%</h2> + +<!-- This document is in XML, and xhtml 1.0 --> +<!-- Please make sure to properly nest your tags --> +<!-- and ensure that your final document validates --> +<!-- consistent with W3C xhtml 1.0 and CSS standards --> +<!-- See validator.w3.org --> + +<address>Free Software Foundation</address> +<address>last updated %%DATE%%</address> + +<p>This manual (%%PACKAGE%%) is available in the following formats:</p> + +<ul> +<li><a href="%%PACKAGE%%.html">HTML + (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li> +<li><a href="html_node/index.html">HTML</a> - with one web page per + node.</li> +%%IF HTML_SECTION%% +<li><a href="html_section/index.html">HTML</a> - with one web page per + section.</li> +%%ENDIF HTML_SECTION%% +%%IF HTML_CHAPTER%% +<li><a href="html_chapter/index.html">HTML</a> - with one web page per + chapter.</li> +%%ENDIF HTML_CHAPTER%% +<li><a href="%%PACKAGE%%.html.gz">HTML compressed + (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on + one web page.</li> +<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed + (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per node.</li> +%%IF HTML_SECTION%% +<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed + (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per section.</li> +%%ENDIF HTML_SECTION%% +%%IF HTML_CHAPTER%% +<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed + (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> - + with one web page per chapter.</li> +%%ENDIF HTML_CHAPTER%% +<li><a href="%%PACKAGE%%.info.tar.gz">Info document + (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li> +<li><a href="%%PACKAGE%%.txt">ASCII text + (%%ASCII_SIZE%%K bytes)</a>.</li> +<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed + (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li> +<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file + (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li> +<li><a href="%%PACKAGE%%.ps.gz">PostScript file + (%%PS_GZ_SIZE%%K bytes gzipped)</a>.</li> +<li><a href="%%PACKAGE%%.pdf">PDF file + (%%PDF_SIZE%%K bytes)</a>.</li> +<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source + (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li> +</ul> + +<p>You can <a href="http://shop.fsf.org/">buy printed copies of +some manuals</a> (among other items) from the Free Software Foundation; +this helps support FSF activities.</p> + +<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%% +script</a>.)</p> + +<!-- If needed, change the copyright block at the bottom. In general, --> +<!-- all pages on the GNU web server should have the section about --> +<!-- verbatim copying. Please do NOT remove this without talking --> +<!-- with the webmasters first. --> +<!-- Please make sure the copyright date is consistent with the document --> +<!-- and that it is like this "2001, 2002" not this "2001-2002." --> +</div><!-- for id="content", starts in the include above --> +<!--#include virtual="/server/footer.html" --> +<div id="footer"> + +<p> +Please send FSF & GNU inquiries to +<a href="mailto:gnu@gnu.org"><gnu@gnu.org></a>. +There are also <a href="/contact/">other ways to contact</a> +the FSF.<br /> +Please send broken links and other corrections or suggestions to +<a href="mailto:%%EMAIL%%"><%%EMAIL%%></a>. +</p> + +<p>Copyright © 2010 Free Software Foundation, Inc.</p> + +<p>Verbatim copying and distribution of this entire article is +permitted in any medium, provided this notice is preserved.</p> + +</div> +</div> +</body> +</html> diff --git a/doc/gpl-3.0.texi b/doc/gpl-3.0.texi new file mode 100644 index 0000000..97a17e1 --- /dev/null +++ b/doc/gpl-3.0.texi @@ -0,0 +1,717 @@ +@c The GNU General Public License. +@center Version 3, 29 June 2007 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +@end display + +@heading Preamble + +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom +to share and change all versions of a program---to make sure it remains +free software for all its users. We, the Free Software Foundation, +use the GNU General Public License for most of our software; it +applies also to any other work released this way by its authors. You +can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, +receive or can get the source code. And you must show them these +terms so they know their rights. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the GPL, as needed to protect the +freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +@heading TERMS AND CONDITIONS + +@enumerate 0 +@item Definitions. + +``This License'' refers to version 3 of the GNU General Public License. + +``Copyright'' also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. + +``The Program'' refers to any copyrightable work licensed under this +License. Each licensee is addressed as ``you''. ``Licensees'' and +``recipients'' may be individuals or organizations. + +To ``modify'' a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a ``modified version'' of +the earlier work or a work ``based on'' the earlier work. + +A ``covered work'' means either the unmodified Program or a work based +on the Program. + +To ``propagate'' a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To ``convey'' a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. + +An interactive user interface displays ``Appropriate Legal Notices'' to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +@item Source Code. + +The ``source code'' for a work means the preferred form of the work for +making modifications to it. ``Object code'' means any non-source form +of a work. + +A ``Standard Interface'' means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The ``System Libraries'' of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +``Major Component'', in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The ``Corresponding Source'' for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +@item Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + +@item Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. + +@item Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +@item Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: + +@enumerate a +@item +The work must carry prominent notices stating that you modified it, +and giving a relevant date. + +@item +The work must carry prominent notices stating that it is released +under this License and any conditions added under section 7. This +requirement modifies the requirement in section 4 to ``keep intact all +notices''. + +@item +You must license the entire work, as a whole, under this License to +anyone who comes into possession of a copy. This License will +therefore apply, along with any applicable section 7 additional terms, +to the whole of the work, and all its parts, regardless of how they +are packaged. This License gives no permission to license the work in +any other way, but it does not invalidate such permission if you have +separately received it. + +@item +If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive +interfaces that do not display Appropriate Legal Notices, your work +need not make them do so. +@end enumerate + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +``aggregate'' if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +@item Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +@enumerate a +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the +Corresponding Source fixed on a durable physical medium customarily +used for software interchange. + +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a written +offer, valid for at least three years and valid for as long as you +offer spare parts or customer support for that product model, to give +anyone who possesses the object code either (1) a copy of the +Corresponding Source for all the software in the product that is +covered by this License, on a durable physical medium customarily used +for software interchange, for a price no more than your reasonable +cost of physically performing this conveying of source, or (2) access +to copy the Corresponding Source from a network server at no charge. + +@item +Convey individual copies of the object code with a copy of the written +offer to provide the Corresponding Source. This alternative is +allowed only occasionally and noncommercially, and only if you +received the object code with such an offer, in accord with subsection +6b. + +@item +Convey the object code by offering access from a designated place +(gratis or for a charge), and offer equivalent access to the +Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the +Corresponding Source along with the object code. If the place to copy +the object code is a network server, the Corresponding Source may be +on a different server (operated by you or a third party) that supports +equivalent copying facilities, provided you maintain clear directions +next to the object code saying where to find the Corresponding Source. +Regardless of what server hosts the Corresponding Source, you remain +obligated to ensure that it is available for as long as needed to +satisfy these requirements. + +@item +Convey the object code using peer-to-peer transmission, provided you +inform other peers where the object code and Corresponding Source of +the work are being offered to the general public at no charge under +subsection 6d. + +@end enumerate + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A ``User Product'' is either (1) a ``consumer product'', which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +``normally used'' refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. + +``Installation Information'' for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +@item Additional Terms. + +``Additional permissions'' are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +@enumerate a +@item +Disclaiming warranty or limiting liability differently from the terms +of sections 15 and 16 of this License; or + +@item +Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices +displayed by works containing it; or + +@item +Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in +reasonable ways as different from the original version; or + +@item +Limiting the use for publicity purposes of names of licensors or +authors of the material; or + +@item +Declining to grant rights under trademark law for use of some trade +names, trademarks, or service marks; or + +@item +Requiring indemnification of licensors and authors of that material by +anyone who conveys the material (or modified versions of it) with +contractual assumptions of liability to the recipient, for any +liability that these contractual assumptions directly impose on those +licensors and authors. +@end enumerate + +All other non-permissive additional terms are considered ``further +restrictions'' within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. + +@item Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +@item Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +@item Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An ``entity transaction'' is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +@item Patents. + +A ``contributor'' is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's ``contributor version''. + +A contributor's ``essential patent claims'' are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, ``control'' includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a ``patent license'' is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To ``grant'' such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. ``Knowingly relying'' means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is ``discriminatory'' if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +@item No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey +a covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree +to terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. + +@item Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +@item Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions +of the GNU General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If +the Program does not specify a version number of the GNU General +Public License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +@item Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +@item Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR +LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM +TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER +PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +@item Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +@end enumerate + +@heading END OF TERMS AND CONDITIONS + +@heading How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) @var{year} @var{name of author} + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or (at +your option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see @url{http://www.gnu.org/licenses/}. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + +@smallexample +@var{program} Copyright (C) @var{year} @var{name of author} +This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. +This is free software, and you are welcome to redistribute it +under certain conditions; type @samp{show c} for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an ``about box''. + +You should also get your employer (if you work as a programmer) or school, +if any, to sign a ``copyright disclaimer'' for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +@url{http://www.gnu.org/licenses/}. + +The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use +the GNU Lesser General Public License instead of this License. But +first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/m4.1 b/doc/m4.1 new file mode 100644 index 0000000..63fbd8e --- /dev/null +++ b/doc/m4.1 @@ -0,0 +1,151 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.38.2. +.TH M4 "1" "March 2011" "GNU M4 1.4.16" "User Commands" +.SH NAME +m4 \- macro processor +.SH SYNOPSIS +.B m4 +[\fIOPTION\fR]... [\fIFILE\fR]... +.SH DESCRIPTION +Process macros in FILEs. If no FILE or if FILE is `\-', standard input +is read. +.PP +Mandatory or optional arguments to long options are mandatory or optional +for short options too. +.SS "Operation modes:" +.TP +\fB\-\-help\fR +display this help and exit +.TP +\fB\-\-version\fR +output version information and exit +.TP +\fB\-E\fR, \fB\-\-fatal\-warnings\fR +once: warnings become errors, twice: stop +execution at first error +.TP +\fB\-i\fR, \fB\-\-interactive\fR +unbuffer output, ignore interrupts +.TP +\fB\-P\fR, \fB\-\-prefix\-builtins\fR +force a `m4_' prefix to all builtins +.TP +\fB\-Q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR +suppress some warnings for builtins +.TP +\fB\-\-warn\-macro\-sequence\fR[=\fIREGEXP\fR] +warn if macro definition matches REGEXP, +.IP +default \e$\e({[^}]*}\e|[0\-9][0\-9]+\e) +.SS "Preprocessor features:" +.TP +\fB\-D\fR, \fB\-\-define=NAME\fR[=\fIVALUE\fR] +define NAME as having VALUE, or empty +.TP +\fB\-I\fR, \fB\-\-include\fR=\fIDIRECTORY\fR +append DIRECTORY to include path +.TP +\fB\-s\fR, \fB\-\-synclines\fR +generate `#line NUM "FILE"' lines +.TP +\fB\-U\fR, \fB\-\-undefine\fR=\fINAME\fR +undefine NAME +.SS "Limits control:" +.TP +\fB\-g\fR, \fB\-\-gnu\fR +override \fB\-G\fR to re\-enable GNU extensions +.TP +\fB\-G\fR, \fB\-\-traditional\fR +suppress all GNU extensions +.TP +\fB\-H\fR, \fB\-\-hashsize\fR=\fIPRIME\fR +set symbol lookup hash table size [509] +.TP +\fB\-L\fR, \fB\-\-nesting\-limit\fR=\fINUMBER\fR +change nesting limit, 0 for unlimited [0] +.SS "Frozen state files:" +.TP +\fB\-F\fR, \fB\-\-freeze\-state\fR=\fIFILE\fR +produce a frozen state on FILE at end +.TP +\fB\-R\fR, \fB\-\-reload\-state\fR=\fIFILE\fR +reload a frozen state from FILE at start +.SS "Debugging:" +.TP +\fB\-d\fR, \fB\-\-debug\fR[=\fIFLAGS\fR] +set debug level (no FLAGS implies `aeq') +.TP +\fB\-\-debugfile\fR[=\fIFILE\fR] +redirect debug and trace output to FILE +(default stderr, discard if empty string) +.TP +\fB\-l\fR, \fB\-\-arglength\fR=\fINUM\fR +restrict macro tracing size +.TP +\fB\-t\fR, \fB\-\-trace\fR=\fINAME\fR +trace NAME when it is defined +.SS "FLAGS is any of:" +.TP +a +show actual arguments +.TP +c +show before collect, after collect and after call +.TP +e +show expansion +.TP +f +say current input file name +.TP +i +show changes in input files +.TP +l +say current input line number +.TP +p +show results of path searches +.TP +q +quote values as necessary, with a or e flag +.TP +t +trace for all macro calls, not only traceon'ed +.TP +x +add a unique macro call id, useful with c flag +.TP +V +shorthand for all of the above flags +.PP +If defined, the environment variable `M4PATH' is a colon\-separated list +of directories included after any specified by `\-I'. +.PP +Exit status is 0 for success, 1 for failure, 63 for frozen file version +mismatch, or whatever value was passed to the m4exit macro. +.SH AUTHOR +Written by Rene' Seindal. +.SH "REPORTING BUGS" +Report bugs to: bug\-m4@gnu.org +.br +GNU M4 home page: <http://www.gnu.org/software/m4/> +.br +General help using GNU software: <http://www.gnu.org/gethelp/> +.SH COPYRIGHT +Copyright \(co 2011 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.SH "SEE ALSO" +The full documentation for +.B m4 +is maintained as a Texinfo manual. If the +.B info +and +.B m4 +programs are properly installed at your site, the command +.IP +.B info m4 +.PP +should give you access to the complete manual. diff --git a/doc/m4.info b/doc/m4.info new file mode 100644 index 0000000..8c81aa7 --- /dev/null +++ b/doc/m4.info @@ -0,0 +1,134 @@ +This is m4.info, produced by makeinfo version 4.13 from m4.texinfo. + +This manual (28 February 2011) is for GNU M4 (version 1.4.16), a +package containing an implementation of the m4 macro language. + + Copyright (C) 1989-1994, 2004-2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License." + +INFO-DIR-SECTION Text creation and manipulation +START-INFO-DIR-ENTRY +* M4: (m4). A powerful macro processor. +END-INFO-DIR-ENTRY + + +Indirect: +m4.info-1: 817 +m4.info-2: 300465 + +Tag Table: +(Indirect) +Node: Top817 +Node: Preliminaries9625 +Node: Intro10311 +Node: History11943 +Node: Bugs14789 +Node: Manual16040 +Node: Invoking m419438 +Node: Operation modes21584 +Node: Preprocessor features24556 +Node: Limits control27653 +Node: Frozen state31555 +Node: Debugging options32354 +Node: Command line files34338 +Node: Syntax35911 +Node: Names37030 +Node: Quoted strings37492 +Node: Comments38141 +Node: Other tokens39018 +Node: Input processing39596 +Ref: Input processing-Footnote-147517 +Node: Macros47712 +Node: Invocation48206 +Node: Inhibiting Invocation49007 +Node: Macro Arguments53138 +Node: Quoting Arguments56200 +Node: Macro expansion58323 +Node: Definitions59024 +Node: Define59809 +Node: Arguments62247 +Node: Pseudo Arguments65919 +Node: Undefine69461 +Node: Defn70591 +Node: Pushdef75041 +Node: Indir77667 +Node: Builtin79795 +Node: Conditionals82021 +Node: Ifdef82963 +Node: Ifelse83826 +Node: Shift87144 +Node: Forloop97693 +Node: Foreach100329 +Node: Stacks105817 +Node: Composition108856 +Node: Debugging114796 +Node: Dumpdef115381 +Node: Trace116791 +Node: Debug Levels120364 +Node: Debug Output125068 +Node: Input Control126352 +Node: Dnl126889 +Node: Changequote128790 +Node: Changecom134887 +Node: Changeword138583 +Node: M4wrap144024 +Node: File Inclusion148020 +Node: Include148337 +Node: Search Path151048 +Node: Diversions151965 +Node: Divert153648 +Node: Undivert156174 +Node: Divnum159497 +Node: Cleardivert159961 +Node: Text handling161166 +Node: Len161889 +Node: Index macro162274 +Node: Regexp163147 +Node: Substr165686 +Node: Translit166737 +Node: Patsubst169459 +Node: Format173985 +Node: Arithmetic177178 +Node: Incr177627 +Node: Eval178402 +Node: Shell commands186365 +Node: Platform macros187287 +Node: Syscmd189402 +Node: Esyscmd191682 +Node: Sysval193191 +Node: Mkstemp194873 +Node: Miscellaneous198828 +Node: Errprint199261 +Node: Location200480 +Node: M4exit203254 +Node: Frozen files205341 +Node: Using frozen files206122 +Node: Frozen file format209386 +Node: Compatibility212450 +Node: Extensions213516 +Node: Incompatibilities217383 +Node: Other Incompatibilities226309 +Node: Answers228955 +Node: Improved exch229737 +Node: Improved forloop230275 +Node: Improved foreach235607 +Node: Improved copy248624 +Node: Improved m4wrap252578 +Node: Improved cleardivert255002 +Node: Improved capitalize255983 +Node: Improved fatal_error260846 +Node: Copying This Package261907 +Node: GNU General Public License262386 +Node: Copying This Manual299945 +Node: GNU Free Documentation License300465 +Node: Indices325596 +Node: Macro index325876 +Node: Concept index332113 + +End Tag Table diff --git a/doc/m4.info-1 b/doc/m4.info-1 new file mode 100644 index 0000000..e1a6138 --- /dev/null +++ b/doc/m4.info-1 @@ -0,0 +1,7858 @@ +This is m4.info, produced by makeinfo version 4.13 from m4.texinfo. + +This manual (28 February 2011) is for GNU M4 (version 1.4.16), a +package containing an implementation of the m4 macro language. + + Copyright (C) 1989-1994, 2004-2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License." + +INFO-DIR-SECTION Text creation and manipulation +START-INFO-DIR-ENTRY +* M4: (m4). A powerful macro processor. +END-INFO-DIR-ENTRY + + +File: m4.info, Node: Top, Next: Preliminaries, Up: (dir) + +GNU M4 +****** + +This manual (28 February 2011) is for GNU M4 (version 1.4.16), a +package containing an implementation of the m4 macro language. + + Copyright (C) 1989-1994, 2004-2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License." + + GNU `m4' is an implementation of the traditional UNIX macro +processor. It is mostly SVR4 compatible, although it has some +extensions (for example, handling more than 9 positional parameters to +macros). `m4' also has builtin functions for including files, running +shell commands, doing arithmetic, etc. Autoconf needs GNU `m4' for +generating `configure' scripts, but not for running them. + + GNU `m4' was originally written by Rene' Seindal, with subsequent +changes by Franc,ois Pinard and other volunteers on the Internet. All +names and email addresses can be found in the files `m4-1.4.16/AUTHORS' +and `m4-1.4.16/THANKS' from the GNU M4 distribution. + + This is release 1.4.16. It is now considered stable: future +releases in the 1.4.x series are only meant to fix bugs, increase speed, +or improve documentation. However... + + An experimental feature, which would improve `m4' usefulness, allows +for changing the syntax for what is a "word" in `m4'. You should use: + ./configure --enable-changeword + if you want this feature compiled in. The current implementation +slows down `m4' considerably and is hardly acceptable. In the future, +`m4' 2.0 will come with a different set of new features that provide +similar capabilities, but without the inefficiencies, so changeword +will go away and _you should not count on it_. + +* Menu: + +* Preliminaries:: Introduction and preliminaries +* Invoking m4:: Invoking `m4' +* Syntax:: Lexical and syntactic conventions + +* Macros:: How to invoke macros +* Definitions:: How to define new macros +* Conditionals:: Conditionals, loops, and recursion + +* Debugging:: How to debug macros and input + +* Input Control:: Input control +* File Inclusion:: File inclusion +* Diversions:: Diverting and undiverting output + +* Text handling:: Macros for text handling +* Arithmetic:: Macros for doing arithmetic +* Shell commands:: Macros for running shell commands +* Miscellaneous:: Miscellaneous builtin macros +* Frozen files:: Fast loading of frozen state + +* Compatibility:: Compatibility with other versions of `m4' +* Answers:: Correct version of some examples + +* Copying This Package:: How to make copies of the overall M4 package +* Copying This Manual:: How to make copies of this manual +* Indices:: Indices of concepts and macros + + --- The Detailed Node Listing --- + +Introduction and preliminaries + +* Intro:: Introduction to `m4' +* History:: Historical references +* Bugs:: Problems and bugs +* Manual:: Using this manual + +Invoking `m4' + +* Operation modes:: Command line options for operation modes +* Preprocessor features:: Command line options for preprocessor features +* Limits control:: Command line options for limits control +* Frozen state:: Command line options for frozen state +* Debugging options:: Command line options for debugging +* Command line files:: Specifying input files on the command line + +Lexical and syntactic conventions + +* Names:: Macro names +* Quoted strings:: Quoting input to `m4' +* Comments:: Comments in `m4' input +* Other tokens:: Other kinds of input tokens +* Input processing:: How `m4' copies input to output + +How to invoke macros + +* Invocation:: Macro invocation +* Inhibiting Invocation:: Preventing macro invocation +* Macro Arguments:: Macro arguments +* Quoting Arguments:: On Quoting Arguments to macros +* Macro expansion:: Expanding macros + +How to define new macros + +* Define:: Defining a new macro +* Arguments:: Arguments to macros +* Pseudo Arguments:: Special arguments to macros +* Undefine:: Deleting a macro +* Defn:: Renaming macros +* Pushdef:: Temporarily redefining macros + +* Indir:: Indirect call of macros +* Builtin:: Indirect call of builtins + +Conditionals, loops, and recursion + +* Ifdef:: Testing if a macro is defined +* Ifelse:: If-else construct, or multibranch +* Shift:: Recursion in `m4' +* Forloop:: Iteration by counting +* Foreach:: Iteration by list contents +* Stacks:: Working with definition stacks +* Composition:: Building macros with macros + +How to debug macros and input + +* Dumpdef:: Displaying macro definitions +* Trace:: Tracing macro calls +* Debug Levels:: Controlling debugging output +* Debug Output:: Saving debugging output + +Input control + +* Dnl:: Deleting whitespace in input +* Changequote:: Changing the quote characters +* Changecom:: Changing the comment delimiters +* Changeword:: Changing the lexical structure of words +* M4wrap:: Saving text until end of input + +File inclusion + +* Include:: Including named files +* Search Path:: Searching for include files + +Diverting and undiverting output + +* Divert:: Diverting output +* Undivert:: Undiverting output +* Divnum:: Diversion numbers +* Cleardivert:: Discarding diverted text + +Macros for text handling + +* Len:: Calculating length of strings +* Index macro:: Searching for substrings +* Regexp:: Searching for regular expressions +* Substr:: Extracting substrings +* Translit:: Translating characters +* Patsubst:: Substituting text by regular expression +* Format:: Formatting strings (printf-like) + +Macros for doing arithmetic + +* Incr:: Decrement and increment operators +* Eval:: Evaluating integer expressions + +Macros for running shell commands + +* Platform macros:: Determining the platform +* Syscmd:: Executing simple commands +* Esyscmd:: Reading the output of commands +* Sysval:: Exit status +* Mkstemp:: Making temporary files + +Miscellaneous builtin macros + +* Errprint:: Printing error messages +* Location:: Printing current location +* M4exit:: Exiting from `m4' + +Fast loading of frozen state + +* Using frozen files:: Using frozen files +* Frozen file format:: Frozen file format + +Compatibility with other versions of `m4' + +* Extensions:: Extensions in GNU M4 +* Incompatibilities:: Facilities in System V m4 not in GNU M4 +* Other Incompatibilities:: Other incompatibilities + +Correct version of some examples + +* Improved exch:: Solution for `exch' +* Improved forloop:: Solution for `forloop' +* Improved foreach:: Solution for `foreach' +* Improved copy:: Solution for `copy' +* Improved m4wrap:: Solution for `m4wrap' +* Improved cleardivert:: Solution for `cleardivert' +* Improved capitalize:: Solution for `capitalize' +* Improved fatal_error:: Solution for `fatal_error' + +How to make copies of the overall M4 package + +* GNU General Public License:: License for copying the M4 package + +How to make copies of this manual + +* GNU Free Documentation License:: License for copying this manual + +Indices of concepts and macros + +* Macro index:: Index for all `m4' macros +* Concept index:: Index for many concepts + + +File: m4.info, Node: Preliminaries, Next: Invoking m4, Prev: Top, Up: Top + +1 Introduction and preliminaries +******************************** + +This first chapter explains what GNU `m4' is, where `m4' comes from, +how to read and use this documentation, how to call the `m4' program, +and how to report bugs about it. It concludes by giving tips for +reading the remainder of the manual. + + The following chapters then detail all the features of the `m4' +language. + +* Menu: + +* Intro:: Introduction to `m4' +* History:: Historical references +* Bugs:: Problems and bugs +* Manual:: Using this manual + + +File: m4.info, Node: Intro, Next: History, Up: Preliminaries + +1.1 Introduction to `m4' +======================== + +`m4' is a macro processor, in the sense that it copies its input to the +output, expanding macros as it goes. Macros are either builtin or +user-defined, and can take any number of arguments. Besides just doing +macro expansion, `m4' has builtin functions for including named files, +running shell commands, doing integer arithmetic, manipulating text in +various ways, performing recursion, etc.... `m4' can be used either as +a front-end to a compiler, or as a macro processor in its own right. + + The `m4' macro processor is widely available on all UNIXes, and has +been standardized by POSIX. Usually, only a small percentage of users +are aware of its existence. However, those who find it often become +committed users. The popularity of GNU Autoconf, which requires GNU +`m4' for _generating_ `configure' scripts, is an incentive for many to +install it, while these people will not themselves program in `m4'. +GNU `m4' is mostly compatible with the System V, Release 3 version, +except for some minor differences. *Note Compatibility::, for more +details. + + Some people find `m4' to be fairly addictive. They first use `m4' +for simple problems, then take bigger and bigger challenges, learning +how to write complex sets of `m4' macros along the way. Once really +addicted, users pursue writing of sophisticated `m4' applications even +to solve simple problems, devoting more time debugging their `m4' +scripts than doing real work. Beware that `m4' may be dangerous for +the health of compulsive programmers. + + +File: m4.info, Node: History, Next: Bugs, Prev: Intro, Up: Preliminaries + +1.2 Historical references +========================= + +`GPM' was an important ancestor of `m4'. See C. Strachey: "A General +Purpose Macro generator", Computer Journal 8,3 (1965), pp. 225 ff. +`GPM' is also succinctly described into David Gries classic "Compiler +Construction for Digital Computers". + + The classic B. Kernighan and P.J. Plauger: "Software Tools", +Addison-Wesley, Inc. (1976) describes and implements a Unix +macro-processor language, which inspired Dennis Ritchie to write `m3', +a macro processor for the AP-3 minicomputer. + + Kernighan and Ritchie then joined forces to develop the original +`m4', as described in "The M4 Macro Processor", Bell Laboratories +(1977). It had only 21 builtin macros. + + While `GPM' was more _pure_, `m4' is meant to deal with the true +intricacies of real life: macros can be recognized without being +pre-announced, skipping whitespace or end-of-lines is easier, more +constructs are builtin instead of derived, etc. + + Originally, the Kernighan and Plauger macro-processor, and then +`m3', formed the engine for the Rational FORTRAN preprocessor, that is, +the `Ratfor' equivalent of `cpp'. Later, `m4' was used as a front-end +for `Ratfor', `C' and `Cobol'. + + Rene' Seindal released his implementation of `m4', GNU `m4', in +1990, with the aim of removing the artificial limitations in many of +the traditional `m4' implementations, such as maximum line length, +macro size, or number of macros. + + The late Professor A. Dain Samples described and implemented a +further evolution in the form of `M5': "User's Guide to the M5 Macro +Language: 2nd edition", Electronic Announcement on comp.compilers +newsgroup (1992). + + Franc,ois Pinard took over maintenance of GNU `m4' in 1992, until +1994 when he released GNU `m4' 1.4, which was the stable release for 10 +years. It was at this time that GNU Autoconf decided to require GNU +`m4' as its underlying engine, since all other implementations of `m4' +had too many limitations. + + More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which +addressed some long standing bugs in the venerable 1.4 release. Then in +2005, Gary V. Vaughan collected together the many patches to GNU `m4' +1.4 that were floating around the net and released 1.4.3 and 1.4.4. +And in 2006, Eric Blake joined the team and prepared patches for the +release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8. More bug fixes were +incorporated in 2007, with releases 1.4.9 and 1.4.10. Eric continued +with some portability fixes for 1.4.11 and 1.4.12 in 2008, 1.4.13 in +2009, 1.4.14 and 1.4.15 in 2010, and 1.4.16 in 2011. + + Meanwhile, development has continued on new features for `m4', such +as dynamic module loading and additional builtins. When complete, GNU +`m4' 2.0 will start a new series of releases. + + +File: m4.info, Node: Bugs, Next: Manual, Prev: History, Up: Preliminaries + +1.3 Problems and bugs +===================== + +If you have problems with GNU M4 or think you've found a bug, please +report it. Before reporting a bug, make sure you've actually found a +real bug. Carefully reread the documentation and see if it really says +you can do what you're trying to do. If it's not clear whether you +should be able to do something or not, report that too; it's a bug in +the documentation! + + Before reporting a bug or trying to fix it yourself, try to isolate +it to the smallest possible input file that reproduces the problem. +Then send us the input file and the exact results `m4' gave you. Also +say what you expected to occur; this will help us decide whether the +problem was really in the documentation. + + Once you've got a precise problem, send e-mail to <bug-m4@gnu.org>. +Please include the version number of `m4' you are using. You can get +this information with the command `m4 --version'. Also provide details +about the platform you are executing on. + + Non-bug suggestions are always welcome as well. If you have +questions about things that are unclear in the documentation or are +just obscure features, please report them too. + + +File: m4.info, Node: Manual, Prev: Bugs, Up: Preliminaries + +1.4 Using this manual +===================== + +This manual contains a number of examples of `m4' input and output, and +a simple notation is used to distinguish input, output and error +messages from `m4'. Examples are set out from the normal text, and +shown in a fixed width font, like this + + This is an example of an example! + + To distinguish input from output, all output from `m4' is prefixed +by the string `=>', and all error messages by the string `error-->'. +When showing how command line options affect matters, the command line +is shown with a prompt `$ like this', otherwise, you can assume that a +simple `m4' invocation will work. Thus: + + $ command line to invoke m4 + Example of input line + =>Output line from m4 + error-->and an error message + + The sequence `^D' in an example indicates the end of the input file. +The sequence `<NL>' refers to the newline character. The majority of +these examples are self-contained, and you can run them with similar +results by invoking `m4 -d'. In fact, the testsuite that is bundled in +the GNU M4 package consists of the examples in this document! Some of +the examples assume that your current directory is located where you +unpacked the installation, so if you plan on following along, you may +find it helpful to do this now: + + $ cd m4-1.4.16 + + As each of the predefined macros in `m4' is described, a prototype +call of the macro will be shown, giving descriptive names to the +arguments, e.g., + + -- Composite: example (STRING, [COUNT = `1'], [ARGUMENT]...) + This is a sample prototype. There is not really a macro named + `example', but this documents that if there were, it would be a + Composite macro, rather than a Builtin. It requires at least one + argument, STRING. Remember that in `m4', there must not be a + space between the macro name and the opening parenthesis, unless + it was intended to call the macro without any arguments. The + brackets around COUNT and ARGUMENT show that these arguments are + optional. If COUNT is omitted, the macro behaves as if count were + `1', whereas if ARGUMENT is omitted, the macro behaves as if it + were the empty string. A blank argument is not the same as an + omitted argument. For example, `example(`a')', `example(`a',`1')', + and `example(`a',`1',)' would behave identically with COUNT set to + `1'; while `example(`a',)' and `example(`a',`')' would explicitly + pass the empty string for COUNT. The ellipses (`...') show that + the macro processes additional arguments after ARGUMENT, rather + than ignoring them. + + All macro arguments in `m4' are strings, but some are given special +interpretation, e.g., as numbers, file names, regular expressions, etc. +The documentation for each macro will state how the parameters are +interpreted, and what happens if the argument cannot be parsed +according to the desired interpretation. Unless specified otherwise, a +parameter specified to be a number is parsed as a decimal, even if the +argument has leading zeros; and parsing the empty string as a number +results in 0 rather than an error, although a warning will be issued. + + This document consistently writes and uses "builtin", without a +hyphen, as if it were an English word. This is how the `builtin' +primitive is spelled within `m4'. + + +File: m4.info, Node: Invoking m4, Next: Syntax, Prev: Preliminaries, Up: Top + +2 Invoking `m4' +*************** + +The format of the `m4' command is: + + `m4' [OPTION...] [FILE...] + + All options begin with `-', or if long option names are used, with +`--'. A long option name need not be written completely, any +unambiguous prefix is sufficient. POSIX requires `m4' to recognize +arguments intermixed with files, even when `POSIXLY_CORRECT' is set in +the environment. Most options take effect at startup regardless of +their position, but some are documented below as taking effect after +any files that occurred earlier in the command line. The argument `--' +is a marker to denote the end of options. + + With short options, options that do not take arguments may be +combined into a single command line argument with subsequent options, +options with mandatory arguments may be provided either as a single +command line argument or as two arguments, and options with optional +arguments must be provided as a single argument. In other words, `m4 +-QPDfoo -d a -df' is equivalent to `m4 -Q -P -D foo -d -df -- ./a', +although the latter form is considered canonical. + + With long options, options with mandatory arguments may be provided +with an equal sign (`=') in a single argument, or as two arguments, and +options with optional arguments must be provided as a single argument. +In other words, `m4 --def foo --debug a' is equivalent to `m4 +--define=foo --debug= -- ./a', although the latter form is considered +canonical (not to mention more robust, in case a future version of `m4' +introduces an option named `--default'). + + `m4' understands the following options, grouped by functionality. + +* Menu: + +* Operation modes:: Command line options for operation modes +* Preprocessor features:: Command line options for preprocessor features +* Limits control:: Command line options for limits control +* Frozen state:: Command line options for frozen state +* Debugging options:: Command line options for debugging +* Command line files:: Specifying input files on the command line + + +File: m4.info, Node: Operation modes, Next: Preprocessor features, Up: Invoking m4 + +2.1 Command line options for operation modes +============================================ + +Several options control the overall operation of `m4': + +`--help' + Print a help summary on standard output, then immediately exit + `m4' without reading any input files or performing any other + actions. + +`--version' + Print the version number of the program on standard output, then + immediately exit `m4' without reading any input files or + performing any other actions. + +`-E' +`--fatal-warnings' + Controls the effect of warnings. If unspecified, then execution + continues and exit status is unaffected when a warning is printed. + If specified exactly once, warnings become fatal; when one is + issued, execution continues, but the exit status will be non-zero. + If specified multiple times, then execution halts with non-zero + status the first time a warning is issued. The introduction of + behavior levels is new to M4 1.4.9; for behavior consistent with + earlier versions, you should specify `-E' twice. + +`-i' +`--interactive' +`-e' + Makes this invocation of `m4' interactive. This means that all + output will be unbuffered, and interrupts will be ignored. The + spelling `-e' exists for compatibility with other `m4' + implementations, and issues a warning because it may be withdrawn + in a future version of GNU M4. + +`-P' +`--prefix-builtins' + Internally modify _all_ builtin macro names so they all start with + the prefix `m4_'. For example, using this option, one should write + `m4_define' instead of `define', and `m4___file__' instead of + `__file__'. This option has no effect if `-R' is also specified. + +`-Q' +`--quiet' +`--silent' + Suppress warnings, such as missing or superfluous arguments in + macro calls, or treating the empty string as zero. + +`--warn-macro-sequence[=REGEXP]' + Issue a warning if the regular expression REGEXP has a non-empty + match in any macro definition (either by `define' or `pushdef'). + Empty matches are ignored; therefore, supplying the empty string + as REGEXP disables any warning. If the optional REGEXP is not + supplied, then the default regular expression is + `\$\({[^}]*}\|[0-9][0-9]+\)' (a literal `$' followed by multiple + digits or by an open brace), since these sequences will change + semantics in the default operation of GNU M4 2.0 (due to a change + in how more than 9 arguments in a macro definition will be + handled, *note Arguments::). Providing an alternate regular + expression can provide a useful reverse lookup feature of finding + where a macro is defined to have a given definition. + +`-W REGEXP' +`--word-regexp=REGEXP' + Use REGEXP as an alternative syntax for macro names. This + experimental option will not be present in all GNU `m4' + implementations (*note Changeword::). + + +File: m4.info, Node: Preprocessor features, Next: Limits control, Prev: Operation modes, Up: Invoking m4 + +2.2 Command line options for preprocessor features +================================================== + +Several options allow `m4' to behave more like a preprocessor. Macro +definitions and deletions can be made on the command line, the search +path can be altered, and the output file can track where the input came +from. These features occur with the following options: + +`-D NAME[=VALUE]' +`--define=NAME[=VALUE]' + This enters NAME into the symbol table. If `=VALUE' is missing, + the value is taken to be the empty string. The VALUE can be any + string, and the macro can be defined to take arguments, just as if + it was defined from within the input. This option may be given + more than once; order with respect to file names is significant, + and redefining the same NAME loses the previous value. + +`-I DIRECTORY' +`--include=DIRECTORY' + Make `m4' search DIRECTORY for included files that are not found + in the current working directory. *Note Search Path::, for more + details. This option may be given more than once. + +`-s' +`--synclines' + Generate synchronization lines, for use by the C preprocessor or + other similar tools. Order is significant with respect to file + names. This option is useful, for example, when `m4' is used as a + front end to a compiler. Source file name and line number + information is conveyed by directives of the form `#line LINENUM + "FILE"', which are inserted as needed into the middle of the + output. Such directives mean that the following line originated + or was expanded from the contents of input file FILE at line + LINENUM. The `"FILE"' part is often omitted when the file name + did not change from the previous directive. + + Synchronization directives are always given on complete lines by + themselves. When a synchronization discrepancy occurs in the + middle of an output line, the associated synchronization directive + is delayed until the next newline that does not occur in the + middle of a quoted string or comment. + + define(`twoline', `1 + 2') + =>#line 2 "stdin" + => + changecom(`/*', `*/') + => + define(`comment', `/*1 + 2*/') + =>#line 5 + => + dnl no line + hello + =>#line 7 + =>hello + twoline + =>1 + =>#line 8 + =>2 + comment + =>/*1 + =>2*/ + one comment `two + three' + =>#line 10 + =>one /*1 + =>2*/ two + =>three + goodbye + =>#line 12 + =>goodbye + +`-U NAME' +`--undefine=NAME' + This deletes any predefined meaning NAME might have. Obviously, + only predefined macros can be deleted in this way. This option + may be given more than once; undefining a NAME that does not have a + definition is silently ignored. Order is significant with respect + to file names. + + +File: m4.info, Node: Limits control, Next: Frozen state, Prev: Preprocessor features, Up: Invoking m4 + +2.3 Command line options for limits control +=========================================== + +There are some limits within `m4' that can be tuned. For +compatibility, `m4' also accepts some options that control limits in +other implementations, but which are automatically unbounded (limited +only by your hardware and operating system constraints) in GNU `m4'. + +`-g' +`--gnu' + Enable all the extensions in this implementation. In this release + of M4, this option is always on by default; it is currently only + useful when overriding a prior use of `--traditional'. However, + having GNU behavior as default makes it impossible to write a + strictly POSIX-compliant client that avoids all incompatible GNU + M4 extensions, since such a client would have to use the non-POSIX + command-line option to force full POSIX behavior. Thus, a future + version of M4 will be changed to implicitly use the option + `--traditional' if the environment variable `POSIXLY_CORRECT' is + set. Projects that intentionally use GNU extensions should + consider using `--gnu' to state their intentions, so that the + project will not mysteriously break if the user upgrades to a + newer M4 and has `POSIXLY_CORRECT' set in their environment. + +`-G' +`--traditional' + Suppress all the extensions made in this implementation, compared + to the System V version. *Note Compatibility::, for a list of + these. + +`-H NUM' +`--hashsize=NUM' + Make the internal hash table for symbol lookup be NUM entries big. + For better performance, the number should be prime, but this is not + checked. The default is 509 entries. It should not be necessary + to increase this value, unless you define an excessive number of + macros. + +`-L NUM' +`--nesting-limit=NUM' + Artificially limit the nesting of macro calls to NUM levels, + stopping program execution if this limit is ever exceeded. When + not specified, nesting defaults to unlimited on platforms that can + detect stack overflow, and to 1024 levels otherwise. A value of + zero means unlimited; but then heavily nested code could + potentially cause a stack overflow. + + The precise effect of this option is more correctly associated + with textual nesting than dynamic recursion. It has been useful + when some complex `m4' input was generated by mechanical means, and + also in diagnosing recursive algorithms that do not scale well. + Most users never need to change this option from its default. + + This option does _not_ have the ability to break endless + rescanning loops, since these do not necessarily consume much + memory or stack space. Through clever usage of rescanning loops, + one can request complex, time-consuming computations from `m4' + with useful results. Putting limitations in this area would break + `m4' power. There are many pathological cases: + `define(`a', `a')a' is only the simplest example (but *note + Compatibility::). Expecting GNU `m4' to detect these would be a + little like expecting a compiler system to detect and diagnose + endless loops: it is a quite _hard_ problem in general, if not + undecidable! + +`-B NUM' +`-S NUM' +`-T NUM' + These options are present for compatibility with System V `m4', but + do nothing in this implementation. They may disappear in future + releases, and issue a warning to that effect. + +`-N NUM' +`--diversions=NUM' + These options are present only for compatibility with previous + versions of GNU `m4', and were controlling the number of possible + diversions which could be used at the same time. They do nothing, + because there is no fixed limit anymore. They may disappear in + future releases, and issue a warning to that effect. + + +File: m4.info, Node: Frozen state, Next: Debugging options, Prev: Limits control, Up: Invoking m4 + +2.4 Command line options for frozen state +========================================= + +GNU `m4' comes with a feature of freezing internal state (*note Frozen +files::). This can be used to speed up `m4' execution when reusing a +common initialization script. + +`-F FILE' +`--freeze-state=FILE' + Once execution is finished, write out the frozen state on the + specified FILE. It is conventional, but not required, for FILE to + end in `.m4f'. + +`-R FILE' +`--reload-state=FILE' + Before execution starts, recover the internal state from the + specified frozen FILE. The options `-D', `-U', and `-t' take + effect after state is reloaded, but before the input files are + read. + + +File: m4.info, Node: Debugging options, Next: Command line files, Prev: Frozen state, Up: Invoking m4 + +2.5 Command line options for debugging +====================================== + +Finally, there are several options for aiding in debugging `m4' scripts. + +`-d[FLAGS]' +`--debug[=FLAGS]' + Set the debug-level according to the flags FLAGS. The debug-level + controls the format and amount of information presented by the + debugging functions. *Note Debug Levels::, for more details on + the format and meaning of FLAGS. If omitted, FLAGS defaults to + `aeq'. + +`--debugfile[=FILE]' +`-o FILE' +`--error-output=FILE' + Redirect `dumpdef' output, debug messages, and trace output to the + named FILE. Warnings, error messages, and `errprint' output are + still printed to standard error. If these options are not used, or + if FILE is unspecified (only possible for `--debugfile'), debug + output goes to standard error; if FILE is the empty string, debug + output is discarded. *Note Debug Output::, for more details. The + option `--debugfile' may be given more than once, and order is + significant with respect to file names. The spellings `-o' and + `--error-output' are misleading and inconsistent with other GNU + tools; for now they are silently accepted as synonyms of + `--debugfile' and only recognized once, but in a future version of + M4, using them will cause a warning to be issued. + +`-l NUM' +`--arglength=NUM' + Restrict the size of the output generated by macro tracing to NUM + characters per trace line. If unspecified or zero, output is + unlimited. *Note Debug Levels::, for more details. + +`-t NAME' +`--trace=NAME' + This enables tracing for the macro NAME, at any point where it is + defined. NAME need not be defined when this option is given. + This option may be given more than once, and order is significant + with respect to file names. *Note Trace::, for more details. + + +File: m4.info, Node: Command line files, Prev: Debugging options, Up: Invoking m4 + +2.6 Specifying input files on the command line +============================================== + +The remaining arguments on the command line are taken to be input file +names. If no names are present, standard input is read. A file name +of `-' is taken to mean standard input. It is conventional, but not +required, for input files to end in `.m4'. + + The input files are read in the sequence given. Standard input can +be read more than once, so the file name `-' may appear multiple times +on the command line; this makes a difference when input is from a +terminal or other special file type. It is an error if an input file +ends in the middle of argument collection, a comment, or a quoted +string. + + The options `--define' (`-D'), `--undefine' (`-U'), `--synclines' +(`-s'), and `--trace' (`-t') only take effect after processing input +from any file names that occur earlier on the command line. For +example, assume the file `foo' contains: + + $ cat foo + bar + + The text `bar' can then be redefined over multiple uses of `foo': + + $ m4 -Dbar=hello foo -Dbar=world foo + =>hello + =>world + + If none of the input files invoked `m4exit' (*note M4exit::), the +exit status of `m4' will be 0 for success, 1 for general failure (such +as problems with reading an input file), and 63 for version mismatch +(*note Using frozen files::). + + If you need to read a file whose name starts with a `-', you can +specify it as `./-file', or use `--' to mark the end of options. + + +File: m4.info, Node: Syntax, Next: Macros, Prev: Invoking m4, Up: Top + +3 Lexical and syntactic conventions +*********************************** + +As `m4' reads its input, it separates it into "tokens". A token is +either a name, a quoted string, or any single character, that is not a +part of either a name or a string. Input to `m4' can also contain +comments. GNU `m4' does not yet understand multibyte locales; all +operations are byte-oriented rather than character-oriented (although +if your locale uses a single byte encoding, such as ISO-8859-1, you +will not notice a difference). However, `m4' is eight-bit clean, so +you can use non-ASCII characters in quoted strings (*note +Changequote::), comments (*note Changecom::), and macro names (*note +Indir::), with the exception of the NUL character (the zero byte +`'\0''). + +* Menu: + +* Names:: Macro names +* Quoted strings:: Quoting input to `m4' +* Comments:: Comments in `m4' input +* Other tokens:: Other kinds of input tokens +* Input processing:: How `m4' copies input to output + + +File: m4.info, Node: Names, Next: Quoted strings, Up: Syntax + +3.1 Macro names +=============== + +A name is any sequence of letters, digits, and the character `_' +(underscore), where the first character is not a digit. `m4' will use +the longest such sequence found in the input. If a name has a macro +definition, it will be subject to macro expansion (*note Macros::). +Names are case-sensitive. + + Examples of legal names are: `foo', `_tmp', and `name01'. + + +File: m4.info, Node: Quoted strings, Next: Comments, Prev: Names, Up: Syntax + +3.2 Quoting input to `m4' +========================= + +A quoted string is a sequence of characters surrounded by quote +strings, defaulting to ``' and `'', where the nested begin and end +quotes within the string are balanced. The value of a string token is +the text, with one level of quotes stripped off. Thus + + `' + => + +is the empty string, and double-quoting turns into single-quoting. + + ``quoted'' + =>`quoted' + + The quote characters can be changed at any time, using the builtin +macro `changequote'. *Note Changequote::, for more information. + + +File: m4.info, Node: Comments, Next: Other tokens, Prev: Quoted strings, Up: Syntax + +3.3 Comments in `m4' input +========================== + +Comments in `m4' are normally delimited by the characters `#' and +newline. All characters between the comment delimiters are ignored, +but the entire comment (including the delimiters) is passed through to +the output--comments are _not_ discarded by `m4'. + + Comments cannot be nested, so the first newline after a `#' ends the +comment. The commenting effect of the begin-comment string can be +inhibited by quoting it. + + $ m4 + `quoted text' # `commented text' + =>quoted text # `commented text' + `quoting inhibits' `#' `comments' + =>quoting inhibits # comments + + The comment delimiters can be changed to any string at any time, +using the builtin macro `changecom'. *Note Changecom::, for more +information. + + +File: m4.info, Node: Other tokens, Next: Input processing, Prev: Comments, Up: Syntax + +3.4 Other kinds of input tokens +=============================== + +Any character, that is neither a part of a name, nor of a quoted string, +nor a comment, is a token by itself. When not in the context of macro +expansion, all of these tokens are just copied to output. However, +during macro expansion, whitespace characters (space, tab, newline, +formfeed, carriage return, vertical tab), parentheses (`(' and `)'), +comma (`,'), and dollar (`$') have additional roles, explained later. + + +File: m4.info, Node: Input processing, Prev: Other tokens, Up: Syntax + +3.5 How `m4' copies input to output +=================================== + +As `m4' reads the input token by token, it will copy each token +directly to the output immediately. + + The exception is when it finds a word with a macro definition. In +that case `m4' will calculate the macro's expansion, possibly reading +more input to get the arguments. It then inserts the expansion in front +of the remaining input. In other words, the resulting text from a macro +call will be read and parsed into tokens again. + + `m4' expands a macro as soon as possible. If it finds a macro call +when collecting the arguments to another, it will expand the second call +first. This process continues until there are no more macro calls to +expand and all the input has been consumed. + + For a running example, examine how `m4' handles this input: + + format(`Result is %d', eval(`2**15')) + +First, `m4' sees that the token `format' is a macro name, so it +collects the tokens `(', ``Result is %d'', `,', and ` ', before +encountering another potential macro. Sure enough, `eval' is a macro +name, so the nested argument collection picks up `(', ``2**15'', and +`)', invoking the eval macro with the lone argument of `2**15'. The +expansion of `eval(2**15)' is `32768', which is then rescanned as the +five tokens `3', `2', `7', `6', and `8'; and combined with the next +`)', the format macro now has all its arguments, as if the user had +typed: + + format(`Result is %d', 32768) + +The format macro expands to `Result is 32768', and we have another +round of scanning for the tokens `Result', ` ', `is', ` ', `3', `2', +`7', `6', and `8'. None of these are macros, so the final output is + + =>Result is 32768 + + As a more complicated example, we will contrast an actual code +example from the Gnulib project(1), showing both a buggy approach and +the desired results. The user desires to output a shell assignment +statement that takes its argument and turns it into a shell variable by +converting it to uppercase and prepending a prefix. The original +attempt looks like this: + + changequote([,])dnl + define([gl_STRING_MODULE_INDICATOR], + [ + dnl comment + GNULIB_]translit([$1],[a-z],[A-Z])[=1 + ])dnl + gl_STRING_MODULE_INDICATOR([strcase]) + => + => GNULIB_strcase=1 + => + + Oops - the argument did not get capitalized. And although the manual +is not able to easily show it, both lines that appear empty actually +contain two trailing spaces. By stepping through the parse, it is easy +to see what happened. First, `m4' sees the token `changequote', which +it recognizes as a macro, followed by `(', `[', `,', `]', and `)' to +form the argument list. The macro expands to the empty string, but +changes the quoting characters to something more useful for generating +shell code (unbalanced ``' and `'' appear all the time in shell scripts, +but unbalanced `[]' tend to be rare). Also in the first line, `m4' +sees the token `dnl', which it recognizes as a builtin macro that +consumes the rest of the line, resulting in no output for that line. + + The second line starts a macro definition. `m4' sees the token +`define', which it recognizes as a macro, followed by a `(', +`[gl_STRING_MODULE_INDICATOR]', and `,'. Because an unquoted comma was +encountered, the first argument is known to be the expansion of the +single-quoted string token, or `gl_STRING_MODULE_INDICATOR'. Next, +`m4' sees `<NL>', ` ', and ` ', but this whitespace is discarded as +part of argument collection. Then comes a rather lengthy single-quoted +string token, `[<NL> dnl comment<NL> GNULIB_]'. This is followed +by the token `translit', which `m4' recognizes as a macro name, so a +nested macro expansion has started. + + The arguments to the `translit' are found by the tokens `(', `[$1]', +`,', `[a-z]', `,', `[A-Z]', and finally `)'. All three string +arguments are expanded (or in other words, the quotes are stripped), +and since neither `$' nor `1' need capitalization, the result of the +macro is `$1'. This expansion is rescanned, resulting in the two +literal characters `$' and `1'. + + Scanning of the outer macro resumes, and picks up with `[=1<NL> ]', +and finally `)'. The collected pieces of expanded text are +concatenated, with the end result that the macro +`gl_STRING_MODULE_INDICATOR' is now defined to be the sequence `<NL> +dnl comment<NL> GNULIB_$1=1<NL> '. Once again, `dnl' is recognized +and avoids a newline in the output. + + The final line is then parsed, beginning with ` ' and ` ' that are +output literally. Then `gl_STRING_MODULE_INDICATOR' is recognized as a +macro name, with an argument list of `(', `[strcase]', and `)'. Since +the definition of the macro contains the sequence `$1', that sequence +is replaced with the argument `strcase' prior to starting the rescan. +The rescan sees `<NL>' and four spaces, which are output literally, then +`dnl', which discards the text ` comment<NL>'. Next comes four more +spaces, also output literally, and the token `GNULIB_strcase', which +resulted from the earlier parameter substitution. Since that is not a +macro name, it is output literally, followed by the literal tokens `=', +`1', `<NL>', and two more spaces. Finally, the original `<NL>' seen +after the macro invocation is scanned and output literally. + + Now for a corrected approach. This rearranges the use of newlines +and whitespace so that less whitespace is output (which, although +harmless to shell scripts, can be visually unappealing), and fixes the +quoting issues so that the capitalization occurs when the macro +`gl_STRING_MODULE_INDICATOR' is invoked, rather then when it is +defined. It also adds another layer of quoting to the first argument of +`translit', to ensure that the output will be rescanned as a string +rather than a potential uppercase macro name needing further expansion. + + changequote([,])dnl + define([gl_STRING_MODULE_INDICATOR], + [dnl comment + GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl + ])dnl + gl_STRING_MODULE_INDICATOR([strcase]) + => GNULIB_STRCASE=1 + + The parsing of the first line is unchanged. The second line sees the +name of the macro to define, then sees the discarded `<NL>' and two +spaces, as before. But this time, the next token is `[dnl comment<NL> +GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl<NL>]', which includes +nested quotes, followed by `)' to end the macro definition and `dnl' to +skip the newline. No early expansion of `translit' occurs, so the +entire string becomes the definition of the macro. + + The final line is then parsed, beginning with two spaces that are +output literally, and an invocation of `gl_STRING_MODULE_INDICATOR' +with the argument `strcase'. Again, the `$1' in the macro definition +is substituted prior to rescanning. Rescanning first encounters `dnl', +and discards ` comment<NL>'. Then two spaces are output literally. +Next comes the token `GNULIB_', but that is not a macro, so it is +output literally. The token `[]' is an empty string, so it does not +affect output. Then the token `translit' is encountered. + + This time, the arguments to `translit' are parsed as `(', +`[[strcase]]', `,', ` ', `[a-z]', `,', ` ', `[A-Z]', and `)'. The two +spaces are discarded, and the translit results in the desired result +`[STRCASE]'. This is rescanned, but since it is a string, the quotes +are stripped and the only output is a literal `STRCASE'. Then the +scanner sees `=' and `1', which are output literally, followed by `dnl' +which discards the rest of the definition of +`gl_STRING_MODULE_INDICATOR'. The newline at the end of output is the +literal `<NL>' that appeared after the invocation of the macro. + + The order in which `m4' expands the macros can be further explored +using the trace facilities of GNU `m4' (*note Trace::). + + ---------- Footnotes ---------- + + (1) Derived from a patch in +`http://lists.gnu.org/archive/html/bug-gnulib/2007-01/msg00389.html', +and a followup patch in +`http://lists.gnu.org/archive/html/bug-gnulib/2007-02/msg00000.html' + + +File: m4.info, Node: Macros, Next: Definitions, Prev: Syntax, Up: Top + +4 How to invoke macros +********************** + +This chapter covers macro invocation, macro arguments and how macro +expansion is treated. + +* Menu: + +* Invocation:: Macro invocation +* Inhibiting Invocation:: Preventing macro invocation +* Macro Arguments:: Macro arguments +* Quoting Arguments:: On Quoting Arguments to macros +* Macro expansion:: Expanding macros + + +File: m4.info, Node: Invocation, Next: Inhibiting Invocation, Up: Macros + +4.1 Macro invocation +==================== + +Macro invocations has one of the forms + + name + +which is a macro invocation without any arguments, or + + name(arg1, arg2, ..., argN) + +which is a macro invocation with N arguments. Macros can have any +number of arguments. All arguments are strings, but different macros +might interpret the arguments in different ways. + + The opening parenthesis _must_ follow the NAME directly, with no +spaces in between. If it does not, the macro is called with no +arguments at all. + + For a macro call to have no arguments, the parentheses _must_ be +left out. The macro call + + name() + +is a macro call with one argument, which is the empty string, not a call +with no arguments. + + +File: m4.info, Node: Inhibiting Invocation, Next: Macro Arguments, Prev: Invocation, Up: Macros + +4.2 Preventing macro invocation +=============================== + +An innovation of the `m4' language, compared to some of its +predecessors (like Strachey's `GPM', for example), is the ability to +recognize macro calls without resorting to any special, prefixed +invocation character. While generally useful, this feature might +sometimes be the source of spurious, unwanted macro calls. So, GNU +`m4' offers several mechanisms or techniques for inhibiting the +recognition of names as macro calls. + + First of all, many builtin macros cannot meaningfully be called +without arguments. As a GNU extension, for any of these macros, +whenever an opening parenthesis does not immediately follow their name, +the builtin macro call is not triggered. This solves the most usual +cases, like for `include' or `eval'. Later in this document, the +sentence "This macro is recognized only with parameters" refers to this +specific provision of GNU M4, also known as a blind builtin macro. For +the builtins defined by POSIX that bear this disclaimer, POSIX +specifically states that invoking those builtins without arguments is +unspecified, because many other implementations simply invoke the +builtin as though it were given one empty argument instead. + + $ m4 + eval + =>eval + eval(`1') + =>1 + + There is also a command line option (`--prefix-builtins', or `-P', +*note Invoking m4: Operation modes.) that renames all builtin macros +with a prefix of `m4_' at startup. The option has no effect whatsoever +on user defined macros. For example, with this option, one has to +write `m4_dnl' and even `m4_m4exit'. It also has no effect on whether +a macro requires parameters. + + $ m4 -P + eval + =>eval + eval(`1') + =>eval(1) + m4_eval + =>m4_eval + m4_eval(`1') + =>1 + + Another alternative is to redefine problematic macros to a name less +likely to cause conflicts, *Note Definitions::. + + If your version of GNU `m4' has the `changeword' feature compiled +in, it offers far more flexibility in specifying the syntax of macro +names, both builtin or user-defined. *Note Changeword::, for more +information on this experimental feature. + + Of course, the simplest way to prevent a name from being interpreted +as a call to an existing macro is to quote it. The remainder of this +section studies a little more deeply how quoting affects macro +invocation, and how quoting can be used to inhibit macro invocation. + + Even if quoting is usually done over the whole macro name, it can +also be done over only a few characters of this name (provided, of +course, that the unquoted portions are not also a macro). It is also +possible to quote the empty string, but this works only _inside_ the +name. For example: + + `divert' + =>divert + `d'ivert + =>divert + di`ver't + =>divert + div`'ert + =>divert + +all yield the string `divert'. While in both: + + `'divert + => + divert`' + => + +the `divert' builtin macro will be called, which expands to the empty +string. + + The output of macro evaluations is always rescanned. In the +following example, the input `x`'y' yields the string `bCD', exactly as +if `m4' has been given `substr(ab`'cde, `1', `3')' as input: + + define(`cde', `CDE') + => + define(`x', `substr(ab') + => + define(`y', `cde, `1', `3')') + => + x`'y + =>bCD + + Unquoted strings on either side of a quoted string are subject to +being recognized as macro names. In the following example, quoting the +empty string allows for the second `macro' to be recognized as such: + + define(`macro', `m') + => + macro(`m')macro + =>mmacro + macro(`m')`'macro + =>mm + + Quoting may prevent recognizing as a macro name the concatenation of +a macro expansion with the surrounding characters. In this example: + + define(`macro', `di$1') + => + macro(`v')`ert' + =>divert + macro(`v')ert + => + +the input will produce the string `divert'. When the quotes were +removed, the `divert' builtin was called instead. + + +File: m4.info, Node: Macro Arguments, Next: Quoting Arguments, Prev: Inhibiting Invocation, Up: Macros + +4.3 Macro arguments +=================== + +When a name is seen, and it has a macro definition, it will be expanded +as a macro. + + If the name is followed by an opening parenthesis, the arguments +will be collected before the macro is called. If too few arguments are +supplied, the missing arguments are taken to be the empty string. +However, some builtins are documented to behave differently for a +missing optional argument than for an explicit empty string. If there +are too many arguments, the excess arguments are ignored. Unquoted +leading whitespace is stripped off all arguments, but whitespace +generated by a macro expansion or occurring after a macro that expanded +to an empty string remains intact. Whitespace includes space, tab, +newline, carriage return, vertical tab, and formfeed. + + define(`macro', `$1') + => + macro( unquoted leading space lost) + =>unquoted leading space lost + macro(` quoted leading space kept') + => quoted leading space kept + macro( + divert `unquoted space kept after expansion') + => unquoted space kept after expansion + macro(macro(` + ')`whitespace from expansion kept') + => + =>whitespace from expansion kept + macro(`unquoted trailing whitespace kept' + ) + =>unquoted trailing whitespace kept + => + + Normally `m4' will issue warnings if a builtin macro is called with +an inappropriate number of arguments, but it can be suppressed with the +`--quiet' command line option (or `--silent', or `-Q', *note Invoking +m4: Operation modes.). For user defined macros, there is no check of +the number of arguments given. + + $ m4 + index(`abc') + error-->m4:stdin:1: Warning: too few arguments to builtin `index' + =>0 + index(`abc',) + =>0 + index(`abc', `b', `ignored') + error-->m4:stdin:3: Warning: excess arguments to builtin `index' ignored + =>1 + + $ m4 -Q + index(`abc') + =>0 + index(`abc',) + =>0 + index(`abc', `b', `ignored') + =>1 + + Macros are expanded normally during argument collection, and whatever +commas, quotes and parentheses that might show up in the resulting +expanded text will serve to define the arguments as well. Thus, if FOO +expands to `, b, c', the macro call + + bar(a foo, d) + +is a macro call with four arguments, which are `a ', `b', `c' and `d'. +To understand why the first argument contains whitespace, remember that +unquoted leading whitespace is never part of an argument, but trailing +whitespace always is. + + It is possible for a macro's definition to change during argument +collection, in which case the expansion uses the definition that was in +effect at the time the opening `(' was seen. + + define(`f', `1') + => + f(define(`f', `2')) + =>1 + f + =>2 + + It is an error if the end of file occurs while collecting arguments. + + hello world + =>hello world + define( + ^D + error-->m4:stdin:2: ERROR: end of file in argument list + + +File: m4.info, Node: Quoting Arguments, Next: Macro expansion, Prev: Macro Arguments, Up: Macros + +4.4 On Quoting Arguments to macros +================================== + +Each argument has unquoted leading whitespace removed. Within each +argument, all unquoted parentheses must match. For example, if FOO is +a macro, + + foo(() (`(') `(') + +is a macro call, with one argument, whose value is `() (() ('. Commas +separate arguments, except when they occur inside quotes, comments, or +unquoted parentheses. *Note Pseudo Arguments::, for examples. + + It is common practice to quote all arguments to macros, unless you +are sure you want the arguments expanded. Thus, in the above example +with the parentheses, the `right' way to do it is like this: + + foo(`() (() (') + + It is, however, in certain cases necessary (because nested expansion +must occur to create the arguments for the outer macro) or convenient +(because it uses fewer characters) to leave out quotes for some +arguments, and there is nothing wrong in doing it. It just makes life a +bit harder, if you are not careful to follow a consistent quoting style. +For consistency, this manual follows the rule of thumb that each layer +of parentheses introduces another layer of single quoting, except when +showing the consequences of quoting rules. This is done even when the +quoted string cannot be a macro, such as with integers when you have not +changed the syntax via `changeword' (*note Changeword::). + + The quoting rule of thumb of one level of quoting per parentheses +has a nice property: when a macro name appears inside parentheses, you +can determine when it will be expanded. If it is not quoted, it will be +expanded prior to the outer macro, so that its expansion becomes the +argument. If it is single-quoted, it will be expanded after the outer +macro. And if it is double-quoted, it will be used as literal text +instead of a macro name. + + define(`active', `ACT, IVE') + => + define(`show', `$1 $1') + => + show(active) + =>ACT ACT + show(`active') + =>ACT, IVE ACT, IVE + show(``active'') + =>active active + + +File: m4.info, Node: Macro expansion, Prev: Quoting Arguments, Up: Macros + +4.5 Macro expansion +=================== + +When the arguments, if any, to a macro call have been collected, the +macro is expanded, and the expansion text is pushed back onto the input +(unquoted), and reread. The expansion text from one macro call might +therefore result in more macros being called, if the calls are included, +completely or partially, in the first macro calls' expansion. + + Taking a very simple example, if FOO expands to `bar', and BAR +expands to `Hello', the input + + $ m4 -Dbar=Hello -Dfoo=bar + foo + =>Hello + +will expand first to `bar', and when this is reread and expanded, into +`Hello'. + + +File: m4.info, Node: Definitions, Next: Conditionals, Prev: Macros, Up: Top + +5 How to define new macros +************************** + +Macros can be defined, redefined and deleted in several different ways. +Also, it is possible to redefine a macro without losing a previous +value, and bring back the original value at a later time. + +* Menu: + +* Define:: Defining a new macro +* Arguments:: Arguments to macros +* Pseudo Arguments:: Special arguments to macros +* Undefine:: Deleting a macro +* Defn:: Renaming macros +* Pushdef:: Temporarily redefining macros + +* Indir:: Indirect call of macros +* Builtin:: Indirect call of builtins + + +File: m4.info, Node: Define, Next: Arguments, Up: Definitions + +5.1 Defining a macro +==================== + +The normal way to define or redefine macros is to use the builtin +`define': + + -- Builtin: define (NAME, [EXPANSION]) + Defines NAME to expand to EXPANSION. If EXPANSION is not given, + it is taken to be empty. + + The expansion of `define' is void. The macro `define' is + recognized only with parameters. + + The following example defines the macro FOO to expand to the text +`Hello World.'. + + define(`foo', `Hello world.') + => + foo + =>Hello world. + + The empty line in the output is there because the newline is not a +part of the macro definition, and it is consequently copied to the +output. This can be avoided by use of the macro `dnl'. *Note Dnl::, +for details. + + The first argument to `define' should be quoted; otherwise, if the +macro is already defined, you will be defining a different macro. This +example shows the problems with underquoting, since we did not want to +redefine `one': + + define(foo, one) + => + define(foo, two) + => + one + =>two + + GNU `m4' normally replaces only the _topmost_ definition of a macro +if it has several definitions from `pushdef' (*note Pushdef::). Some +other implementations of `m4' replace all definitions of a macro with +`define'. *Note Incompatibilities::, for more details. + + As a GNU extension, the first argument to `define' does not have to +be a simple word. It can be any text string, even the empty string. A +macro with a non-standard name cannot be invoked in the normal way, as +the name is not recognized. It can only be referenced by the builtins +`indir' (*note Indir::) and `defn' (*note Defn::). + + Arrays and associative arrays can be simulated by using non-standard +macro names. + + -- Composite: array (INDEX) + -- Composite: array_set (INDEX, [VALUE]) + Provide access to entries within an array. `array' reads the entry + at location INDEX, and `array_set' assigns VALUE to location INDEX. + + define(`array', `defn(format(``array[%d]'', `$1'))') + => + define(`array_set', `define(format(``array[%d]'', `$1'), `$2')') + => + array_set(`4', `array element no. 4') + => + array_set(`17', `array element no. 17') + => + array(`4') + =>array element no. 4 + array(eval(`10 + 7')) + =>array element no. 17 + + Change the `%d' to `%s' and it is an associative array. + + +File: m4.info, Node: Arguments, Next: Pseudo Arguments, Prev: Define, Up: Definitions + +5.2 Arguments to macros +======================= + +Macros can have arguments. The Nth argument is denoted by `$n' in the +expansion text, and is replaced by the Nth actual argument, when the +macro is expanded. Replacement of arguments happens before rescanning, +regardless of how many nesting levels of quoting appear in the +expansion. Here is an example of a macro with two arguments. + + -- Composite: exch (ARG1, ARG2) + Expands to ARG2 followed by ARG1, effectively exchanging their + order. + + define(`exch', `$2, $1') + => + exch(`arg1', `arg2') + =>arg2, arg1 + + This can be used, for example, if you like the arguments to `define' +to be reversed. + + define(`exch', `$2, $1') + => + define(exch(``expansion text'', ``macro'')) + => + macro + =>expansion text + + *Note Quoting Arguments::, for an explanation of the double quotes. +(You should try and improve this example so that clients of `exch' do +not have to double quote; or *note Answers: Improved exch.). + + As a special case, the zeroth argument, `$0', is always the name of +the macro being expanded. + + define(`test', ``Macro name: $0'') + => + test + =>Macro name: test + + If you want quoted text to appear as part of the expansion text, +remember that quotes can be nested in quoted strings. Thus, in + + define(`foo', `This is macro `foo'.') + => + foo + =>This is macro foo. + +The `foo' in the expansion text is _not_ expanded, since it is a quoted +string, and not a name. + + GNU `m4' allows the number following the `$' to consist of one or +more digits, allowing macros to have any number of arguments. The +extension of accepting multiple digits is incompatible with POSIX, and +is different than traditional implementations of `m4', which only +recognize one digit. Therefore, future versions of GNU M4 will phase +out this feature. To portably access beyond the ninth argument, you +can use the `argn' macro documented later (*note Shift::). + + POSIX also states that `$' followed immediately by `{' in a macro +definition is implementation-defined. This version of M4 passes the +literal characters `${' through unchanged, but M4 2.0 will implement an +optional feature similar to `sh', where `${11}' expands to the eleventh +argument, to replace the current recognition of `$11'. Meanwhile, if +you want to guarantee that you will get a literal `${' in output when +expanding a macro, even when you upgrade to M4 2.0, you can use nested +quoting to your advantage: + + define(`foo', `single quoted $`'{1} output') + => + define(`bar', ``double quoted $'`{2} output'') + => + foo(`a', `b') + =>single quoted ${1} output + bar(`a', `b') + =>double quoted ${2} output + + To help you detect places in your M4 input files that might change in +behavior due to the changed behavior of M4 2.0, you can use the +`--warn-macro-sequence' command-line option (*note Invoking m4: +Operation modes.) with the default regular expression. This will add a +warning any time a macro definition includes `$' followed by multiple +digits, or by `{'. The warning is not enabled by default, because it +triggers a number of warnings in Autoconf 2.61 (and Autoconf uses `-E' +to treat warnings as errors), and because it will still be possible to +restore older behavior in M4 2.0. + + $ m4 --warn-macro-sequence + define(`foo', `$001 ${1} $1') + error-->m4:stdin:1: Warning: definition of `foo' contains sequence `$001' + error-->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}' + => + foo(`bar') + =>bar ${1} bar + + +File: m4.info, Node: Pseudo Arguments, Next: Undefine, Prev: Arguments, Up: Definitions + +5.3 Special arguments to macros +=============================== + +There is a special notation for the number of actual arguments supplied, +and for all the actual arguments. + + The number of actual arguments in a macro call is denoted by `$#' in +the expansion text. + + -- Composite: nargs (...) + Expands to a count of the number of arguments supplied. + + define(`nargs', `$#') + => + nargs + =>0 + nargs() + =>1 + nargs(`arg1', `arg2', `arg3') + =>3 + nargs(`commas can be quoted, like this') + =>1 + nargs(arg1#inside comments, commas do not separate arguments + still arg1) + =>1 + nargs((unquoted parentheses, like this, group arguments)) + =>1 + + Remember that `#' defaults to the comment character; if you forget +quotes to inhibit the comment behavior, your macro definition may not +end where you expected. + + dnl Attempt to define a macro to just `$#' + define(underquoted, $#) + oops) + => + underquoted + =>0) + =>oops + + The notation `$*' can be used in the expansion text to denote all +the actual arguments, unquoted, with commas in between. For example + + define(`echo', `$*') + => + echo(arg1, arg2, arg3 , arg4) + =>arg1,arg2,arg3 ,arg4 + + Often each argument should be quoted, and the notation `$@' handles +that. It is just like `$*', except that it quotes each argument. A +simple example of that is: + + define(`echo', `$@') + => + echo(arg1, arg2, arg3 , arg4) + =>arg1,arg2,arg3 ,arg4 + + Where did the quotes go? Of course, they were eaten, when the +expanded text were reread by `m4'. To show the difference, try + + define(`echo1', `$*') + => + define(`echo2', `$@') + => + define(`foo', `This is macro `foo'.') + => + echo1(foo) + =>This is macro This is macro foo.. + echo1(`foo') + =>This is macro foo. + echo2(foo) + =>This is macro foo. + echo2(`foo') + =>foo + +*Note Trace::, if you do not understand this. As another example of the +difference, remember that comments encountered in arguments are passed +untouched to the macro, and that quoting disables comments. + + define(`echo1', `$*') + => + define(`echo2', `$@') + => + define(`foo', `bar') + => + echo1(#foo'foo + foo) + =>#foo'foo + =>bar + echo2(#foo'foo + foo) + =>#foobar + =>bar' + + A `$' sign in the expansion text, that is not followed by anything +`m4' understands, is simply copied to the macro expansion, as any other +text is. + + define(`foo', `$$$ hello $$$') + => + foo + =>$$$ hello $$$ + + If you want a macro to expand to something like `$12', the judicious +use of nested quoting can put a safe character between the `$' and the +next character, relying on the rescanning to remove the nested quote. +This will prevent `m4' from interpreting the `$' sign as a reference to +an argument. + + define(`foo', `no nested quote: $1') + => + foo(`arg') + =>no nested quote: arg + define(`foo', `nested quote around $: `$'1') + => + foo(`arg') + =>nested quote around $: $1 + define(`foo', `nested empty quote after $: $`'1') + => + foo(`arg') + =>nested empty quote after $: $1 + define(`foo', `nested quote around next character: $`1'') + => + foo(`arg') + =>nested quote around next character: $1 + define(`foo', `nested quote around both: `$1'') + => + foo(`arg') + =>nested quote around both: arg + + +File: m4.info, Node: Undefine, Next: Defn, Prev: Pseudo Arguments, Up: Definitions + +5.4 Deleting a macro +==================== + +A macro definition can be removed with `undefine': + + -- Builtin: undefine (NAME...) + For each argument, remove the macro NAME. The macro names must + necessarily be quoted, since they will be expanded otherwise. + + The expansion of `undefine' is void. The macro `undefine' is + recognized only with parameters. + + foo bar blah + =>foo bar blah + define(`foo', `some')define(`bar', `other')define(`blah', `text') + => + foo bar blah + =>some other text + undefine(`foo') + => + foo bar blah + =>foo other text + undefine(`bar', `blah') + => + foo bar blah + =>foo bar blah + + Undefining a macro inside that macro's expansion is safe; the macro +still expands to the definition that was in effect at the `('. + + define(`f', ``$0':$1') + => + f(f(f(undefine(`f')`hello world'))) + =>f:f:f:hello world + f(`bye') + =>f(bye) + + It is not an error for NAME to have no macro definition. In that +case, `undefine' does nothing. + + +File: m4.info, Node: Defn, Next: Pushdef, Prev: Undefine, Up: Definitions + +5.5 Renaming macros +=================== + +It is possible to rename an already defined macro. To do this, you need +the builtin `defn': + + -- Builtin: defn (NAME...) + Expands to the _quoted definition_ of each NAME. If an argument + is not a defined macro, the expansion for that argument is empty. + + If NAME is a user-defined macro, the quoted definition is simply + the quoted expansion text. If, instead, there is only one NAME + and it is a builtin, the expansion is a special token, which + points to the builtin's internal definition. This token is only + meaningful as the second argument to `define' (and `pushdef'), and + is silently converted to an empty string in most other contexts. + Combining a builtin with anything else is not supported; a warning + is issued and the builtin is omitted from the final expansion. + + The macro `defn' is recognized only with parameters. + + Its normal use is best understood through an example, which shows +how to rename `undefine' to `zap': + + define(`zap', defn(`undefine')) + => + zap(`undefine') + => + undefine(`zap') + =>undefine(zap) + + In this way, `defn' can be used to copy macro definitions, and also +definitions of builtin macros. Even if the original macro is removed, +the other name can still be used to access the definition. + + The fact that macro definitions can be transferred also explains why +you should use `$0', rather than retyping a macro's name in its +definition: + + define(`foo', `This is `$0'') + => + define(`bar', defn(`foo')) + => + bar + =>This is bar + + Macros used as string variables should be referred through `defn', +to avoid unwanted expansion of the text: + + define(`string', `The macro dnl is very useful + ') + => + string + =>The macro + defn(`string') + =>The macro dnl is very useful + => + + However, it is important to remember that `m4' rescanning is purely +textual. If an unbalanced end-quote string occurs in a macro +definition, the rescan will see that embedded quote as the termination +of the quoted string, and the remainder of the macro's definition will +be rescanned unquoted. Thus it is a good idea to avoid unbalanced +end-quotes in macro definitions or arguments to macros. + + define(`foo', a'a) + => + define(`a', `A') + => + define(`echo', `$@') + => + foo + =>A'A + defn(`foo') + =>aA' + echo(foo) + =>AA' + + On the other hand, it is possible to exploit the fact that `defn' +can concatenate multiple macros prior to the rescanning phase, in order +to join the definitions of macros that, in isolation, have unbalanced +quotes. This is particularly useful when one has used several macros to +accumulate text that M4 should rescan as a whole. In the example below, +note how the use of `defn' on `l' in isolation opens a string, which is +not closed until the next line; but used on `l' and `r' together +results in nested quoting. + + define(`l', `<[>')define(`r', `<]>') + => + changequote(`[', `]') + => + defn([l])defn([r]) + ]) + =><[>]defn([r]) + =>) + defn([l], [r]) + =><[>][<]> + + Using `defn' to generate special tokens for builtin macros outside +of expected contexts can sometimes trigger warnings. But most of the +time, such tokens are silently converted to the empty string. + + $ m4 -d + defn(`defn') + => + define(defn(`divnum'), `cannot redefine a builtin token') + error-->m4:stdin:2: Warning: define: invalid macro name ignored + => + divnum + =>0 + len(defn(`divnum')) + =>0 + + Also note that `defn' with multiple arguments can only join text +macros, not builtins, although a future version of GNU M4 may lift this +restriction. + + $ m4 -d + define(`a', `A')define(`AA', `b') + => + traceon(`defn', `define') + => + defn(`a', `divnum', `a') + error-->m4:stdin:3: Warning: cannot concatenate builtin `divnum' + error-->m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A'' + =>AA + define(`mydivnum', defn(`divnum', `divnum'))mydivnum + error-->m4:stdin:4: Warning: cannot concatenate builtin `divnum' + error-->m4:stdin:4: Warning: cannot concatenate builtin `divnum' + error-->m4trace: -2- defn(`divnum', `divnum') + error-->m4trace: -1- define(`mydivnum', `') + => + traceoff(`defn', `define') + => + + +File: m4.info, Node: Pushdef, Next: Indir, Prev: Defn, Up: Definitions + +5.6 Temporarily redefining macros +================================= + +It is possible to redefine a macro temporarily, reverting to the +previous definition at a later time. This is done with the builtins +`pushdef' and `popdef': + + -- Builtin: pushdef (NAME, [EXPANSION]) + -- Builtin: popdef (NAME...) + Analogous to `define' and `undefine'. + + These macros work in a stack-like fashion. A macro is temporarily + redefined with `pushdef', which replaces an existing definition of + NAME, while saving the previous definition, before the new one is + installed. If there is no previous definition, `pushdef' behaves + exactly like `define'. + + If a macro has several definitions (of which only one is + accessible), the topmost definition can be removed with `popdef'. + If there is no previous definition, `popdef' behaves like + `undefine'. + + The expansion of both `pushdef' and `popdef' is void. The macros + `pushdef' and `popdef' are recognized only with parameters. + + define(`foo', `Expansion one.') + => + foo + =>Expansion one. + pushdef(`foo', `Expansion two.') + => + foo + =>Expansion two. + pushdef(`foo', `Expansion three.') + => + pushdef(`foo', `Expansion four.') + => + popdef(`foo') + => + foo + =>Expansion three. + popdef(`foo', `foo') + => + foo + =>Expansion one. + popdef(`foo') + => + foo + =>foo + + If a macro with several definitions is redefined with `define', the +topmost definition is _replaced_ with the new definition. If it is +removed with `undefine', _all_ the definitions are removed, and not +only the topmost one. However, POSIX allows other implementations that +treat `define' as replacing an entire stack of definitions with a +single new definition, so to be portable to other implementations, it +may be worth explicitly using `popdef' and `pushdef' rather than +relying on the GNU behavior of `define'. + + define(`foo', `Expansion one.') + => + foo + =>Expansion one. + pushdef(`foo', `Expansion two.') + => + foo + =>Expansion two. + define(`foo', `Second expansion two.') + => + foo + =>Second expansion two. + undefine(`foo') + => + foo + =>foo + + Local variables within macros are made with `pushdef' and `popdef'. +At the start of the macro a new definition is pushed, within the macro +it is manipulated and at the end it is popped, revealing the former +definition. + + It is possible to temporarily redefine a builtin with `pushdef' and +`defn'. + + +File: m4.info, Node: Indir, Next: Builtin, Prev: Pushdef, Up: Definitions + +5.7 Indirect call of macros +=========================== + +Any macro can be called indirectly with `indir': + + -- Builtin: indir (NAME, [ARGS...]) + Results in a call to the macro NAME, which is passed the rest of + the arguments ARGS. If NAME is not defined, an error message is + printed, and the expansion is void. + + The macro `indir' is recognized only with parameters. + + This can be used to call macros with computed or "invalid" names +(`define' allows such names to be defined): + + define(`$$internal$macro', `Internal macro (name `$0')') + => + $$internal$macro + =>$$internal$macro + indir(`$$internal$macro') + =>Internal macro (name $$internal$macro) + + The point is, here, that larger macro packages can have private +macros defined, that will not be called by accident. They can _only_ be +called through the builtin `indir'. + + One other point to observe is that argument collection occurs before +`indir' invokes NAME, so if argument collection changes the value of +NAME, that will be reflected in the final expansion. This is different +than the behavior when invoking macros directly, where the definition +that was in effect before argument collection is used. + + $ m4 -d + define(`f', `1') + => + f(define(`f', `2')) + =>1 + indir(`f', define(`f', `3')) + =>3 + indir(`f', undefine(`f')) + error-->m4:stdin:4: undefined macro `f' + => + + When handed the result of `defn' (*note Defn::) as one of its +arguments, `indir' defers to the invoked NAME for whether a token +representing a builtin is recognized or flattened to the empty string. + + $ m4 -d + indir(defn(`defn'), `divnum') + error-->m4:stdin:1: Warning: indir: invalid macro name ignored + => + indir(`define', defn(`defn'), `divnum') + error-->m4:stdin:2: Warning: define: invalid macro name ignored + => + indir(`define', `foo', defn(`divnum')) + => + foo + =>0 + indir(`divert', defn(`foo')) + error-->m4:stdin:5: empty string treated as 0 in builtin `divert' + => + + +File: m4.info, Node: Builtin, Prev: Indir, Up: Definitions + +5.8 Indirect call of builtins +============================= + +Builtin macros can be called indirectly with `builtin': + + -- Builtin: builtin (NAME, [ARGS...]) + Results in a call to the builtin NAME, which is passed the rest of + the arguments ARGS. If NAME does not name a builtin, an error + message is printed, and the expansion is void. + + The macro `builtin' is recognized only with parameters. + + This can be used even if NAME has been given another definition that +has covered the original, or been undefined so that no macro maps to +the builtin. + + pushdef(`define', `hidden') + => + undefine(`undefine') + => + define(`foo', `bar') + =>hidden + foo + =>foo + builtin(`define', `foo', defn(`divnum')) + => + foo + =>0 + builtin(`define', `foo', `BAR') + => + foo + =>BAR + undefine(`foo') + =>undefine(foo) + foo + =>BAR + builtin(`undefine', `foo') + => + foo + =>foo + + The NAME argument only matches the original name of the builtin, +even when the `--prefix-builtins' option (or `-P', *note Invoking m4: +Operation modes.) is in effect. This is different from `indir', which +only tracks current macro names. + + $ m4 -P + m4_builtin(`divnum') + =>0 + m4_builtin(`m4_divnum') + error-->m4:stdin:2: undefined builtin `m4_divnum' + => + m4_indir(`divnum') + error-->m4:stdin:3: undefined macro `divnum' + => + m4_indir(`m4_divnum') + =>0 + + Note that `indir' and `builtin' can be used to invoke builtins +without arguments, even when they normally require parameters to be +recognized; but it will provoke a warning, and result in a void +expansion. + + builtin + =>builtin + builtin() + error-->m4:stdin:2: undefined builtin `' + => + builtin(`builtin') + error-->m4:stdin:3: Warning: too few arguments to builtin `builtin' + => + builtin(`builtin',) + error-->m4:stdin:4: undefined builtin `' + => + builtin(`builtin', ``' + ') + error-->m4:stdin:5: undefined builtin ``' + error-->' + => + indir(`index') + error-->m4:stdin:7: Warning: too few arguments to builtin `index' + => + + +File: m4.info, Node: Conditionals, Next: Debugging, Prev: Definitions, Up: Top + +6 Conditionals, loops, and recursion +************************************ + +Macros, expanding to plain text, perhaps with arguments, are not quite +enough. We would like to have macros expand to different things, based +on decisions taken at run-time. For that, we need some kind of +conditionals. Also, we would like to have some kind of loop construct, +so we could do something a number of times, or while some condition is +true. + +* Menu: + +* Ifdef:: Testing if a macro is defined +* Ifelse:: If-else construct, or multibranch +* Shift:: Recursion in `m4' +* Forloop:: Iteration by counting +* Foreach:: Iteration by list contents +* Stacks:: Working with definition stacks +* Composition:: Building macros with macros + + +File: m4.info, Node: Ifdef, Next: Ifelse, Up: Conditionals + +6.1 Testing if a macro is defined +================================= + +There are two different builtin conditionals in `m4'. The first is +`ifdef': + + -- Builtin: ifdef (NAME, STRING-1, [STRING-2]) + If NAME is defined as a macro, `ifdef' expands to STRING-1, + otherwise to STRING-2. If STRING-2 is omitted, it is taken to be + the empty string (according to the normal rules). + + The macro `ifdef' is recognized only with parameters. + + ifdef(`foo', ``foo' is defined', ``foo' is not defined') + =>foo is not defined + define(`foo', `') + => + ifdef(`foo', ``foo' is defined', ``foo' is not defined') + =>foo is defined + ifdef(`no_such_macro', `yes', `no', `extra argument') + error-->m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored + =>no + + +File: m4.info, Node: Ifelse, Next: Shift, Prev: Ifdef, Up: Conditionals + +6.2 If-else construct, or multibranch +===================================== + +The other conditional, `ifelse', is much more powerful. It can be used +as a way to introduce a long comment, as an if-else construct, or as a +multibranch, depending on the number of arguments supplied: + + -- Builtin: ifelse (COMMENT) + -- Builtin: ifelse (STRING-1, STRING-2, EQUAL, [NOT-EQUAL]) + -- Builtin: ifelse (STRING-1, STRING-2, EQUAL-1, STRING-3, STRING-4, + EQUAL-2, ..., [NOT-EQUAL]) + Used with only one argument, the `ifelse' simply discards it and + produces no output. + + If called with three or four arguments, `ifelse' expands into + EQUAL, if STRING-1 and STRING-2 are equal (character for + character), otherwise it expands to NOT-EQUAL. A final fifth + argument is ignored, after triggering a warning. + + If called with six or more arguments, and STRING-1 and STRING-2 + are equal, `ifelse' expands into EQUAL-1, otherwise the first + three arguments are discarded and the processing starts again. + + The macro `ifelse' is recognized only with parameters. + + Using only one argument is a common `m4' idiom for introducing a +block comment, as an alternative to repeatedly using `dnl'. This +special usage is recognized by GNU `m4', so that in this case, the +warning about missing arguments is never triggered. + + ifelse(`some comments') + => + ifelse(`foo', `bar') + error-->m4:stdin:2: Warning: too few arguments to builtin `ifelse' + => + + Using three or four arguments provides decision points. + + ifelse(`foo', `bar', `true') + => + ifelse(`foo', `foo', `true') + =>true + define(`foo', `bar') + => + ifelse(foo, `bar', `true', `false') + =>true + ifelse(foo, `foo', `true', `false') + =>false + + Notice how the first argument was used unquoted; it is common to +compare the expansion of a macro with a string. With this macro, you +can now reproduce the behavior of blind builtins, where the macro is +recognized only with arguments. + + define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')') + => + foo + =>foo + foo() + =>arguments:1 + foo(`a', `b', `c') + =>arguments:3 + + For an example of a way to make defining blind macros easier, see +*note Composition::. + + The macro `ifelse' can take more than four arguments. If given more +than four arguments, `ifelse' works like a `case' or `switch' statement +in traditional programming languages. If STRING-1 and STRING-2 are +equal, `ifelse' expands into EQUAL-1, otherwise the procedure is +repeated with the first three arguments discarded. This calls for an +example: + + ifelse(`foo', `bar', `third', `gnu', `gnats') + error-->m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored + =>gnu + ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth') + => + ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh') + =>seventh + ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8') + error-->m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored + =>7 + + Naturally, the normal case will be slightly more advanced than these +examples. A common use of `ifelse' is in macros implementing loops of +various kinds. + + +File: m4.info, Node: Shift, Next: Forloop, Prev: Ifelse, Up: Conditionals + +6.3 Recursion in `m4' +===================== + +There is no direct support for loops in `m4', but macros can be +recursive. There is no limit on the number of recursion levels, other +than those enforced by your hardware and operating system. + + Loops can be programmed using recursion and the conditionals +described previously. + + There is a builtin macro, `shift', which can, among other things, be +used for iterating through the actual arguments to a macro: + + -- Builtin: shift (ARG1, ...) + Takes any number of arguments, and expands to all its arguments + except ARG1, separated by commas, with each argument quoted. + + The macro `shift' is recognized only with parameters. + + shift + =>shift + shift(`bar') + => + shift(`foo', `bar', `baz') + =>bar,baz + + An example of the use of `shift' is this macro: + + -- Composite: reverse (...) + Takes any number of arguments, and reverses their order. + + It is implemented as: + + define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', + `reverse(shift($@)), `$1'')') + => + reverse + => + reverse(`foo') + =>foo + reverse(`foo', `bar', `gnats', `and gnus') + =>and gnus, gnats, bar, foo + + While not a very interesting macro, it does show how simple loops +can be made with `shift', `ifelse' and recursion. It also shows that +`shift' is usually used with `$@'. Another example of this is an +implementation of a short-circuiting conditional operator. + + -- Composite: cond (TEST-1, STRING-1, EQUAL-1, [TEST-2], [STRING-2], + [EQUAL-2], ..., [NOT-EQUAL]) + Similar to `ifelse', where an equal comparison between the first + two strings results in the third, otherwise the first three + arguments are discarded and the process repeats. The difference + is that each TEST-<N> is expanded only when it is encountered. + This means that every third argument to `cond' is normally given + one more level of quoting than the corresponding argument to + `ifelse'. + + Here is the implementation of `cond', along with a demonstration of +how it can short-circuit the side effects in `side'. Notice how all +the unquoted side effects happen regardless of how many comparisons are +made with `ifelse', compared with only the relevant effects with `cond'. + + define(`cond', + `ifelse(`$#', `1', `$1', + `ifelse($1, `$2', `$3', + `$0(shift(shift(shift($@))))')')')dnl + define(`side', `define(`counter', incr(counter))$1')dnl + define(`example1', + `define(`counter', `0')dnl + ifelse(side(`$1'), `yes', `one comparison: ', + side(`$1'), `no', `two comparisons: ', + side(`$1'), `maybe', `three comparisons: ', + `side(`default answer: ')')counter')dnl + define(`example2', + `define(`counter', `0')dnl + cond(`side(`$1')', `yes', `one comparison: ', + `side(`$1')', `no', `two comparisons: ', + `side(`$1')', `maybe', `three comparisons: ', + `side(`default answer: ')')counter')dnl + example1(`yes') + =>one comparison: 3 + example1(`no') + =>two comparisons: 3 + example1(`maybe') + =>three comparisons: 3 + example1(`feeling rather indecisive today') + =>default answer: 4 + example2(`yes') + =>one comparison: 1 + example2(`no') + =>two comparisons: 2 + example2(`maybe') + =>three comparisons: 3 + example2(`feeling rather indecisive today') + =>default answer: 4 + + Another common task that requires iteration is joining a list of +arguments into a single string. + + -- Composite: join ([SEPARATOR], [ARGS...]) + -- Composite: joinall ([SEPARATOR], [ARGS...]) + Generate a single-quoted string, consisting of each ARG separated + by SEPARATOR. While `joinall' always outputs a SEPARATOR between + arguments, `join' avoids the SEPARATOR for an empty ARG. + + Here are some examples of its usage, based on the implementation +`m4-1.4.16/examples/join.m4' distributed in this package: + + $ m4 -I examples + include(`join.m4') + => + join,join(`-'),join(`-', `'),join(`-', `', `') + =>,,, + joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `') + =>,,,- + join(`-', `1') + =>1 + join(`-', `1', `2', `3') + =>1-2-3 + join(`', `1', `2', `3') + =>123 + join(`-', `', `1', `', `', `2', `') + =>1-2 + joinall(`-', `', `1', `', `', `2', `') + =>-1---2- + join(`,', `1', `2', `3') + =>1,2,3 + define(`nargs', `$#')dnl + nargs(join(`,', `1', `2', `3')) + =>1 + + Examining the implementation shows some interesting points about +several m4 programming idioms. + + $ m4 -I examples + undivert(`join.m4')dnl + =>divert(`-1') + =># join(sep, args) - join each non-empty ARG into a single + =># string, with each element separated by SEP + =>define(`join', + =>`ifelse(`$#', `2', ``$2'', + => `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@)))')') + =>define(`_join', + =>`ifelse(`$#$2', `2', `', + => `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@)))')') + =># joinall(sep, args) - join each ARG, including empty ones, + =># into a single string, with each element separated by SEP + =>define(`joinall', ``$2'_$0(`$1', shift($@))') + =>define(`_joinall', + =>`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@)))')') + =>divert`'dnl + + First, notice that this implementation creates helper macros `_join' +and `_joinall'. This division of labor makes it easier to output the +correct number of SEPARATOR instances: `join' and `joinall' are +responsible for the first argument, without a separator, while `_join' +and `_joinall' are responsible for all remaining arguments, always +outputting a separator when outputting an argument. + + Next, observe how `join' decides to iterate to itself, because the +first ARG was empty, or to output the argument and swap over to +`_join'. If the argument is non-empty, then the nested `ifelse' +results in an unquoted `_', which is concatenated with the `$0' to form +the next macro name to invoke. The `joinall' implementation is simpler +since it does not have to suppress empty ARG; it always executes once +then defers to `_joinall'. + + Another important idiom is the idea that SEPARATOR is reused for +each iteration. Each iteration has one less argument, but rather than +discarding `$1' by iterating with `$0(shift($@))', the macro discards +`$2' by using `$0(`$1', shift(shift($@)))'. + + Next, notice that it is possible to compare more than one condition +in a single `ifelse' test. The test of `$#$2' against `2' allows +`_join' to iterate for two separate reasons--either there are still +more than two arguments, or there are exactly two arguments but the +last argument is not empty. + + Finally, notice that these macros require exactly two arguments to +terminate recursion, but that they still correctly result in empty +output when given no ARGS (i.e., zero or one macro argument). On the +first pass when there are too few arguments, the `shift' results in no +output, but leaves an empty string to serve as the required second +argument for the second pass. Put another way, ``$1', shift($@)' is +not the same as `$@', since only the former guarantees at least two +arguments. + + Sometimes, a recursive algorithm requires adding quotes to each +element, or treating multiple arguments as a single element: + + -- Composite: quote (...) + -- Composite: dquote (...) + -- Composite: dquote_elt (...) + Takes any number of arguments, and adds quoting. With `quote', + only one level of quoting is added, effectively removing whitespace + after commas and turning multiple arguments into a single string. + With `dquote', two levels of quoting are added, one around each + element, and one around the list. And with `dquote_elt', two + levels of quoting are added around each element. + + An actual implementation of these three macros is distributed as +`m4-1.4.16/examples/quote.m4' in this package. First, let's examine +their usage: + + $ m4 -I examples + include(`quote.m4') + => + -quote-dquote-dquote_elt- + =>---- + -quote()-dquote()-dquote_elt()- + =>--`'-`'- + -quote(`1')-dquote(`1')-dquote_elt(`1')- + =>-1-`1'-`1'- + -quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')- + =>-1,2-`1',`2'-`1',`2'- + define(`n', `$#')dnl + -n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))- + =>-1-1-2- + dquote(dquote_elt(`1', `2')) + =>``1'',``2'' + dquote_elt(dquote(`1', `2')) + =>``1',`2'' + + The last two lines show that when given two arguments, `dquote' +results in one string, while `dquote_elt' results in two. Now, examine +the implementation. Note that `quote' and `dquote_elt' make decisions +based on their number of arguments, so that when called without +arguments, they result in nothing instead of a quoted empty string; +this is so that it is possible to distinguish between no arguments and +an empty first argument. `dquote', on the other hand, results in a +string no matter what, since it is still possible to tell whether it +was invoked without arguments based on the resulting string. + + $ m4 -I examples + undivert(`quote.m4')dnl + =>divert(`-1') + =># quote(args) - convert args to single-quoted string + =>define(`quote', `ifelse(`$#', `0', `', ``$*'')') + =># dquote(args) - convert args to quoted list of quoted strings + =>define(`dquote', ``$@'') + =># dquote_elt(args) - convert args to list of double-quoted strings + =>define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''', + => ```$1'',$0(shift($@))')') + =>divert`'dnl + + It is worth pointing out that `quote(ARGS)' is more efficient than +`joinall(`,', ARGS)' for producing the same output. + + One more useful macro based on `shift' allows portably selecting an +arbitrary argument (usually greater than the ninth argument), without +relying on the GNU extension of multi-digit arguments (*note +Arguments::). + + -- Composite: argn (N, ...) + Expands to argument N out of the remaining arguments. N must be a + positive number. Usually invoked as `argn(`N',$@)'. + + It is implemented as: + + define(`argn', `ifelse(`$1', 1, ``$2'', + `argn(decr(`$1'), shift(shift($@)))')') + => + argn(`1', `a') + =>a + define(`foo', `argn(`11', $@)') + => + foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l') + =>k + + +File: m4.info, Node: Forloop, Next: Foreach, Prev: Shift, Up: Conditionals + +6.4 Iteration by counting +========================= + +Here is an example of a loop macro that implements a simple for loop. + + -- Composite: forloop (ITERATOR, START, END, TEXT) + Takes the name in ITERATOR, which must be a valid macro name, and + successively assign it each integer value from START to END, + inclusive. For each assignment to ITERATOR, append TEXT to the + expansion of the `forloop'. TEXT may refer to ITERATOR. Any + definition of ITERATOR prior to this invocation is restored. + + It can, for example, be used for simple counting: + + $ m4 -I examples + include(`forloop.m4') + => + forloop(`i', `1', `8', `i ') + =>1 2 3 4 5 6 7 8 + + For-loops can be nested, like: + + $ m4 -I examples + include(`forloop.m4') + => + forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)') + ') + => (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8) + => (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8) + => (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8) + => (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8) + => + + The implementation of the `forloop' macro is fairly straightforward. +The `forloop' macro itself is simply a wrapper, which saves the +previous definition of the first argument, calls the internal macro +`_forloop', and re-establishes the saved definition of the first +argument. + + The macro `_forloop' expands the fourth argument once, and tests to +see if the iterator has reached the final value. If it has not +finished, it increments the iterator (using the predefined macro +`incr', *note Incr::), and recurses. + + Here is an actual implementation of `forloop', distributed as +`m4-1.4.16/examples/forloop.m4' in this package: + + $ m4 -I examples + undivert(`forloop.m4')dnl + =>divert(`-1') + =># forloop(var, from, to, stmt) - simple version + =>define(`forloop', `pushdef(`$1', `$2')_forloop($@)popdef(`$1')') + =>define(`_forloop', + => `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@)')') + =>divert`'dnl + + Notice the careful use of quotes. Certain macro arguments are left +unquoted, each for its own reason. Try to find out _why_ these +arguments are left unquoted, and see what happens if they are quoted. +(As presented, these two macros are useful but not very robust for +general use. They lack even basic error handling for cases like START +less than END, END not numeric, or ITERATOR not being a macro name. +See if you can improve these macros; or *note Answers: Improved +forloop.). + + +File: m4.info, Node: Foreach, Next: Stacks, Prev: Forloop, Up: Conditionals + +6.5 Iteration by list contents +============================== + +Here is an example of a loop macro that implements list iteration. + + -- Composite: foreach (ITERATOR, PAREN-LIST, TEXT) + -- Composite: foreachq (ITERATOR, QUOTE-LIST, TEXT) + Takes the name in ITERATOR, which must be a valid macro name, and + successively assign it each value from PAREN-LIST or QUOTE-LIST. + In `foreach', PAREN-LIST is a comma-separated list of elements + contained in parentheses. In `foreachq', QUOTE-LIST is a + comma-separated list of elements contained in a quoted string. + For each assignment to ITERATOR, append TEXT to the overall + expansion. TEXT may refer to ITERATOR. Any definition of + ITERATOR prior to this invocation is restored. + + As an example, this displays each word in a list inside of a +sentence, using an implementation of `foreach' distributed as +`m4-1.4.16/examples/foreach.m4', and `foreachq' in +`m4-1.4.16/examples/foreachq.m4'. + + $ m4 -I examples + include(`foreach.m4') + => + foreach(`x', (foo, bar, foobar), `Word was: x + ')dnl + =>Word was: foo + =>Word was: bar + =>Word was: foobar + include(`foreachq.m4') + => + foreachq(`x', `foo, bar, foobar', `Word was: x + ')dnl + =>Word was: foo + =>Word was: bar + =>Word was: foobar + + It is possible to be more complex; each element of the PAREN-LIST or +QUOTE-LIST can itself be a list, to pass as further arguments to a +helper macro. This example generates a shell case statement: + + $ m4 -I examples + include(`foreach.m4') + => + define(`_case', ` $1) + $2=" $1";; + ')dnl + define(`_cat', `$1$2')dnl + case $`'1 in + =>case $1 in + foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')', + `_cat(`_case', x)')dnl + => a) + => vara=" a";; + => b) + => varb=" b";; + => c) + => varc=" c";; + esac + =>esac + + The implementation of the `foreach' macro is a bit more involved; it +is a wrapper around two helper macros. First, `_arg1' is needed to +grab the first element of a list. Second, `_foreach' implements the +recursion, successively walking through the original list. Here is a +simple implementation of `foreach': + + $ m4 -I examples + undivert(`foreach.m4')dnl + =>divert(`-1') + =># foreach(x, (item_1, item_2, ..., item_n), stmt) + =># parenthesized list, simple version + =>define(`foreach', `pushdef(`$1')_foreach($@)popdef(`$1')') + =>define(`_arg1', `$1') + =>define(`_foreach', `ifelse(`$2', `()', `', + => `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')') + =>divert`'dnl + + Unfortunately, that implementation is not robust to macro names as +list elements. Each iteration of `_foreach' is stripping another layer +of quotes, leading to erratic results if list elements are not already +fully expanded. The first cut at implementing `foreachq' takes this +into account. Also, when using quoted elements in a PAREN-LIST, the +overall list must be quoted. A QUOTE-LIST has the nice property of +requiring fewer characters to create a list containing the same quoted +elements. To see the difference between the two macros, we attempt to +pass double-quoted macro names in a list, expecting the macro name on +output after one layer of quotes is removed during list iteration and +the final layer removed during the final rescan: + + $ m4 -I examples + define(`a', `1')define(`b', `2')define(`c', `3') + => + include(`foreach.m4') + => + include(`foreachq.m4') + => + foreach(`x', `(``a'', ``(b'', ``c)'')', `x + ') + =>1 + =>(2)1 + => + =>, x + =>) + foreachq(`x', ```a'', ``(b'', ``c)''', `x + ')dnl + =>a + =>(b + =>c) + + Obviously, `foreachq' did a better job; here is its implementation: + + $ m4 -I examples + undivert(`foreachq.m4')dnl + =>include(`quote.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, simple version + =>define(`foreachq', `pushdef(`$1')_foreachq($@)popdef(`$1')') + =>define(`_arg1', `$1') + =>define(`_foreachq', `ifelse(quote($2), `', `', + => `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')') + =>divert`'dnl + + Notice that `_foreachq' had to use the helper macro `quote' defined +earlier (*note Shift::), to ensure that the embedded `ifelse' call does +not go haywire if a list element contains a comma. Unfortunately, this +implementation of `foreachq' has its own severe flaw. Whereas the +`foreach' implementation was linear, this macro is quadratic in the +number of list elements, and is much more likely to trip up the limit +set by the command line option `--nesting-limit' (or `-L', *note +Invoking m4: Limits control.). Additionally, this implementation does +not expand `defn(`ITERATOR')' very well, when compared with `foreach'. + + $ m4 -I examples + include(`foreach.m4')include(`foreachq.m4') + => + foreach(`name', `(`a', `b')', ` defn(`name')') + => a b + foreachq(`name', ``a', `b'', ` defn(`name')') + => _arg1(`a', `b') _arg1(shift(`a', `b')) + + It is possible to have robust iteration with linear behavior and sane +ITERATOR contents for either list style. See if you can learn from the +best elements of both of these implementations to create robust macros +(or *note Answers: Improved foreach.). + + +File: m4.info, Node: Stacks, Next: Composition, Prev: Foreach, Up: Conditionals + +6.6 Working with definition stacks +================================== + +Thanks to `pushdef', manipulation of a stack is an intrinsic operation +in `m4'. Normally, only the topmost definition in a stack is +important, but sometimes, it is desirable to manipulate the entire +definition stack. + + -- Composite: stack_foreach (MACRO, ACTION) + -- Composite: stack_foreach_lifo (MACRO, ACTION) + For each of the `pushdef' definitions associated with MACRO, + invoke the macro ACTION with a single argument of that definition. + `stack_foreach' visits the oldest definition first, while + `stack_foreach_lifo' visits the current definition first. ACTION + should not modify or dereference MACRO. There are a few special + macros, such as `defn', which cannot be used as the MACRO + parameter. + + A sample implementation of these macros is distributed in the file +`m4-1.4.16/examples/stack.m4'. + + $ m4 -I examples + include(`stack.m4') + => + pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') + => + define(`show', ``$1' + ') + => + stack_foreach(`a', `show')dnl + =>1 + =>2 + =>3 + stack_foreach_lifo(`a', `show')dnl + =>3 + =>2 + =>1 + + Now for the implementation. Note the definition of a helper macro, +`_stack_reverse', which destructively swaps the contents of one stack +of definitions into the reverse order in the temporary macro `tmp-$1'. +By calling the helper twice, the original order is restored back into +the macro `$1'; since the operation is destructive, this explains why +`$1' must not be modified or dereferenced during the traversal. The +caller can then inject additional code to pass the definition currently +being visited to `$2'. The choice of helper names is intentional; +since `-' is not valid as part of a macro name, there is no risk of +conflict with a valid macro name, and the code is guaranteed to use +`defn' where necessary. Finally, note that any macro used in the +traversal of a `pushdef' stack, such as `pushdef' or `defn', cannot be +handled by `stack_foreach', since the macro would temporarily be +undefined during the algorithm. + + $ m4 -I examples + undivert(`stack.m4')dnl + =>divert(`-1') + =># stack_foreach(macro, action) + =># Invoke ACTION with a single argument of each definition + =># from the definition stack of MACRO, starting with the oldest. + =>define(`stack_foreach', + =>`_stack_reverse(`$1', `tmp-$1')'dnl + =>`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')') + =># stack_foreach_lifo(macro, action) + =># Invoke ACTION with a single argument of each definition + =># from the definition stack of MACRO, starting with the newest. + =>define(`stack_foreach_lifo', + =>`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl + =>`_stack_reverse(`tmp-$1', `$1')') + =>define(`_stack_reverse', + =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@)')') + =>divert`'dnl + + +File: m4.info, Node: Composition, Prev: Stacks, Up: Conditionals + +6.7 Building macros with macros +=============================== + +Since m4 is a macro language, it is possible to write macros that can +build other macros. First on the list is a way to automate the +creation of blind macros. + + -- Composite: define_blind (NAME, [VALUE]) + Defines NAME as a blind macro, such that NAME will expand to VALUE + only when given explicit arguments. VALUE should not be the + result of `defn' (*note Defn::). This macro is only recognized + with parameters, and results in an empty string. + + Defining a macro to define another macro can be a bit tricky. We +want to use a literal `$#' in the argument to the nested `define'. +However, if `$' and `#' are adjacent in the definition of +`define_blind', then it would be expanded as the number of arguments to +`define_blind' rather than the intended number of arguments to NAME. +The solution is to pass the difficult characters through extra +arguments to a helper macro `_define_blind'. When composing macros, it +is a common idiom to need a helper macro to concatenate text that forms +parameters in the composed macro, rather than interpreting the text as +a parameter of the composing macro. + + As for the limitation against using `defn', there are two reasons. +If a macro was previously defined with `define_blind', then it can +safely be renamed to a new blind macro using plain `define'; using +`define_blind' to rename it just adds another layer of `ifelse', +occupying memory and slowing down execution. And if a macro is a +builtin, then it would result in an attempt to define a macro +consisting of both text and a builtin token; this is not supported, and +the builtin token is flattened to an empty string. + + With that explanation, here's the definition, and some sample usage. +Notice that `define_blind' is itself a blind macro. + + $ m4 -d + define(`define_blind', `ifelse(`$#', `0', ``$0'', + `_$0(`$1', `$2', `$'`#', `$'`0')')') + => + define(`_define_blind', `define(`$1', + `ifelse(`$3', `0', ``$4'', `$2')')') + => + define_blind + =>define_blind + define_blind(`foo', `arguments were $*') + => + foo + =>foo + foo(`bar') + =>arguments were bar + define(`blah', defn(`foo')) + => + blah + =>blah + blah(`a', `b') + =>arguments were a,b + defn(`blah') + =>ifelse(`$#', `0', ``$0'', `arguments were $*') + + Another interesting composition tactic is argument "currying", or +factoring a macro that takes multiple arguments for use in a context +that provides exactly one argument. + + -- Composite: curry (MACRO, ...) + Expand to a macro call that takes exactly one argument, then + appends that argument to the original arguments and invokes MACRO + with the resulting list of arguments. + + A demonstration of currying makes the intent of this macro a little +more obvious. The macro `stack_foreach' mentioned earlier is an example +of a context that provides exactly one argument to a macro name. But +coupled with currying, we can invoke `reverse' with two arguments for +each definition of a macro stack. This example uses the file +`m4-1.4.16/examples/curry.m4' included in the distribution. + + $ m4 -I examples + include(`curry.m4')include(`stack.m4') + => + define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', + `reverse(shift($@)), `$1'')') + => + pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') + => + stack_foreach(`a', `:curry(`reverse', `4')') + =>:1, 4:2, 4:3, 4 + curry(`curry', `reverse', `1')(`2')(`3') + =>3, 2, 1 + + Now for the implementation. Notice how `curry' leaves off with a +macro name but no open parenthesis, while still in the middle of +collecting arguments for `$1'. The macro `_curry' is the helper macro +that takes one argument, then adds it to the list and finally supplies +the closing parenthesis. The use of a comma inside the `shift' call +allows currying to also work for a macro that takes one argument, +although it often makes more sense to invoke that macro directly rather +than going through `curry'. + + $ m4 -I examples + undivert(`curry.m4')dnl + =>divert(`-1') + =># curry(macro, args) + =># Expand to a macro call that takes one argument, then invoke + =># macro(args, extra). + =>define(`curry', `$1(shift($@,)_$0') + =>define(`_curry', ``$1')') + =>divert`'dnl + + Unfortunately, with M4 1.4.x, `curry' is unable to handle builtin +tokens, which are silently flattened to the empty string when passed +through another text macro. This limitation will be lifted in a future +release of M4. + + Putting the last few concepts together, it is possible to copy or +rename an entire stack of macro definitions. + + -- Composite: copy (SOURCE, DEST) + -- Composite: rename (SOURCE, DEST) + Ensure that DEST is undefined, then define it to the same stack of + definitions currently in SOURCE. `copy' leaves SOURCE unchanged, + while `rename' undefines SOURCE. There are only a few macros, + such as `copy' or `defn', which cannot be copied via this macro. + + The implementation is relatively straightforward (although since it +uses `curry', it is unable to copy builtin macros, such as the second +definition of `a' as a synonym for `divnum'. See if you can design a +version that works around this limitation, or *note Answers: Improved +copy.). + + $ m4 -I examples + include(`curry.m4')include(`stack.m4') + => + define(`rename', `copy($@)undefine(`$1')')dnl + define(`copy', `ifdef(`$2', `errprint(`$2 already defined + ')m4exit(`1')', + `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl + pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2') + => + copy(`a', `b') + => + rename(`b', `c') + => + a b c + =>2 b 2 + popdef(`a', `c')c a + => 0 + popdef(`a', `c')a c + =>1 1 + + +File: m4.info, Node: Debugging, Next: Input Control, Prev: Conditionals, Up: Top + +7 How to debug macros and input +******************************* + +When writing macros for `m4', they often do not work as intended on the +first try (as is the case with most programming languages). +Fortunately, there is support for macro debugging in `m4'. + +* Menu: + +* Dumpdef:: Displaying macro definitions +* Trace:: Tracing macro calls +* Debug Levels:: Controlling debugging output +* Debug Output:: Saving debugging output + + +File: m4.info, Node: Dumpdef, Next: Trace, Up: Debugging + +7.1 Displaying macro definitions +================================ + +If you want to see what a name expands into, you can use the builtin +`dumpdef': + + -- Builtin: dumpdef ([NAMES...]) + Accepts any number of arguments. If called without any arguments, + it displays the definitions of all known names, otherwise it + displays the definitions of the NAMES given. The output is + printed to the current debug file (usually standard error), and is + sorted by name. If an unknown name is encountered, a warning is + printed. + + The expansion of `dumpdef' is void. + + $ m4 -d + define(`foo', `Hello world.') + => + dumpdef(`foo') + error-->foo: `Hello world.' + => + dumpdef(`define') + error-->define: <define> + => + + The last example shows how builtin macros definitions are displayed. +The definition that is dumped corresponds to what would occur if the +macro were to be called at that point, even if other definitions are +still live due to redefining a macro during argument collection. + + $ m4 -d + pushdef(`f', ``$0'1')pushdef(`f', ``$0'2') + => + f(popdef(`f')dumpdef(`f')) + error-->f: ``$0'1' + =>f2 + f(popdef(`f')dumpdef(`f')) + error-->m4:stdin:3: undefined macro `f' + =>f1 + + *Note Debug Levels::, for information on controlling the details of +the display. + + +File: m4.info, Node: Trace, Next: Debug Levels, Prev: Dumpdef, Up: Debugging + +7.2 Tracing macro calls +======================= + +It is possible to trace macro calls and expansions through the builtins +`traceon' and `traceoff': + + -- Builtin: traceon ([NAMES...]) + -- Builtin: traceoff ([NAMES...]) + When called without any arguments, `traceon' and `traceoff' will + turn tracing on and off, respectively, for all currently defined + macros. + + When called with arguments, only the macros listed in NAMES are + affected, whether or not they are currently defined. + + The expansion of `traceon' and `traceoff' is void. + + Whenever a traced macro is called and the arguments have been +collected, the call is displayed. If the expansion of the macro call +is not void, the expansion can be displayed after the call. The output +is printed to the current debug file (defaulting to standard error, +*note Debug Output::). + + $ m4 -d + define(`foo', `Hello World.') + => + define(`echo', `$@') + => + traceon(`foo', `echo') + => + foo + error-->m4trace: -1- foo -> `Hello World.' + =>Hello World. + echo(`gnus', `and gnats') + error-->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats'' + =>gnus,and gnats + + The number between dashes is the depth of the expansion. It is one +most of the time, signifying an expansion at the outermost level, but it +increases when macro arguments contain unquoted macro calls. The +maximum number that will appear between dashes is controlled by the +option `--nesting-limit' (or `-L', *note Invoking m4: Limits control.). +Additionally, the option `--trace' (or `-t') can be used to invoke +`traceon(NAME)' before parsing input. + + $ m4 -L 3 -t ifelse + ifelse(`one level') + error-->m4trace: -1- ifelse + => + ifelse(ifelse(ifelse(`three levels'))) + error-->m4trace: -3- ifelse + error-->m4trace: -2- ifelse + error-->m4trace: -1- ifelse + => + ifelse(ifelse(ifelse(ifelse(`four levels')))) + error-->m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it + + Tracing by name is an attribute that is preserved whether the macro +is defined or not. This allows the selection of macros to trace before +those macros are defined. + + $ m4 -d + traceoff(`foo') + => + traceon(`foo') + => + foo + =>foo + defn(`foo') + => + define(`foo', `bar') + => + foo + error-->m4trace: -1- foo -> `bar' + =>bar + undefine(`foo') + => + ifdef(`foo', `yes', `no') + =>no + indir(`foo') + error-->m4:stdin:9: undefined macro `foo' + => + define(`foo', `blah') + => + foo + error-->m4trace: -1- foo -> `blah' + =>blah + traceoff + => + foo + =>blah + + Tracing even works on builtins. However, `defn' (*note Defn::) does +not transfer tracing status. + + $ m4 -d + traceon(`traceon') + => + traceon(`traceoff') + error-->m4trace: -1- traceon(`traceoff') + => + traceoff(`traceoff') + error-->m4trace: -1- traceoff(`traceoff') + => + traceoff(`traceon') + => + traceon(`eval', `m4_divnum') + => + define(`m4_eval', defn(`eval')) + => + define(`m4_divnum', defn(`divnum')) + => + eval(divnum) + error-->m4trace: -1- eval(`0') -> `0' + =>0 + m4_eval(m4_divnum) + error-->m4trace: -2- m4_divnum -> `0' + =>0 + + *Note Debug Levels::, for information on controlling the details of +the display. The format of the trace output is not specified by POSIX, +and varies between implementations of `m4'. + + +File: m4.info, Node: Debug Levels, Next: Debug Output, Prev: Trace, Up: Debugging + +7.3 Controlling debugging output +================================ + +The `-d' option to `m4' (or `--debug', *note Invoking m4: Debugging +options.) controls the amount of details presented in three categories +of output. Trace output is requested by `traceon' (*note Trace::), and +each line is prefixed by `m4trace:' in relation to a macro invocation. +Debug output tracks useful events not associated with a macro +invocation, and each line is prefixed by `m4debug:'. Finally, +`dumpdef' (*note Dumpdef::) output is affected, with no prefix added to +the output lines. + + The FLAGS following the option can be one or more of the following: + +`a' + In trace output, show the actual arguments that were collected + before invoking the macro. This applies to all macro calls if the + `t' flag is used, otherwise only the macros covered by calls of + `traceon'. Arguments are subject to length truncation specified by + the command line option `--arglength' (or `-l'). + +`c' + In trace output, show several trace lines for each macro call. A + line is shown when the macro is seen, but before the arguments are + collected; a second line when the arguments have been collected + and a third line after the call has completed. + +`e' + In trace output, show the expansion of each macro call, if it is + not void. This applies to all macro calls if the `t' flag is used, + otherwise only the macros covered by calls of `traceon'. The + expansion is subject to length truncation specified by the command + line option `--arglength' (or `-l'). + +`f' + In debug and trace output, include the name of the current input + file in the output line. + +`i' + In debug output, print a message each time the current input file + is changed. + +`l' + In debug and trace output, include the current input line number + in the output line. + +`p' + In debug output, print a message when a named file is found + through the path search mechanism (*note Search Path::), giving + the actual file name used. + +`q' + In trace and dumpdef output, quote actual arguments and macro + expansions in the display with the current quotes. This is useful + in connection with the `a' and `e' flags above. + +`t' + In trace output, trace all macro calls made in this invocation of + `m4', regardless of the settings of `traceon'. + +`x' + In trace output, add a unique `macro call id' to each line of the + trace output. This is useful in connection with the `c' flag + above. + +`V' + A shorthand for all of the above flags. + + If no flags are specified with the `-d' option, the default is +`aeq'. The examples throughout this manual assume the default flags. + + There is a builtin macro `debugmode', which allows on-the-fly +control of the debugging output format: + + -- Builtin: debugmode ([FLAGS]) + The argument FLAGS should be a subset of the letters listed above. + As special cases, if the argument starts with a `+', the flags are + added to the current debug flags, and if it starts with a `-', they + are removed. If no argument is present, all debugging flags are + cleared (as if no `-d' was given), and with an empty argument the + flags are reset to the default of `aeq'. + + The expansion of `debugmode' is void. + + $ m4 + define(`foo', `FOO') + => + traceon(`foo') + => + debugmode() + => + foo + error-->m4trace: -1- foo -> `FOO' + =>FOO + debugmode + => + foo + error-->m4trace: -1- foo + =>FOO + debugmode(`+l') + => + foo + error-->m4trace:8: -1- foo + =>FOO + + The following example demonstrates the behavior of length truncation, +when specified on the command line. Note that each argument and the +final result are individually truncated. Also, the special tokens for +builtin functions are not truncated. + + $ m4 -d -l 6 + define(`echo', `$@')debugmode(`+t') + => + echo(`1', `long string') + error-->m4trace: -1- echo(`1', `long s...') -> ``1',`l...' + =>1,long string + indir(`echo', defn(`changequote')) + error-->m4trace: -2- defn(`change...') + error-->m4trace: -1- indir(`echo', <changequote>) -> ``'' + => + + This example shows the effects of the debug flags that are not +related to macro tracing. + + $ m4 -dip -I examples + error-->m4debug: input read from stdin + include(`foo')dnl + error-->m4debug: path search for `foo' found `examples/foo' + error-->m4debug: input read from examples/foo + =>bar + error-->m4debug: input reverted to stdin, line 1 + ^D + error-->m4debug: input exhausted + + +File: m4.info, Node: Debug Output, Prev: Debug Levels, Up: Debugging + +7.4 Saving debugging output +=========================== + +Debug and tracing output can be redirected to files using either the +`--debugfile' option to `m4' (*note Invoking m4: Debugging options.), +or with the builtin macro `debugfile': + + -- Builtin: debugfile ([FILE]) + Sends all further debug and trace output to FILE, opened in append + mode. If FILE is the empty string, debug and trace output are + discarded. If `debugfile' is called without any arguments, debug + and trace output are sent to standard error. This does not affect + warnings, error messages, or `errprint' output, which are always + sent to standard error. If FILE cannot be opened, the current + debug file is unchanged, and an error is issued. + + The expansion of `debugfile' is void. + + $ m4 -d + traceon(`divnum') + => + divnum(`extra') + error-->m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored + error-->m4trace: -1- divnum(`extra') -> `0' + =>0 + debugfile() + => + divnum(`extra') + error-->m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored + =>0 + debugfile + => + divnum + error-->m4trace: -1- divnum -> `0' + =>0 + + +File: m4.info, Node: Input Control, Next: File Inclusion, Prev: Debugging, Up: Top + +8 Input control +*************** + +This chapter describes various builtin macros for controlling the input +to `m4'. + +* Menu: + +* Dnl:: Deleting whitespace in input +* Changequote:: Changing the quote characters +* Changecom:: Changing the comment delimiters +* Changeword:: Changing the lexical structure of words +* M4wrap:: Saving text until end of input + + +File: m4.info, Node: Dnl, Next: Changequote, Up: Input Control + +8.1 Deleting whitespace in input +================================ + +The builtin `dnl' stands for "Discard to Next Line": + + -- Builtin: dnl + All characters, up to and including the next newline, are discarded + without performing any macro expansion. A warning is issued if + the end of the file is encountered without a newline. + + The expansion of `dnl' is void. + + It is often used in connection with `define', to remove the newline +that follows the call to `define'. Thus + + define(`foo', `Macro `foo'.')dnl A very simple macro, indeed. + foo + =>Macro foo. + + The input up to and including the next newline is discarded, as +opposed to the way comments are treated (*note Comments::). + + Usually, `dnl' is immediately followed by an end of line or some +other whitespace. GNU `m4' will produce a warning diagnostic if `dnl' +is followed by an open parenthesis. In this case, `dnl' will collect +and process all arguments, looking for a matching close parenthesis. +All predictable side effects resulting from this collection will take +place. `dnl' will return no output. The input following the matching +close parenthesis up to and including the next newline, on whatever +line containing it, will still be discarded. + + dnl(`args are ignored, but side effects occur', + define(`foo', `like this')) while this text is ignored: undefine(`foo') + error-->m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored + See how `foo' was defined, foo? + =>See how foo was defined, like this? + + If the end of file is encountered without a newline character, a +warning is issued and dnl stops consuming input. + + m4wrap(`m4wrap(`2 hi + ')0 hi dnl 1 hi') + => + define(`hi', `HI') + => + ^D + error-->m4:stdin:1: Warning: end of file treated as newline + =>0 HI 2 HI + + +File: m4.info, Node: Changequote, Next: Changecom, Prev: Dnl, Up: Input Control + +8.2 Changing the quote characters +================================= + +The default quote delimiters can be changed with the builtin +`changequote': + + -- Builtin: changequote ([START = ``'], [END = `'']) + This sets START as the new begin-quote delimiter and END as the + new end-quote delimiter. If both arguments are missing, the + default quotes (``' and `'') are used. If START is void, then + quoting is disabled. Otherwise, if END is missing or void, the + default end-quote delimiter (`'') is used. The quote delimiters + can be of any length. + + The expansion of `changequote' is void. + + changequote(`[', `]') + => + define([foo], [Macro [foo].]) + => + foo + =>Macro foo. + + The quotation strings can safely contain eight-bit characters. If +no single character is appropriate, START and END can be of any length. +Other implementations cap the delimiter length to five characters, but +GNU has no inherent limit. + + changequote(`[[[', `]]]') + => + define([[[foo]]], [[[Macro [[[[[foo]]]]].]]]) + => + foo + =>Macro [[foo]]. + + Calling `changequote' with START as the empty string will +effectively disable the quoting mechanism, leaving no way to quote text. +However, using an empty string is not portable, as some other +implementations of `m4' revert to the default quoting, while others +preserve the prior non-empty delimiter. If START is not empty, then an +empty END will use the default end-quote delimiter of `'', as +otherwise, it would be impossible to end a quoted string. Again, this +is not portable, as some other `m4' implementations reuse START as the +end-quote delimiter, while others preserve the previous non-empty +value. Omitting both arguments restores the default begin-quote and +end-quote delimiters; fortunately this behavior is portable to all +implementations of `m4'. + + define(`foo', `Macro `FOO'.') + => + changequote(`', `') + => + foo + =>Macro `FOO'. + `foo' + =>`Macro `FOO'.' + changequote(`,) + => + foo + =>Macro FOO. + + There is no way in `m4' to quote a string containing an unmatched +begin-quote, except using `changequote' to change the current quotes. + + If the quotes should be changed from, say, `[' to `[[', temporary +quote characters have to be defined. To achieve this, two calls of +`changequote' must be made, one for the temporary quotes and one for +the new quotes. + + Macros are recognized in preference to the begin-quote string, so if +a prefix of START can be recognized as part of a potential macro name, +the quoting mechanism is effectively disabled. Unless you use +`changeword' (*note Changeword::), this means that START should not +begin with a letter, digit, or `_' (underscore). However, even though +quoted strings are not recognized, the quote characters can still be +discerned in macro expansion and in trace output. + + define(`echo', `$@') + => + define(`hi', `HI') + => + changequote(`q', `Q') + => + q hi Q hi + =>q HI Q HI + echo(hi) + =>qHIQ + changequote + => + changequote(`-', `EOF') + => + - hi EOF hi + => hi HI + changequote + => + changequote(`1', `2') + => + hi1hi2 + =>hi1hi2 + hi 1hi2 + =>HI hi + + Quotes are recognized in preference to argument collection. In +particular, if START is a single `(', then argument collection is +effectively disabled. For portability with other implementations, it +is a good idea to avoid `(', `,', and `)' as the first character in +START. + + define(`echo', `$#:$@:') + => + define(`hi', `HI') + => + changequote(`(',`)') + => + echo(hi) + =>0::hi + changequote + => + changequote(`((', `))') + => + echo(hi) + =>1:HI: + echo((hi)) + =>0::hi + changequote + => + changequote(`,', `)') + => + echo(hi,hi)bye) + =>1:HIhibye: + + However, if you are not worried about portability, using `(' and `)' +as quoting characters has an interesting property--you can use it to +compute a quoted string containing the expansion of any quoted text, as +long as the expansion results in both balanced quotes and balanced +parentheses. The trick is realizing `expand' uses `$1' unquoted, to +trigger its expansion using the normal quoting characters, but uses +extra parentheses to group unquoted commas that occur in the expansion +without consuming whitespace following those commas. Then `_expand' +uses `changequote' to convert the extra parentheses back into quoting +characters. Note that it takes two more `changequote' invocations to +restore the original quotes. Contrast the behavior on whitespace when +using `$*', via `quote', to attempt the same task. + + changequote(`[', `]')dnl + define([a], [1, (b)])dnl + define([b], [2])dnl + define([quote], [[$*]])dnl + define([expand], [_$0(($1))])dnl + define([_expand], + [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl + expand([a, a, [a, a], [[a, a]]]) + =>1, (2), 1, (2), a, a, [a, a] + quote(a, a, [a, a], [[a, a]]) + =>1,(2),1,(2),a, a,[a, a] + + If END is a prefix of START, the end-quote will be recognized in +preference to a nested begin-quote. In particular, changing the quotes +to have the same string for START and END disables nesting of quotes. +When quote nesting is disabled, it is impossible to double-quote +strings across macro expansions, so using the same string is not done +very often. + + define(`hi', `HI') + => + changequote(`""', `"') + => + ""hi"""hi" + =>hihi + ""hi" ""hi" + =>hi hi + ""hi"" "hi" + =>hi" "HI" + changequote + => + `hi`hi'hi' + =>hi`hi'hi + changequote(`"', `"') + => + "hi"hi"hi" + =>hiHIhi + + It is an error if the end of file occurs within a quoted string. + + `hello world' + =>hello world + `dangling quote + ^D + error-->m4:stdin:2: ERROR: end of file in string + + ifelse(`dangling quote + ^D + error-->m4:stdin:1: ERROR: end of file in string + + +File: m4.info, Node: Changecom, Next: Changeword, Prev: Changequote, Up: Input Control + +8.3 Changing the comment delimiters +=================================== + +The default comment delimiters can be changed with the builtin macro +`changecom': + + -- Builtin: changecom ([START], [END = `<NL>']) + This sets START as the new begin-comment delimiter and END as the + new end-comment delimiter. If both arguments are missing, or + START is void, then comments are disabled. Otherwise, if END is + missing or void, the default end-comment delimiter of newline is + used. The comment delimiters can be of any length. + + The expansion of `changecom' is void. + + define(`comment', `COMMENT') + => + # A normal comment + =># A normal comment + changecom(`/*', `*/') + => + # Not a comment anymore + =># Not a COMMENT anymore + But: /* this is a comment now */ while this is not a comment + =>But: /* this is a comment now */ while this is not a COMMENT + + Note how comments are copied to the output, much as if they were +quoted strings. If you want the text inside a comment expanded, quote +the begin-comment delimiter. + + Calling `changecom' without any arguments, or with START as the +empty string, will effectively disable the commenting mechanism. To +restore the original comment start of `#', you must explicitly ask for +it. If START is not empty, then an empty END will use the default +end-comment delimiter of newline, as otherwise, it would be impossible +to end a comment. However, this is not portable, as some other `m4' +implementations preserve the previous non-empty delimiters instead. + + define(`comment', `COMMENT') + => + changecom + => + # Not a comment anymore + =># Not a COMMENT anymore + changecom(`#', `') + => + # comment again + =># comment again + + The comment strings can safely contain eight-bit characters. If no +single character is appropriate, START and END can be of any length. +Other implementations cap the delimiter length to five characters, but +GNU has no inherent limit. + + Comments are recognized in preference to macros. However, this is +not compatible with other implementations, where macros and even quoting +takes precedence over comments, so it may change in a future release. +For portability, this means that START should not begin with a letter, +digit, or `_' (underscore), and that neither the start-quote nor the +start-comment string should be a prefix of the other. + + define(`hi', `HI') + => + define(`hi1hi2', `hello') + => + changecom(`q', `Q') + => + q hi Q hi + =>q hi Q HI + changecom(`1', `2') + => + hi1hi2 + =>hello + hi 1hi2 + =>HI 1hi2 + + Comments are recognized in preference to argument collection. In +particular, if START is a single `(', then argument collection is +effectively disabled. For portability with other implementations, it +is a good idea to avoid `(', `,', and `)' as the first character in +START. + + define(`echo', `$#:$*:$@:') + => + define(`hi', `HI') + => + changecom(`(',`)') + => + echo(hi) + =>0:::(hi) + changecom + => + changecom(`((', `))') + => + echo(hi) + =>1:HI:HI: + echo((hi)) + =>0:::((hi)) + changecom(`,', `)') + => + echo(hi,hi)bye) + =>1:HI,hi)bye:HI,hi)bye: + changecom + => + echo(hi,`,`'hi',hi) + =>3:HI,,HI,HI:HI,,`'hi,HI: + echo(hi,`,`'hi',hi`'changecom(`,,', `hi')) + =>3:HI,,`'hi,HI:HI,,`'hi,HI: + + It is an error if the end of file occurs within a comment. + + changecom(`/*', `*/') + => + /*dangling comment + ^D + error-->m4:stdin:2: ERROR: end of file in comment + + +File: m4.info, Node: Changeword, Next: M4wrap, Prev: Changecom, Up: Input Control + +8.4 Changing the lexical structure of words +=========================================== + + The macro `changeword' and all associated functionality is + experimental. It is only available if the `--enable-changeword' + option was given to `configure', at GNU `m4' installation time. + The functionality will go away in the future, to be replaced by + other new features that are more efficient at providing the same + capabilities. _Do not rely on it_. Please direct your comments + about it the same way you would do for bugs. + + A file being processed by `m4' is split into quoted strings, words +(potential macro names) and simple tokens (any other single character). +Initially a word is defined by the following regular expression: + + [_a-zA-Z][_a-zA-Z0-9]* + + Using `changeword', you can change this regular expression: + + -- Optional builtin: changeword (REGEX) + Changes the regular expression for recognizing macro names to be + REGEX. If REGEX is empty, use `[_a-zA-Z][_a-zA-Z0-9]*'. REGEX + must obey the constraint that every prefix of the desired final + pattern is also accepted by the regular expression. If REGEX + contains grouping parentheses, the macro invoked is the portion + that matched the first group, rather than the entire matching + string. + + The expansion of `changeword' is void. The macro `changeword' is + recognized only with parameters. + + Relaxing the lexical rules of `m4' might be useful (for example) if +you wanted to apply translations to a file of numbers: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + changeword(`[_a-zA-Z0-9]+') + => + define(`1', `0')1 + =>0 + + Tightening the lexical rules is less useful, because it will +generally make some of the builtins unavailable. You could use it to +prevent accidental call of builtins, for example: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + define(`_indir', defn(`indir')) + => + changeword(`_[_a-zA-Z0-9]*') + => + esyscmd(`foo') + =>esyscmd(foo) + _indir(`esyscmd', `echo hi') + =>hi + => + + Because `m4' constructs its words a character at a time, there is a +restriction on the regular expressions that may be passed to +`changeword'. This is that if your regular expression accepts `foo', +it must also accept `f' and `fo'. + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + define(`foo + ', `bar + ') + => + dnl This example wants to recognize changeword, dnl, and `foo\n'. + dnl First, we check that our regexp will match. + regexp(`changeword', `[cd][a-z]*\|foo[ + ]') + =>0 + regexp(`foo + ', `[cd][a-z]*\|foo[ + ]') + =>0 + regexp(`f', `[cd][a-z]*\|foo[ + ]') + =>-1 + foo + =>foo + changeword(`[cd][a-z]*\|foo[ + ]') + => + dnl Even though `foo\n' matches, we forgot to allow `f'. + foo + =>foo + changeword(`[cd][a-z]*\|fo*[ + ]?') + => + dnl Now we can call `foo\n'. + foo + =>bar + + `changeword' has another function. If the regular expression +supplied contains any grouped subexpressions, then text outside the +first of these is discarded before symbol lookup. So: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics + ')m4exit(`77')')dnl + changecom(`/*', `*/')dnl + define(`foo', `bar')dnl + changeword(`#\([_a-zA-Z0-9]*\)') + => + #esyscmd(`echo foo \#foo') + =>foo bar + => + + `m4' now requires a `#' mark at the beginning of every macro +invocation, so one can use `m4' to preprocess plain text without losing +various words like `divert'. + + In `m4', macro substitution is based on text, while in TeX, it is +based on tokens. `changeword' can throw this difference into relief. +For example, here is the same idea represented in TeX and `m4'. First, +the TeX version: + + \def\a{\message{Hello}} + \catcode`\@=0 + \catcode`\\=12 + @a + @bye + =>Hello + +Then, the `m4' version: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + define(`a', `errprint(`Hello')')dnl + changeword(`@\([_a-zA-Z0-9]*\)') + => + @a + =>errprint(Hello) + + In the TeX example, the first line defines a macro `a' to print the +message `Hello'. The second line defines <@> to be usable instead of +<\> as an escape character. The third line defines <\> to be a normal +printing character, not an escape. The fourth line invokes the macro +`a'. So, when TeX is run on this file, it displays the message `Hello'. + + When the `m4' example is passed through `m4', it outputs +`errprint(Hello)'. The reason for this is that TeX does lexical +analysis of macro definition when the macro is _defined_. `m4' just +stores the text, postponing the lexical analysis until the macro is +_used_. + + You should note that using `changeword' will slow `m4' down by a +factor of about seven, once it is changed to something other than the +default regular expression. You can invoke `changeword' with the empty +string to restore the default word definition, and regain the parsing +speed. + + +File: m4.info, Node: M4wrap, Prev: Changeword, Up: Input Control + +8.5 Saving text until end of input +================================== + +It is possible to `save' some text until the end of the normal input has +been seen. Text can be saved, to be read again by `m4' when the normal +input has been exhausted. This feature is normally used to initiate +cleanup actions before normal exit, e.g., deleting temporary files. + + To save input text, use the builtin `m4wrap': + + -- Builtin: m4wrap (STRING, ...) + Stores STRING in a safe place, to be reread when end of input is + reached. As a GNU extension, additional arguments are + concatenated with a space to the STRING. + + The expansion of `m4wrap' is void. The macro `m4wrap' is + recognized only with parameters. + + define(`cleanup', `This is the `cleanup' action. + ') + => + m4wrap(`cleanup') + => + This is the first and last normal input line. + =>This is the first and last normal input line. + ^D + =>This is the cleanup action. + + The saved input is only reread when the end of normal input is seen, +and not if `m4exit' is used to exit `m4'. + + It is safe to call `m4wrap' from saved text, but then the order in +which the saved text is reread is undefined. If `m4wrap' is not used +recursively, the saved pieces of text are reread in the opposite order +in which they were saved (LIFO--last in, first out). However, this +behavior is likely to change in a future release, to match POSIX, so +you should not depend on this order. + + It is possible to emulate POSIX behavior even with older versions of +GNU M4 by including the file `m4-1.4.16/examples/wrapfifo.m4' from the +distribution: + + $ m4 -I examples + undivert(`wrapfifo.m4')dnl + =>dnl Redefine m4wrap to have FIFO semantics. + =>define(`_m4wrap_level', `0')dnl + =>define(`m4wrap', + =>`ifdef(`m4wrap'_m4wrap_level, + => `define(`m4wrap'_m4wrap_level, + => defn(`m4wrap'_m4wrap_level)`$1')', + => `builtin(`m4wrap', `define(`_m4wrap_level', + => incr(_m4wrap_level))dnl + =>m4wrap'_m4wrap_level)dnl + =>define(`m4wrap'_m4wrap_level, `$1')')')dnl + include(`wrapfifo.m4') + => + m4wrap(`a`'m4wrap(`c + ', `d')')m4wrap(`b') + => + ^D + =>abc + + It is likewise possible to emulate LIFO behavior without resorting to +the GNU M4 extension of `builtin', by including the file +`m4-1.4.16/examples/wraplifo.m4' from the distribution. +(Unfortunately, both examples shown here share some subtle bugs. See +if you can find and correct them; or *note Answers: Improved m4wrap.). + + $ m4 -I examples + undivert(`wraplifo.m4')dnl + =>dnl Redefine m4wrap to have LIFO semantics. + =>define(`_m4wrap_level', `0')dnl + =>define(`_m4wrap', defn(`m4wrap'))dnl + =>define(`m4wrap', + =>`ifdef(`m4wrap'_m4wrap_level, + => `define(`m4wrap'_m4wrap_level, + => `$1'defn(`m4wrap'_m4wrap_level))', + => `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl + =>m4wrap'_m4wrap_level)dnl + =>define(`m4wrap'_m4wrap_level, `$1')')')dnl + include(`wraplifo.m4') + => + m4wrap(`a`'m4wrap(`c + ', `d')')m4wrap(`b') + => + ^D + =>bac + + Here is an example of implementing a factorial function using +`m4wrap': + + define(`f', `ifelse(`$1', `0', `Answer: 0!=1 + ', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1') + ', `m4wrap(`f(decr(`$1'), `$2$1*')')')') + => + f(`10') + => + ^D + =>Answer: 10*9*8*7*6*5*4*3*2*1=3628800 + + Invocations of `m4wrap' at the same recursion level are concatenated +and rescanned as usual: + + define(`aa', `AA + ') + => + m4wrap(`a')m4wrap(`a') + => + ^D + =>AA + +however, the transition between recursion levels behaves like an end of +file condition between two input files. + + m4wrap(`m4wrap(`)')len(abc') + => + ^D + error-->m4:stdin:1: ERROR: end of file in argument list + + +File: m4.info, Node: File Inclusion, Next: Diversions, Prev: Input Control, Up: Top + +9 File inclusion +**************** + +`m4' allows you to include named files at any point in the input. + +* Menu: + +* Include:: Including named files +* Search Path:: Searching for include files + + +File: m4.info, Node: Include, Next: Search Path, Up: File Inclusion + +9.1 Including named files +========================= + +There are two builtin macros in `m4' for including files: + + -- Builtin: include (FILE) + -- Builtin: sinclude (FILE) + Both macros cause the file named FILE to be read by `m4'. When + the end of the file is reached, input is resumed from the previous + input file. + + The expansion of `include' and `sinclude' is therefore the + contents of FILE. + + If FILE does not exist, is a directory, or cannot otherwise be + read, the expansion is void, and `include' will fail with an error + while `sinclude' is silent. The empty string counts as a file + that does not exist. + + The macros `include' and `sinclude' are recognized only with + parameters. + + include(`none') + error-->m4:stdin:1: cannot open `none': No such file or directory + => + include() + error-->m4:stdin:2: cannot open `': No such file or directory + => + sinclude(`none') + => + sinclude() + => + + The rest of this section assumes that `m4' is invoked with the `-I' +option (*note Invoking m4: Preprocessor features.) pointing to the +`m4-1.4.16/examples' directory shipped as part of the GNU `m4' package. +The file `m4-1.4.16/examples/incl.m4' in the distribution contains the +lines: + + $ cat examples/incl.m4 + =>Include file start + =>foo + =>Include file end + + Normally file inclusion is used to insert the contents of a file +into the input stream. The contents of the file will be read by `m4' +and macro calls in the file will be expanded: + + $ m4 -I examples + define(`foo', `FOO') + => + include(`incl.m4') + =>Include file start + =>FOO + =>Include file end + => + + The fact that `include' and `sinclude' expand to the contents of the +file can be used to define macros that operate on entire files. Here +is an example, which defines `bar' to expand to the contents of +`incl.m4': + + $ m4 -I examples + define(`bar', include(`incl.m4')) + => + This is `bar': >>bar<< + =>This is bar: >>Include file start + =>foo + =>Include file end + =><< + + This use of `include' is not trivial, though, as files can contain +quotes, commas, and parentheses, which can interfere with the way the +`m4' parser works. GNU `m4' seamlessly concatenates the file contents +with the next character, even if the included file ended in the middle +of a comment, string, or macro call. These conditions are only treated +as end of file errors if specified as input files on the command line. + + In GNU `m4', an alternative method of reading files is using +`undivert' (*note Undivert::) on a named file. + + +File: m4.info, Node: Search Path, Prev: Include, Up: File Inclusion + +9.2 Searching for include files +=============================== + +GNU `m4' allows included files to be found in other directories than +the current working directory. + + If the `--prepend-include' or `-B' command-line option was provided +(*note Invoking m4: Preprocessor features.), those directories are +searched first, in reverse order that those options were listed on the +command line. Then `m4' looks in the current working directory. Next +comes the directories specified with the `--include' or `-I' option, in +the order found on the command line. Finally, if the `M4PATH' +environment variable is set, it is expected to contain a +colon-separated list of directories, which will be searched in order. + + If the automatic search for include-files causes trouble, the `p' +debug flag (*note Debug Levels::) can help isolate the problem. + + +File: m4.info, Node: Diversions, Next: Text handling, Prev: File Inclusion, Up: Top + +10 Diverting and undiverting output +*********************************** + +Diversions are a way of temporarily saving output. The output of `m4' +can at any time be diverted to a temporary file, and be reinserted into +the output stream, "undiverted", again at a later time. + + Numbered diversions are counted from 0 upwards, diversion number 0 +being the normal output stream. GNU `m4' tries to keep diversions in +memory. However, there is a limit to the overall memory usable by all +diversions taken together (512K, currently). When this maximum is +about to be exceeded, a temporary file is opened to receive the +contents of the biggest diversion still in memory, freeing this memory +for other diversions. When creating the temporary file, `m4' honors +the value of the environment variable `TMPDIR', and falls back to +`/tmp'. Thus, the amount of available disk space provides the only +real limit on the number and aggregate size of diversions. + + Diversions make it possible to generate output in a different order +than the input was read. It is possible to implement topological +sorting dependencies. For example, GNU Autoconf makes use of +diversions under the hood to ensure that the expansion of a prerequisite +macro appears in the output prior to the expansion of a dependent macro, +regardless of which order the two macros were invoked in the user's +input file. + +* Menu: + +* Divert:: Diverting output +* Undivert:: Undiverting output +* Divnum:: Diversion numbers +* Cleardivert:: Discarding diverted text + + +File: m4.info, Node: Divert, Next: Undivert, Up: Diversions + +10.1 Diverting output +===================== + +Output is diverted using `divert': + + -- Builtin: divert ([NUMBER = `0']) + The current diversion is changed to NUMBER. If NUMBER is left out + or empty, it is assumed to be zero. If NUMBER cannot be parsed, + the diversion is unchanged. + + The expansion of `divert' is void. + + When all the `m4' input will have been processed, all existing +diversions are automatically undiverted, in numerical order. + + divert(`1') + This text is diverted. + divert + => + This text is not diverted. + =>This text is not diverted. + ^D + => + =>This text is diverted. + + Several calls of `divert' with the same argument do not overwrite +the previous diverted text, but append to it. Diversions are printed +after any wrapped text is expanded. + + define(`text', `TEXT') + => + divert(`1')`diverted text.' + divert + => + m4wrap(`Wrapped text precedes ') + => + ^D + =>Wrapped TEXT precedes diverted text. + + If output is diverted to a negative diversion, it is simply +discarded. This can be used to suppress unwanted output. A common +example of unwanted output is the trailing newlines after macro +definitions. Here is a common programming idiom in `m4' for avoiding +them. + + divert(`-1') + define(`foo', `Macro `foo'.') + define(`bar', `Macro `bar'.') + divert + => + + Traditional implementations only supported ten diversions. But as a +GNU extension, diversion numbers can be as large as positive integers +will allow, rather than treating a multi-digit diversion number as a +request to discard text. + + divert(eval(`1<<28'))world + divert(`2')hello + ^D + =>hello + =>world + + Note that `divert' is an English word, but also an active macro +without arguments. When processing plain text, the word might appear in +normal text and be unintentionally swallowed as a macro invocation. One +way to avoid this is to use the `-P' option to rename all builtins +(*note Invoking m4: Operation modes.). Another is to write a wrapper +that requires a parameter to be recognized. + + We decided to divert the stream for irrigation. + =>We decided to the stream for irrigation. + define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@)')') + => + divert(`-1') + Ignored text. + divert(`0') + => + We decided to divert the stream for irrigation. + =>We decided to divert the stream for irrigation. + + +File: m4.info, Node: Undivert, Next: Divnum, Prev: Divert, Up: Diversions + +10.2 Undiverting output +======================= + +Diverted text can be undiverted explicitly using the builtin `undivert': + + -- Builtin: undivert ([DIVERSIONS...]) + Undiverts the numeric DIVERSIONS given by the arguments, in the + order given. If no arguments are supplied, all diversions are + undiverted, in numerical order. + + As a GNU extension, DIVERSIONS may contain non-numeric strings, + which are treated as the names of files to copy into the output + without expansion. A warning is issued if a file could not be + opened. + + The expansion of `undivert' is void. + + divert(`1') + This text is diverted. + divert + => + This text is not diverted. + =>This text is not diverted. + undivert(`1') + => + =>This text is diverted. + => + + Notice the last two blank lines. One of them comes from the newline +following `undivert', the other from the newline that followed the +`divert'! A diversion often starts with a blank line like this. + + When diverted text is undiverted, it is _not_ reread by `m4', but +rather copied directly to the current output, and it is therefore not +an error to undivert into a diversion. Undiverting the empty string is +the same as specifying diversion 0; in either case nothing happens +since the output has already been flushed. + + divert(`1')diverted text + divert + => + undivert() + => + undivert(`0') + => + undivert + =>diverted text + => + divert(`1')more + divert(`2')undivert(`1')diverted text`'divert + => + undivert(`1') + => + undivert(`2') + =>more + =>diverted text + + When a diversion has been undiverted, the diverted text is discarded, +and it is not possible to bring back diverted text more than once. + + divert(`1') + This text is diverted first. + divert(`0')undivert(`1')dnl + => + =>This text is diverted first. + undivert(`1') + => + divert(`1') + This text is also diverted but not appended. + divert(`0')undivert(`1')dnl + => + =>This text is also diverted but not appended. + + Attempts to undivert the current diversion are silently ignored. +Thus, when the current diversion is not 0, the current diversion does +not get rearranged among the other diversions. + + divert(`1')one + divert(`2')two + divert(`3')three + divert(`2')undivert`'dnl + divert`'undivert`'dnl + =>two + =>one + =>three + + GNU `m4' allows named files to be undiverted. Given a non-numeric +argument, the contents of the file named will be copied, uninterpreted, +to the current output. This complements the builtin `include' (*note +Include::). To illustrate the difference, assume the file `foo' +contains: + + $ cat foo + bar + +then + + define(`bar', `BAR') + => + undivert(`foo') + =>bar + => + include(`foo') + =>BAR + => + + If the file is not found (or cannot be read), an error message is +issued, and the expansion is void. It is possible to intermix files +and diversion numbers. + + divert(`1')diversion one + divert(`2')undivert(`foo')dnl + divert(`3')diversion three + divert`'dnl + undivert(`1', `2', `foo', `3')dnl + =>diversion one + =>bar + =>bar + =>diversion three + + +File: m4.info, Node: Divnum, Next: Cleardivert, Prev: Undivert, Up: Diversions + +10.3 Diversion numbers +====================== + +The current diversion is tracked by the builtin `divnum': + + -- Builtin: divnum + Expands to the number of the current diversion. + + Initial divnum + =>Initial 0 + divert(`1') + Diversion one: divnum + divert(`2') + Diversion two: divnum + ^D + => + =>Diversion one: 1 + => + =>Diversion two: 2 + + +File: m4.info, Node: Cleardivert, Prev: Divnum, Up: Diversions + +10.4 Discarding diverted text +============================= + +Often it is not known, when output is diverted, whether the diverted +text is actually needed. Since all non-empty diversion are brought back +on the main output stream when the end of input is seen, a method of +discarding a diversion is needed. If all diversions should be +discarded, the easiest is to end the input to `m4' with `divert(`-1')' +followed by an explicit `undivert': + + divert(`1') + Diversion one: divnum + divert(`2') + Diversion two: divnum + divert(`-1') + undivert + ^D + +No output is produced at all. + + Clearing selected diversions can be done with the following macro: + + -- Composite: cleardivert ([DIVERSIONS...]) + Discard the contents of each of the listed numeric DIVERSIONS. + + define(`cleardivert', + `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')') + => + + It is called just like `undivert', but the effect is to clear the +diversions, given by the arguments. (This macro has a nasty bug! You +should try to see if you can find it and correct it; or *note Answers: +Improved cleardivert.). + + +File: m4.info, Node: Text handling, Next: Arithmetic, Prev: Diversions, Up: Top + +11 Macros for text handling +*************************** + +There are a number of builtins in `m4' for manipulating text in various +ways, extracting substrings, searching, substituting, and so on. + +* Menu: + +* Len:: Calculating length of strings +* Index macro:: Searching for substrings +* Regexp:: Searching for regular expressions +* Substr:: Extracting substrings +* Translit:: Translating characters +* Patsubst:: Substituting text by regular expression +* Format:: Formatting strings (printf-like) + + +File: m4.info, Node: Len, Next: Index macro, Up: Text handling + +11.1 Calculating length of strings +================================== + +The length of a string can be calculated by `len': + + -- Builtin: len (STRING) + Expands to the length of STRING, as a decimal number. + + The macro `len' is recognized only with parameters. + + len() + =>0 + len(`abcdef') + =>6 + + +File: m4.info, Node: Index macro, Next: Regexp, Prev: Len, Up: Text handling + +11.2 Searching for substrings +============================= + +Searching for substrings is done with `index': + + -- Builtin: index (STRING, SUBSTRING) + Expands to the index of the first occurrence of SUBSTRING in + STRING. The first character in STRING has index 0. If SUBSTRING + does not occur in STRING, `index' expands to `-1'. + + The macro `index' is recognized only with parameters. + + index(`gnus, gnats, and armadillos', `nat') + =>7 + index(`gnus, gnats, and armadillos', `dag') + =>-1 + + Omitting SUBSTRING evokes a warning, but still produces output; +contrast this with an empty SUBSTRING. + + index(`abc') + error-->m4:stdin:1: Warning: too few arguments to builtin `index' + =>0 + index(`abc', `') + =>0 + index(`abc', `b') + =>1 + + +File: m4.info, Node: Regexp, Next: Substr, Prev: Index macro, Up: Text handling + +11.3 Searching for regular expressions +====================================== + +Searching for regular expressions is done with the builtin `regexp': + + -- Builtin: regexp (STRING, REGEXP, [REPLACEMENT]) + Searches for REGEXP in STRING. The syntax for regular expressions + is the same as in GNU Emacs, which is similar to BRE, Basic + Regular Expressions in POSIX. *Note Syntax of Regular + Expressions: (emacs)Regexps. Support for ERE, Extended Regular + Expressions is not available, but will be added in GNU M4 2.0. + + If REPLACEMENT is omitted, `regexp' expands to the index of the + first match of REGEXP in STRING. If REGEXP does not match + anywhere in STRING, it expands to -1. + + If REPLACEMENT is supplied, and there was a match, `regexp' + changes the expansion to this argument, with `\N' substituted by + the text matched by the Nth parenthesized sub-expression of + REGEXP, up to nine sub-expressions. The escape `\&' is replaced + by the text of the entire regular expression matched. For all + other characters, `\' treats the next character literally. A + warning is issued if there were fewer sub-expressions than the + `\N' requested, or if there is a trailing `\'. If there was no + match, `regexp' expands to the empty string. + + The macro `regexp' is recognized only with parameters. + + regexp(`GNUs not Unix', `\<[a-z]\w+') + =>5 + regexp(`GNUs not Unix', `\<Q\w*') + =>-1 + regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***') + =>*** Unix *** nix *** + regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***') + => + + Here are some more examples on the handling of backslash: + + regexp(`abc', `\(b\)', `\\\10\a') + =>\b0a + regexp(`abc', `b', `\1\') + error-->m4:stdin:2: Warning: sub-expression 1 not present + error-->m4:stdin:2: Warning: trailing \ ignored in replacement + => + regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6') + error-->m4:stdin:3: Warning: sub-expression 4 not present + error-->m4:stdin:3: Warning: sub-expression 5 not present + error-->m4:stdin:3: Warning: sub-expression 6 not present + =>c + + Omitting REGEXP evokes a warning, but still produces output; +contrast this with an empty REGEXP argument. + + regexp(`abc') + error-->m4:stdin:1: Warning: too few arguments to builtin `regexp' + =>0 + regexp(`abc', `') + =>0 + regexp(`abc', `', `\\def') + =>\def + + +File: m4.info, Node: Substr, Next: Translit, Prev: Regexp, Up: Text handling + +11.4 Extracting substrings +========================== + +Substrings are extracted with `substr': + + -- Builtin: substr (STRING, FROM, [LENGTH]) + Expands to the substring of STRING, which starts at index FROM, + and extends for LENGTH characters, or to the end of STRING, if + LENGTH is omitted. The starting index of a string is always 0. + The expansion is empty if there is an error parsing FROM or + LENGTH, if FROM is beyond the end of STRING, or if LENGTH is + negative. + + The macro `substr' is recognized only with parameters. + + substr(`gnus, gnats, and armadillos', `6') + =>gnats, and armadillos + substr(`gnus, gnats, and armadillos', `6', `5') + =>gnats + + Omitting FROM evokes a warning, but still produces output. + + substr(`abc') + error-->m4:stdin:1: Warning: too few arguments to builtin `substr' + =>abc + substr(`abc',) + error-->m4:stdin:2: empty string treated as 0 in builtin `substr' + =>abc + + +File: m4.info, Node: Translit, Next: Patsubst, Prev: Substr, Up: Text handling + +11.5 Translating characters +=========================== + +Character translation is done with `translit': + + -- Builtin: translit (STRING, CHARS, [REPLACEMENT]) + Expands to STRING, with each character that occurs in CHARS + translated into the character from REPLACEMENT with the same index. + + If REPLACEMENT is shorter than CHARS, the excess characters of + CHARS are deleted from the expansion; if CHARS is shorter, the + excess characters in REPLACEMENT are silently ignored. If + REPLACEMENT is omitted, all characters in STRING that are present + in CHARS are deleted from the expansion. If a character appears + more than once in CHARS, only the first instance is used in making + the translation. Only a single translation pass is made, even if + characters in REPLACEMENT also appear in CHARS. + + As a GNU extension, both CHARS and REPLACEMENT can contain + character-ranges, e.g., `a-z' (meaning all lowercase letters) or + `0-9' (meaning all digits). To include a dash `-' in CHARS or + REPLACEMENT, place it first or last in the entire string, or as + the last character of a range. Back-to-back ranges can share a + common endpoint. It is not an error for the last character in the + range to be `larger' than the first. In that case, the range runs + backwards, i.e., `9-0' means the string `9876543210'. The + expansion of a range is dependent on the underlying encoding of + characters, so using ranges is not always portable between + machines. + + The macro `translit' is recognized only with parameters. + + translit(`GNUs not Unix', `A-Z') + =>s not nix + translit(`GNUs not Unix', `a-z', `A-Z') + =>GNUS NOT UNIX + translit(`GNUs not Unix', `A-Z', `z-a') + =>tmfs not fnix + translit(`+,-12345', `+--1-5', `<;>a-c-a') + =><;>abcba + translit(`abcdef', `aabdef', `bcged') + =>bgced + + In the ASCII encoding, the first example deletes all uppercase +letters, the second converts lowercase to uppercase, and the third +`mirrors' all uppercase letters, while converting them to lowercase. +The two first cases are by far the most common, even though they are not +portable to EBCDIC or other encodings. The fourth example shows a +range ending in `-', as well as back-to-back ranges. The final example +shows that `a' is mapped to `b', not `c'; the resulting `b' is not +further remapped to `g'; the `d' and `e' are swapped, and the `f' is +discarded. + + Omitting CHARS evokes a warning, but still produces output. + + translit(`abc') + error-->m4:stdin:1: Warning: too few arguments to builtin `translit' + =>abc + + +File: m4.info, Node: Patsubst, Next: Format, Prev: Translit, Up: Text handling + +11.6 Substituting text by regular expression +============================================ + +Global substitution in a string is done by `patsubst': + + -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT]) + Searches STRING for matches of REGEXP, and substitutes REPLACEMENT + for each match. The syntax for regular expressions is the same as + in GNU Emacs (*note Regexp::). + + The parts of STRING that are not covered by any match of REGEXP + are copied to the expansion. Whenever a match is found, the + search proceeds from the end of the match, so a character from + STRING will never be substituted twice. If REGEXP matches a + string of zero length, the start position for the search is + incremented, to avoid infinite loops. + + When a replacement is to be made, REPLACEMENT is inserted into the + expansion, with `\N' substituted by the text matched by the Nth + parenthesized sub-expression of PATSUBST, for up to nine + sub-expressions. The escape `\&' is replaced by the text of the + entire regular expression matched. For all other characters, `\' + treats the next character literally. A warning is issued if there + were fewer sub-expressions than the `\N' requested, or if there is + a trailing `\'. + + The REPLACEMENT argument can be omitted, in which case the text + matched by REGEXP is deleted. + + The macro `patsubst' is recognized only with parameters. + + patsubst(`GNUs not Unix', `^', `OBS: ') + =>OBS: GNUs not Unix + patsubst(`GNUs not Unix', `\<', `OBS: ') + =>OBS: GNUs OBS: not OBS: Unix + patsubst(`GNUs not Unix', `\w*', `(\&)') + =>(GNUs)() (not)() (Unix)() + patsubst(`GNUs not Unix', `\w+', `(\&)') + =>(GNUs) (not) (Unix) + patsubst(`GNUs not Unix', `[A-Z][a-z]+') + =>GN not + patsubst(`GNUs not Unix', `not', `NOT\') + error-->m4:stdin:6: Warning: trailing \ ignored in replacement + =>GNUs NOT Unix + + Here is a slightly more realistic example, which capitalizes +individual words or whole sentences, by substituting calls of the macros +`upcase' and `downcase' into the strings. + + -- Composite: upcase (TEXT) + -- Composite: downcase (TEXT) + -- Composite: capitalize (TEXT) + Expand to TEXT, but with capitalization changed: `upcase' changes + all letters to upper case, `downcase' changes all letters to lower + case, and `capitalize' changes the first character of each word to + upper case and the remaining characters to lower case. + + First, an example of their usage, using implementations distributed +in `m4-1.4.16/examples/capitalize.m4'. + + $ m4 -I examples + include(`capitalize.m4') + => + upcase(`GNUs not Unix') + =>GNUS NOT UNIX + downcase(`GNUs not Unix') + =>gnus not unix + capitalize(`GNUs not Unix') + =>Gnus Not Unix + + Now for the implementation. There is a helper macro `_capitalize' +which puts only its first word in mixed case. Then `capitalize' merely +parses out the words, and replaces them with an invocation of +`_capitalize'. (As presented here, the `capitalize' macro has some +subtle flaws. You should try to see if you can find and correct them; +or *note Answers: Improved capitalize.). + + $ m4 -I examples + undivert(`capitalize.m4')dnl + =>divert(`-1') + =># upcase(text) + =># downcase(text) + =># capitalize(text) + =># change case of text, simple version + =>define(`upcase', `translit(`$*', `a-z', `A-Z')') + =>define(`downcase', `translit(`$*', `A-Z', `a-z')') + =>define(`_capitalize', + => `regexp(`$1', `^\(\w\)\(\w*\)', + => `upcase(`\1')`'downcase(`\2')')') + =>define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')') + =>divert`'dnl + + While `regexp' replaces the whole input with the replacement as soon +as there is a match, `patsubst' replaces each _occurrence_ of a match +and preserves non-matching pieces: + + define(`patreg', + `patsubst($@) + regexp($@)')dnl + patreg(`bar foo baz Foo', `foo\|Foo', `FOO') + =>bar FOO baz FOO + =>FOO + patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2') + =>bab abb 212 + =>bab + + Omitting REGEXP evokes a warning, but still produces output; +contrast this with an empty REGEXP argument. + + patsubst(`abc') + error-->m4:stdin:1: Warning: too few arguments to builtin `patsubst' + =>abc + patsubst(`abc', `') + =>abc + patsubst(`abc', `', `\\-') + =>\-a\-b\-c\- + + +File: m4.info, Node: Format, Prev: Patsubst, Up: Text handling + +11.7 Formatting strings (printf-like) +===================================== + +Formatted output can be made with `format': + + -- Builtin: format (FORMAT-STRING, ...) + Works much like the C function `printf'. The first argument + FORMAT-STRING can contain `%' specifications which are satisfied + by additional arguments, and the expansion of `format' is the + formatted string. + + The macro `format' is recognized only with parameters. + + Its use is best described by a few examples: + + define(`foo', `The brown fox jumped over the lazy dog') + => + format(`The string "%s" uses %d characters', foo, len(foo)) + =>The string "The brown fox jumped over the lazy dog" uses 38 characters + format(`%*.*d', `-1', `-1', `1') + =>1 + format(`%.0f', `56789.9876') + =>56790 + len(format(`%-*X', `5000', `1')) + =>5000 + ifelse(format(`%010F', `infinity'), ` INF', `success', + format(`%010F', `infinity'), ` INFINITY', `success', + format(`%010F', `infinity')) + =>success + ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success', + format(`%.1A', `1.999'), `0X2.0P+0', `success', + format(`%.1A', `1.999')) + =>success + format(`%g', `0xa.P+1') + =>20 + + Using the `forloop' macro defined earlier (*note Forloop::), this +example shows how `format' can be used to produce tabular output. + + $ m4 -I examples + include(`forloop.m4') + => + forloop(`i', `1', `10', `format(`%6d squared is %10d + ', i, eval(i**2))') + => 1 squared is 1 + => 2 squared is 4 + => 3 squared is 9 + => 4 squared is 16 + => 5 squared is 25 + => 6 squared is 36 + => 7 squared is 49 + => 8 squared is 64 + => 9 squared is 81 + => 10 squared is 100 + => + + The builtin `format' is modeled after the ANSI C `printf' function, +and supports these `%' specifiers: `c', `s', `d', `o', `x', `X', `u', +`a', `A', `e', `E', `f', `F', `g', `G', and `%'; it supports field +widths and precisions, and the flags `+', `-', ` ', `0', `#', and `''. +For integer specifiers, the width modifiers `hh', `h', and `l' are +recognized, and for floating point specifiers, the width modifier `l' +is recognized. Items not yet supported include positional arguments, +the `n', `p', `S', and `C' specifiers, the `z', `t', `j', `L' and `ll' +modifiers, and any platform extensions available in the native +`printf'. For more details on the functioning of `printf', see the C +Library Manual, or the POSIX specification (for example, `%a' is +supported even on platforms that haven't yet implemented C99 +hexadecimal floating point output natively). + + Unrecognized specifiers result in a warning. It is anticipated that +a future release of GNU `m4' will support more specifiers, and give +better warnings when various problems such as overflow are encountered. +Likewise, escape sequences are not yet recognized. + + format(`%p', `0') + error-->m4:stdin:1: Warning: unrecognized specifier in `%p' + => + + +File: m4.info, Node: Arithmetic, Next: Shell commands, Prev: Text handling, Up: Top + +12 Macros for doing arithmetic +****************************** + +Integer arithmetic is included in `m4', with a C-like syntax. As +convenient shorthands, there are builtins for simple increment and +decrement operations. + +* Menu: + +* Incr:: Decrement and increment operators +* Eval:: Evaluating integer expressions + + +File: m4.info, Node: Incr, Next: Eval, Up: Arithmetic + +12.1 Decrement and increment operators +====================================== + +Increment and decrement of integers are supported using the builtins +`incr' and `decr': + + -- Builtin: incr (NUMBER) + -- Builtin: decr (NUMBER) + Expand to the numerical value of NUMBER, incremented or + decremented, respectively, by one. Except for the empty string, + the expansion is empty if NUMBER could not be parsed. + + The macros `incr' and `decr' are recognized only with parameters. + + incr(`4') + =>5 + decr(`7') + =>6 + incr() + error-->m4:stdin:3: empty string treated as 0 in builtin `incr' + =>1 + decr() + error-->m4:stdin:4: empty string treated as 0 in builtin `decr' + =>-1 + + +File: m4.info, Node: Eval, Prev: Incr, Up: Arithmetic + +12.2 Evaluating integer expressions +=================================== + +Integer expressions are evaluated with `eval': + + -- Builtin: eval (EXPRESSION, [RADIX = `10'], [WIDTH]) + Expands to the value of EXPRESSION. The expansion is empty if a + problem is encountered while parsing the arguments. If specified, + RADIX and WIDTH control the format of the output. + + Calculations are done with 32-bit signed numbers. Overflow + silently results in wraparound. A warning is issued if division + by zero is attempted, or if EXPRESSION could not be parsed. + + Expressions can contain the following operators, listed in order of + decreasing precedence. + + `()' + Parentheses + + `+ - ~ !' + Unary plus and minus, and bitwise and logical negation + + `**' + Exponentiation + + `* / %' + Multiplication, division, and modulo + + `+ -' + Addition and subtraction + + `<< >>' + Shift left or right + + `> >= < <=' + Relational operators + + `== !=' + Equality operators + + `&' + Bitwise and + + `^' + Bitwise exclusive-or + + `|' + Bitwise or + + `&&' + Logical and + + `||' + Logical or + + The macro `eval' is recognized only with parameters. + + All binary operators, except exponentiation, are left associative. C +operators that perform variable assignment, such as `+=' or `--', are +not implemented, since `eval' only operates on constants, not +variables. Attempting to use them results in an error. However, since +traditional implementations treated `=' as an undocumented alias for +`==' as opposed to an assignment operator, this usage is supported as a +special case. Be aware that a future version of GNU M4 may support +assignment semantics as an extension when POSIX mode is not requested, +and that using `=' to check equality is not portable. + + eval(`2 = 2') + error-->m4:stdin:1: Warning: recommend ==, not =, for equality operator + =>1 + eval(`++0') + error-->m4:stdin:2: invalid operator in eval: ++0 + => + eval(`0 |= 1') + error-->m4:stdin:3: invalid operator in eval: 0 |= 1 + => + + Note that some older `m4' implementations use `^' as an alternate +operator for the exponentiation, although POSIX requires the C behavior +of bitwise exclusive-or. The precedence of the negation operators, `~' +and `!', was traditionally lower than equality. The unary operators +could not be used reliably more than once on the same term without +intervening parentheses. The traditional precedence of the equality +operators `==' and `!=' was identical instead of lower than the +relational operators such as `<', even through GNU M4 1.4.8. Starting +with version 1.4.9, GNU M4 correctly follows POSIX precedence rules. +M4 scripts designed to be portable between releases must be aware that +parentheses may be required to enforce C precedence rules. Likewise, +division by zero, even in the unused branch of a short-circuiting +operator, is not always well-defined in other implementations. + + Following are some examples where the current version of M4 follows C +precedence rules, but where older versions and some other +implementations of `m4' require explicit parentheses to get the correct +result: + + eval(`1 == 2 > 0') + =>1 + eval(`(1 == 2) > 0') + =>0 + eval(`! 0 * 2') + =>2 + eval(`! (0 * 2)') + =>1 + eval(`1 | 1 ^ 1') + =>1 + eval(`(1 | 1) ^ 1') + =>0 + eval(`+ + - ~ ! ~ 0') + =>1 + eval(`2 || 1 / 0') + =>1 + eval(`0 || 1 / 0') + error-->m4:stdin:9: divide by zero in eval: 0 || 1 / 0 + => + eval(`0 && 1 % 0') + =>0 + eval(`2 && 1 % 0') + error-->m4:stdin:11: modulo by zero in eval: 2 && 1 % 0 + => + + As a GNU extension, the operator `**' performs integral +exponentiation. The operator is right-associative, and if evaluated, +the exponent must be non-negative, and at least one of the arguments +must be non-zero, or a warning is issued. + + eval(`2 ** 3 ** 2') + =>512 + eval(`(2 ** 3) ** 2') + =>64 + eval(`0 ** 1') + =>0 + eval(`2 ** 0') + =>1 + eval(`0 ** 0') + => + error-->m4:stdin:5: divide by zero in eval: 0 ** 0 + eval(`4 ** -2') + error-->m4:stdin:6: negative exponent in eval: 4 ** -2 + => + + Within EXPRESSION, (but not RADIX or WIDTH), numbers without a +special prefix are decimal. A simple `0' prefix introduces an octal +number. `0x' introduces a hexadecimal number. As GNU extensions, `0b' +introduces a binary number. `0r' introduces a number expressed in any +radix between 1 and 36: the prefix should be immediately followed by +the decimal expression of the radix, a colon, then the digits making +the number. For radix 1, leading zeros are ignored, and all remaining +digits must be `1'; for all other radices, the digits are `0', `1', `2', +.... Beyond `9', the digits are `a', `b' ... up to `z'. Lower and +upper case letters can be used interchangeably in numbers prefixes and +as number digits. + + Parentheses may be used to group subexpressions whenever needed. +For the relational operators, a true relation returns `1', and a false +relation return `0'. + + Here are a few examples of use of `eval'. + + eval(`-3 * 5') + =>-15 + eval(`-99 / 10') + =>-9 + eval(`-99 % 10') + =>-9 + eval(`99 % -10') + =>9 + eval(index(`Hello world', `llo') >= 0) + =>1 + eval(`0r1:0111 + 0b100 + 0r3:12') + =>12 + define(`square', `eval(`($1) ** 2')') + => + square(`9') + =>81 + square(square(`5')` + 1') + =>676 + define(`foo', `666') + => + eval(`foo / 6') + error-->m4:stdin:11: bad expression in eval: foo / 6 + => + eval(foo / 6) + =>111 + + As the last two lines show, `eval' does not handle macro names, even +if they expand to a valid expression (or part of a valid expression). +Therefore all macros must be expanded before they are passed to `eval'. + + Some calculations are not portable to other implementations, since +they have undefined semantics in C, but GNU `m4' has well-defined +behavior on overflow. When shifting, an out-of-range shift amount is +implicitly brought into the range of 32-bit signed integers using an +implicit bit-wise and with 0x1f). + + define(`max_int', eval(`0x7fffffff')) + => + define(`min_int', incr(max_int)) + => + eval(min_int` < 0') + =>1 + eval(max_int` > 0') + =>1 + ifelse(eval(min_int` / -1'), min_int, `overflow occurred') + =>overflow occurred + min_int + =>-2147483648 + eval(`0x80000000 % -1') + =>0 + eval(`-4 >> 1') + =>-2 + eval(`-4 >> 33') + =>-2 + + If RADIX is specified, it specifies the radix to be used in the +expansion. The default radix is 10; this is also the case if RADIX is +the empty string. A warning results if the radix is outside the range +of 1 through 36, inclusive. The result of `eval' is always taken to be +signed. No radix prefix is output, and for radices greater than 10, +the digits are lower case. The WIDTH argument specifies the minimum +output width, excluding any negative sign. The result is zero-padded +to extend the expansion to the requested width. A warning results if +the width is negative. If RADIX or WIDTH is out of bounds, the +expansion of `eval' is empty. + + eval(`666', `10') + =>666 + eval(`666', `11') + =>556 + eval(`666', `6') + =>3030 + eval(`666', `6', `10') + =>0000003030 + eval(`-666', `6', `10') + =>-0000003030 + eval(`10', `', `0') + =>10 + `0r1:'eval(`10', `1', `11') + =>0r1:01111111111 + eval(`10', `16') + =>a + eval(`1', `37') + error-->m4:stdin:9: radix 37 in builtin `eval' out of range + => + eval(`1', , `-1') + error-->m4:stdin:10: negative width to builtin `eval' + => + eval() + error-->m4:stdin:11: empty string treated as 0 in builtin `eval' + =>0 + + +File: m4.info, Node: Shell commands, Next: Miscellaneous, Prev: Arithmetic, Up: Top + +13 Macros for running shell commands +************************************ + +There are a few builtin macros in `m4' that allow you to run shell +commands from within `m4'. + + Note that the definition of a valid shell command is system +dependent. On UNIX systems, this is the typical `/bin/sh'. But on +other systems, such as native Windows, the shell has a different syntax +of commands that it understands. Some examples in this chapter assume +`/bin/sh', and also demonstrate how to quit early with a known exit +value if this is not the case. + +* Menu: + +* Platform macros:: Determining the platform +* Syscmd:: Executing simple commands +* Esyscmd:: Reading the output of commands +* Sysval:: Exit status +* Mkstemp:: Making temporary files + + +File: m4.info, Node: Platform macros, Next: Syscmd, Up: Shell commands + +13.1 Determining the platform +============================= + +Sometimes it is desirable for an input file to know which platform `m4' +is running on. GNU `m4' provides several macros that are predefined to +expand to the empty string; checking for their existence will confirm +platform details. + + -- Optional builtin: __gnu__ + -- Optional builtin: __os2__ + -- Optional builtin: os2 + -- Optional builtin: __unix__ + -- Optional builtin: unix + -- Optional builtin: __windows__ + -- Optional builtin: windows + Each of these macros is conditionally defined as needed to + describe the environment of `m4'. If defined, each macro expands + to the empty string. For now, these macros silently ignore all + arguments, but in a future release of M4, they might warn if + arguments are present. + + When GNU extensions are in effect (that is, when you did not use the +`-G' option, *note Invoking m4: Limits control.), GNU `m4' will define +the macro `__gnu__' to expand to the empty string. + + $ m4 + __gnu__ + => + __gnu__(`ignored') + => + Extensions are ifdef(`__gnu__', `active', `inactive') + =>Extensions are active + + $ m4 -G + __gnu__ + =>__gnu__ + __gnu__(`ignored') + =>__gnu__(ignored) + Extensions are ifdef(`__gnu__', `active', `inactive') + =>Extensions are inactive + + On UNIX systems, GNU `m4' will define `__unix__' by default, or +`unix' when the `-G' option is specified. + + On native Windows systems, GNU `m4' will define `__windows__' by +default, or `windows' when the `-G' option is specified. + + On OS/2 systems, GNU `m4' will define `__os2__' by default, or `os2' +when the `-G' option is specified. + + If GNU `m4' does not provide a platform macro for your system, +please report that as a bug. + + define(`provided', `0') + => + ifdef(`__unix__', `define(`provided', incr(provided))') + => + ifdef(`__windows__', `define(`provided', incr(provided))') + => + ifdef(`__os2__', `define(`provided', incr(provided))') + => + provided + =>1 + + +File: m4.info, Node: Syscmd, Next: Esyscmd, Prev: Platform macros, Up: Shell commands + +13.2 Executing simple commands +============================== + +Any shell command can be executed, using `syscmd': + + -- Builtin: syscmd (SHELL-COMMAND) + Executes SHELL-COMMAND as a shell command. + + The expansion of `syscmd' is void, _not_ the output from + SHELL-COMMAND! Output or error messages from SHELL-COMMAND are + not read by `m4'. *Note Esyscmd::, if you need to process the + command output. + + Prior to executing the command, `m4' flushes its buffers. The + default standard input, output and error of SHELL-COMMAND are the + same as those of `m4'. + + By default, the SHELL-COMMAND will be used as the argument to the + `-c' option of the `/bin/sh' shell (or the version of `sh' + specified by `command -p getconf PATH', if your system supports + that). If you prefer a different shell, the `configure' script + can be given the option `--with-syscmd-shell=LOCATION' to set the + location of an alternative shell at GNU `m4' installation; the + alternative shell must still support `-c'. + + The macro `syscmd' is recognized only with parameters. + + define(`foo', `FOO') + => + syscmd(`echo foo') + =>foo + => + + Note how the expansion of `syscmd' keeps the trailing newline of the +command, as well as using the newline that appeared after the macro. + + The following is an example of SHELL-COMMAND using the same standard +input as `m4': + + $ echo "m4wrap(\`syscmd(\`cat')')" | m4 + => + + It tells `m4' to read all of its input before executing the wrapped +text, then hand a valid (albeit emptied) pipe as standard input for the +`cat' subcommand. Therefore, you should be careful when using standard +input (either by specifying no files, or by passing `-' as a file name +on the command line, *note Invoking m4: Command line files.), and also +invoking subcommands via `syscmd' or `esyscmd' that consume data from +standard input. When standard input is a seekable file, the subprocess +will pick up with the next character not yet processed by `m4'; when it +is a pipe or other non-seekable file, there is no guarantee how much +data will already be buffered by `m4' and thus unavailable to the child. + + +File: m4.info, Node: Esyscmd, Next: Sysval, Prev: Syscmd, Up: Shell commands + +13.3 Reading the output of commands +=================================== + +If you want `m4' to read the output of a shell command, use `esyscmd': + + -- Builtin: esyscmd (SHELL-COMMAND) + Expands to the standard output of the shell command SHELL-COMMAND. + + Prior to executing the command, `m4' flushes its buffers. The + default standard input and standard error of SHELL-COMMAND are the + same as those of `m4'. The error output of SHELL-COMMAND is not a + part of the expansion: it will appear along with the error output + of `m4'. + + By default, the SHELL-COMMAND will be used as the argument to the + `-c' option of the `/bin/sh' shell (or the version of `sh' + specified by `command -p getconf PATH', if your system supports + that). If you prefer a different shell, the `configure' script + can be given the option `--with-syscmd-shell=LOCATION' to set the + location of an alternative shell at GNU `m4' installation; the + alternative shell must still support `-c'. + + The macro `esyscmd' is recognized only with parameters. + + define(`foo', `FOO') + => + esyscmd(`echo foo') + =>FOO + => + + Note how the expansion of `esyscmd' keeps the trailing newline of +the command, as well as using the newline that appeared after the macro. + + Just as with `syscmd', care must be exercised when sharing standard +input between `m4' and the child process of `esyscmd'. + + +File: m4.info, Node: Sysval, Next: Mkstemp, Prev: Esyscmd, Up: Shell commands + +13.4 Exit status +================ + +To see whether a shell command succeeded, use `sysval': + + -- Builtin: sysval + Expands to the exit status of the last shell command run with + `syscmd' or `esyscmd'. Expands to 0 if no command has been run + yet. + + sysval + =>0 + syscmd(`false') + => + ifelse(sysval, `0', `zero', `non-zero') + =>non-zero + syscmd(`exit 2') + => + sysval + =>2 + syscmd(`true') + => + sysval + =>0 + esyscmd(`false') + => + ifelse(sysval, `0', `zero', `non-zero') + =>non-zero + esyscmd(`echo dnl && exit 127') + => + sysval + =>127 + esyscmd(`true') + => + sysval + =>0 + + `sysval' results in 127 if there was a problem executing the +command, for example, if the system-imposed argument length is exceeded, +or if there were not enough resources to fork. It is not possible to +distinguish between failed execution and successful execution that had +an exit status of 127, unless there was output from the child process. + + On UNIX platforms, where it is possible to detect when command +execution is terminated by a signal, rather than a normal exit, the +result is the signal number shifted left by eight bits. + + dnl This test assumes kill is a shell builtin, and that signals are + dnl recognizable. + ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics + ')m4exit(`77')')dnl + syscmd(`kill -9 $$') + => + sysval + =>2304 + syscmd() + => + sysval + =>0 + esyscmd(`kill -9 $$') + => + sysval + =>2304 + + +File: m4.info, Node: Mkstemp, Prev: Sysval, Up: Shell commands + +13.5 Making temporary files +=========================== + +Commands specified to `syscmd' or `esyscmd' might need a temporary +file, for output or for some other purpose. There is a builtin macro, +`mkstemp', for making a temporary file: + + -- Builtin: mkstemp (TEMPLATE) + -- Builtin: maketemp (TEMPLATE) + Expands to the quoted name of a new, empty file, made from the + string TEMPLATE, which should end with the string `XXXXXX'. The + six `X' characters are then replaced with random characters + matching the regular expression `[a-zA-Z0-9._-]', in order to make + the file name unique. If fewer than six `X' characters are found + at the end of `template', the result will be longer than the + template. The created file will have access permissions as if by + `chmod =rw,go=', meaning that the current umask of the `m4' + process is taken into account, and at most only the current user + can read and write the file. + + The traditional behavior, standardized by POSIX, is that + `maketemp' merely replaces the trailing `X' with the process id, + without creating a file or quoting the expansion, and without + ensuring that the resulting string is a unique file name. In + part, this means that using the same TEMPLATE twice in the same + input file will result in the same expansion. This behavior is a + security hole, as it is very easy for another process to guess the + name that will be generated, and thus interfere with a subsequent + use of `syscmd' trying to manipulate that file name. Hence, POSIX + has recommended that all new implementations of `m4' provide the + secure `mkstemp' builtin, and that users of `m4' check for its + existence. + + The expansion is void and an error issued if a temporary file could + not be created. + + The macros `mkstemp' and `maketemp' are recognized only with + parameters. + + If you try this next example, you will most likely get different +output for the two file names, since the replacement characters are +randomly chosen: + + $ m4 + define(`tmp', `oops') + => + maketemp(`/tmp/fooXXXXXX') + =>/tmp/fooa07346 + ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))', + `define(`mkstemp', defn(`maketemp'))dnl + errprint(`warning: potentially insecure maketemp implementation + ')') + => + mkstemp(`doc') + =>docQv83Uw + + Unless you use the `--traditional' command line option (or `-G', +*note Invoking m4: Limits control.), the GNU version of `maketemp' is +secure. This means that using the same template to multiple calls will +generate multiple files. However, we recommend that you use the new +`mkstemp' macro, introduced in GNU M4 1.4.8, which is secure even in +traditional mode. Also, as of M4 1.4.11, the secure implementation +quotes the resulting file name, so that you are guaranteed to know what +file was created even if the random file name happens to match an +existing macro. Notice that this example is careful to use `defn' to +avoid unintended expansion of `foo'. + + $ m4 + define(`foo', `errprint(`oops')') + => + syscmd(`rm -f foo-??????')sysval + =>0 + define(`file1', maketemp(`foo-XXXXXX'))dnl + ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ', + `no file', `created') + =>created + define(`file2', maketemp(`foo-XX'))dnl + define(`file3', mkstemp(`foo-XXXXXX'))dnl + ifelse(len(defn(`file1')), len(defn(`file2')), + `same length', `different') + =>same length + ifelse(defn(`file1'), defn(`file2'), `same', `different file') + =>different file + ifelse(defn(`file2'), defn(`file3'), `same', `different file') + =>different file + ifelse(defn(`file1'), defn(`file3'), `same', `different file') + =>different file + syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3')) + => + sysval + =>0 + + +File: m4.info, Node: Miscellaneous, Next: Frozen files, Prev: Shell commands, Up: Top + +14 Miscellaneous builtin macros +******************************* + +This chapter describes various builtins, that do not really belong in +any of the previous chapters. + +* Menu: + +* Errprint:: Printing error messages +* Location:: Printing current location +* M4exit:: Exiting from `m4' + + +File: m4.info, Node: Errprint, Next: Location, Up: Miscellaneous + +14.1 Printing error messages +============================ + +You can print error messages using `errprint': + + -- Builtin: errprint (MESSAGE, ...) + Prints MESSAGE and the rest of the arguments to standard error, + separated by spaces. Standard error is used, regardless of the + `--debugfile' option (*note Invoking m4: Debugging options.). + + The expansion of `errprint' is void. The macro `errprint' is + recognized only with parameters. + + errprint(`Invalid arguments to forloop + ') + error-->Invalid arguments to forloop + => + errprint(`1')errprint(`2',`3 + ') + error-->12 3 + => + + A trailing newline is _not_ printed automatically, so it should be +supplied as part of the argument, as in the example. Unfortunately, the +exact output of `errprint' is not very portable to other `m4' +implementations: POSIX requires that all arguments be printed, but some +implementations of `m4' only print the first. Furthermore, some BSD +implementations always append a newline for each `errprint' call, +regardless of whether the last argument already had one, and POSIX is +silent on whether this is acceptable. + + +File: m4.info, Node: Location, Next: M4exit, Prev: Errprint, Up: Miscellaneous + +14.2 Printing current location +============================== + +To make it possible to specify the location of an error, three utility +builtins exist: + + -- Builtin: __file__ + -- Builtin: __line__ + -- Builtin: __program__ + Expand to the quoted name of the current input file, the current + input line number in that file, and the quoted name of the current + invocation of `m4'. + + errprint(__program__:__file__:__line__: `input error + ') + error-->m4:stdin:1: input error + => + + Line numbers start at 1 for each file. If the file was found due to +the `-I' option or `M4PATH' environment variable, that is reflected in +the file name. The syncline option (`-s', *note Invoking m4: +Preprocessor features.), and the `f' and `l' flags of `debugmode' +(*note Debug Levels::), also use this notion of current file and line. +Redefining the three location macros has no effect on syncline, debug, +warning, or error message output. + + This example reuses the file `incl.m4' mentioned earlier (*note +Include::): + + $ m4 -I examples + define(`foo', ``$0' called at __file__:__line__') + => + foo + =>foo called at stdin:2 + include(`incl.m4') + =>Include file start + =>foo called at examples/incl.m4:2 + =>Include file end + => + + The location of macros invoked during the rescanning of macro +expansion text corresponds to the location in the file where the +expansion was triggered, regardless of how many newline characters the +expansion text contains. As of GNU M4 1.4.8, the location of text +wrapped with `m4wrap' (*note M4wrap::) is the point at which the +`m4wrap' was invoked. Previous versions, however, behaved as though +wrapped text came from line 0 of the file "". + + define(`echo', `$@') + => + define(`foo', `echo(__line__ + __line__)') + => + echo(__line__ + __line__) + =>4 + =>5 + m4wrap(`foo + ') + => + foo(errprint(__line__ + __line__ + )) + error-->8 + error-->9 + =>8 + =>8 + __line__ + =>11 + m4wrap(`__line__ + ') + => + ^D + =>12 + =>6 + =>6 + + The `__program__' macro behaves like `$0' in shell terminology. If +you invoke `m4' through an absolute path or a link with a different +spelling, rather than by relying on a `PATH' search for plain `m4', it +will affect how `__program__' expands. The intent is that you can use +it to produce error messages with the same formatting that `m4' +produces internally. It can also be used within `syscmd' (*note +Syscmd::) to pick the same version of `m4' that is currently running, +rather than whatever version of `m4' happens to be first in `PATH'. It +was first introduced in GNU M4 1.4.6. + + +File: m4.info, Node: M4exit, Prev: Location, Up: Miscellaneous + +14.3 Exiting from `m4' +====================== + +If you need to exit from `m4' before the entire input has been read, +you can use `m4exit': + + -- Builtin: m4exit ([CODE = `0']) + Causes `m4' to exit, with exit status CODE. If CODE is left out, + the exit status is zero. If CODE cannot be parsed, or is outside + the range of 0 to 255, the exit status is one. No further input + is read, and all wrapped and diverted text is discarded. + + m4wrap(`This text is lost due to `m4exit'.') + => + divert(`1') So is this. + divert + => + m4exit And this is never read. + + A common use of this is to abort processing: + + -- Composite: fatal_error (MESSAGE) + Abort processing with an error message and non-zero status. Prefix + MESSAGE with details about where the error occurred, and print the + resulting string to standard error. + + define(`fatal_error', + `errprint(__program__:__file__:__line__`: fatal error: $* + ')m4exit(`1')') + => + fatal_error(`this is a BAD one, buster') + error-->m4:stdin:4: fatal error: this is a BAD one, buster + + After this macro call, `m4' will exit with exit status 1. This macro +is only intended for error exits, since the normal exit procedures are +not followed, i.e., diverted text is not undiverted, and saved text +(*note M4wrap::) is not reread. (This macro could be made more robust +to earlier versions of `m4'. You should try to see if you can find +weaknesses and correct them; or *note Answers: Improved fatal_error.). + + Note that it is still possible for the exit status to be different +than what was requested by `m4exit'. If `m4' detects some other error, +such as a write error on standard output, the exit status will be +non-zero even if `m4exit' requested zero. + + If standard input is seekable, then the file will be positioned at +the next unread character. If it is a pipe or other non-seekable file, +then there are no guarantees how much data `m4' might have read into +buffers, and thus discarded. + + +File: m4.info, Node: Frozen files, Next: Compatibility, Prev: Miscellaneous, Up: Top + +15 Fast loading of frozen state +******************************* + +Some bigger `m4' applications may be built over a common base +containing hundreds of definitions and other costly initializations. +Usually, the common base is kept in one or more declarative files, +which files are listed on each `m4' invocation prior to the user's +input file, or else each input file uses `include'. + + Reading the common base of a big application, over and over again, +may be time consuming. GNU `m4' offers some machinery to speed up the +start of an application using lengthy common bases. + +* Menu: + +* Using frozen files:: Using frozen files +* Frozen file format:: Frozen file format + + +File: m4.info, Node: Using frozen files, Next: Frozen file format, Up: Frozen files + +15.1 Using frozen files +======================= + +Suppose a user has a library of `m4' initializations in `base.m4', +which is then used with multiple input files: + + $ m4 base.m4 input1.m4 + $ m4 base.m4 input2.m4 + $ m4 base.m4 input3.m4 + + Rather than spending time parsing the fixed contents of `base.m4' +every time, the user might rather execute: + + $ m4 -F base.m4f base.m4 + +once, and further execute, as often as needed: + + $ m4 -R base.m4f input1.m4 + $ m4 -R base.m4f input2.m4 + $ m4 -R base.m4f input3.m4 + +with the varying input. The first call, containing the `-F' option, +only reads and executes file `base.m4', defining various application +macros and computing other initializations. Once the input file +`base.m4' has been completely processed, GNU `m4' produces in +`base.m4f' a "frozen" file, that is, a file which contains a kind of +snapshot of the `m4' internal state. + + Later calls, containing the `-R' option, are able to reload the +internal state of `m4', from `base.m4f', _prior_ to reading any other +input files. This means instead of starting with a virgin copy of +`m4', input will be read after having effectively recovered the effect +of a prior run. In our example, the effect is the same as if file +`base.m4' has been read anew. However, this effect is achieved a lot +faster. + + Only one frozen file may be created or read in any one `m4' +invocation. It is not possible to recover two frozen files at once. +However, frozen files may be updated incrementally, through using `-R' +and `-F' options simultaneously. For example, if some care is taken, +the command: + + $ m4 file1.m4 file2.m4 file3.m4 file4.m4 + +could be broken down in the following sequence, accumulating the same +output: + + $ m4 -F file1.m4f file1.m4 + $ m4 -R file1.m4f -F file2.m4f file2.m4 + $ m4 -R file2.m4f -F file3.m4f file3.m4 + $ m4 -R file3.m4f file4.m4 + + Some care is necessary because not every effort has been made for +this to work in all cases. In particular, the trace attribute of +macros is not handled, nor the current setting of `changeword'. +Currently, `m4wrap' and `sysval' also have problems. Also, +interactions for some options of `m4', being used in one call and not +in the next, have not been fully analyzed yet. On the other end, you +may be confident that stacks of `pushdef' definitions are handled +correctly, as well as undefined or renamed builtins, and changed +strings for quotes or comments. And future releases of GNU M4 will +improve on the utility of frozen files. + + When an `m4' run is to be frozen, the automatic undiversion which +takes place at end of execution is inhibited. Instead, all positively +numbered diversions are saved into the frozen file. The active +diversion number is also transmitted. + + A frozen file to be reloaded need not reside in the current +directory. It is looked up the same way as an `include' file (*note +Search Path::). + + If the frozen file was generated with a newer version of `m4', and +contains directives that an older `m4' cannot parse, attempting to load +the frozen file with option `-R' will cause `m4' to exit with status 63 +to indicate version mismatch. + + +File: m4.info, Node: Frozen file format, Prev: Using frozen files, Up: Frozen files + +15.2 Frozen file format +======================= + +Frozen files are sharable across architectures. It is safe to write a +frozen file on one machine and read it on another, given that the +second machine uses the same or newer version of GNU `m4'. It is +conventional, but not required, to give a frozen file the suffix of +`.m4f'. + + These are simple (editable) text files, made up of directives, each +starting with a capital letter and ending with a newline (<NL>). +Wherever a directive is expected, the character `#' introduces a +comment line; empty lines are also ignored if they are not part of an +embedded string. In the following descriptions, each LEN refers to the +length of the corresponding strings STR in the next line of input. +Numbers are always expressed in decimal. There are no escape +characters. The directives are: + +`C LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Uses STR1 and STR2 as the begin-comment and end-comment strings. + If omitted, then `#' and <NL> are the comment delimiters. + +`D NUMBER, LEN <NL> STR <NL>' + Selects diversion NUMBER, making it current, then copy STR in the + current diversion. NUMBER may be a negative number for a + non-existing diversion. To merely specify an active selection, + use this command with an empty STR. With 0 as the diversion + NUMBER, STR will be issued on standard output at reload time. GNU + `m4' will not produce the `D' directive with non-zero length for + diversion 0, but this can be done with manual edits. This + directive may appear more than once for the same diversion, in + which case the diversion is the concatenation of the various uses. + If omitted, then diversion 0 is current. + +`F LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Defines, through `pushdef', a definition for STR1 expanding to the + function whose builtin name is STR2. If the builtin does not + exist (for example, if the frozen file was produced by a copy of + `m4' compiled with changeword support, but the version of `m4' + reloading was compiled without it), the reload is silent, but any + subsequent use of the definition of STR1 will result in a warning. + This directive may appear more than once for the same name, and + its order, along with `T', is important. If omitted, you will + have no access to any builtins. + +`Q LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Uses STR1 and STR2 as the begin-quote and end-quote strings. If + omitted, then ``' and `'' are the quote delimiters. + +`T LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Defines, though `pushdef', a definition for STR1 expanding to the + text given by STR2. This directive may appear more than once for + the same name, and its order, along with `F', is important. + +`V NUMBER <NL>' + Confirms the format of the file. `m4' 1.4.16 only creates and + understands frozen files where NUMBER is 1. This directive must + be the first non-comment in the file, and may not appear more than + once. + + +File: m4.info, Node: Compatibility, Next: Answers, Prev: Frozen files, Up: Top + +16 Compatibility with other versions of `m4' +******************************************** + +This chapter describes the many of the differences between this +implementation of `m4', and of other implementations found under UNIX, +such as System V Release 3, Solaris, and BSD flavors. In particular, +it lists the known differences and extensions to POSIX. However, the +list is not necessarily comprehensive. + + At the time of this writing, POSIX 2001 (also known as IEEE Std +1003.1-2001) is the latest standard, although a new version of POSIX is +under development and includes several proposals for modifying what +`m4' is required to do. The requirements for `m4' are shared between +SUSv3 and POSIX, and can be viewed at +`http://www.opengroup.org/onlinepubs/000095399/utilities/m4.html'. + +* Menu: + +* Extensions:: Extensions in GNU M4 +* Incompatibilities:: Facilities in System V m4 not in GNU M4 +* Other Incompatibilities:: Other incompatibilities + + +File: m4.info, Node: Extensions, Next: Incompatibilities, Up: Compatibility + +16.1 Extensions in GNU M4 +========================= + +This version of `m4' contains a few facilities that do not exist in +System V `m4'. These extra facilities are all suppressed by using the +`-G' command line option (*note Invoking m4: Limits control.), unless +overridden by other command line options. + + * In the `$N' notation for macro arguments, N can contain several + digits, while the System V `m4' only accepts one digit. This + allows macros in GNU `m4' to take any number of arguments, and not + only nine (*note Arguments::). + + This means that `define(`foo', `$11')' is ambiguous between + implementations. To portably choose between grabbing the first + parameter and appending 1 to the expansion, or grabbing the + eleventh parameter, you can do the following: + + define(`a1', `A1') + => + dnl First argument, concatenated with 1 + define(`_1', `$1')define(`first1', `_1($@)1') + => + dnl Eleventh argument, portable + define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))') + => + dnl Eleventh argument, GNU style + define(`Eleventh', `$11') + => + first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') + =>A1 + eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') + =>k + Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') + =>k + + Also see the `argn' macro (*note Shift::). + + * The `divert' (*note Divert::) macro can manage more than 9 + diversions. GNU `m4' treats all positive numbers as valid + diversions, rather than discarding diversions greater than 9. + + * Files included with `include' and `sinclude' are sought in a user + specified search path, if they are not found in the working + directory. The search path is specified by the `-I' option and the + `M4PATH' environment variable (*note Search Path::). + + * Arguments to `undivert' can be non-numeric, in which case the named + file will be included uninterpreted in the output (*note + Undivert::). + + * Formatted output is supported through the `format' builtin, which + is modeled after the C library function `printf' (*note Format::). + + * Searches and text substitution through basic regular expressions + are supported by the `regexp' (*note Regexp::) and `patsubst' + (*note Patsubst::) builtins. Some BSD implementations use + extended regular expressions instead. + + * The output of shell commands can be read into `m4' with `esyscmd' + (*note Esyscmd::). + + * There is indirect access to any builtin macro with `builtin' + (*note Builtin::). + + * Macros can be called indirectly through `indir' (*note Indir::). + + * The name of the program, the current input file, and the current + input line number are accessible through the builtins + `__program__', `__file__', and `__line__' (*note Location::). + + * The format of the output from `dumpdef' and macro tracing can be + controlled with `debugmode' (*note Debug Levels::). + + * The destination of trace and debug output can be controlled with + `debugfile' (*note Debug Output::). + + * The `maketemp' (*note Mkstemp::) macro behaves like `mkstemp', + creating a new file with a unique name on every invocation, rather + than following the insecure behavior of replacing the trailing `X' + characters with the `m4' process id. + + * POSIX only requires support for the command line options `-s', + `-D', and `-U', so all other options accepted by GNU M4 are + extensions. *Note Invoking m4::, for a description of these + options. + + The debugging and tracing facilities in GNU `m4' are much more + extensive than in most other versions of `m4'. + + +File: m4.info, Node: Incompatibilities, Next: Other Incompatibilities, Prev: Extensions, Up: Compatibility + +16.2 Facilities in System V `m4' not in GNU `m4' +================================================ + +The version of `m4' from System V contains a few facilities that have +not been implemented in GNU `m4' yet. Additionally, POSIX requires +some behaviors that GNU `m4' has not implemented yet. Relying on these +behaviors is non-portable, as a future release of GNU `m4' may change. + + * POSIX requires support for multiple arguments to `defn', without + any clarification on how `defn' behaves when one of the multiple + arguments names a builtin. System V `m4' and some other + implementations allow mixing builtins and text macros into a single + macro. GNU `m4' only supports joining multiple text arguments, + although a future implementation may lift this restriction to + behave more like System V. The only portable way to join text + macros with builtins is via helper macros and implicit + concatenation of macro results. + + * POSIX requires an application to exit with non-zero status if it + wrote an error message to stderr. This has not yet been + consistently implemented for the various builtins that are + required to issue an error (such as `eval' (*note Eval::) when an + argument cannot be parsed). + + * Some traditional implementations only allow reading standard input + once, but GNU `m4' correctly handles multiple instances of `-' on + the command line. + + * POSIX requires `m4wrap' (*note M4wrap::) to act in FIFO (first-in, + first-out) order, but GNU `m4' currently uses LIFO order. + Furthermore, POSIX states that only the first argument to `m4wrap' + is saved for later evaluation, but GNU `m4' saves and processes + all arguments, with output separated by spaces. + + * POSIX states that builtins that require arguments, but are called + without arguments, have undefined behavior. Traditional + implementations simply behave as though empty strings had been + passed. For example, `a`'define`'b' would expand to `ab'. But + GNU `m4' ignores certain builtins if they have missing arguments, + giving `adefineb' for the above example. + + * Traditional implementations handle `define(`f',`1')' (*note + Define::) by undefining the entire stack of previous definitions, + and if doing `undefine(`f')' first. GNU `m4' replaces just the top + definition on the stack, as if doing `popdef(`f')' followed by + `pushdef(`f',`1')'. POSIX allows either behavior. + + * POSIX 2001 requires `syscmd' (*note Syscmd::) to evaluate command + output for macro expansion, but this was a mistake that is + anticipated to be corrected in the next version of POSIX. GNU + `m4' follows traditional behavior in `syscmd' where output is not + rescanned, and provides the extension `esyscmd' that does scan the + output. + + * At one point, POSIX required `changequote(ARG)' (*note + Changequote::) to use newline as the close quote, but this was a + bug, and the next version of POSIX is anticipated to state that + using empty strings or just one argument is unspecified. + Meanwhile, the GNU `m4' behavior of treating an empty end-quote + delimiter as `'' is not portable, as Solaris treats it as + repeating the start-quote delimiter, and BSD treats it as leaving + the previous end-quote delimiter unchanged. For predictable + results, never call changequote with just one argument, or with + empty strings for arguments. + + * At one point, POSIX required `changecom(ARG,)' (*note Changecom::) + to make it impossible to end a comment, but this is a bug, and the + next version of POSIX is anticipated to state that using empty + strings is unspecified. Meanwhile, the GNU `m4' behavior of + treating an empty end-comment delimiter as newline is not + portable, as BSD treats it as leaving the previous end-comment + delimiter unchanged. It is also impossible in BSD implementations + to disable comments, even though that is required by POSIX. For + predictable results, never call changecom with empty strings for + arguments. + + * Most implementations of `m4' give macros a higher precedence than + comments when parsing, meaning that if the start delimiter given to + `changecom' (*note Changecom::) starts with a macro name, comments + are effectively disabled. POSIX does not specify what the + precedence is, so this version of GNU `m4' parser recognizes + comments, then macros, then quoted strings. + + * Traditional implementations allow argument collection, but not + string and comment processing, to span file boundaries. Thus, if + `a.m4' contains `len(', and `b.m4' contains `abc)', `m4 a.m4 b.m4' + outputs `3' with traditional `m4', but gives an error message that + the end of file was encountered inside a macro with GNU `m4'. On + the other hand, traditional implementations do end of file + processing for files included with `include' or `sinclude' (*note + Include::), while GNU `m4' seamlessly integrates the content of + those files. Thus `include(`a.m4')include(`b.m4')' will output + `3' instead of giving an error. + + * Traditional `m4' treats `traceon' (*note Trace::) without + arguments as a global variable, independent of named macro tracing. + Also, once a macro is undefined, named tracing of that macro is + lost. On the other hand, when GNU `m4' encounters `traceon' + without arguments, it turns tracing on for all existing + definitions at the time, but does not trace future definitions; + `traceoff' without arguments turns tracing off for all definitions + regardless of whether they were also traced by name; and tracing + by name, such as with `-tfoo' at the command line or + `traceon(`foo')' in the input, is an attribute that is preserved + even if the macro is currently undefined. + + Additionally, while POSIX requires trace output, it makes no + demands on the formatting of that output. Parsing trace output is + not guaranteed to be reliable, even between different releases of + GNU M4; however, the intent is that any future changes in trace + output will only occur under the direction of additional + `debugmode' flags (*note Debug Levels::). + + * POSIX requires `eval' (*note Eval::) to treat all operators with + the same precedence as C. However, earlier versions of GNU `m4' + followed the traditional behavior of other `m4' implementations, + where bitwise and logical negation (`~' and `!') have lower + precedence than equality operators; and where equality operators + (`==' and `!=') had the same precedence as relational operators + (such as `<'). Use explicit parentheses to ensure proper + precedence. As extensions to POSIX, GNU `m4' gives well-defined + semantics to operations that C leaves undefined, such as when + overflow occurs, when shifting negative numbers, or when + performing division by zero. POSIX also requires `=' to cause an + error, but many traditional implementations allowed it as an alias + for `=='. + + * POSIX 2001 requires `translit' (*note Translit::) to treat each + character of the second and third arguments literally. However, + it is anticipated that the next version of POSIX will allow the + GNU `m4' behavior of treating `-' as a range operator. + + * POSIX requires `m4' to honor the locale environment variables of + `LANG', `LC_ALL', `LC_CTYPE', `LC_MESSAGES', and `NLSPATH', but + this has not yet been implemented in GNU `m4'. + + * POSIX states that only unquoted leading newlines and blanks (that + is, space and tab) are ignored when collecting macro arguments. + However, this appears to be a bug in POSIX, since most traditional + implementations also ignore all whitespace (formfeed, carriage + return, and vertical tab). GNU `m4' follows tradition and ignores + all leading unquoted whitespace. + + * A strictly-compliant POSIX client is not allowed to use + command-line arguments not specified by POSIX. However, since + this version of M4 ignores `POSIXLY_CORRECT' and enables the option + `--gnu' by default (*note Invoking m4: Limits control.), a client + desiring to be strictly compliant has no way to disable GNU + extensions that conflict with POSIX when directly invoking the + compiled `m4'. A future version of `GNU' M4 will honor the + environment variable `POSIXLY_CORRECT', implicitly enabling + `--traditional' if it is set, in order to allow a + strictly-compliant client. In the meantime, a client needing + strict POSIX compliance can use the workaround of invoking a shell + script wrapper, where the wrapper then adds `--traditional' to the + arguments passed to the compiled `m4'. + + +File: m4.info, Node: Other Incompatibilities, Prev: Incompatibilities, Up: Compatibility + +16.3 Other incompatibilities +============================ + +There are a few other incompatibilities between this implementation of +`m4', and the System V version. + + * GNU `m4' implements sync lines differently from System V `m4', + when text is being diverted. GNU `m4' outputs the sync lines when + the text is being diverted, and System V `m4' when the diverted + text is being brought back. + + The problem is which lines and file names should be attached to + text that is being, or has been, diverted. System V `m4' regards + all the diverted text as being generated by the source line + containing the `undivert' call, whereas GNU `m4' regards the + diverted text as being generated at the time it is diverted. + + The sync line option is used mostly when using `m4' as a front end + to a compiler. If a diverted line causes a compiler error, the + error messages should most probably refer to the place where the + diversion was made, and not where it was inserted again. + + divert(2)2 + divert(1)1 + divert`'0 + =>#line 3 "stdin" + =>0 + ^D + =>#line 2 "stdin" + =>1 + =>#line 1 "stdin" + =>2 + + The current `m4' implementation has a limitation that the syncline + output at the start of each diversion occurs no matter what, even + if the previous diversion did not end with a newline. This goes + contrary to the claim that synclines appear on a line by + themselves, so this limitation may be corrected in a future + version of `m4'. In the meantime, when using `-s', it is wisest + to make sure all diversions end with newline. + + * GNU `m4' makes no attempt at prohibiting self-referential + definitions like: + + define(`x', `x') + => + define(`x', `x ') + => + + There is nothing inherently wrong with defining `x' to return `x'. + The wrong thing is to expand `x' unquoted, because that would + cause an infinite rescan loop. In `m4', one might use macros to + hold strings, as we do for variables in other programming + languages, further checking them with: + + ifelse(defn(`HOLDER'), `VALUE', ...) + + In cases like this one, an interdiction for a macro to hold its + own name would be a useless limitation. Of course, this leaves + more rope for the GNU `m4' user to hang himself! Rescanning hangs + may be avoided through careful programming, a little like for + endless loops in traditional programming languages. + + +File: m4.info, Node: Answers, Next: Copying This Package, Prev: Compatibility, Up: Top + +17 Correct version of some examples +*********************************** + +Some of the examples in this manuals are buggy or not very robust, for +demonstration purposes. Improved versions of these composite macros are +presented here. + +* Menu: + +* Improved exch:: Solution for `exch' +* Improved forloop:: Solution for `forloop' +* Improved foreach:: Solution for `foreach' +* Improved copy:: Solution for `copy' +* Improved m4wrap:: Solution for `m4wrap' +* Improved cleardivert:: Solution for `cleardivert' +* Improved capitalize:: Solution for `capitalize' +* Improved fatal_error:: Solution for `fatal_error' + + +File: m4.info, Node: Improved exch, Next: Improved forloop, Up: Answers + +17.1 Solution for `exch' +======================== + +The `exch' macro (*note Arguments::) as presented requires clients to +double quote their arguments. A nicer definition, which lets clients +follow the rule of thumb of one level of quoting per level of +parentheses, involves adding quotes in the definition of `exch', as +follows: + + define(`exch', ``$2', `$1'') + => + define(exch(`expansion text', `macro')) + => + macro + =>expansion text + + +File: m4.info, Node: Improved forloop, Next: Improved foreach, Prev: Improved exch, Up: Answers + +17.2 Solution for `forloop' +=========================== + +The `forloop' macro (*note Forloop::) as presented earlier can go into +an infinite loop if given an iterator that is not parsed as a macro +name. It does not do any sanity checking on its numeric bounds, and +only permits decimal numbers for bounds. Here is an improved version, +shipped as `m4-1.4.16/examples/forloop2.m4'; this version also +optimizes overhead by calling four macros instead of six per iteration +(excluding those in TEXT), by not dereferencing the ITERATOR in the +helper `_forloop'. + + $ m4 -d -I examples + undivert(`forloop2.m4')dnl + =>divert(`-1') + =># forloop(var, from, to, stmt) - improved version: + =># works even if VAR is not a strict macro name + =># performs sanity check that FROM is larger than TO + =># allows complex numerical expressions in TO and FROM + =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1', + => `pushdef(`$1')_$0(`$1', eval(`$2'), + => eval(`$3'), `$4')popdef(`$1')')') + =>define(`_forloop', + => `define(`$1', `$2')$4`'ifelse(`$2', `$3', `', + => `$0(`$1', incr(`$2'), `$3', `$4')')') + =>divert`'dnl + include(`forloop2.m4') + => + forloop(`i', `2', `1', `no iteration occurs') + => + forloop(`', `1', `2', ` odd iterator name') + => odd iterator name odd iterator name + forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')') + => 0xa 0xb 0xc + forloop(`i', `a', `b', `non-numeric bounds') + error-->m4:stdin:6: bad expression in eval (bad input): (a) <= (b) + => + + One other change to notice is that the improved version used `_$0' +rather than `_foreach' to invoke the helper routine. In general, this +is a good practice to follow, because then the set of macros can be +uniformly transformed. The following example shows a transformation +that doubles the current quoting and appends a suffix `2' to each +transformed macro. If `foreach' refers to the literal `_foreach', then +`foreach2' invokes `_foreach' instead of the intended `_foreach2', and +the mixing of quoting paradigms leads to an infinite recursion loop in +this example. + + $ m4 -d -L 9 -I examples + define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4') + => + define(`double', `define(`$1'`2', + arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))') + => + double(`forloop')double(`_forloop')defn(`forloop2') + =>ifelse(eval(``($2) <= ($3)''), ``1'', + => ``pushdef(``$1'')_$0(``$1'', eval(``$2''), + => eval(``$3''), ``$4'')popdef(``$1'')'') + forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)') + => + changequote(`[', `]')changequote([``], ['']) + => + forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'') + => + changequote`'include(`forloop.m4') + => + double(`forloop')double(`_forloop')defn(`forloop2') + =>pushdef(``$1'', ``$2'')_forloop($@)popdef(``$1'') + forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)') + => + changequote(`[', `]')changequote([``], ['']) + => + forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'') + error-->m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it + + One more optimization is still possible. Instead of repeatedly +assigning a variable then invoking or dereferencing it, it is possible +to pass the current iterator value as a single argument. Coupled with +`curry' if other arguments are needed (*note Composition::), or with +helper macros if the argument is needed in more than one place in the +expansion, the output can be generated with three, rather than four, +macros of overhead per iteration. Notice how the file +`m4-1.4.16/examples/forloop3.m4' rearranges the arguments of the helper +`_forloop' to take two arguments that are placed around the current +value. By splitting a balanced set of parantheses across multiple +arguments, the helper macro can now be shared by `forloop' and the new +`forloop_arg'. + + $ m4 -I examples + include(`forloop3.m4') + => + undivert(`forloop3.m4')dnl + =>divert(`-1') + =># forloop_arg(from, to, macro) - invoke MACRO(value) for + =># each value between FROM and TO, without define overhead + =>define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1', + => `_forloop(`$1', eval(`$2'), `$3(', `)')')') + =># forloop(var, from, to, stmt) - refactored to share code + =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1', + => `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'), + => `define(`$1',', `)$4')popdef(`$1')')') + =>define(`_forloop', + => `$3`$1'$4`'ifelse(`$1', `$2', `', + => `$0(incr(`$1'), `$2', `$3', `$4')')') + =>divert`'dnl + forloop(`i', `1', `3', ` i') + => 1 2 3 + define(`echo', `$@') + => + forloop_arg(`1', `3', ` echo') + => 1 2 3 + include(`curry.m4') + => + forloop_arg(`1', `3', `curry(`pushdef', `a')') + => + a + =>3 + popdef(`a')a + =>2 + popdef(`a')a + =>1 + popdef(`a')a + =>a + + Of course, it is possible to make even more improvements, such as +adding an optional step argument, or allowing iteration through +descending sequences. GNU Autoconf provides some of these additional +bells and whistles in its `m4_for' macro. + + +File: m4.info, Node: Improved foreach, Next: Improved copy, Prev: Improved forloop, Up: Answers + +17.3 Solution for `foreach' +=========================== + +The `foreach' and `foreachq' macros (*note Foreach::) as presented +earlier each have flaws. First, we will examine and fix the quadratic +behavior of `foreachq': + + $ m4 -I examples + include(`foreachq.m4') + => + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + error-->m4trace: -3- shift(`1', `2', `3', `4') + error-->m4trace: -2- shift(`1', `2', `3', `4') + =>2 + error-->m4trace: -4- shift(`1', `2', `3', `4') + error-->m4trace: -3- shift(`2', `3', `4') + error-->m4trace: -3- shift(`1', `2', `3', `4') + error-->m4trace: -2- shift(`2', `3', `4') + =>3 + error-->m4trace: -5- shift(`1', `2', `3', `4') + error-->m4trace: -4- shift(`2', `3', `4') + error-->m4trace: -3- shift(`3', `4') + error-->m4trace: -4- shift(`1', `2', `3', `4') + error-->m4trace: -3- shift(`2', `3', `4') + error-->m4trace: -2- shift(`3', `4') + =>4 + error-->m4trace: -6- shift(`1', `2', `3', `4') + error-->m4trace: -5- shift(`2', `3', `4') + error-->m4trace: -4- shift(`3', `4') + error-->m4trace: -3- shift(`4') + + Each successive iteration was adding more quoted `shift' +invocations, and the entire list contents were passing through every +iteration. In general, when recursing, it is a good idea to make the +recursion use fewer arguments, rather than adding additional quoted +uses of `shift'. By doing so, `m4' uses less memory, invokes fewer +macros, is less likely to run into machine limits, and most +importantly, performs faster. The fixed version of `foreachq' can be +found in `m4-1.4.16/examples/foreachq2.m4': + + $ m4 -I examples + include(`foreachq2.m4') + => + undivert(`foreachq2.m4')dnl + =>include(`quote.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, improved version + =>define(`foreachq', `pushdef(`$1')_$0($@)popdef(`$1')') + =>define(`_arg1q', ``$1'') + =>define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@))')') + =>define(`_foreachq', `ifelse(`$2', `', `', + => `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + error-->m4trace: -3- shift(`1', `2', `3', `4') + =>2 + error-->m4trace: -3- shift(`2', `3', `4') + =>3 + error-->m4trace: -3- shift(`3', `4') + =>4 + + Note that the fixed version calls unquoted helper macros in +`_foreachq' to trim elements immediately; those helper macros in turn +must re-supply the layer of quotes lost in the macro invocation. +Contrast the use of `_arg1q', which quotes the first list element, with +`_arg1' of the earlier implementation that returned the first list +element directly. Additionally, by calling the helper method +immediately, the `defn(`ITERATOR')' no longer contains unexpanded +macros. + + The astute m4 programmer might notice that the solution above still +uses more memory and macro invocations, and thus more time, than +strictly necessary. Note that `$2', which contains an arbitrarily long +quoted list, is expanded and rescanned three times per iteration of +`_foreachq'. Furthermore, every iteration of the algorithm effectively +unboxes then reboxes the list, which costs a couple of macro +invocations. It is possible to rewrite the algorithm for a bit more +speed by swapping the order of the arguments to `_foreachq' in order to +operate on an unboxed list in the first place, and by using the +fixed-length `$#' instead of an arbitrary length list as the key to end +recursion. The result is an overhead of six macro invocations per loop +(excluding any macros in TEXT), instead of eight. This alternative +approach is available as `m4-1.4.16/examples/foreach3.m4': + + $ m4 -I examples + include(`foreachq3.m4') + => + undivert(`foreachq3.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, alternate improved version + =>define(`foreachq', `ifelse(`$2', `', `', + => `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')') + =>define(`_foreachq', `ifelse(`$#', `3', `', + => `define(`$1', `$4')$2`'$0(`$1', `$2', + => shift(shift(shift($@))))')') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + error-->m4trace: -4- shift(`x', `x + error-->', `', `1', `2', `3', `4') + error-->m4trace: -3- shift(`x + error-->', `', `1', `2', `3', `4') + error-->m4trace: -2- shift(`', `1', `2', `3', `4') + =>2 + error-->m4trace: -4- shift(`x', `x + error-->', `1', `2', `3', `4') + error-->m4trace: -3- shift(`x + error-->', `1', `2', `3', `4') + error-->m4trace: -2- shift(`1', `2', `3', `4') + =>3 + error-->m4trace: -4- shift(`x', `x + error-->', `2', `3', `4') + error-->m4trace: -3- shift(`x + error-->', `2', `3', `4') + error-->m4trace: -2- shift(`2', `3', `4') + =>4 + error-->m4trace: -4- shift(`x', `x + error-->', `3', `4') + error-->m4trace: -3- shift(`x + error-->', `3', `4') + error-->m4trace: -2- shift(`3', `4') + + In the current version of M4, every instance of `$@' is rescanned as +it is encountered. Thus, the `foreachq3.m4' alternative uses much less +memory than `foreachq2.m4', and executes as much as 10% faster, since +each iteration encounters fewer `$@'. However, the implementation of +rescanning every byte in `$@' is quadratic in the number of bytes +scanned (for example, making the broken version in `foreachq.m4' cubic, +rather than quadratic, in behavior). A future release of M4 will +improve the underlying implementation by reusing results of previous +scans, so that both styles of `foreachq' can become linear in the +number of bytes scanned. Notice how the implementation injects an +empty argument prior to expanding `$2' within `foreachq'; the helper +macro `_foreachq' then ignores the third argument altogether, and ends +recursion when there are three arguments left because there was nothing +left to pass through `shift'. Thus, each iteration only needs one +`ifelse', rather than the two conditionals used in the version from +`foreachq2.m4'. + + So far, all of the implementations of `foreachq' presented have been +quadratic with M4 1.4.x. But `forloop' is linear, because each +iteration parses a constant amount of arguments. So, it is possible to +design a variant that uses `forloop' to do the iteration, then uses +`$@' only once at the end, giving a linear result even with older M4 +implementations. This implementation relies on the GNU extension that +`$10' expands to the tenth argument rather than the first argument +concatenated with `0'. The trick is to define an intermediate macro +that repeats the text `m4_define(`$1', `$N')$2`'', with `n' set to +successive integers corresponding to each argument. The helper macro +`_foreachq_' is needed in order to generate the literal sequences such +as `$1' into the intermediate macro, rather than expanding them as the +arguments of `_foreachq'. With this approach, no `shift' calls are +even needed! Even though there are seven macros of overhead per +iteration instead of six in `foreachq3.m4', the linear scaling is +apparent at relatively small list sizes. However, this approach will +need adjustment when a future version of M4 follows POSIX by no longer +treating `$10' as the tenth argument; the anticipation is that `${10}' +can be used instead, although that alternative syntax is not yet +supported. + + $ m4 -I examples + include(`foreachq4.m4') + => + undivert(`foreachq4.m4')dnl + =>include(`forloop2.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, version based on forloop + =>define(`foreachq', + =>`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')') + =>define(`_foreachq', + =>`pushdef(`$1', forloop(`$1', `3', `$#', + => `$0_(`1', `2', indir(`$1'))')`popdef( + => `$1')')indir(`$1', $@)') + =>define(`_foreachq_', + =>``define(`$$1', `$$3')$$2`''') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + =>2 + =>3 + =>4 + + For yet another approach, the improved version of `foreach', +available in `m4-1.4.16/examples/foreach2.m4', simply overquotes the +arguments to `_foreach' to begin with, using `dquote_elt'. Then +`_foreach' can just use `_arg1' to remove the extra layer of quoting +that was added up front: + + $ m4 -I examples + include(`foreach2.m4') + => + undivert(`foreach2.m4')dnl + =>include(`quote.m4')dnl + =>divert(`-1') + =># foreach(x, (item_1, item_2, ..., item_n), stmt) + =># parenthesized list, improved version + =>define(`foreach', `pushdef(`$1')_$0(`$1', + => (dquote(dquote_elt$2)), `$3')popdef(`$1')') + =>define(`_arg1', `$1') + =>define(`_foreach', `ifelse(`$2', `(`')', `', + => `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreach(`x', `(`1', `2', `3', `4')', `x + ')dnl + error-->m4trace: -4- shift(`1', `2', `3', `4') + error-->m4trace: -4- shift(`2', `3', `4') + error-->m4trace: -4- shift(`3', `4') + =>1 + error-->m4trace: -3- shift(``1'', ``2'', ``3'', ``4'') + =>2 + error-->m4trace: -3- shift(``2'', ``3'', ``4'') + =>3 + error-->m4trace: -3- shift(``3'', ``4'') + =>4 + error-->m4trace: -3- shift(``4'') + + It is likewise possible to write a variant of `foreach' that +performs in linear time on M4 1.4.x; the easiest method is probably +writing a version of `foreach' that unboxes its list, then invokes +`_foreachq' as previously defined in `foreachq4.m4'. + + In summary, recursion over list elements is trickier than it +appeared at first glance, but provides a powerful idiom within `m4' +processing. As a final demonstration, both list styles are now able to +handle several scenarios that would wreak havoc on one or both of the +original implementations. This points out one other difference between +the list styles. `foreach' evaluates unquoted list elements only once, +in preparation for calling `_foreach', similary for `foreachq' as +provided by `foreachq3.m4' or `foreachq4.m4'. But `foreachq', as +provided by `foreachq2.m4', evaluates unquoted list elements twice +while visiting the first list element, once in `_arg1q' and once in +`_rest'. When deciding which list style to use, one must take into +account whether repeating the side effects of unquoted list elements +will have any detrimental effects. + + $ m4 -I examples + include(`foreach2.m4') + => + include(`foreachq2.m4') + => + dnl 0-element list: + foreach(`x', `', `<x>') / foreachq(`x', `', `<x>') + => / + dnl 1-element list of empty element + foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>') + =><> / <> + dnl 2-element list of empty elements + foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>') + =><><> / <><> + dnl 1-element list of a comma + foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>') + =><,> / <,> + dnl 2-element list of unbalanced parentheses + foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>') + =><(><)> / <(><)> + define(`ab', `oops')dnl using defn(`iterator') + foreach(`x', `(`a', `b')', `defn(`x')') /dnl + foreachq(`x', ``a', `b'', `defn(`x')') + =>ab / ab + define(`active', `ACT, IVE') + => + traceon(`active') + => + dnl list of unquoted macros; expansion occurs before recursion + foreach(`x', `(active, active)', `<x> + ')dnl + error-->m4trace: -4- active -> `ACT, IVE' + error-->m4trace: -4- active -> `ACT, IVE' + =><ACT> + =><IVE> + =><ACT> + =><IVE> + foreachq(`x', `active, active', `<x> + ')dnl + error-->m4trace: -3- active -> `ACT, IVE' + error-->m4trace: -3- active -> `ACT, IVE' + =><ACT> + error-->m4trace: -3- active -> `ACT, IVE' + error-->m4trace: -3- active -> `ACT, IVE' + =><IVE> + =><ACT> + =><IVE> + dnl list of quoted macros; expansion occurs during recursion + foreach(`x', `(`active', `active')', `<x> + ')dnl + error-->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + error-->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + foreachq(`x', ``active', `active'', `<x> + ')dnl + error-->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + error-->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + dnl list of double-quoted macro names; no expansion + foreach(`x', `(``active'', ``active'')', `<x> + ')dnl + =><active> + =><active> + foreachq(`x', ```active'', ``active''', `<x> + ')dnl + =><active> + =><active> + + +File: m4.info, Node: Improved copy, Next: Improved m4wrap, Prev: Improved foreach, Up: Answers + +17.4 Solution for `copy' +======================== + +The macro `copy' presented above is unable to handle builtin tokens +with M4 1.4.x, because it tries to pass the builtin token through the +macro `curry', where it is silently flattened to an empty string (*note +Composition::). Rather than using the problematic `curry' to work +around the limitation that `stack_foreach' expects to invoke a macro +that takes exactly one argument, we can write a new macro that lets us +form the exact two-argument `pushdef' call sequence needed, so that we +are no longer passing a builtin token through a text macro. + + -- Composite: stack_foreach_sep (MACRO, PRE, POST, SEP) + -- Composite: stack_foreach_sep_lifo (MACRO, PRE, POST, SEP) + For each of the `pushdef' definitions associated with MACRO, + expand the sequence `PRE`'definition`'POST'. Additionally, expand + SEP between definitions. `stack_foreach_sep' visits the oldest + definition first, while `stack_foreach_sep_lifo' visits the + current definition first. The expansion may dereference MACRO, + but should not modify it. There are a few special macros, such as + `defn', which cannot be used as the MACRO parameter. + + Note that `stack_foreach(`MACRO', `ACTION')' is equivalent to +`stack_foreach_sep(`MACRO', `ACTION(', `)')'. By supplying explicit +parentheses, split among the PRE and POST arguments to +`stack_foreach_sep', it is now possible to construct macro calls with +more than one argument, without passing builtin tokens through a macro +call. It is likewise possible to directly reference the stack +definitions without a macro call, by leaving PRE and POST empty. Thus, +in addition to fixing `copy' on builtin tokens, it also executes with +fewer macro invocations. + + The new macro also adds a separator that is only output after the +first iteration of the helper `_stack_reverse_sep', implemented by +prepending the original SEP to PRE and omitting a SEP argument in +subsequent iterations. Note that the empty string that separates SEP +from PRE is provided as part of the fourth argument when originally +calling `_stack_reverse_sep', and not by writing `$4`'$3' as the third +argument in the recursive call; while the other approach would give the +same output, it does so at the expense of increasing the argument size +on each iteration of `_stack_reverse_sep', which results in quadratic +instead of linear execution time. The improved stack walking macros +are available in `m4-1.4.16/examples/stack_sep.m4': + + $ m4 -I examples + include(`stack_sep.m4') + => + define(`copy', `ifdef(`$2', `errprint(`$2 already defined + ')m4exit(`1')', + `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl + pushdef(`a', `1')pushdef(`a', defn(`divnum')) + => + copy(`a', `b') + => + b + =>0 + popdef(`b') + => + b + =>1 + pushdef(`c', `1')pushdef(`c', `2') + => + stack_foreach_sep_lifo(`c', `', `', `, ') + =>2, 1 + undivert(`stack_sep.m4')dnl + =>divert(`-1') + =># stack_foreach_sep(macro, pre, post, sep) + =># Invoke PRE`'defn`'POST with a single argument of each definition + =># from the definition stack of MACRO, starting with the oldest, and + =># separated by SEP between definitions. + =>define(`stack_foreach_sep', + =>`_stack_reverse_sep(`$1', `tmp-$1')'dnl + =>`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')') + =># stack_foreach_sep_lifo(macro, pre, post, sep) + =># Like stack_foreach_sep, but starting with the newest definition. + =>define(`stack_foreach_sep_lifo', + =>`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl + =>`_stack_reverse_sep(`tmp-$1', `$1')') + =>define(`_stack_reverse_sep', + =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0( + => `$1', `$2', `$4$3')')') + =>divert`'dnl + + +File: m4.info, Node: Improved m4wrap, Next: Improved cleardivert, Prev: Improved copy, Up: Answers + +17.5 Solution for `m4wrap' +========================== + +The replacement `m4wrap' versions presented above, designed to +guarantee FIFO or LIFO order regardless of the underlying M4 +implementation, share a bug when dealing with wrapped text that looks +like parameter expansion. Note how the invocation of `m4wrapN' +interprets these parameters, while using the builtin preserves them for +their intended use. + + $ m4 -I examples + include(`wraplifo.m4') + => + m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') + ') + => + builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b') + ') + => + ^D + =>bar:-a-a,b-2- + =>m4wrap0:---0- + + Additionally, the computation of `_m4wrap_level' and creation of +multiple `m4wrapN' placeholders in the original examples is more +expensive in time and memory than strictly necessary. Notice how the +improved version grabs the wrapped text via `defn' to avoid parameter +expansion, then undefines `_m4wrap_text', before stripping a level of +quotes with `_arg1' to expand the text. That way, each level of +wrapping reuses the single placeholder, which starts each nesting level +in an undefined state. + + Finally, it is worth emulating the GNU M4 extension of saving all +arguments to `m4wrap', separated by a space, rather than saving just +the first argument. This is done with the `join' macro documented +previously (*note Shift::). The improved LIFO example is shipped as +`m4-1.4.16/examples/wraplifo2.m4', and can easily be converted to a +FIFO solution by swapping the adjacent invocations of `joinall' and +`defn'. + + $ m4 -I examples + include(`wraplifo2.m4') + => + undivert(`wraplifo2.m4')dnl + =>dnl Redefine m4wrap to have LIFO semantics, improved example. + =>include(`join.m4')dnl + =>define(`_m4wrap', defn(`m4wrap'))dnl + =>define(`_arg1', `$1')dnl + =>define(`m4wrap', + =>`ifdef(`_$0_text', + => `define(`_$0_text', joinall(` ', $@)defn(`_$0_text'))', + => `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl + =>define(`_$0_text', joinall(` ', $@))')')dnl + m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') + ') + => + m4wrap(`lifo text + m4wrap(`nested', `', `$@ + ')') + => + ^D + =>lifo text + =>foo:-a-a,b-2- + =>nested $@ + + +File: m4.info, Node: Improved cleardivert, Next: Improved capitalize, Prev: Improved m4wrap, Up: Answers + +17.6 Solution for `cleardivert' +=============================== + +The `cleardivert' macro (*note Cleardivert::) cannot, as it stands, be +called without arguments to clear all pending diversions. That is +because using undivert with an empty string for an argument is different +than using it with no arguments at all. Compare the earlier definition +with one that takes the number of arguments into account: + + define(`cleardivert', + `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')') + => + divert(`1')one + divert + => + cleardivert + => + undivert + =>one + => + define(`cleardivert', + `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0', + `undivert`'', `undivert($@)')divert(_num)popdef(`_num')') + => + divert(`2')two + divert + => + cleardivert + => + undivert + => + + +File: m4.info, Node: Improved capitalize, Next: Improved fatal_error, Prev: Improved cleardivert, Up: Answers + +17.7 Solution for `capitalize' +============================== + +The `capitalize' macro (*note Patsubst::) as presented earlier does not +allow clients to follow the quoting rule of thumb. Consider the three +macros `active', `Active', and `ACTIVE', and the difference between +calling `capitalize' with the expansion of a macro, expanding the +result of a case change, and changing the case of a double-quoted +string: + + $ m4 -I examples + include(`capitalize.m4')dnl + define(`active', `act1, ive')dnl + define(`Active', `Act2, Ive')dnl + define(`ACTIVE', `ACT3, IVE')dnl + upcase(active) + =>ACT1,IVE + upcase(`active') + =>ACT3, IVE + upcase(``active'') + =>ACTIVE + downcase(ACTIVE) + =>act3,ive + downcase(`ACTIVE') + =>act1, ive + downcase(``ACTIVE'') + =>active + capitalize(active) + =>Act1 + capitalize(`active') + =>Active + capitalize(``active'') + =>_capitalize(`active') + define(`A', `OOPS') + => + capitalize(active) + =>OOPSct1 + capitalize(`active') + =>OOPSctive + + First, when `capitalize' is called with more than one argument, it +was throwing away later arguments, whereas `upcase' and `downcase' used +`$*' to collect them all. The fix is simple: use `$*' consistently. + + Next, with single-quoting, `capitalize' outputs a single character, +a set of quotes, then the rest of the characters, making it impossible +to invoke `Active' after the fact, and allowing the alternate macro `A' +to interfere. Here, the solution is to use additional quoting in the +helper macros, then pass the final over-quoted output string through +`_arg1' to remove the extra quoting and finally invoke the concatenated +portions as a single string. + + Finally, when passed a double-quoted string, the nested macro +`_capitalize' is never invoked because it ended up nested inside +quotes. This one is the toughest to fix. In short, we have no idea how +many levels of quotes are in effect on the substring being altered by +`patsubst'. If the replacement string cannot be expressed entirely in +terms of literal text and backslash substitutions, then we need a +mechanism to guarantee that the helper macros are invoked outside of +quotes. In other words, this sounds like a job for `changequote' +(*note Changequote::). By changing the active quoting characters, we +can guarantee that replacement text injected by `patsubst' always +occurs in the middle of a string that has exactly one level of +over-quoting using alternate quotes; so the replacement text closes the +quoted string, invokes the helper macros, then reopens the quoted +string. In turn, that means the replacement text has unbalanced quotes, +necessitating another round of `changequote'. + + In the fixed version below, (also shipped as +`m4-1.4.16/examples/capitalize2.m4'), `capitalize' uses the alternate +quotes of `<<[' and `]>>' (the longer strings are chosen so as to be +less likely to appear in the text being converted). The helpers +`_to_alt' and `_from_alt' merely reduce the number of characters +required to perform a `changequote', since the definition changes +twice. The outermost pair means that `patsubst' and `_capitalize_alt' +are invoked with alternate quoting; the innermost pair is used so that +the third argument to `patsubst' can contain an unbalanced `]>>'/`<<[' +pair. Note that `upcase' and `downcase' must be redefined as +`_upcase_alt' and `_downcase_alt', since they contain nested quotes but +are invoked with the alternate quoting scheme in effect. + + $ m4 -I examples + include(`capitalize2.m4')dnl + define(`active', `act1, ive')dnl + define(`Active', `Act2, Ive')dnl + define(`ACTIVE', `ACT3, IVE')dnl + define(`A', `OOPS')dnl + capitalize(active; `active'; ``active''; ```actIVE''') + =>Act1,Ive; Act2, Ive; Active; `Active' + undivert(`capitalize2.m4')dnl + =>divert(`-1') + =># upcase(text) + =># downcase(text) + =># capitalize(text) + =># change case of text, improved version + =>define(`upcase', `translit(`$*', `a-z', `A-Z')') + =>define(`downcase', `translit(`$*', `A-Z', `a-z')') + =>define(`_arg1', `$1') + =>define(`_to_alt', `changequote(`<<[', `]>>')') + =>define(`_from_alt', `changequote(<<[`]>>, <<[']>>)') + =>define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)') + =>define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)') + =>define(`_capitalize_alt', + => `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>, + => <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)') + =>define(`capitalize', + => `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>, + => _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())') + =>divert`'dnl + + +File: m4.info, Node: Improved fatal_error, Prev: Improved capitalize, Up: Answers + +17.8 Solution for `fatal_error' +=============================== + +The `fatal_error' macro (*note M4exit::) is not robust to versions of +GNU M4 earlier than 1.4.8, where invoking `__file__' (*note Location::) +inside `m4wrap' would result in an empty string, and `__line__' +resulted in `0' even though all files start at line 1. Furthermore, +versions earlier than 1.4.6 did not support the `__program__' macro. +If you want `fatal_error' to work across the entire 1.4.x release +series, a better implementation would be: + + define(`fatal_error', + `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl + `:ifelse(__line__, `0', `', + `__file__:__line__:')` fatal error: $* + ')m4exit(`1')') + => + m4wrap(`divnum(`demo of internal message') + fatal_error(`inside wrapped text')') + => + ^D + error-->m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored + =>0 + error-->m4:stdin:6: fatal error: inside wrapped text + + +File: m4.info, Node: Copying This Package, Next: Copying This Manual, Prev: Answers, Up: Top + +Appendix A How to make copies of the overall M4 package +******************************************************* + +This appendix covers the license for copying the source code of the +overall M4 package. This manual is under a different set of +restrictions, covered later (*note Copying This Manual::). + +* Menu: + +* GNU General Public License:: License for copying the M4 package + + +File: m4.info, Node: GNU General Public License, Up: Copying This Package + +A.1 License for copying the M4 package +====================================== + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains +free software for all its users. We, the Free Software Foundation, use +the GNU General Public License for most of our software; it applies +also to any other work released this way by its authors. You can apply +it to your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the software, +or if you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those domains +in future versions of the GPL, as needed to protect the freedom of +users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +==================== + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it + on a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may + convey the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any + non-source form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work + with that Major Component, or to implement a Standard Interface + for which an implementation is available to the public in source + code form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including + scripts to control those activities. However, it does not include + the work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files + associated with source files for the work, and the source code for + shared libraries and dynamically linked subprograms that the work + is specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, + given its content, constitutes a covered work. This License + acknowledges your rights of fair use or other equivalent, as + provided by copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for + you, or provide you with facilities for running those works, + provided that you comply with the terms of this License in + conveying all material for which you do not control copyright. + Those thus making or running the covered works for you must do so + exclusively on your behalf, under your direction and control, on + terms that prohibit them from making any copies of your + copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention + to limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for + as long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of + the written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access + to the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated + by you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to + the object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long + as needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product + is a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or + installed by the recipient, or for the User Product in which it + has been modified or installed. Access to a network may be denied + when the modification itself materially and adversely affects the + operation of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License + with terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be + marked in reasonable ways as different from the original + version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or + conveying under this License, you may add to a covered work + material governed by the terms of that license document, provided + that the further restriction does not survive such relicensing or + conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under + the third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, you do not qualify to receive new + licenses for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to + possession of the Corresponding Source of the work from the + predecessor in interest, if the predecessor has it or can get it + with reasonable efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for + exercise of rights granted under this License, and you may not + initiate litigation (including a cross-claim or counterclaim in a + lawsuit) alleging that any patent claim is infringed by making, + using, selling, offering for sale, or importing the Program or any + portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its + contributor version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To + "grant" such a patent license to a party means to make such an + agreement or commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under + which you make payment to the third party based on the extent of + your activity of conveying the work, and under which the third + party grants, to any of the parties who would receive the covered + work from you, a discriminatory patent license (a) in connection + with copies of the covered work conveyed by you (or copies made + from those copies), or (b) primarily for and in connection with + specific products or compilations that contain the covered work, + unless you entered into that arrangement, or that patent license + was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot convey a covered work so as to satisfy + simultaneously your obligations under this License and any other + pertinent obligations, then as a consequence you may not convey it + at all. For example, if you agree to terms that obligate you to + collect a royalty for further conveying from those to whom you + convey the Program, the only way you could satisfy both those + terms and this License would be to refrain entirely from conveying + the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the + Free Software Foundation. If the Program does not specify a + version number of the GNU General Public License, you may choose + any version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU + FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + + +END OF TERMS AND CONDITIONS +=========================== + +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see `http://www.gnu.org/licenses/'. + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see `http://www.gnu.org/licenses/'. + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. + + +File: m4.info, Node: Copying This Manual, Next: Indices, Prev: Copying This Package, Up: Top + +Appendix B How to make copies of this manual +******************************************** + +This appendix covers the license for copying this manual. Note that +some of the longer examples in this manual are also distributed in the +directory `m4-1.4.16/examples/', where a more permissive license is in +effect when copying just the examples. + +* Menu: + +* GNU Free Documentation License:: License for copying this manual + diff --git a/doc/m4.info-2 b/doc/m4.info-2 new file mode 100644 index 0000000..1ac7d3b --- /dev/null +++ b/doc/m4.info-2 @@ -0,0 +1,909 @@ +This is m4.info, produced by makeinfo version 4.13 from m4.texinfo. + +This manual (28 February 2011) is for GNU M4 (version 1.4.16), a +package containing an implementation of the m4 macro language. + + Copyright (C) 1989-1994, 2004-2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License." + +INFO-DIR-SECTION Text creation and manipulation +START-INFO-DIR-ENTRY +* M4: (m4). A powerful macro processor. +END-INFO-DIR-ENTRY + + +File: m4.info, Node: GNU Free Documentation License, Up: Copying This Manual + +B.1 License for copying this manual +=================================== + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, receipt of a copy of some or all of + the same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. If the Document specifies that a proxy + can decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: m4.info, Node: Indices, Prev: Copying This Manual, Up: Top + +Appendix C Indices of concepts and macros +***************************************** + +* Menu: + +* Macro index:: Index for all `m4' macros +* Concept index:: Index for many concepts + + +File: m4.info, Node: Macro index, Next: Concept index, Up: Indices + +C.1 Index for all `m4' macros +============================= + +This index covers all `m4' builtins, as well as several useful +composite macros. References are exclusively to the places where a +macro is introduced the first time. + + +* Menu: + +* __file__: Location. (line 10) +* __gnu__: Platform macros. (line 12) +* __line__: Location. (line 11) +* __os2__: Platform macros. (line 13) +* __program__: Location. (line 12) +* __unix__: Platform macros. (line 15) +* __windows__: Platform macros. (line 17) +* argn: Shift. (line 258) +* array: Define. (line 56) +* array_set: Define. (line 57) +* builtin: Builtin. (line 9) +* capitalize: Patsubst. (line 55) +* changecom: Changecom. (line 10) +* changequote: Changequote. (line 10) +* changeword: Changeword. (line 23) +* cleardivert: Cleardivert. (line 26) +* cond: Shift. (line 53) +* copy: Composition. (line 120) +* curry: Composition. (line 68) +* debugfile: Debug Output. (line 11) +* debugmode: Debug Levels. (line 78) +* decr: Incr. (line 11) +* define: Define. (line 10) +* define_blind: Composition. (line 11) +* defn: Defn. (line 10) +* divert: Divert. (line 9) +* divnum: Divnum. (line 9) +* dnl: Dnl. (line 9) +* downcase: Patsubst. (line 54) +* dquote: Shift. (line 196) +* dquote_elt: Shift. (line 197) +* dumpdef: Dumpdef. (line 10) +* errprint: Errprint. (line 9) +* esyscmd: Esyscmd. (line 9) +* eval: Eval. (line 9) +* example: Manual. (line 40) +* exch: Arguments. (line 13) +* fatal_error: M4exit. (line 25) +* foreach: Foreach. (line 9) +* foreachq: Foreach. (line 10) +* forloop: Forloop. (line 9) +* format: Format. (line 9) +* ifdef: Ifdef. (line 10) +* ifelse: Ifelse. (line 11) +* include: Include. (line 9) +* incr: Incr. (line 10) +* index: Index macro. (line 9) +* indir: Indir. (line 9) +* join: Shift. (line 104) +* joinall: Shift. (line 105) +* len: Len. (line 9) +* m4exit: M4exit. (line 10) +* m4wrap: M4wrap. (line 14) +* maketemp: Mkstemp. (line 12) +* mkstemp: Mkstemp. (line 11) +* nargs: Pseudo Arguments. (line 13) +* os2: Platform macros. (line 14) +* patsubst: Patsubst. (line 9) +* popdef: Pushdef. (line 12) +* pushdef: Pushdef. (line 11) +* quote: Shift. (line 195) +* regexp: Regexp. (line 9) +* rename: Composition. (line 121) +* reverse: Shift. (line 32) +* shift: Shift. (line 17) +* sinclude: Include. (line 10) +* stack_foreach: Stacks. (line 12) +* stack_foreach_lifo: Stacks. (line 13) +* stack_foreach_sep: Improved copy. (line 16) +* stack_foreach_sep_lifo: Improved copy. (line 17) +* substr: Substr. (line 9) +* syscmd: Syscmd. (line 9) +* sysval: Sysval. (line 9) +* traceoff: Trace. (line 11) +* traceon: Trace. (line 10) +* translit: Translit. (line 9) +* undefine: Undefine. (line 9) +* undivert: Undivert. (line 9) +* unix: Platform macros. (line 16) +* upcase: Patsubst. (line 53) +* windows: Platform macros. (line 18) + + +File: m4.info, Node: Concept index, Prev: Macro index, Up: Indices + +C.2 Index for many concepts +=========================== + + +* Menu: + +* argument currying: Composition. (line 63) +* arguments to macros <1>: Arguments. (line 6) +* arguments to macros: Macro Arguments. (line 6) +* arguments to macros, special: Pseudo Arguments. (line 6) +* arguments, joining: Shift. (line 100) +* arguments, more than nine <1>: Improved foreach. (line 155) +* arguments, more than nine <2>: Shift. (line 252) +* arguments, more than nine: Arguments. (line 54) +* arguments, quoted macro: Quoting Arguments. (line 6) +* arguments, reversing: Shift. (line 31) +* arithmetic: Arithmetic. (line 6) +* arrays: Define. (line 52) +* avoiding quadratic behavior: Improved foreach. (line 38) +* basic regular expressions <1>: Patsubst. (line 6) +* basic regular expressions: Regexp. (line 6) +* blind macro <1>: Composition. (line 10) +* blind macro <2>: Ifelse. (line 52) +* blind macro: Inhibiting Invocation. + (line 14) +* bug reports: Bugs. (line 6) +* builtins, indirect call of: Builtin. (line 6) +* builtins, special tokens: Defn. (line 101) +* call of builtins, indirect: Builtin. (line 6) +* call of macros, indirect: Indir. (line 6) +* case statement: Ifelse. (line 69) +* changing comment delimiters: Changecom. (line 6) +* changing quote delimiters: Changequote. (line 6) +* changing syntax: Changeword. (line 6) +* characters, translating: Translit. (line 6) +* command line: Invoking m4. (line 6) +* command line, file names on the: Command line files. (line 6) +* command line, macro definitions on the: Preprocessor features. + (line 6) +* command line, options: Invoking m4. (line 10) +* commands, exit status from shell: Sysval. (line 6) +* commands, running shell: Shell commands. (line 6) +* comment delimiters, changing: Changecom. (line 6) +* comments: Comments. (line 6) +* comments, copied to output: Changecom. (line 29) +* comparing strings: Ifelse. (line 6) +* compatibility: Compatibility. (line 6) +* composing macros: Composition. (line 6) +* concatenating arguments: Shift. (line 100) +* conditional, short-circuiting: Shift. (line 51) +* conditionals: Ifdef. (line 6) +* controlling debugging output: Debug Levels. (line 6) +* copying macros: Composition. (line 116) +* counting loops: Forloop. (line 6) +* currying arguments: Composition. (line 63) +* debugging macros: Debugging. (line 6) +* debugging output, controlling: Debug Levels. (line 6) +* debugging output, saving: Debug Output. (line 6) +* decrement operator: Incr. (line 6) +* deferring expansion: M4wrap. (line 6) +* deferring output: Diversions. (line 6) +* defining new macros: Definitions. (line 6) +* definition stack <1>: Stacks. (line 6) +* definition stack: Pushdef. (line 6) +* definitions, displaying macro <1>: Dumpdef. (line 6) +* definitions, displaying macro: Defn. (line 6) +* deleting macros: Undefine. (line 6) +* deleting whitespace in input: Dnl. (line 6) +* delimiters, changing <1>: Changecom. (line 6) +* delimiters, changing: Changequote. (line 6) +* discarding diverted text: Cleardivert. (line 6) +* discarding input <1>: Divert. (line 42) +* discarding input <2>: Dnl. (line 6) +* discarding input: Ifelse. (line 6) +* displaying macro definitions: Dumpdef. (line 6) +* diversion numbers: Divnum. (line 6) +* diverted text, discarding: Cleardivert. (line 6) +* diverting output to files: Divert. (line 6) +* dumping into frozen file: Using frozen files. (line 6) +* error messages, printing: Errprint. (line 6) +* errors, fatal: Operation modes. (line 20) +* evaluation, of integer expressions: Eval. (line 6) +* examples, understanding: Manual. (line 6) +* executing shell commands: Shell commands. (line 6) +* exit status from shell commands: Sysval. (line 6) +* exiting from m4: M4exit. (line 6) +* expansion of macros: Macro expansion. (line 6) +* expansion, deferring: M4wrap. (line 6) +* expansion, tracing macro: Trace. (line 6) +* expressions, evaluation of integer: Eval. (line 6) +* expressions, regular <1>: Patsubst. (line 6) +* expressions, regular: Regexp. (line 6) +* extracting substrings: Substr. (line 6) +* fast loading of frozen files: Using frozen files. (line 6) +* fatal errors: Operation modes. (line 20) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* file format, frozen file: Frozen file format. (line 6) +* file inclusion <1>: Undivert. (line 13) +* file inclusion: File Inclusion. (line 6) +* file names, on the command line: Command line files. (line 6) +* files, diverting output to: Divert. (line 6) +* files, names of temporary: Mkstemp. (line 6) +* for each loops: Foreach. (line 6) +* for loops: Forloop. (line 6) +* formatted output: Format. (line 6) +* Free Documentation License (FDL), GNU: GNU Free Documentation License. + (line 6) +* frozen file format: Frozen file format. (line 6) +* frozen files for fast loading: Using frozen files. (line 6) +* General Public License (GPL), GNU: GNU General Public License. + (line 6) +* GNU extensions <1>: Extensions. (line 6) +* GNU extensions <2>: Using frozen files. (line 6) +* GNU extensions <3>: Mkstemp. (line 59) +* GNU extensions <4>: Esyscmd. (line 6) +* GNU extensions <5>: Eval. (line 125) +* GNU extensions <6>: Format. (line 6) +* GNU extensions <7>: Patsubst. (line 6) +* GNU extensions <8>: Regexp. (line 6) +* GNU extensions <9>: Undivert. (line 13) +* GNU extensions <10>: Divert. (line 54) +* GNU extensions <11>: Search Path. (line 6) +* GNU extensions <12>: Debug Output. (line 6) +* GNU extensions <13>: Debug Levels. (line 74) +* GNU extensions <14>: Builtin. (line 6) +* GNU extensions <15>: Indir. (line 6) +* GNU extensions <16>: Arguments. (line 54) +* GNU extensions <17>: Define. (line 41) +* GNU extensions: Inhibiting Invocation. + (line 14) +* GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* GNU General Public License: GNU General Public License. + (line 6) +* GNU M4, history of: History. (line 6) +* GPL, GNU General Public License: GNU General Public License. + (line 6) +* history of m4: History. (line 6) +* included files, search path for: Search Path. (line 6) +* inclusion, of files <1>: Undivert. (line 13) +* inclusion, of files: File Inclusion. (line 6) +* increment operator: Incr. (line 6) +* indirect call of builtins: Builtin. (line 6) +* indirect call of macros: Indir. (line 6) +* initialization, frozen state: Using frozen files. (line 6) +* input location <1>: Location. (line 6) +* input location: Preprocessor features. + (line 28) +* input tokens: Syntax. (line 6) +* input, discarding <1>: Divert. (line 42) +* input, discarding <2>: Dnl. (line 6) +* input, discarding: Ifelse. (line 6) +* input, saving: M4wrap. (line 6) +* integer arithmetic: Arithmetic. (line 6) +* integer expression evaluation: Eval. (line 6) +* invoking m4: Invoking m4. (line 6) +* invoking macros: Invocation. (line 6) +* iterating over lists: Foreach. (line 6) +* joining arguments: Shift. (line 100) +* length of strings: Len. (line 6) +* lexical structure of words: Changeword. (line 6) +* License, code: Copying This Package. + (line 6) +* License, manual: Copying This Manual. (line 6) +* limit, nesting: Limits control. (line 43) +* literal output: Pseudo Arguments. (line 106) +* local variables: Pushdef. (line 79) +* location, input <1>: Location. (line 6) +* location, input: Preprocessor features. + (line 28) +* loops: Shift. (line 10) +* loops, counting: Forloop. (line 6) +* loops, list iteration: Foreach. (line 6) +* M4PATH: Search Path. (line 9) +* macro composition: Composition. (line 6) +* macro definitions, on the command line: Preprocessor features. + (line 6) +* macro expansion, tracing: Trace. (line 6) +* macro invocation: Invocation. (line 6) +* macro, blind <1>: Composition. (line 10) +* macro, blind <2>: Ifelse. (line 52) +* macro, blind: Inhibiting Invocation. + (line 14) +* macros, arguments to <1>: Arguments. (line 6) +* macros, arguments to: Macro Arguments. (line 6) +* macros, copying: Composition. (line 116) +* macros, debugging: Debugging. (line 6) +* macros, displaying definitions <1>: Dumpdef. (line 6) +* macros, displaying definitions: Defn. (line 6) +* macros, expansion of: Macro expansion. (line 6) +* macros, how to define new: Definitions. (line 6) +* macros, how to delete: Undefine. (line 6) +* macros, how to rename: Defn. (line 6) +* macros, indirect call of: Indir. (line 6) +* macros, quoted arguments to: Quoting Arguments. (line 6) +* macros, recursive: Shift. (line 6) +* macros, special arguments to: Pseudo Arguments. (line 6) +* macros, temporary redefinition of: Pushdef. (line 6) +* manipulating quotes: Shift. (line 191) +* messages, printing error: Errprint. (line 6) +* more than nine arguments <1>: Improved foreach. (line 155) +* more than nine arguments <2>: Shift. (line 252) +* more than nine arguments: Arguments. (line 54) +* multibranches: Ifelse. (line 69) +* names: Names. (line 6) +* nesting limit: Limits control. (line 43) +* nine arguments, more than <1>: Improved foreach. (line 155) +* nine arguments, more than <2>: Shift. (line 252) +* nine arguments, more than: Arguments. (line 54) +* numbers: Manual. (line 57) +* options, command line: Invoking m4. (line 10) +* output, diverting to files: Divert. (line 6) +* output, formatted: Format. (line 6) +* output, literal: Pseudo Arguments. (line 106) +* output, saving debugging: Debug Output. (line 6) +* overview of m4: Intro. (line 6) +* pattern substitution: Patsubst. (line 6) +* platform macros: Platform macros. (line 6) +* positional parameters, more than nine: Arguments. (line 54) +* POSIX: Extensions. (line 6) +* POSIXLY_CORRECT <1>: Incompatibilities. (line 146) +* POSIXLY_CORRECT: Invoking m4. (line 10) +* preprocessor features: Preprocessor features. + (line 6) +* printing error messages: Errprint. (line 6) +* pushdef stack <1>: Stacks. (line 6) +* pushdef stack: Pushdef. (line 6) +* quadratic behavior, avoiding: Improved foreach. (line 38) +* quote delimiters, changing: Changequote. (line 6) +* quote manipulation: Shift. (line 191) +* quoted macro arguments: Quoting Arguments. (line 6) +* quoted string: Quoted strings. (line 6) +* quoting rule of thumb: Quoting Arguments. (line 22) +* recursive macros: Shift. (line 6) +* redefinition of macros, temporary: Pushdef. (line 6) +* regular expressions <1>: Patsubst. (line 6) +* regular expressions <2>: Regexp. (line 6) +* regular expressions: Changeword. (line 6) +* reloading a frozen file: Using frozen files. (line 6) +* renaming macros <1>: Composition. (line 116) +* renaming macros: Defn. (line 6) +* reporting bugs: Bugs. (line 6) +* rescanning <1>: Other Incompatibilities. + (line 52) +* rescanning <2>: Defn. (line 61) +* rescanning <3>: Pseudo Arguments. (line 106) +* rescanning <4>: Inhibiting Invocation. + (line 87) +* rescanning: Limits control. (line 56) +* reversing arguments: Shift. (line 31) +* rule of thumb, quoting: Quoting Arguments. (line 22) +* running shell commands: Shell commands. (line 6) +* saving debugging output: Debug Output. (line 6) +* saving input: M4wrap. (line 6) +* search path for included files: Search Path. (line 6) +* shell commands, exit status from: Sysval. (line 6) +* shell commands, running: Shell commands. (line 6) +* short-circuiting conditional: Shift. (line 51) +* special arguments to macros: Pseudo Arguments. (line 6) +* stack, macro definition <1>: Stacks. (line 6) +* stack, macro definition: Pushdef. (line 6) +* standard error, output to <1>: Errprint. (line 6) +* standard error, output to <2>: Trace. (line 6) +* standard error, output to: Dumpdef. (line 6) +* status of shell commands: Sysval. (line 6) +* status, setting m4 exit: M4exit. (line 6) +* string, quoted: Quoted strings. (line 6) +* strings, length of: Len. (line 6) +* substitution by regular expression: Patsubst. (line 6) +* substrings, extracting: Substr. (line 6) +* substrings, locating: Index macro. (line 6) +* suggestions, reporting: Bugs. (line 6) +* suppressing warnings: Macro Arguments. (line 38) +* switch statement: Ifelse. (line 69) +* synchronization lines: Preprocessor features. + (line 28) +* syntax, changing: Changeword. (line 6) +* temporary file names: Mkstemp. (line 6) +* temporary redefinition of macros: Pushdef. (line 6) +* TMPDIR: Diversions. (line 10) +* tokens: Syntax. (line 6) +* tokens, builtin macro: Defn. (line 101) +* tokens, special: Other tokens. (line 6) +* tracing macro expansion: Trace. (line 6) +* translating characters: Translit. (line 6) +* undefining macros: Undefine. (line 6) +* UNIX commands, exit status from: Sysval. (line 6) +* UNIX commands, running: Shell commands. (line 6) +* variables, local: Pushdef. (line 79) +* warnings, suppressing: Macro Arguments. (line 38) +* words: Names. (line 6) +* words, lexical structure of: Changeword. (line 6) + + diff --git a/doc/m4.texinfo b/doc/m4.texinfo new file mode 100644 index 0000000..1dcc8e4 --- /dev/null +++ b/doc/m4.texinfo @@ -0,0 +1,8729 @@ +\input texinfo @c -*- texinfo -*- +@comment ======================================================== +@comment %**start of header +@setfilename m4.info +@include version.texi +@settitle GNU M4 @value{VERSION} macro processor +@setchapternewpage odd +@ifnothtml +@setcontentsaftertitlepage +@end ifnothtml +@finalout + +@c @tabchar{} +@c ---------- +@c The testsuite expects literal tab output in some examples, but +@c literal tabs in texinfo lead to formatting issues. +@macro tabchar +@ @c +@end macro + +@c @ovar{ARG} +@c ------------------- +@c The ARG is an optional argument. To be used for macro arguments in +@c their documentation (@defmac). +@macro ovar{varname} +@r{[}@var{\varname\}@r{]}@c +@end macro + +@c @dvar{ARG, DEFAULT} +@c ------------------- +@c The ARG is an optional argument, defaulting to DEFAULT. To be used +@c for macro arguments in their documentation (@defmac). +@macro dvar{varname, default} +@r{[}@var{\varname\} = @samp{\default\}@r{]}@c +@end macro + +@comment %**end of header +@comment ======================================================== + +@copying + +This manual (@value{UPDATED}) is for GNU M4 (version +@value{VERSION}), a package containing an implementation of the m4 macro +language. + +Copyright @copyright{} 1989-1994, 2004-2011 Free Software Foundation, +Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, +Version 1.3 or any later version published by the Free Software +Foundation; with no Invariant Sections, no Front-Cover Texts, and no +Back-Cover Texts. A copy of the license is included in the section +entitled ``GNU Free Documentation License.'' +@end quotation +@end copying + +@dircategory Text creation and manipulation +@direntry +* M4: (m4). A powerful macro processor. +@end direntry + +@titlepage +@title GNU M4, version @value{VERSION} +@subtitle A powerful macro processor +@subtitle Edition @value{EDITION}, @value{UPDATED} +@author by Ren@'e Seindal, Fran@,{c}ois Pinard, +@author Gary V. Vaughan, and Eric Blake +@author (@email{bug-m4@@gnu.org}) + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU M4 +@insertcopying +@end ifnottex + +GNU @code{m4} is an implementation of the traditional UNIX macro +processor. It is mostly SVR4 compatible, although it has some +extensions (for example, handling more than 9 positional parameters +to macros). @code{m4} also has builtin functions for including +files, running shell commands, doing arithmetic, etc. Autoconf needs +GNU @code{m4} for generating @file{configure} scripts, but not for +running them. + +GNU @code{m4} was originally written by Ren@'e Seindal, with +subsequent changes by Fran@,{c}ois Pinard and other volunteers +on the Internet. All names and email addresses can be found in the +files @file{m4-@value{VERSION}/@/AUTHORS} and +@file{m4-@value{VERSION}/@/THANKS} from the GNU M4 +distribution. + +This is release @value{VERSION}. It is now considered stable: future +releases in the 1.4.x series are only meant to fix bugs, increase speed, +or improve documentation. However@dots{} + +An experimental feature, which would improve @code{m4} usefulness, +allows for changing the syntax for what is a @dfn{word} in @code{m4}. +You should use: +@comment ignore +@example +./configure --enable-changeword +@end example +@noindent +if you want this feature compiled in. The current implementation +slows down @code{m4} considerably and is hardly acceptable. In the +future, @code{m4} 2.0 will come with a different set of new features +that provide similar capabilities, but without the inefficiencies, so +changeword will go away and @emph{you should not count on it}. + +@menu +* Preliminaries:: Introduction and preliminaries +* Invoking m4:: Invoking @code{m4} +* Syntax:: Lexical and syntactic conventions + +* Macros:: How to invoke macros +* Definitions:: How to define new macros +* Conditionals:: Conditionals, loops, and recursion + +* Debugging:: How to debug macros and input + +* Input Control:: Input control +* File Inclusion:: File inclusion +* Diversions:: Diverting and undiverting output + +* Text handling:: Macros for text handling +* Arithmetic:: Macros for doing arithmetic +* Shell commands:: Macros for running shell commands +* Miscellaneous:: Miscellaneous builtin macros +* Frozen files:: Fast loading of frozen state + +* Compatibility:: Compatibility with other versions of @code{m4} +* Answers:: Correct version of some examples + +* Copying This Package:: How to make copies of the overall M4 package +* Copying This Manual:: How to make copies of this manual +* Indices:: Indices of concepts and macros + +@detailmenu + --- The Detailed Node Listing --- + +Introduction and preliminaries + +* Intro:: Introduction to @code{m4} +* History:: Historical references +* Bugs:: Problems and bugs +* Manual:: Using this manual + +Invoking @code{m4} + +* Operation modes:: Command line options for operation modes +* Preprocessor features:: Command line options for preprocessor features +* Limits control:: Command line options for limits control +* Frozen state:: Command line options for frozen state +* Debugging options:: Command line options for debugging +* Command line files:: Specifying input files on the command line + +Lexical and syntactic conventions + +* Names:: Macro names +* Quoted strings:: Quoting input to @code{m4} +* Comments:: Comments in @code{m4} input +* Other tokens:: Other kinds of input tokens +* Input processing:: How @code{m4} copies input to output + +How to invoke macros + +* Invocation:: Macro invocation +* Inhibiting Invocation:: Preventing macro invocation +* Macro Arguments:: Macro arguments +* Quoting Arguments:: On Quoting Arguments to macros +* Macro expansion:: Expanding macros + +How to define new macros + +* Define:: Defining a new macro +* Arguments:: Arguments to macros +* Pseudo Arguments:: Special arguments to macros +* Undefine:: Deleting a macro +* Defn:: Renaming macros +* Pushdef:: Temporarily redefining macros + +* Indir:: Indirect call of macros +* Builtin:: Indirect call of builtins + +Conditionals, loops, and recursion + +* Ifdef:: Testing if a macro is defined +* Ifelse:: If-else construct, or multibranch +* Shift:: Recursion in @code{m4} +* Forloop:: Iteration by counting +* Foreach:: Iteration by list contents +* Stacks:: Working with definition stacks +* Composition:: Building macros with macros + +How to debug macros and input + +* Dumpdef:: Displaying macro definitions +* Trace:: Tracing macro calls +* Debug Levels:: Controlling debugging output +* Debug Output:: Saving debugging output + +Input control + +* Dnl:: Deleting whitespace in input +* Changequote:: Changing the quote characters +* Changecom:: Changing the comment delimiters +* Changeword:: Changing the lexical structure of words +* M4wrap:: Saving text until end of input + +File inclusion + +* Include:: Including named files +* Search Path:: Searching for include files + +Diverting and undiverting output + +* Divert:: Diverting output +* Undivert:: Undiverting output +* Divnum:: Diversion numbers +* Cleardivert:: Discarding diverted text + +Macros for text handling + +* Len:: Calculating length of strings +* Index macro:: Searching for substrings +* Regexp:: Searching for regular expressions +* Substr:: Extracting substrings +* Translit:: Translating characters +* Patsubst:: Substituting text by regular expression +* Format:: Formatting strings (printf-like) + +Macros for doing arithmetic + +* Incr:: Decrement and increment operators +* Eval:: Evaluating integer expressions + +Macros for running shell commands + +* Platform macros:: Determining the platform +* Syscmd:: Executing simple commands +* Esyscmd:: Reading the output of commands +* Sysval:: Exit status +* Mkstemp:: Making temporary files + +Miscellaneous builtin macros + +* Errprint:: Printing error messages +* Location:: Printing current location +* M4exit:: Exiting from @code{m4} + +Fast loading of frozen state + +* Using frozen files:: Using frozen files +* Frozen file format:: Frozen file format + +Compatibility with other versions of @code{m4} + +* Extensions:: Extensions in GNU M4 +* Incompatibilities:: Facilities in System V m4 not in GNU M4 +* Other Incompatibilities:: Other incompatibilities + +Correct version of some examples + +* Improved exch:: Solution for @code{exch} +* Improved forloop:: Solution for @code{forloop} +* Improved foreach:: Solution for @code{foreach} +* Improved copy:: Solution for @code{copy} +* Improved m4wrap:: Solution for @code{m4wrap} +* Improved cleardivert:: Solution for @code{cleardivert} +* Improved capitalize:: Solution for @code{capitalize} +* Improved fatal_error:: Solution for @code{fatal_error} + +How to make copies of the overall M4 package + +* GNU General Public License:: License for copying the M4 package + +How to make copies of this manual + +* GNU Free Documentation License:: License for copying this manual + +Indices of concepts and macros + +* Macro index:: Index for all @code{m4} macros +* Concept index:: Index for many concepts + +@end detailmenu +@end menu + +@node Preliminaries +@chapter Introduction and preliminaries + +This first chapter explains what GNU @code{m4} is, where @code{m4} +comes from, how to read and use this documentation, how to call the +@code{m4} program, and how to report bugs about it. It concludes by +giving tips for reading the remainder of the manual. + +The following chapters then detail all the features of the @code{m4} +language. + +@menu +* Intro:: Introduction to @code{m4} +* History:: Historical references +* Bugs:: Problems and bugs +* Manual:: Using this manual +@end menu + +@node Intro +@section Introduction to @code{m4} + +@cindex overview of @code{m4} +@code{m4} is a macro processor, in the sense that it copies its +input to the output, expanding macros as it goes. Macros are either +builtin or user-defined, and can take any number of arguments. +Besides just doing macro expansion, @code{m4} has builtin functions +for including named files, running shell commands, doing integer +arithmetic, manipulating text in various ways, performing recursion, +etc.@dots{} @code{m4} can be used either as a front-end to a compiler, +or as a macro processor in its own right. + +The @code{m4} macro processor is widely available on all UNIXes, and has +been standardized by POSIX. +Usually, only a small percentage of users are aware of its existence. +However, those who find it often become committed users. The +popularity of GNU Autoconf, which requires GNU +@code{m4} for @emph{generating} @file{configure} scripts, is an incentive +for many to install it, while these people will not themselves +program in @code{m4}. GNU @code{m4} is mostly compatible with the +System V, Release 3 version, except for some minor differences. +@xref{Compatibility}, for more details. + +Some people find @code{m4} to be fairly addictive. They first use +@code{m4} for simple problems, then take bigger and bigger challenges, +learning how to write complex sets of @code{m4} macros along the way. +Once really addicted, users pursue writing of sophisticated @code{m4} +applications even to solve simple problems, devoting more time +debugging their @code{m4} scripts than doing real work. Beware that +@code{m4} may be dangerous for the health of compulsive programmers. + +@node History +@section Historical references + +@cindex history of @code{m4} +@cindex GNU M4, history of +@code{GPM} was an important ancestor of @code{m4}. See +C. Strachey: ``A General Purpose Macro generator'', Computer Journal +8,3 (1965), pp.@: 225 ff. @code{GPM} is also succinctly described into +David Gries classic ``Compiler Construction for Digital Computers''. + +The classic B. Kernighan and P.J. Plauger: ``Software Tools'', +Addison-Wesley, Inc.@: (1976) describes and implements a Unix +macro-processor language, which inspired Dennis Ritchie to write +@code{m3}, a macro processor for the AP-3 minicomputer. + +Kernighan and Ritchie then joined forces to develop the original +@code{m4}, as described in ``The M4 Macro Processor'', Bell +Laboratories (1977). It had only 21 builtin macros. + +While @code{GPM} was more @emph{pure}, @code{m4} is meant to deal with +the true intricacies of real life: macros can be recognized without +being pre-announced, skipping whitespace or end-of-lines is easier, +more constructs are builtin instead of derived, etc. + +Originally, the Kernighan and Plauger macro-processor, and then +@code{m3}, formed the engine for the Rational FORTRAN preprocessor, +that is, the @code{Ratfor} equivalent of @code{cpp}. Later, @code{m4} +was used as a front-end for @code{Ratfor}, @code{C} and @code{Cobol}. + +Ren@'e Seindal released his implementation of @code{m4}, GNU +@code{m4}, +in 1990, with the aim of removing the artificial limitations in many +of the traditional @code{m4} implementations, such as maximum line +length, macro size, or number of macros. + +The late Professor A. Dain Samples described and implemented a further +evolution in the form of @code{M5}: ``User's Guide to the M5 Macro +Language: 2nd edition'', Electronic Announcement on comp.compilers +newsgroup (1992). + +Fran@,{c}ois Pinard took over maintenance of GNU @code{m4} in +1992, until 1994 when he released GNU @code{m4} 1.4, which was +the stable release for 10 years. It was at this time that GNU +Autoconf decided to require GNU @code{m4} as its underlying +engine, since all other implementations of @code{m4} had too many +limitations. + +More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which +addressed some long standing bugs in the venerable 1.4 release. Then in +2005, Gary V. Vaughan collected together the many patches to +GNU @code{m4} 1.4 that were floating around the net and +released 1.4.3 and 1.4.4. And in 2006, Eric Blake joined the team and +prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8. +More bug fixes were incorporated in 2007, with releases 1.4.9 and +1.4.10. Eric continued with some portability fixes for 1.4.11 and +1.4.12 in 2008, 1.4.13 in 2009, 1.4.14 and 1.4.15 in 2010, and 1.4.16 in +2011. + +Meanwhile, development has continued on new features for @code{m4}, such +as dynamic module loading and additional builtins. When complete, +GNU @code{m4} 2.0 will start a new series of releases. + +@node Bugs +@section Problems and bugs + +@cindex reporting bugs +@cindex bug reports +@cindex suggestions, reporting +If you have problems with GNU M4 or think you've found a bug, +please report it. Before reporting a bug, make sure you've actually +found a real bug. Carefully reread the documentation and see if it +really says you can do what you're trying to do. If it's not clear +whether you should be able to do something or not, report that too; it's +a bug in the documentation! + +Before reporting a bug or trying to fix it yourself, try to isolate it +to the smallest possible input file that reproduces the problem. Then +send us the input file and the exact results @code{m4} gave you. Also +say what you expected to occur; this will help us decide whether the +problem was really in the documentation. + +Once you've got a precise problem, send e-mail to +@email{bug-m4@@gnu.org}. Please include the version number of @code{m4} +you are using. You can get this information with the command +@kbd{m4 --version}. Also provide details about the platform you are +executing on. + +Non-bug suggestions are always welcome as well. If you have questions +about things that are unclear in the documentation or are just obscure +features, please report them too. + +@node Manual +@section Using this manual + +@cindex examples, understanding +This manual contains a number of examples of @code{m4} input and output, +and a simple notation is used to distinguish input, output and error +messages from @code{m4}. Examples are set out from the normal text, and +shown in a fixed width font, like this + +@comment ignore +@example +This is an example of an example! +@end example + +To distinguish input from output, all output from @code{m4} is prefixed +by the string @samp{@result{}}, and all error messages by the string +@samp{@error{}}. When showing how command line options affect matters, +the command line is shown with a prompt @samp{$ @kbd{like this}}, +otherwise, you can assume that a simple @kbd{m4} invocation will work. +Thus: + +@comment ignore +@example +$ @kbd{command line to invoke m4} +Example of input line +@result{}Output line from m4 +@error{}and an error message +@end example + +The sequence @samp{^D} in an example indicates the end of the input +file. The sequence @samp{@key{NL}} refers to the newline character. +The majority of these examples are self-contained, and you can run them +with similar results by invoking @kbd{m4 -d}. In fact, the testsuite +that is bundled in the GNU M4 package consists of the examples +in this document! Some of the examples assume that your current +directory is located where you unpacked the installation, so if you plan +on following along, you may find it helpful to do this now: + +@comment ignore +@example +$ @kbd{cd m4-@value{VERSION}} +@end example + +As each of the predefined macros in @code{m4} is described, a prototype +call of the macro will be shown, giving descriptive names to the +arguments, e.g., + +@deffn Composite example (@var{string}, @dvar{count, 1}, @ + @ovar{argument}@dots{}) +This is a sample prototype. There is not really a macro named +@code{example}, but this documents that if there were, it would be a +Composite macro, rather than a Builtin. It requires at least one +argument, @var{string}. Remember that in @code{m4}, there must not be a +space between the macro name and the opening parenthesis, unless it was +intended to call the macro without any arguments. The brackets around +@var{count} and @var{argument} show that these arguments are optional. +If @var{count} is omitted, the macro behaves as if count were @samp{1}, +whereas if @var{argument} is omitted, the macro behaves as if it were +the empty string. A blank argument is not the same as an omitted +argument. For example, @samp{example(`a')}, @samp{example(`a',`1')}, +and @samp{example(`a',`1',)} would behave identically with @var{count} +set to @samp{1}; while @samp{example(`a',)} and @samp{example(`a',`')} +would explicitly pass the empty string for @var{count}. The ellipses +(@samp{@dots{}}) show that the macro processes additional arguments +after @var{argument}, rather than ignoring them. +@end deffn + +@cindex numbers +All macro arguments in @code{m4} are strings, but some are given +special interpretation, e.g., as numbers, file names, regular +expressions, etc. The documentation for each macro will state how the +parameters are interpreted, and what happens if the argument cannot be +parsed according to the desired interpretation. Unless specified +otherwise, a parameter specified to be a number is parsed as a decimal, +even if the argument has leading zeros; and parsing the empty string as +a number results in 0 rather than an error, although a warning will be +issued. + +This document consistently writes and uses @dfn{builtin}, without a +hyphen, as if it were an English word. This is how the @code{builtin} +primitive is spelled within @code{m4}. + +@node Invoking m4 +@chapter Invoking @code{m4} + +@cindex command line +@cindex invoking @code{m4} +The format of the @code{m4} command is: + +@comment ignore +@example +@code{m4} @r{[}@var{option}@dots{}@r{]} @r{[}@var{file}@dots{}@r{]} +@end example + +@cindex command line, options +@cindex options, command line +@cindex @env{POSIXLY_CORRECT} +All options begin with @samp{-}, or if long option names are used, with +@samp{--}. A long option name need not be written completely, any +unambiguous prefix is sufficient. POSIX requires @code{m4} to +recognize arguments intermixed with files, even when +@env{POSIXLY_CORRECT} is set in the environment. Most options take +effect at startup regardless of their position, but some are documented +below as taking effect after any files that occurred earlier in the +command line. The argument @option{--} is a marker to denote the end of +options. + +With short options, options that do not take arguments may be combined +into a single command line argument with subsequent options, options +with mandatory arguments may be provided either as a single command line +argument or as two arguments, and options with optional arguments must +be provided as a single argument. In other words, +@kbd{m4 -QPDfoo -d a -df} is equivalent to +@kbd{m4 -Q -P -D foo -d -df -- ./a}, although the latter form is +considered canonical. + +With long options, options with mandatory arguments may be provided with +an equal sign (@samp{=}) in a single argument, or as two arguments, and +options with optional arguments must be provided as a single argument. +In other words, @kbd{m4 --def foo --debug a} is equivalent to +@kbd{m4 --define=foo --debug= -- ./a}, although the latter form is +considered canonical (not to mention more robust, in case a future +version of @code{m4} introduces an option named @option{--default}). + +@code{m4} understands the following options, grouped by functionality. + +@menu +* Operation modes:: Command line options for operation modes +* Preprocessor features:: Command line options for preprocessor features +* Limits control:: Command line options for limits control +* Frozen state:: Command line options for frozen state +* Debugging options:: Command line options for debugging +* Command line files:: Specifying input files on the command line +@end menu + +@node Operation modes +@section Command line options for operation modes + +Several options control the overall operation of @code{m4}: + +@table @code +@item --help +Print a help summary on standard output, then immediately exit +@code{m4} without reading any input files or performing any other +actions. + +@item --version +Print the version number of the program on standard output, then +immediately exit @code{m4} without reading any input files or +performing any other actions. + +@item -E +@itemx --fatal-warnings +@cindex errors, fatal +@cindex fatal errors +Controls the effect of warnings. If unspecified, then execution +continues and exit status is unaffected when a warning is printed. If +specified exactly once, warnings become fatal; when one is issued, +execution continues, but the exit status will be non-zero. If specified +multiple times, then execution halts with non-zero status the first time +a warning is issued. The introduction of behavior levels is new to M4 +1.4.9; for behavior consistent with earlier versions, you should specify +@option{-E} twice. + +@item -i +@itemx --interactive +@itemx -e +Makes this invocation of @code{m4} interactive. This means that all +output will be unbuffered, and interrupts will be ignored. The +spelling @option{-e} exists for compatibility with other @code{m4} +implementations, and issues a warning because it may be withdrawn in a +future version of GNU M4. + +@item -P +@itemx --prefix-builtins +Internally modify @emph{all} builtin macro names so they all start with +the prefix @samp{m4_}. For example, using this option, one should write +@samp{m4_define} instead of @samp{define}, and @samp{m4___file__} +instead of @samp{__file__}. This option has no effect if @option{-R} +is also specified. + +@item -Q +@itemx --quiet +@itemx --silent +Suppress warnings, such as missing or superfluous arguments in macro +calls, or treating the empty string as zero. + +@item --warn-macro-sequence@r{[}=@var{regexp}@r{]} +Issue a warning if the regular expression @var{regexp} has a non-empty +match in any macro definition (either by @code{define} or +@code{pushdef}). Empty matches are ignored; therefore, supplying the +empty string as @var{regexp} disables any warning. If the optional +@var{regexp} is not supplied, then the default regular expression is +@samp{\$\(@{[^@}]*@}\|[0-9][0-9]+\)} (a literal @samp{$} followed by +multiple digits or by an open brace), since these sequences will +change semantics in the default operation of GNU M4 2.0 (due +to a change in how more than 9 arguments in a macro definition will be +handled, @pxref{Arguments}). Providing an alternate regular +expression can provide a useful reverse lookup feature of finding +where a macro is defined to have a given definition. + +@item -W @var{regexp} +@itemx --word-regexp=@var{regexp} +Use @var{regexp} as an alternative syntax for macro names. This +experimental option will not be present in all GNU @code{m4} +implementations (@pxref{Changeword}). +@end table + +@node Preprocessor features +@section Command line options for preprocessor features + +@cindex macro definitions, on the command line +@cindex command line, macro definitions on the +@cindex preprocessor features +Several options allow @code{m4} to behave more like a preprocessor. +Macro definitions and deletions can be made on the command line, the +search path can be altered, and the output file can track where the +input came from. These features occur with the following options: + +@table @code +@item -D @var{name}@r{[}=@var{value}@r{]} +@itemx --define=@var{name}@r{[}=@var{value}@r{]} +This enters @var{name} into the symbol table. If @samp{=@var{value}} is +missing, the value is taken to be the empty string. The @var{value} can +be any string, and the macro can be defined to take arguments, just as +if it was defined from within the input. This option may be given more +than once; order with respect to file names is significant, and +redefining the same @var{name} loses the previous value. + +@item -I @var{directory} +@itemx --include=@var{directory} +Make @code{m4} search @var{directory} for included files that are not +found in the current working directory. @xref{Search Path}, for more +details. This option may be given more than once. + +@item -s +@itemx --synclines +@cindex synchronization lines +@cindex location, input +@cindex input location +Generate synchronization lines, for use by the C preprocessor or other +similar tools. Order is significant with respect to file names. This +option is useful, for example, when @code{m4} is used as a +front end to a compiler. Source file name and line number information +is conveyed by directives of the form @samp{#line @var{linenum} +"@var{file}"}, which are inserted as needed into the middle of the +output. Such directives mean that the following line originated or was +expanded from the contents of input file @var{file} at line +@var{linenum}. The @samp{"@var{file}"} part is often omitted when +the file name did not change from the previous directive. + +Synchronization directives are always given on complete lines by +themselves. When a synchronization discrepancy occurs in the middle of +an output line, the associated synchronization directive is delayed +until the next newline that does not occur in the middle of a quoted +string or comment. + +@comment options: -s +@example +define(`twoline', `1 +2') +@result{}#line 2 "stdin" +@result{} +changecom(`/*', `*/') +@result{} +define(`comment', `/*1 +2*/') +@result{}#line 5 +@result{} +dnl no line +hello +@result{}#line 7 +@result{}hello +twoline +@result{}1 +@result{}#line 8 +@result{}2 +comment +@result{}/*1 +@result{}2*/ +one comment `two +three' +@result{}#line 10 +@result{}one /*1 +@result{}2*/ two +@result{}three +goodbye +@result{}#line 12 +@result{}goodbye +@end example + +@item -U @var{name} +@itemx --undefine=@var{name} +This deletes any predefined meaning @var{name} might have. Obviously, +only predefined macros can be deleted in this way. This option may be +given more than once; undefining a @var{name} that does not have a +definition is silently ignored. Order is significant with respect to +file names. +@end table + +@node Limits control +@section Command line options for limits control + +There are some limits within @code{m4} that can be tuned. For +compatibility, @code{m4} also accepts some options that control limits +in other implementations, but which are automatically unbounded (limited +only by your hardware and operating system constraints) in GNU +@code{m4}. + +@table @code +@item -g +@itemx --gnu +Enable all the extensions in this implementation. In this release of +M4, this option is always on by default; it is currently only useful +when overriding a prior use of @option{--traditional}. However, having +GNU behavior as default makes it impossible to write a +strictly POSIX-compliant client that avoids all incompatible +GNU M4 extensions, since such a client would have to use the +non-POSIX command-line option to force full POSIX +behavior. Thus, a future version of M4 will be changed to implicitly +use the option @option{--traditional} if the environment variable +@env{POSIXLY_CORRECT} is set. Projects that intentionally use +GNU extensions should consider using @option{--gnu} to state +their intentions, so that the project will not mysteriously break if the +user upgrades to a newer M4 and has @env{POSIXLY_CORRECT} set in their +environment. + +@item -G +@itemx --traditional +Suppress all the extensions made in this implementation, compared to the +System V version. @xref{Compatibility}, for a list of these. + +@item -H @var{num} +@itemx --hashsize=@var{num} +Make the internal hash table for symbol lookup be @var{num} entries big. +For better performance, the number should be prime, but this is not +checked. The default is 509 entries. It should not be necessary to +increase this value, unless you define an excessive number of macros. + +@item -L @var{num} +@itemx --nesting-limit=@var{num} +@cindex nesting limit +@cindex limit, nesting +Artificially limit the nesting of macro calls to @var{num} levels, +stopping program execution if this limit is ever exceeded. When not +specified, nesting defaults to unlimited on platforms that can detect +stack overflow, and to 1024 levels otherwise. A value of zero means +unlimited; but then heavily nested code could potentially cause a stack +overflow. + +The precise effect of this option is more correctly associated +with textual nesting than dynamic recursion. It has been useful +when some complex @code{m4} input was generated by mechanical means, and +also in diagnosing recursive algorithms that do not scale well. +Most users never need to change this option from its default. + +@cindex rescanning +This option does @emph{not} have the ability to break endless +rescanning loops, since these do not necessarily consume much memory +or stack space. Through clever usage of rescanning loops, one can +request complex, time-consuming computations from @code{m4} with useful +results. Putting limitations in this area would break @code{m4} power. +There are many pathological cases: @w{@samp{define(`a', `a')a}} is +only the simplest example (but @pxref{Compatibility}). Expecting GNU +@code{m4} to detect these would be a little like expecting a compiler +system to detect and diagnose endless loops: it is a quite @emph{hard} +problem in general, if not undecidable! + +@item -B @var{num} +@itemx -S @var{num} +@itemx -T @var{num} +These options are present for compatibility with System V @code{m4}, but +do nothing in this implementation. They may disappear in future +releases, and issue a warning to that effect. + +@item -N @var{num} +@itemx --diversions=@var{num} +These options are present only for compatibility with previous +versions of GNU @code{m4}, and were controlling the number of +possible diversions which could be used at the same time. They do nothing, +because there is no fixed limit anymore. They may disappear in future +releases, and issue a warning to that effect. +@end table + +@node Frozen state +@section Command line options for frozen state + +GNU @code{m4} comes with a feature of freezing internal state +(@pxref{Frozen files}). This can be used to speed up @code{m4} +execution when reusing a common initialization script. + +@table @code +@item -F @var{file} +@itemx --freeze-state=@var{file} +Once execution is finished, write out the frozen state on the specified +@var{file}. It is conventional, but not required, for @var{file} to end +in @samp{.m4f}. + +@item -R @var{file} +@itemx --reload-state=@var{file} +Before execution starts, recover the internal state from the specified +frozen @var{file}. The options @option{-D}, @option{-U}, and +@option{-t} take effect after state is reloaded, but before the input +files are read. +@end table + +@node Debugging options +@section Command line options for debugging + +Finally, there are several options for aiding in debugging @code{m4} +scripts. + +@table @code +@item -d@r{[}@var{flags}@r{]} +@itemx --debug@r{[}=@var{flags}@r{]} +Set the debug-level according to the flags @var{flags}. The debug-level +controls the format and amount of information presented by the debugging +functions. @xref{Debug Levels}, for more details on the format and +meaning of @var{flags}. If omitted, @var{flags} defaults to @samp{aeq}. + +@item --debugfile@r{[}=@var{file}@r{]} +@itemx -o @var{file} +@itemx --error-output=@var{file} +Redirect @code{dumpdef} output, debug messages, and trace output to the +named @var{file}. Warnings, error messages, and @code{errprint} output +are still printed to standard error. If these options are not used, or +if @var{file} is unspecified (only possible for @option{--debugfile}), +debug output goes to standard error; if @var{file} is the empty string, +debug output is discarded. @xref{Debug Output}, for more details. The +option @option{--debugfile} may be given more than once, and order is +significant with respect to file names. The spellings @option{-o} and +@option{--error-output} are misleading and inconsistent with other +GNU tools; for now they are silently accepted as synonyms of +@option{--debugfile} and only recognized once, but in a future version +of M4, using them will cause a warning to be issued. + +@ignore +@comment not worth including in the manual, but provides a good test + +@comment examples +@comment options: -Dbar=hello -tbar --debugfile= foo --debugfile - +@example +$ @kbd{m4 -d -Iexamples -Dbar=hello -tbar --debugfile= foo --debugfile - +@result{}hello +errprint(`hi +')dnl +@error{}hi +bar +@error{}m4trace: -1- bar -> `hello' +@result{}hello +@end example +@end ignore + +@item -l @var{num} +@itemx --arglength=@var{num} +Restrict the size of the output generated by macro tracing to @var{num} +characters per trace line. If unspecified or zero, output is +unlimited. @xref{Debug Levels}, for more details. + +@item -t @var{name} +@itemx --trace=@var{name} +This enables tracing for the macro @var{name}, at any point where it is +defined. @var{name} need not be defined when this option is given. +This option may be given more than once, and order is significant with +respect to file names. @xref{Trace}, for more details. +@end table + +@node Command line files +@section Specifying input files on the command line + +@cindex command line, file names on the +@cindex file names, on the command line +The remaining arguments on the command line are taken to be input file +names. If no names are present, standard input is read. A file +name of @file{-} is taken to mean standard input. It is +conventional, but not required, for input files to end in @samp{.m4}. + +The input files are read in the sequence given. Standard input can be +read more than once, so the file name @file{-} may appear multiple times +on the command line; this makes a difference when input is from a +terminal or other special file type. It is an error if an input file +ends in the middle of argument collection, a comment, or a quoted +string. + +The options @option{--define} (@option{-D}), @option{--undefine} +(@option{-U}), @option{--synclines} (@option{-s}), and @option{--trace} +(@option{-t}) only take effect after processing input from any file +names that occur earlier on the command line. For example, assume the +file @file{foo} contains: + +@comment ignore +@example +$ @kbd{cat foo} +bar +@end example + +The text @samp{bar} can then be redefined over multiple uses of +@file{foo}: + +@comment options: -Dbar=hello foo -Dbar=world foo +@example +$ @kbd{m4 -Dbar=hello foo -Dbar=world foo} +@result{}hello +@result{}world +@end example + +If none of the input files invoked @code{m4exit} (@pxref{M4exit}), the +exit status of @code{m4} will be 0 for success, 1 for general failure +(such as problems with reading an input file), and 63 for version +mismatch (@pxref{Using frozen files}). + +If you need to read a file whose name starts with a @file{-}, you can +specify it as @samp{./-file}, or use @option{--} to mark the end of +options. + +@ignore +@comment Test that 'm4 file/' detects that file is not a directory; we +@comment can assume that the current directory contains a Makefile. +@comment mingw fails with EINVAL rather than ENOTDIR. + +@comment status: 1 +@comment xerr: ignore +@comment options: Makefile/ +@example +@error{}m4: cannot open `Makefile/': Not a directory +@end example + +@comment Test that closed stderr does not cause a crash. Not all +@comment systems have the same message for EBADF. + +@comment xerr: ignore +@example +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +changequote(`[', `]')dnl +syscmd([echo | ']__program__[' >&-])dnl +@error{}m4: write error: Bad file descriptor +sysval +@result{}1 +@end example + +@example +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +changequote(`[', `]')dnl +syscmd([echo 'esyscmd(echo hi >&2 && echo err"print(bye +)d"nl)dnl' > tmp.m4 \ + && ']__program__[' tmp.m4 <&- >&- \ + && rm tmp.m4])sysval +@error{}hi +@error{}bye +@result{}0 +@end example + +@comment Test that we obey POSIX semantics with -D interspersed with +@comment files, even with POSIXLY_CORRECT (BSD getopt gets it wrong). + +$ @kbd{m4 } +@example +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +changequote(`[', `]')dnl +syscmd([POSIXLY_CORRECT=1 ']__program__[' -Dbar=hello foo -Dbar=world foo])dnl +@result{}hello +@result{}world +sysval +@result{}0 +@end example +@end ignore + +@node Syntax +@chapter Lexical and syntactic conventions + +@cindex input tokens +@cindex tokens +As @code{m4} reads its input, it separates it into @dfn{tokens}. A +token is either a name, a quoted string, or any single character, that +is not a part of either a name or a string. Input to @code{m4} can also +contain comments. GNU @code{m4} does not yet understand +multibyte locales; all operations are byte-oriented rather than +character-oriented (although if your locale uses a single byte +encoding, such as @sc{ISO-8859-1}, you will not notice a difference). +However, @code{m4} is eight-bit clean, so you can +use non-@sc{ascii} characters in quoted strings (@pxref{Changequote}), +comments (@pxref{Changecom}), and macro names (@pxref{Indir}), with the +exception of the @sc{nul} character (the zero byte @samp{'\0'}). + +@menu +* Names:: Macro names +* Quoted strings:: Quoting input to @code{m4} +* Comments:: Comments in @code{m4} input +* Other tokens:: Other kinds of input tokens +* Input processing:: How @code{m4} copies input to output +@end menu + +@node Names +@section Macro names + +@cindex names +@cindex words +A name is any sequence of letters, digits, and the character @samp{_} +(underscore), where the first character is not a digit. @code{m4} will +use the longest such sequence found in the input. If a name has a +macro definition, it will be subject to macro expansion +(@pxref{Macros}). Names are case-sensitive. + +Examples of legal names are: @samp{foo}, @samp{_tmp}, and @samp{name01}. + +@node Quoted strings +@section Quoting input to @code{m4} + +@cindex quoted string +@cindex string, quoted +A quoted string is a sequence of characters surrounded by quote +strings, defaulting to +@samp{`} and @samp{'}, where the nested begin and end quotes within the +string are balanced. The value of a string token is the text, with one +level of quotes stripped off. Thus + +@comment ignore +@example +`' +@result{} +@end example + +@noindent +is the empty string, and double-quoting turns into single-quoting. + +@comment ignore +@example +``quoted'' +@result{}`quoted' +@end example + +The quote characters can be changed at any time, using the builtin macro +@code{changequote}. @xref{Changequote}, for more information. + +@node Comments +@section Comments in @code{m4} input + +@cindex comments +Comments in @code{m4} are normally delimited by the characters @samp{#} +and newline. All characters between the comment delimiters are ignored, +but the entire comment (including the delimiters) is passed through to +the output---comments are @emph{not} discarded by @code{m4}. + +Comments cannot be nested, so the first newline after a @samp{#} ends +the comment. The commenting effect of the begin-comment string +can be inhibited by quoting it. + +@example +$ @kbd{m4} +`quoted text' # `commented text' +@result{}quoted text # `commented text' +`quoting inhibits' `#' `comments' +@result{}quoting inhibits # comments +@end example + +The comment delimiters can be changed to any string at any time, using +the builtin macro @code{changecom}. @xref{Changecom}, for more +information. + +@ignore +@comment Detect regression in 1.4.10b in regards to reparsing comments. +@comment Not worth including in the manual. +@example +define(`e', `$@@')define(`q', ``$@@'')define(`foo', `bar') +@result{} +q(e(`one +',#two ' foo +)) +@result{}`one +@result{}',`#two bar +@result{}'' +changecom(`<', `>')define(`n', `$#') +@result{} +n(e(<`>, <'>)) +@result{}1 +len(e(<`>, ,<'>)) +@result{}12 +@end example +@end ignore + +@node Other tokens +@section Other kinds of input tokens + +@cindex tokens, special +Any character, that is neither a part of a name, nor of a quoted string, +nor a comment, is a token by itself. When not in the context of macro +expansion, all of these tokens are just copied to output. However, +during macro expansion, whitespace characters (space, tab, newline, +formfeed, carriage return, vertical tab), parentheses (@samp{(} and +@samp{)}), comma (@samp{,}), and dollar (@samp{$}) have additional +roles, explained later. + +@node Input processing +@section How @code{m4} copies input to output + +As @code{m4} reads the input token by token, it will copy each token +directly to the output immediately. + +The exception is when it finds a word with a macro definition. In that +case @code{m4} will calculate the macro's expansion, possibly reading +more input to get the arguments. It then inserts the expansion in front +of the remaining input. In other words, the resulting text from a macro +call will be read and parsed into tokens again. + +@code{m4} expands a macro as soon as possible. If it finds a macro call +when collecting the arguments to another, it will expand the second call +first. This process continues until there are no more macro calls to +expand and all the input has been consumed. + +For a running example, examine how @code{m4} handles this input: + +@comment ignore +@example +format(`Result is %d', eval(`2**15')) +@end example + +@noindent +First, @code{m4} sees that the token @samp{format} is a macro name, so +it collects the tokens @samp{(}, @samp{`Result is %d'}, @samp{,}, +and @samp{@w{ }}, before encountering another potential macro. Sure +enough, @samp{eval} is a macro name, so the nested argument collection +picks up @samp{(}, @samp{`2**15'}, and @samp{)}, invoking the eval macro +with the lone argument of @samp{2**15}. The expansion of +@samp{eval(2**15)} is @samp{32768}, which is then rescanned as the five +tokens @samp{3}, @samp{2}, @samp{7}, @samp{6}, and @samp{8}; and +combined with the next @samp{)}, the format macro now has all its +arguments, as if the user had typed: + +@comment ignore +@example +format(`Result is %d', 32768) +@end example + +@noindent +The format macro expands to @samp{Result is 32768}, and we have another +round of scanning for the tokens @samp{Result}, @samp{@w{ }}, +@samp{is}, @samp{@w{ }}, @samp{3}, @samp{2}, @samp{7}, @samp{6}, and +@samp{8}. None of these are macros, so the final output is + +@comment ignore +@example +@result{}Result is 32768 +@end example + +As a more complicated example, we will contrast an actual code +example from the Gnulib project@footnote{Derived from a patch in +@uref{http://lists.gnu.org/archive/html/bug-gnulib/@/2007-01/@/msg00389.html}, +and a followup patch in +@uref{http://lists.gnu.org/archive/html/bug-gnulib/@/2007-02/@/msg00000.html}}, +showing both a buggy approach and the desired results. The user desires +to output a shell assignment statement that takes its argument and turns +it into a shell variable by converting it to uppercase and prepending a +prefix. The original attempt looks like this: + +@example +changequote([,])dnl +define([gl_STRING_MODULE_INDICATOR], + [ + dnl comment + GNULIB_]translit([$1],[a-z],[A-Z])[=1 + ])dnl + gl_STRING_MODULE_INDICATOR([strcase]) +@result{} @w{ } +@result{} GNULIB_strcase=1 +@result{} @w{ } +@end example + +Oops -- the argument did not get capitalized. And although the manual +is not able to easily show it, both lines that appear empty actually +contain two trailing spaces. By stepping through the parse, it is easy +to see what happened. First, @code{m4} sees the token +@samp{changequote}, which it recognizes as a macro, followed by +@samp{(}, @samp{[}, @samp{,}, @samp{]}, and @samp{)} to form the +argument list. The macro expands to the empty string, but changes the +quoting characters to something more useful for generating shell code +(unbalanced @samp{`} and @samp{'} appear all the time in shell scripts, +but unbalanced @samp{[]} tend to be rare). Also in the first line, +@code{m4} sees the token @samp{dnl}, which it recognizes as a builtin +macro that consumes the rest of the line, resulting in no output for +that line. + +The second line starts a macro definition. @code{m4} sees the token +@samp{define}, which it recognizes as a macro, followed by a @samp{(}, +@samp{[gl_STRING_MODULE_INDICATOR]}, and @samp{,}. Because an unquoted +comma was encountered, the first argument is known to be the expansion +of the single-quoted string token, or @samp{gl_STRING_MODULE_INDICATOR}. +Next, @code{m4} sees @samp{@key{NL}}, @samp{ }, and @samp{ }, but this +whitespace is discarded as part of argument collection. Then comes a +rather lengthy single-quoted string token, @samp{[@key{NL}@ @ @ @ dnl +comment@key{NL}@ @ @ @ GNULIB_]}. This is followed by the token +@samp{translit}, which @code{m4} recognizes as a macro name, so a nested +macro expansion has started. + +The arguments to the @code{translit} are found by the tokens @samp{(}, +@samp{[$1]}, @samp{,}, @samp{[a-z]}, @samp{,}, @samp{[A-Z]}, and finally +@samp{)}. All three string arguments are expanded (or in other words, +the quotes are stripped), and since neither @samp{$} nor @samp{1} need +capitalization, the result of the macro is @samp{$1}. This expansion is +rescanned, resulting in the two literal characters @samp{$} and +@samp{1}. + +Scanning of the outer macro resumes, and picks up with +@samp{[=1@key{NL}@ @ ]}, and finally @samp{)}. The collected pieces of +expanded text are concatenated, with the end result that the macro +@samp{gl_STRING_MODULE_INDICATOR} is now defined to be the sequence +@samp{@key{NL}@ @ @ @ dnl comment@key{NL}@ @ @ @ GNULIB_$1=1@key{NL}@ @ }. +Once again, @samp{dnl} is recognized and avoids a newline in the output. + +The final line is then parsed, beginning with @samp{ } and @samp{ } +that are output literally. Then @samp{gl_STRING_MODULE_INDICATOR} is +recognized as a macro name, with an argument list of @samp{(}, +@samp{[strcase]}, and @samp{)}. Since the definition of the macro +contains the sequence @samp{$1}, that sequence is replaced with the +argument @samp{strcase} prior to starting the rescan. The rescan sees +@samp{@key{NL}} and four spaces, which are output literally, then +@samp{dnl}, which discards the text @samp{ comment@key{NL}}. Next +comes four more spaces, also output literally, and the token +@samp{GNULIB_strcase}, which resulted from the earlier parameter +substitution. Since that is not a macro name, it is output literally, +followed by the literal tokens @samp{=}, @samp{1}, @samp{@key{NL}}, and +two more spaces. Finally, the original @samp{@key{NL}} seen after the +macro invocation is scanned and output literally. + +Now for a corrected approach. This rearranges the use of newlines and +whitespace so that less whitespace is output (which, although harmless +to shell scripts, can be visually unappealing), and fixes the quoting +issues so that the capitalization occurs when the macro +@samp{gl_STRING_MODULE_INDICATOR} is invoked, rather then when it is +defined. It also adds another layer of quoting to the first argument of +@code{translit}, to ensure that the output will be rescanned as a string +rather than a potential uppercase macro name needing further expansion. + +@example +changequote([,])dnl +define([gl_STRING_MODULE_INDICATOR], + [dnl comment + GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl +])dnl + gl_STRING_MODULE_INDICATOR([strcase]) +@result{} GNULIB_STRCASE=1 +@end example + +The parsing of the first line is unchanged. The second line sees the +name of the macro to define, then sees the discarded @samp{@key{NL}} +and two spaces, as before. But this time, the next token is +@samp{[dnl comment@key{NL}@ @ GNULIB_[]translit([[$1]], [a-z], +[A-Z])=1dnl@key{NL}]}, which includes nested quotes, followed by +@samp{)} to end the macro definition and @samp{dnl} to skip the +newline. No early expansion of @code{translit} occurs, so the entire +string becomes the definition of the macro. + +The final line is then parsed, beginning with two spaces that are +output literally, and an invocation of +@code{gl_STRING_MODULE_INDICATOR} with the argument @samp{strcase}. +Again, the @samp{$1} in the macro definition is substituted prior to +rescanning. Rescanning first encounters @samp{dnl}, and discards +@samp{ comment@key{NL}}. Then two spaces are output literally. Next +comes the token @samp{GNULIB_}, but that is not a macro, so it is +output literally. The token @samp{[]} is an empty string, so it does +not affect output. Then the token @samp{translit} is encountered. + +This time, the arguments to @code{translit} are parsed as @samp{(}, +@samp{[[strcase]]}, @samp{,}, @samp{ }, @samp{[a-z]}, @samp{,}, @samp{ }, +@samp{[A-Z]}, and @samp{)}. The two spaces are discarded, and the +translit results in the desired result @samp{[STRCASE]}. This is +rescanned, but since it is a string, the quotes are stripped and the +only output is a literal @samp{STRCASE}. +Then the scanner sees @samp{=} and @samp{1}, which are output +literally, followed by @samp{dnl} which discards the rest of the +definition of @code{gl_STRING_MODULE_INDICATOR}. The newline at the +end of output is the literal @samp{@key{NL}} that appeared after the +invocation of the macro. + +The order in which @code{m4} expands the macros can be further explored +using the trace facilities of GNU @code{m4} (@pxref{Trace}). + +@node Macros +@chapter How to invoke macros + +This chapter covers macro invocation, macro arguments and how macro +expansion is treated. + +@menu +* Invocation:: Macro invocation +* Inhibiting Invocation:: Preventing macro invocation +* Macro Arguments:: Macro arguments +* Quoting Arguments:: On Quoting Arguments to macros +* Macro expansion:: Expanding macros +@end menu + +@node Invocation +@section Macro invocation + +@cindex macro invocation +@cindex invoking macros +Macro invocations has one of the forms + +@comment ignore +@example +name +@end example + +@noindent +which is a macro invocation without any arguments, or + +@comment ignore +@example +name(arg1, arg2, @dots{}, arg@var{n}) +@end example + +@noindent +which is a macro invocation with @var{n} arguments. Macros can have any +number of arguments. All arguments are strings, but different macros +might interpret the arguments in different ways. + +The opening parenthesis @emph{must} follow the @var{name} directly, with +no spaces in between. If it does not, the macro is called with no +arguments at all. + +For a macro call to have no arguments, the parentheses @emph{must} be +left out. The macro call + +@comment ignore +@example +name() +@end example + +@noindent +is a macro call with one argument, which is the empty string, not a call +with no arguments. + +@node Inhibiting Invocation +@section Preventing macro invocation + +An innovation of the @code{m4} language, compared to some of its +predecessors (like Strachey's @code{GPM}, for example), is the ability +to recognize macro calls without resorting to any special, prefixed +invocation character. While generally useful, this feature might +sometimes be the source of spurious, unwanted macro calls. So, GNU +@code{m4} offers several mechanisms or techniques for inhibiting the +recognition of names as macro calls. + +@cindex GNU extensions +@cindex blind macro +@cindex macro, blind +First of all, many builtin macros cannot meaningfully be called without +arguments. As a GNU extension, for any of these macros, +whenever an opening parenthesis does not immediately follow their name, +the builtin macro call is not triggered. This solves the most usual +cases, like for @samp{include} or @samp{eval}. Later in this document, +the sentence ``This macro is recognized only with parameters'' refers to +this specific provision of GNU M4, also known as a blind +builtin macro. For the builtins defined by POSIX that bear +this disclaimer, POSIX specifically states that invoking those +builtins without arguments is unspecified, because many other +implementations simply invoke the builtin as though it were given one +empty argument instead. + +@example +$ @kbd{m4} +eval +@result{}eval +eval(`1') +@result{}1 +@end example + +There is also a command line option (@option{--prefix-builtins}, or +@option{-P}, @pxref{Operation modes, , Invoking m4}) that renames all +builtin macros with a prefix of @samp{m4_} at startup. The option has +no effect whatsoever on user defined macros. For example, with this option, +one has to write @code{m4_dnl} and even @code{m4_m4exit}. It also has +no effect on whether a macro requires parameters. + +@comment options: -P +@example +$ @kbd{m4 -P} +eval +@result{}eval +eval(`1') +@result{}eval(1) +m4_eval +@result{}m4_eval +m4_eval(`1') +@result{}1 +@end example + +Another alternative is to redefine problematic macros to a name less +likely to cause conflicts, @xref{Definitions}. + +If your version of GNU @code{m4} has the @code{changeword} feature +compiled in, it offers far more flexibility in specifying the +syntax of macro names, both builtin or user-defined. @xref{Changeword}, +for more information on this experimental feature. + +Of course, the simplest way to prevent a name from being interpreted +as a call to an existing macro is to quote it. The remainder of +this section studies a little more deeply how quoting affects macro +invocation, and how quoting can be used to inhibit macro invocation. + +Even if quoting is usually done over the whole macro name, it can also +be done over only a few characters of this name (provided, of course, +that the unquoted portions are not also a macro). It is also possible +to quote the empty string, but this works only @emph{inside} the name. +For example: + +@example +`divert' +@result{}divert +`d'ivert +@result{}divert +di`ver't +@result{}divert +div`'ert +@result{}divert +@end example + +@noindent +all yield the string @samp{divert}. While in both: + +@example +`'divert +@result{} +divert`' +@result{} +@end example + +@noindent +the @code{divert} builtin macro will be called, which expands to the +empty string. + +@cindex rescanning +The output of macro evaluations is always rescanned. In the following +example, the input @samp{x`'y} yields the string @samp{bCD}, exactly as +if @code{m4} +has been given @w{@samp{substr(ab`'cde, `1', `3')}} as input: + +@example +define(`cde', `CDE') +@result{} +define(`x', `substr(ab') +@result{} +define(`y', `cde, `1', `3')') +@result{} +x`'y +@result{}bCD +@end example + +@ignore +@comment Similar, but with argument references, to ensure good test +@comment coverage. +@example +define(`x1', `len(`$1'') +@result{} +define(`y1', ``$1')') +@result{} +x1(`01234567890123456789')y1(`98765432109876543210') +@result{}40 +@end example +@end ignore + +Unquoted strings on either side of a quoted string are subject to +being recognized as macro names. In the following example, quoting the +empty string allows for the second @code{macro} to be recognized as such: + +@example +define(`macro', `m') +@result{} +macro(`m')macro +@result{}mmacro +macro(`m')`'macro +@result{}mm +@end example + +Quoting may prevent recognizing as a macro name the concatenation of a +macro expansion with the surrounding characters. In this example: + +@example +define(`macro', `di$1') +@result{} +macro(`v')`ert' +@result{}divert +macro(`v')ert +@result{} +@end example + +@noindent +the input will produce the string @samp{divert}. When the quotes were +removed, the @code{divert} builtin was called instead. + +@node Macro Arguments +@section Macro arguments + +@cindex macros, arguments to +@cindex arguments to macros +When a name is seen, and it has a macro definition, it will be expanded +as a macro. + +If the name is followed by an opening parenthesis, the arguments will be +collected before the macro is called. If too few arguments are +supplied, the missing arguments are taken to be the empty string. +However, some builtins are documented to behave differently for a +missing optional argument than for an explicit empty string. If there +are too many arguments, the excess arguments are ignored. Unquoted +leading whitespace is stripped off all arguments, but whitespace +generated by a macro expansion or occurring after a macro that expanded +to an empty string remains intact. Whitespace includes space, tab, +newline, carriage return, vertical tab, and formfeed. + +@example +define(`macro', `$1') +@result{} +macro( unquoted leading space lost) +@result{}unquoted leading space lost +macro(` quoted leading space kept') +@result{} quoted leading space kept +macro( + divert `unquoted space kept after expansion') +@result{} unquoted space kept after expansion +macro(macro(` +')`whitespace from expansion kept') +@result{} +@result{}whitespace from expansion kept +macro(`unquoted trailing whitespace kept' +) +@result{}unquoted trailing whitespace kept +@result{} +@end example + +@cindex warnings, suppressing +@cindex suppressing warnings +Normally @code{m4} will issue warnings if a builtin macro is called +with an inappropriate number of arguments, but it can be suppressed with +the @option{--quiet} command line option (or @option{--silent}, or +@option{-Q}, @pxref{Operation modes, , Invoking m4}). For user +defined macros, there is no check of the number of arguments given. + +@example +$ @kbd{m4} +index(`abc') +@error{}m4:stdin:1: Warning: too few arguments to builtin `index' +@result{}0 +index(`abc',) +@result{}0 +index(`abc', `b', `ignored') +@error{}m4:stdin:3: Warning: excess arguments to builtin `index' ignored +@result{}1 +@end example + +@comment options: -Q +@example +$ @kbd{m4 -Q} +index(`abc') +@result{}0 +index(`abc',) +@result{}0 +index(`abc', `b', `ignored') +@result{}1 +@end example + +Macros are expanded normally during argument collection, and whatever +commas, quotes and parentheses that might show up in the resulting +expanded text will serve to define the arguments as well. Thus, if +@var{foo} expands to @samp{, b, c}, the macro call + +@comment ignore +@example +bar(a foo, d) +@end example + +@noindent +is a macro call with four arguments, which are @samp{a }, @samp{b}, +@samp{c} and @samp{d}. To understand why the first argument contains +whitespace, remember that unquoted leading whitespace is never part +of an argument, but trailing whitespace always is. + +It is possible for a macro's definition to change during argument +collection, in which case the expansion uses the definition that was in +effect at the time the opening @samp{(} was seen. + +@example +define(`f', `1') +@result{} +f(define(`f', `2')) +@result{}1 +f +@result{}2 +@end example + +It is an error if the end of file occurs while collecting arguments. + +@comment status: 1 +@example +hello world +@result{}hello world +define( +^D +@error{}m4:stdin:2: ERROR: end of file in argument list +@end example + +@node Quoting Arguments +@section On Quoting Arguments to macros + +@cindex quoted macro arguments +@cindex macros, quoted arguments to +@cindex arguments, quoted macro +Each argument has unquoted leading whitespace removed. Within each +argument, all unquoted parentheses must match. For example, if +@var{foo} is a macro, + +@comment ignore +@example +foo(() (`(') `(') +@end example + +@noindent +is a macro call, with one argument, whose value is @samp{() (() (}. +Commas separate arguments, except when they occur inside quotes, +comments, or unquoted parentheses. @xref{Pseudo Arguments}, for +examples. + +It is common practice to quote all arguments to macros, unless you are +sure you want the arguments expanded. Thus, in the above +example with the parentheses, the `right' way to do it is like this: + +@comment ignore +@example +foo(`() (() (') +@end example + +@cindex quoting rule of thumb +@cindex rule of thumb, quoting +It is, however, in certain cases necessary (because nested expansion +must occur to create the arguments for the outer macro) or convenient +(because it uses fewer characters) to leave out quotes for some +arguments, and there is nothing wrong in doing it. It just makes life a +bit harder, if you are not careful to follow a consistent quoting style. +For consistency, this manual follows the rule of thumb that each layer +of parentheses introduces another layer of single quoting, except when +showing the consequences of quoting rules. This is done even when the +quoted string cannot be a macro, such as with integers when you have not +changed the syntax via @code{changeword} (@pxref{Changeword}). + +The quoting rule of thumb of one level of quoting per parentheses has a +nice property: when a macro name appears inside parentheses, you can +determine when it will be expanded. If it is not quoted, it will be +expanded prior to the outer macro, so that its expansion becomes the +argument. If it is single-quoted, it will be expanded after the outer +macro. And if it is double-quoted, it will be used as literal text +instead of a macro name. + +@example +define(`active', `ACT, IVE') +@result{} +define(`show', `$1 $1') +@result{} +show(active) +@result{}ACT ACT +show(`active') +@result{}ACT, IVE ACT, IVE +show(``active'') +@result{}active active +@end example + +@node Macro expansion +@section Macro expansion + +@cindex macros, expansion of +@cindex expansion of macros +When the arguments, if any, to a macro call have been collected, the +macro is expanded, and the expansion text is pushed back onto the input +(unquoted), and reread. The expansion text from one macro call might +therefore result in more macros being called, if the calls are included, +completely or partially, in the first macro calls' expansion. + +Taking a very simple example, if @var{foo} expands to @samp{bar}, and +@var{bar} expands to @samp{Hello}, the input + +@comment options: -Dbar=Hello -Dfoo=bar +@example +$ @kbd{m4 -Dbar=Hello -Dfoo=bar} +foo +@result{}Hello +@end example + +@noindent +will expand first to @samp{bar}, and when this is reread and +expanded, into @samp{Hello}. + +@ignore +@comment not worth documenting, but test that the command line can +@comment define macros that take parameters + +@comment options: -Dfoo -Decho=$@ +@example +$ @kbd{m4 -Dfoo -Decho='$@'} +foo +@result{} +foo(`silently ignored') +@result{} +echo(`1', `2') +@result{}1,2 +@end example +@end ignore + +@node Definitions +@chapter How to define new macros + +@cindex macros, how to define new +@cindex defining new macros +Macros can be defined, redefined and deleted in several different ways. +Also, it is possible to redefine a macro without losing a previous +value, and bring back the original value at a later time. + +@menu +* Define:: Defining a new macro +* Arguments:: Arguments to macros +* Pseudo Arguments:: Special arguments to macros +* Undefine:: Deleting a macro +* Defn:: Renaming macros +* Pushdef:: Temporarily redefining macros + +* Indir:: Indirect call of macros +* Builtin:: Indirect call of builtins +@end menu + +@node Define +@section Defining a macro + +The normal way to define or redefine macros is to use the builtin +@code{define}: + +@deffn Builtin define (@var{name}, @ovar{expansion}) +Defines @var{name} to expand to @var{expansion}. If +@var{expansion} is not given, it is taken to be empty. + +The expansion of @code{define} is void. +The macro @code{define} is recognized only with parameters. +@end deffn + +The following example defines the macro @var{foo} to expand to the text +@samp{Hello World.}. + +@example +define(`foo', `Hello world.') +@result{} +foo +@result{}Hello world. +@end example + +The empty line in the output is there because the newline is not +a part of the macro definition, and it is consequently copied to +the output. This can be avoided by use of the macro @code{dnl}. +@xref{Dnl}, for details. + +The first argument to @code{define} should be quoted; otherwise, if the +macro is already defined, you will be defining a different macro. This +example shows the problems with underquoting, since we did not want to +redefine @code{one}: + +@example +define(foo, one) +@result{} +define(foo, two) +@result{} +one +@result{}two +@end example + +@cindex GNU extensions +GNU @code{m4} normally replaces only the @emph{topmost} +definition of a macro if it has several definitions from @code{pushdef} +(@pxref{Pushdef}). Some other implementations of @code{m4} replace all +definitions of a macro with @code{define}. @xref{Incompatibilities}, +for more details. + +As a GNU extension, the first argument to @code{define} does +not have to be a simple word. +It can be any text string, even the empty string. A macro with a +non-standard name cannot be invoked in the normal way, as the name is +not recognized. It can only be referenced by the builtins @code{indir} +(@pxref{Indir}) and @code{defn} (@pxref{Defn}). + +@cindex arrays +Arrays and associative arrays can be simulated by using non-standard +macro names. + +@deffn Composite array (@var{index}) +@deffnx Composite array_set (@var{index}, @ovar{value}) +Provide access to entries within an array. @code{array} reads the entry +at location @var{index}, and @code{array_set} assigns @var{value} to +location @var{index}. +@end deffn + +@example +define(`array', `defn(format(``array[%d]'', `$1'))') +@result{} +define(`array_set', `define(format(``array[%d]'', `$1'), `$2')') +@result{} +array_set(`4', `array element no. 4') +@result{} +array_set(`17', `array element no. 17') +@result{} +array(`4') +@result{}array element no. 4 +array(eval(`10 + 7')) +@result{}array element no. 17 +@end example + +Change the @samp{%d} to @samp{%s} and it is an associative array. + +@node Arguments +@section Arguments to macros + +@cindex macros, arguments to +@cindex arguments to macros +Macros can have arguments. The @var{n}th argument is denoted by +@code{$n} in the expansion text, and is replaced by the @var{n}th actual +argument, when the macro is expanded. Replacement of arguments happens +before rescanning, regardless of how many nesting levels of quoting +appear in the expansion. Here is an example of a macro with +two arguments. + +@deffn Composite exch (@var{arg1}, @var{arg2}) +Expands to @var{arg2} followed by @var{arg1}, effectively exchanging +their order. +@end deffn + +@example +define(`exch', `$2, $1') +@result{} +exch(`arg1', `arg2') +@result{}arg2, arg1 +@end example + +This can be used, for example, if you like the arguments to +@code{define} to be reversed. + +@example +define(`exch', `$2, $1') +@result{} +define(exch(``expansion text'', ``macro'')) +@result{} +macro +@result{}expansion text +@end example + +@xref{Quoting Arguments}, for an explanation of the double quotes. +(You should try and improve this example so that clients of @code{exch} +do not have to double quote; or @pxref{Improved exch, , Answers}). + +As a special case, the zeroth argument, @code{$0}, is always the name +of the macro being expanded. + +@example +define(`test', ``Macro name: $0'') +@result{} +test +@result{}Macro name: test +@end example + +If you want quoted text to appear as part of the expansion text, +remember that quotes can be nested in quoted strings. Thus, in + +@example +define(`foo', `This is macro `foo'.') +@result{} +foo +@result{}This is macro foo. +@end example + +@noindent +The @samp{foo} in the expansion text is @emph{not} expanded, since it is +a quoted string, and not a name. + +@cindex GNU extensions +@cindex nine arguments, more than +@cindex more than nine arguments +@cindex arguments, more than nine +@cindex positional parameters, more than nine +GNU @code{m4} allows the number following the @samp{$} to +consist of one or more digits, allowing macros to have any number of +arguments. The extension of accepting multiple digits is incompatible +with POSIX, and is different than traditional implementations +of @code{m4}, which only recognize one digit. Therefore, future +versions of GNU M4 will phase out this feature. To portably +access beyond the ninth argument, you can use the @code{argn} macro +documented later (@pxref{Shift}). + +POSIX also states that @samp{$} followed immediately by +@samp{@{} in a macro definition is implementation-defined. This version +of M4 passes the literal characters @samp{$@{} through unchanged, but M4 +2.0 will implement an optional feature similar to @command{sh}, where +@samp{$@{11@}} expands to the eleventh argument, to replace the current +recognition of @samp{$11}. Meanwhile, if you want to guarantee that you +will get a literal @samp{$@{} in output when expanding a macro, even +when you upgrade to M4 2.0, you can use nested quoting to your +advantage: + +@example +define(`foo', `single quoted $`'@{1@} output') +@result{} +define(`bar', ``double quoted $'`@{2@} output'') +@result{} +foo(`a', `b') +@result{}single quoted $@{1@} output +bar(`a', `b') +@result{}double quoted $@{2@} output +@end example + +To help you detect places in your M4 input files that might change in +behavior due to the changed behavior of M4 2.0, you can use the +@option{--warn-macro-sequence} command-line option (@pxref{Operation +modes, , Invoking m4}) with the default regular expression. This will +add a warning any time a macro definition includes @samp{$} followed by +multiple digits, or by @samp{@{}. The warning is not enabled by +default, because it triggers a number of warnings in Autoconf 2.61 (and +Autoconf uses @option{-E} to treat warnings as errors), and because it +will still be possible to restore older behavior in M4 2.0. + +@comment options: --warn-macro-sequence +@example +$ @kbd{m4 --warn-macro-sequence} +define(`foo', `$001 $@{1@} $1') +@error{}m4:stdin:1: Warning: definition of `foo' contains sequence `$001' +@error{}m4:stdin:1: Warning: definition of `foo' contains sequence `$@{1@}' +@result{} +foo(`bar') +@result{}bar $@{1@} bar +@end example + +@node Pseudo Arguments +@section Special arguments to macros + +@cindex special arguments to macros +@cindex macros, special arguments to +@cindex arguments to macros, special +There is a special notation for the number of actual arguments supplied, +and for all the actual arguments. + +The number of actual arguments in a macro call is denoted by @code{$#} +in the expansion text. + +@deffn Composite nargs (@dots{}) +Expands to a count of the number of arguments supplied. +@end deffn + +@example +define(`nargs', `$#') +@result{} +nargs +@result{}0 +nargs() +@result{}1 +nargs(`arg1', `arg2', `arg3') +@result{}3 +nargs(`commas can be quoted, like this') +@result{}1 +nargs(arg1#inside comments, commas do not separate arguments +still arg1) +@result{}1 +nargs((unquoted parentheses, like this, group arguments)) +@result{}1 +@end example + +Remember that @samp{#} defaults to the comment character; if you forget +quotes to inhibit the comment behavior, your macro definition may not +end where you expected. + +@example +dnl Attempt to define a macro to just `$#' +define(underquoted, $#) +oops) +@result{} +underquoted +@result{}0) +@result{}oops +@end example + +The notation @code{$*} can be used in the expansion text to denote all +the actual arguments, unquoted, with commas in between. For example + +@example +define(`echo', `$*') +@result{} +echo(arg1, arg2, arg3 , arg4) +@result{}arg1,arg2,arg3 ,arg4 +@end example + +Often each argument should be quoted, and the notation @code{$@@} handles +that. It is just like @code{$*}, except that it quotes each argument. +A simple example of that is: + +@example +define(`echo', `$@@') +@result{} +echo(arg1, arg2, arg3 , arg4) +@result{}arg1,arg2,arg3 ,arg4 +@end example + +Where did the quotes go? Of course, they were eaten, when the expanded +text were reread by @code{m4}. To show the difference, try + +@example +define(`echo1', `$*') +@result{} +define(`echo2', `$@@') +@result{} +define(`foo', `This is macro `foo'.') +@result{} +echo1(foo) +@result{}This is macro This is macro foo.. +echo1(`foo') +@result{}This is macro foo. +echo2(foo) +@result{}This is macro foo. +echo2(`foo') +@result{}foo +@end example + +@noindent +@xref{Trace}, if you do not understand this. As another example of the +difference, remember that comments encountered in arguments are passed +untouched to the macro, and that quoting disables comments. + +@example +define(`echo1', `$*') +@result{} +define(`echo2', `$@@') +@result{} +define(`foo', `bar') +@result{} +echo1(#foo'foo +foo) +@result{}#foo'foo +@result{}bar +echo2(#foo'foo +foo) +@result{}#foobar +@result{}bar' +@end example + +@ignore +@comment Not worth putting in the manual, but this example is needed for +@comment good test coverage of copying large strings across recursion +@comment levels. + +@example +define(`echo', `$@@')dnl +echo(echo(`01234567890123456789', `01234567890123456789') +echo(`98765432109876543210', `98765432109876543210')) +@result{}01234567890123456789,01234567890123456789 +@result{}98765432109876543210,98765432109876543210 +len((echo(`01234567890123456789', + `01234567890123456789')echo(`98765432109876543210', + `98765432109876543210'))) +@result{}84 +indir(`echo', indir(`echo', `01234567890123456789', + `01234567890123456789') +indir(`echo', `98765432109876543210', `98765432109876543210')) +@result{}01234567890123456789,01234567890123456789 +@result{}98765432109876543210,98765432109876543210 +define(`argn', `$#')dnl +define(`echo1', `-$@@-')define(`echo2', `,$@@,')dnl +echo1(`1', `2', `3') argn(echo1(`1', `2', `3')) +@result{}-1,2,3- 3 +echo2(`1', `2', `3') argn(echo2(`1', `2', `3')) +@result{},1,2,3, 5 +@end example +@end ignore + +A @samp{$} sign in the expansion text, that is not followed by anything +@code{m4} understands, is simply copied to the macro expansion, as any +other text is. + +@example +define(`foo', `$$$ hello $$$') +@result{} +foo +@result{}$$$ hello $$$ +@end example + +@cindex rescanning +@cindex literal output +@cindex output, literal +If you want a macro to expand to something like @samp{$12}, the +judicious use of nested quoting can put a safe character between the +@code{$} and the next character, relying on the rescanning to remove the +nested quote. This will prevent @code{m4} from interpreting the +@code{$} sign as a reference to an argument. + +@example +define(`foo', `no nested quote: $1') +@result{} +foo(`arg') +@result{}no nested quote: arg +define(`foo', `nested quote around $: `$'1') +@result{} +foo(`arg') +@result{}nested quote around $: $1 +define(`foo', `nested empty quote after $: $`'1') +@result{} +foo(`arg') +@result{}nested empty quote after $: $1 +define(`foo', `nested quote around next character: $`1'') +@result{} +foo(`arg') +@result{}nested quote around next character: $1 +define(`foo', `nested quote around both: `$1'') +@result{} +foo(`arg') +@result{}nested quote around both: arg +@end example + +@node Undefine +@section Deleting a macro + +@cindex macros, how to delete +@cindex deleting macros +@cindex undefining macros +A macro definition can be removed with @code{undefine}: + +@deffn Builtin undefine (@var{name}@dots{}) +For each argument, remove the macro @var{name}. The macro names must +necessarily be quoted, since they will be expanded otherwise. + +The expansion of @code{undefine} is void. +The macro @code{undefine} is recognized only with parameters. +@end deffn + +@example +foo bar blah +@result{}foo bar blah +define(`foo', `some')define(`bar', `other')define(`blah', `text') +@result{} +foo bar blah +@result{}some other text +undefine(`foo') +@result{} +foo bar blah +@result{}foo other text +undefine(`bar', `blah') +@result{} +foo bar blah +@result{}foo bar blah +@end example + +Undefining a macro inside that macro's expansion is safe; the macro +still expands to the definition that was in effect at the @samp{(}. + +@example +define(`f', ``$0':$1') +@result{} +f(f(f(undefine(`f')`hello world'))) +@result{}f:f:f:hello world +f(`bye') +@result{}f(bye) +@end example + +It is not an error for @var{name} to have no macro definition. In that +case, @code{undefine} does nothing. + +@node Defn +@section Renaming macros + +@cindex macros, how to rename +@cindex renaming macros +@cindex macros, displaying definitions +@cindex definitions, displaying macro +It is possible to rename an already defined macro. To do this, you need +the builtin @code{defn}: + +@deffn Builtin defn (@var{name}@dots{}) +Expands to the @emph{quoted definition} of each @var{name}. If an +argument is not a defined macro, the expansion for that argument is +empty. + +If @var{name} is a user-defined macro, the quoted definition is simply +the quoted expansion text. If, instead, there is only one @var{name} +and it is a builtin, the +expansion is a special token, which points to the builtin's internal +definition. This token is only meaningful as the second argument to +@code{define} (and @code{pushdef}), and is silently converted to an +empty string in most other contexts. Combining a builtin with anything +else is not supported; a warning is issued and the builtin is omitted +from the final expansion. + +The macro @code{defn} is recognized only with parameters. +@end deffn + +Its normal use is best understood through an example, which shows how to +rename @code{undefine} to @code{zap}: + +@example +define(`zap', defn(`undefine')) +@result{} +zap(`undefine') +@result{} +undefine(`zap') +@result{}undefine(zap) +@end example + +In this way, @code{defn} can be used to copy macro definitions, and also +definitions of builtin macros. Even if the original macro is removed, +the other name can still be used to access the definition. + +The fact that macro definitions can be transferred also explains why you +should use @code{$0}, rather than retyping a macro's name in its +definition: + +@example +define(`foo', `This is `$0'') +@result{} +define(`bar', defn(`foo')) +@result{} +bar +@result{}This is bar +@end example + +Macros used as string variables should be referred through @code{defn}, +to avoid unwanted expansion of the text: + +@example +define(`string', `The macro dnl is very useful +') +@result{} +string +@result{}The macro@w{ } +defn(`string') +@result{}The macro dnl is very useful +@result{} +@end example + +@cindex rescanning +However, it is important to remember that @code{m4} rescanning is purely +textual. If an unbalanced end-quote string occurs in a macro +definition, the rescan will see that embedded quote as the termination +of the quoted string, and the remainder of the macro's definition will +be rescanned unquoted. Thus it is a good idea to avoid unbalanced +end-quotes in macro definitions or arguments to macros. + +@example +define(`foo', a'a) +@result{} +define(`a', `A') +@result{} +define(`echo', `$@@') +@result{} +foo +@result{}A'A +defn(`foo') +@result{}aA' +echo(foo) +@result{}AA' +@end example + +On the other hand, it is possible to exploit the fact that @code{defn} +can concatenate multiple macros prior to the rescanning phase, in order +to join the definitions of macros that, in isolation, have unbalanced +quotes. This is particularly useful when one has used several macros to +accumulate text that M4 should rescan as a whole. In the example below, +note how the use of @code{defn} on @code{l} in isolation opens a string, +which is not closed until the next line; but used on @code{l} and +@code{r} together results in nested quoting. + +@example +define(`l', `<[>')define(`r', `<]>') +@result{} +changequote(`[', `]') +@result{} +defn([l])defn([r]) +]) +@result{}<[>]defn([r]) +@result{}) +defn([l], [r]) +@result{}<[>][<]> +@end example + +@cindex builtins, special tokens +@cindex tokens, builtin macro +Using @code{defn} to generate special tokens for builtin macros outside +of expected contexts can sometimes trigger warnings. But most of the +time, such tokens are silently converted to the empty string. + +@example +$ @kbd{m4 -d} +defn(`defn') +@result{} +define(defn(`divnum'), `cannot redefine a builtin token') +@error{}m4:stdin:2: Warning: define: invalid macro name ignored +@result{} +divnum +@result{}0 +len(defn(`divnum')) +@result{}0 +@end example + +Also note that @code{defn} with multiple arguments can only join text +macros, not builtins, although a future version of GNU M4 may +lift this restriction. + +@example +$ @kbd{m4 -d} +define(`a', `A')define(`AA', `b') +@result{} +traceon(`defn', `define') +@result{} +defn(`a', `divnum', `a') +@error{}m4:stdin:3: Warning: cannot concatenate builtin `divnum' +@error{}m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A'' +@result{}AA +define(`mydivnum', defn(`divnum', `divnum'))mydivnum +@error{}m4:stdin:4: Warning: cannot concatenate builtin `divnum' +@error{}m4:stdin:4: Warning: cannot concatenate builtin `divnum' +@error{}m4trace: -2- defn(`divnum', `divnum') +@error{}m4trace: -1- define(`mydivnum', `') +@result{} +traceoff(`defn', `define') +@result{} +@end example + +@node Pushdef +@section Temporarily redefining macros + +@cindex macros, temporary redefinition of +@cindex temporary redefinition of macros +@cindex redefinition of macros, temporary +@cindex definition stack +@cindex pushdef stack +@cindex stack, macro definition +It is possible to redefine a macro temporarily, reverting to the +previous definition at a later time. This is done with the builtins +@code{pushdef} and @code{popdef}: + +@deffn Builtin pushdef (@var{name}, @ovar{expansion}) +@deffnx Builtin popdef (@var{name}@dots{}) +Analogous to @code{define} and @code{undefine}. + +These macros work in a stack-like fashion. A macro is temporarily +redefined with @code{pushdef}, which replaces an existing definition of +@var{name}, while saving the previous definition, before the new one is +installed. If there is no previous definition, @code{pushdef} behaves +exactly like @code{define}. + +If a macro has several definitions (of which only one is accessible), +the topmost definition can be removed with @code{popdef}. If there is +no previous definition, @code{popdef} behaves like @code{undefine}. + +The expansion of both @code{pushdef} and @code{popdef} is void. +The macros @code{pushdef} and @code{popdef} are recognized only with +parameters. +@end deffn + +@example +define(`foo', `Expansion one.') +@result{} +foo +@result{}Expansion one. +pushdef(`foo', `Expansion two.') +@result{} +foo +@result{}Expansion two. +pushdef(`foo', `Expansion three.') +@result{} +pushdef(`foo', `Expansion four.') +@result{} +popdef(`foo') +@result{} +foo +@result{}Expansion three. +popdef(`foo', `foo') +@result{} +foo +@result{}Expansion one. +popdef(`foo') +@result{} +foo +@result{}foo +@end example + +If a macro with several definitions is redefined with @code{define}, the +topmost definition is @emph{replaced} with the new definition. If it is +removed with @code{undefine}, @emph{all} the definitions are removed, +and not only the topmost one. However, POSIX allows other +implementations that treat @code{define} as replacing an entire stack +of definitions with a single new definition, so to be portable to other +implementations, it may be worth explicitly using @code{popdef} and +@code{pushdef} rather than relying on the GNU behavior of +@code{define}. + +@example +define(`foo', `Expansion one.') +@result{} +foo +@result{}Expansion one. +pushdef(`foo', `Expansion two.') +@result{} +foo +@result{}Expansion two. +define(`foo', `Second expansion two.') +@result{} +foo +@result{}Second expansion two. +undefine(`foo') +@result{} +foo +@result{}foo +@end example + +@cindex local variables +@cindex variables, local +Local variables within macros are made with @code{pushdef} and +@code{popdef}. At the start of the macro a new definition is pushed, +within the macro it is manipulated and at the end it is popped, +revealing the former definition. + +It is possible to temporarily redefine a builtin with @code{pushdef} +and @code{defn}. + +@node Indir +@section Indirect call of macros + +@cindex indirect call of macros +@cindex call of macros, indirect +@cindex macros, indirect call of +@cindex GNU extensions +Any macro can be called indirectly with @code{indir}: + +@deffn Builtin indir (@var{name}, @ovar{args@dots{}}) +Results in a call to the macro @var{name}, which is passed the +rest of the arguments @var{args}. If @var{name} is not defined, an +error message is printed, and the expansion is void. + +The macro @code{indir} is recognized only with parameters. +@end deffn + +This can be used to call macros with computed or ``invalid'' +names (@code{define} allows such names to be defined): + +@example +define(`$$internal$macro', `Internal macro (name `$0')') +@result{} +$$internal$macro +@result{}$$internal$macro +indir(`$$internal$macro') +@result{}Internal macro (name $$internal$macro) +@end example + +The point is, here, that larger macro packages can have private macros +defined, that will not be called by accident. They can @emph{only} be +called through the builtin @code{indir}. + +One other point to observe is that argument collection occurs before +@code{indir} invokes @var{name}, so if argument collection changes the +value of @var{name}, that will be reflected in the final expansion. +This is different than the behavior when invoking macros directly, +where the definition that was in effect before argument collection is +used. + +@example +$ @kbd{m4 -d} +define(`f', `1') +@result{} +f(define(`f', `2')) +@result{}1 +indir(`f', define(`f', `3')) +@result{}3 +indir(`f', undefine(`f')) +@error{}m4:stdin:4: undefined macro `f' +@result{} +@end example + +When handed the result of @code{defn} (@pxref{Defn}) as one of its +arguments, @code{indir} defers to the invoked @var{name} for whether a +token representing a builtin is recognized or flattened to the empty +string. + +@example +$ @kbd{m4 -d} +indir(defn(`defn'), `divnum') +@error{}m4:stdin:1: Warning: indir: invalid macro name ignored +@result{} +indir(`define', defn(`defn'), `divnum') +@error{}m4:stdin:2: Warning: define: invalid macro name ignored +@result{} +indir(`define', `foo', defn(`divnum')) +@result{} +foo +@result{}0 +indir(`divert', defn(`foo')) +@error{}m4:stdin:5: empty string treated as 0 in builtin `divert' +@result{} +@end example + +@node Builtin +@section Indirect call of builtins + +@cindex indirect call of builtins +@cindex call of builtins, indirect +@cindex builtins, indirect call of +@cindex GNU extensions +Builtin macros can be called indirectly with @code{builtin}: + +@deffn Builtin builtin (@var{name}, @ovar{args@dots{}}) +Results in a call to the builtin @var{name}, which is passed the +rest of the arguments @var{args}. If @var{name} does not name a +builtin, an error message is printed, and the expansion is void. + +The macro @code{builtin} is recognized only with parameters. +@end deffn + +This can be used even if @var{name} has been given another definition +that has covered the original, or been undefined so that no macro +maps to the builtin. + +@example +pushdef(`define', `hidden') +@result{} +undefine(`undefine') +@result{} +define(`foo', `bar') +@result{}hidden +foo +@result{}foo +builtin(`define', `foo', defn(`divnum')) +@result{} +foo +@result{}0 +builtin(`define', `foo', `BAR') +@result{} +foo +@result{}BAR +undefine(`foo') +@result{}undefine(foo) +foo +@result{}BAR +builtin(`undefine', `foo') +@result{} +foo +@result{}foo +@end example + +The @var{name} argument only matches the original name of the builtin, +even when the @option{--prefix-builtins} option (or @option{-P}, +@pxref{Operation modes, , Invoking m4}) is in effect. This is different +from @code{indir}, which only tracks current macro names. + +@comment options: -P +@example +$ @kbd{m4 -P} +m4_builtin(`divnum') +@result{}0 +m4_builtin(`m4_divnum') +@error{}m4:stdin:2: undefined builtin `m4_divnum' +@result{} +m4_indir(`divnum') +@error{}m4:stdin:3: undefined macro `divnum' +@result{} +m4_indir(`m4_divnum') +@result{}0 +@end example + +Note that @code{indir} and @code{builtin} can be used to invoke builtins +without arguments, even when they normally require parameters to be +recognized; but it will provoke a warning, and result in a void expansion. + +@example +builtin +@result{}builtin +builtin() +@error{}m4:stdin:2: undefined builtin `' +@result{} +builtin(`builtin') +@error{}m4:stdin:3: Warning: too few arguments to builtin `builtin' +@result{} +builtin(`builtin',) +@error{}m4:stdin:4: undefined builtin `' +@result{} +builtin(`builtin', ``' +') +@error{}m4:stdin:5: undefined builtin ``' +@error{}' +@result{} +indir(`index') +@error{}m4:stdin:7: Warning: too few arguments to builtin `index' +@result{} +@end example + +@ignore +@comment This example is not worth putting in the manual, but it is +@comment needed for full coverage. Autoconf's m4_include relies heavily +@comment on this feature. + +@example +builtin(`include', `foo')dnl +@result{}bar +@end example + +@comment And this example triggers a regression present in 1.4.10b. + +@example +define(`s', `builtin(`shift', $@@)')dnl +define(`loop', `ifelse(`$2', `', `-', `$1$2: $0(`$1', s(s($@@)))')')dnl +loop(`1') +@result{}- +loop(`1', `2') +@result{}12: - +loop(`1', `2', `3') +@result{}12: 13: - +loop(`1', `2', `3', `4') +@result{}12: 13: 14: - +loop(`1', `2', `3', `4', `5') +@result{}12: 13: 14: 15: - +@end example +@end ignore + +@node Conditionals +@chapter Conditionals, loops, and recursion + +Macros, expanding to plain text, perhaps with arguments, are not quite +enough. We would like to have macros expand to different things, based +on decisions taken at run-time. For that, we need some kind of conditionals. +Also, we would like to have some kind of loop construct, so we could do +something a number of times, or while some condition is true. + +@menu +* Ifdef:: Testing if a macro is defined +* Ifelse:: If-else construct, or multibranch +* Shift:: Recursion in @code{m4} +* Forloop:: Iteration by counting +* Foreach:: Iteration by list contents +* Stacks:: Working with definition stacks +* Composition:: Building macros with macros +@end menu + +@node Ifdef +@section Testing if a macro is defined + +@cindex conditionals +There are two different builtin conditionals in @code{m4}. The first is +@code{ifdef}: + +@deffn Builtin ifdef (@var{name}, @var{string-1}, @ovar{string-2}) +If @var{name} is defined as a macro, @code{ifdef} expands to +@var{string-1}, otherwise to @var{string-2}. If @var{string-2} is +omitted, it is taken to be the empty string (according to the normal +rules). + +The macro @code{ifdef} is recognized only with parameters. +@end deffn + +@example +ifdef(`foo', ``foo' is defined', ``foo' is not defined') +@result{}foo is not defined +define(`foo', `') +@result{} +ifdef(`foo', ``foo' is defined', ``foo' is not defined') +@result{}foo is defined +ifdef(`no_such_macro', `yes', `no', `extra argument') +@error{}m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored +@result{}no +@end example + +@node Ifelse +@section If-else construct, or multibranch + +@cindex comparing strings +@cindex discarding input +@cindex input, discarding +The other conditional, @code{ifelse}, is much more powerful. It can be +used as a way to introduce a long comment, as an if-else construct, or +as a multibranch, depending on the number of arguments supplied: + +@deffn Builtin ifelse (@var{comment}) +@deffnx Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal}, @ + @ovar{not-equal}) +@deffnx Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal-1}, @ + @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal}) +Used with only one argument, the @code{ifelse} simply discards it and +produces no output. + +If called with three or four arguments, @code{ifelse} expands into +@var{equal}, if @var{string-1} and @var{string-2} are equal (character +for character), otherwise it expands to @var{not-equal}. A final fifth +argument is ignored, after triggering a warning. + +If called with six or more arguments, and @var{string-1} and +@var{string-2} are equal, @code{ifelse} expands into @var{equal-1}, +otherwise the first three arguments are discarded and the processing +starts again. + +The macro @code{ifelse} is recognized only with parameters. +@end deffn + +Using only one argument is a common @code{m4} idiom for introducing a +block comment, as an alternative to repeatedly using @code{dnl}. This +special usage is recognized by GNU @code{m4}, so that in this +case, the warning about missing arguments is never triggered. + +@example +ifelse(`some comments') +@result{} +ifelse(`foo', `bar') +@error{}m4:stdin:2: Warning: too few arguments to builtin `ifelse' +@result{} +@end example + +Using three or four arguments provides decision points. + +@example +ifelse(`foo', `bar', `true') +@result{} +ifelse(`foo', `foo', `true') +@result{}true +define(`foo', `bar') +@result{} +ifelse(foo, `bar', `true', `false') +@result{}true +ifelse(foo, `foo', `true', `false') +@result{}false +@end example + +@cindex macro, blind +@cindex blind macro +Notice how the first argument was used unquoted; it is common to compare +the expansion of a macro with a string. With this macro, you can now +reproduce the behavior of blind builtins, where the macro is recognized +only with arguments. + +@example +define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')') +@result{} +foo +@result{}foo +foo() +@result{}arguments:1 +foo(`a', `b', `c') +@result{}arguments:3 +@end example + +For an example of a way to make defining blind macros easier, see +@ref{Composition}. + +@cindex multibranches +@cindex switch statement +@cindex case statement +The macro @code{ifelse} can take more than four arguments. If given more +than four arguments, @code{ifelse} works like a @code{case} or @code{switch} +statement in traditional programming languages. If @var{string-1} and +@var{string-2} are equal, @code{ifelse} expands into @var{equal-1}, otherwise +the procedure is repeated with the first three arguments discarded. This +calls for an example: + +@example +ifelse(`foo', `bar', `third', `gnu', `gnats') +@error{}m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored +@result{}gnu +ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth') +@result{} +ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh') +@result{}seventh +ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8') +@error{}m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored +@result{}7 +@end example + +@ignore +@comment Stress tests, not worth documenting. + +@comment Ensure that references compared to strings work regardless of +@comment similar prefixes. +@example +define(`e', `$@@')define(`long', `01234567890123456789') +@result{} +ifelse(long, `01234567890123456789', `yes', `no') +@result{}yes +ifelse(`01234567890123456789', long, `yes', `no') +@result{}yes +ifelse(long, `01234567890123456789-', `yes', `no') +@result{}no +ifelse(`01234567890123456789-', long, `yes', `no') +@result{}no +ifelse(e(long), `01234567890123456789', `yes', `no') +@result{}yes +ifelse(`01234567890123456789', e(long), `yes', `no') +@result{}yes +ifelse(e(long), `01234567890123456789-', `yes', `no') +@result{}no +ifelse(`01234567890123456789-', e(long), `yes', `no') +@result{}no +ifelse(-e(long), `-01234567890123456789', `yes', `no') +@result{}yes +ifelse(-`01234567890123456789', -e(long), `yes', `no') +@result{}yes +ifelse(-e(long), `-01234567890123456789-', `yes', `no') +@result{}no +ifelse(`-01234567890123456789-', -e(long), `yes', `no') +@result{}no +ifelse(-e(long)-, `-01234567890123456789-', `yes', `no') +@result{}yes +ifelse(-`01234567890123456789-', -e(long)-, `yes', `no') +@result{}yes +ifelse(-e(long)-, `-01234567890123456789', `yes', `no') +@result{}no +ifelse(`-01234567890123456789', -e(long)-, `yes', `no') +@result{}no +ifelse(`-'e(long), `-01234567890123456789', `yes', `no') +@result{}yes +ifelse(-`01234567890123456789', `-'e(long), `yes', `no') +@result{}yes +ifelse(`-'e(long), `-01234567890123456789-', `yes', `no') +@result{}no +ifelse(`-01234567890123456789-', `-'e(long), `yes', `no') +@result{}no +ifelse(`-'e(long)`-', `-01234567890123456789-', `yes', `no') +@result{}yes +ifelse(-`01234567890123456789-', `-'e(long)`-', `yes', `no') +@result{}yes +ifelse(`-'e(long)`-', `-01234567890123456789', `yes', `no') +@result{}no +ifelse(`-01234567890123456789', `-'e(long)`-', `yes', `no') +@result{}no +@end example +@end ignore + +Naturally, the normal case will be slightly more advanced than these +examples. A common use of @code{ifelse} is in macros implementing loops +of various kinds. + +@node Shift +@section Recursion in @code{m4} + +@cindex recursive macros +@cindex macros, recursive +There is no direct support for loops in @code{m4}, but macros can be +recursive. There is no limit on the number of recursion levels, other +than those enforced by your hardware and operating system. + +@cindex loops +Loops can be programmed using recursion and the conditionals described +previously. + +There is a builtin macro, @code{shift}, which can, among other things, +be used for iterating through the actual arguments to a macro: + +@deffn Builtin shift (@var{arg1}, @dots{}) +Takes any number of arguments, and expands to all its arguments except +@var{arg1}, separated by commas, with each argument quoted. + +The macro @code{shift} is recognized only with parameters. +@end deffn + +@example +shift +@result{}shift +shift(`bar') +@result{} +shift(`foo', `bar', `baz') +@result{}bar,baz +@end example + +An example of the use of @code{shift} is this macro: + +@cindex reversing arguments +@cindex arguments, reversing +@deffn Composite reverse (@dots{}) +Takes any number of arguments, and reverses their order. +@end deffn + +It is implemented as: + +@example +define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', + `reverse(shift($@@)), `$1'')') +@result{} +reverse +@result{} +reverse(`foo') +@result{}foo +reverse(`foo', `bar', `gnats', `and gnus') +@result{}and gnus, gnats, bar, foo +@end example + +While not a very interesting macro, it does show how simple loops can be +made with @code{shift}, @code{ifelse} and recursion. It also shows +that @code{shift} is usually used with @samp{$@@}. Another example of +this is an implementation of a short-circuiting conditional operator. + +@cindex short-circuiting conditional +@cindex conditional, short-circuiting +@deffn Composite cond (@var{test-1}, @var{string-1}, @var{equal-1}, @ + @ovar{test-2}, @ovar{string-2}, @ovar{equal-2}, @dots{}, @ovar{not-equal}) +Similar to @code{ifelse}, where an equal comparison between the first +two strings results in the third, otherwise the first three arguments +are discarded and the process repeats. The difference is that each +@var{test-<n>} is expanded only when it is encountered. This means that +every third argument to @code{cond} is normally given one more level of +quoting than the corresponding argument to @code{ifelse}. +@end deffn + +Here is the implementation of @code{cond}, along with a demonstration of +how it can short-circuit the side effects in @code{side}. Notice how +all the unquoted side effects happen regardless of how many comparisons +are made with @code{ifelse}, compared with only the relevant effects +with @code{cond}. + +@example +define(`cond', +`ifelse(`$#', `1', `$1', + `ifelse($1, `$2', `$3', + `$0(shift(shift(shift($@@))))')')')dnl +define(`side', `define(`counter', incr(counter))$1')dnl +define(`example1', +`define(`counter', `0')dnl +ifelse(side(`$1'), `yes', `one comparison: ', + side(`$1'), `no', `two comparisons: ', + side(`$1'), `maybe', `three comparisons: ', + `side(`default answer: ')')counter')dnl +define(`example2', +`define(`counter', `0')dnl +cond(`side(`$1')', `yes', `one comparison: ', + `side(`$1')', `no', `two comparisons: ', + `side(`$1')', `maybe', `three comparisons: ', + `side(`default answer: ')')counter')dnl +example1(`yes') +@result{}one comparison: 3 +example1(`no') +@result{}two comparisons: 3 +example1(`maybe') +@result{}three comparisons: 3 +example1(`feeling rather indecisive today') +@result{}default answer: 4 +example2(`yes') +@result{}one comparison: 1 +example2(`no') +@result{}two comparisons: 2 +example2(`maybe') +@result{}three comparisons: 3 +example2(`feeling rather indecisive today') +@result{}default answer: 4 +@end example + +@cindex joining arguments +@cindex arguments, joining +@cindex concatenating arguments +Another common task that requires iteration is joining a list of +arguments into a single string. + +@deffn Composite join (@ovar{separator}, @ovar{args@dots{}}) +@deffnx Composite joinall (@ovar{separator}, @ovar{args@dots{}}) +Generate a single-quoted string, consisting of each @var{arg} separated +by @var{separator}. While @code{joinall} always outputs a +@var{separator} between arguments, @code{join} avoids the +@var{separator} for an empty @var{arg}. +@end deffn + +Here are some examples of its usage, based on the implementation +@file{m4-@value{VERSION}/@/examples/@/join.m4} distributed in this +package: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`join.m4') +@result{} +join,join(`-'),join(`-', `'),join(`-', `', `') +@result{},,, +joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `') +@result{},,,- +join(`-', `1') +@result{}1 +join(`-', `1', `2', `3') +@result{}1-2-3 +join(`', `1', `2', `3') +@result{}123 +join(`-', `', `1', `', `', `2', `') +@result{}1-2 +joinall(`-', `', `1', `', `', `2', `') +@result{}-1---2- +join(`,', `1', `2', `3') +@result{}1,2,3 +define(`nargs', `$#')dnl +nargs(join(`,', `1', `2', `3')) +@result{}1 +@end example + +Examining the implementation shows some interesting points about several +m4 programming idioms. + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`join.m4')dnl +@result{}divert(`-1') +@result{}# join(sep, args) - join each non-empty ARG into a single +@result{}# string, with each element separated by SEP +@result{}define(`join', +@result{}`ifelse(`$#', `2', ``$2'', +@result{} `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@@)))')') +@result{}define(`_join', +@result{}`ifelse(`$#$2', `2', `', +@result{} `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@@)))')') +@result{}# joinall(sep, args) - join each ARG, including empty ones, +@result{}# into a single string, with each element separated by SEP +@result{}define(`joinall', ``$2'_$0(`$1', shift($@@))') +@result{}define(`_joinall', +@result{}`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@@)))')') +@result{}divert`'dnl +@end example + +First, notice that this implementation creates helper macros +@code{_join} and @code{_joinall}. This division of labor makes it +easier to output the correct number of @var{separator} instances: +@code{join} and @code{joinall} are responsible for the first argument, +without a separator, while @code{_join} and @code{_joinall} are +responsible for all remaining arguments, always outputting a separator +when outputting an argument. + +Next, observe how @code{join} decides to iterate to itself, because the +first @var{arg} was empty, or to output the argument and swap over to +@code{_join}. If the argument is non-empty, then the nested +@code{ifelse} results in an unquoted @samp{_}, which is concatenated +with the @samp{$0} to form the next macro name to invoke. The +@code{joinall} implementation is simpler since it does not have to +suppress empty @var{arg}; it always executes once then defers to +@code{_joinall}. + +Another important idiom is the idea that @var{separator} is reused for +each iteration. Each iteration has one less argument, but rather than +discarding @samp{$1} by iterating with @code{$0(shift($@@))}, the macro +discards @samp{$2} by using @code{$0(`$1', shift(shift($@@)))}. + +Next, notice that it is possible to compare more than one condition in a +single @code{ifelse} test. The test of @samp{$#$2} against @samp{2} +allows @code{_join} to iterate for two separate reasons---either there +are still more than two arguments, or there are exactly two arguments +but the last argument is not empty. + +Finally, notice that these macros require exactly two arguments to +terminate recursion, but that they still correctly result in empty +output when given no @var{args} (i.e., zero or one macro argument). On +the first pass when there are too few arguments, the @code{shift} +results in no output, but leaves an empty string to serve as the +required second argument for the second pass. Put another way, +@samp{`$1', shift($@@)} is not the same as @samp{$@@}, since only the +former guarantees at least two arguments. + +@cindex quote manipulation +@cindex manipulating quotes +Sometimes, a recursive algorithm requires adding quotes to each element, +or treating multiple arguments as a single element: + +@deffn Composite quote (@dots{}) +@deffnx Composite dquote (@dots{}) +@deffnx Composite dquote_elt (@dots{}) +Takes any number of arguments, and adds quoting. With @code{quote}, +only one level of quoting is added, effectively removing whitespace +after commas and turning multiple arguments into a single string. With +@code{dquote}, two levels of quoting are added, one around each element, +and one around the list. And with @code{dquote_elt}, two levels of +quoting are added around each element. +@end deffn + +An actual implementation of these three macros is distributed as +@file{m4-@value{VERSION}/@/examples/@/quote.m4} in this package. First, +let's examine their usage: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`quote.m4') +@result{} +-quote-dquote-dquote_elt- +@result{}---- +-quote()-dquote()-dquote_elt()- +@result{}--`'-`'- +-quote(`1')-dquote(`1')-dquote_elt(`1')- +@result{}-1-`1'-`1'- +-quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')- +@result{}-1,2-`1',`2'-`1',`2'- +define(`n', `$#')dnl +-n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))- +@result{}-1-1-2- +dquote(dquote_elt(`1', `2')) +@result{}``1'',``2'' +dquote_elt(dquote(`1', `2')) +@result{}``1',`2'' +@end example + +The last two lines show that when given two arguments, @code{dquote} +results in one string, while @code{dquote_elt} results in two. Now, +examine the implementation. Note that @code{quote} and +@code{dquote_elt} make decisions based on their number of arguments, so +that when called without arguments, they result in nothing instead of a +quoted empty string; this is so that it is possible to distinguish +between no arguments and an empty first argument. @code{dquote}, on the +other hand, results in a string no matter what, since it is still +possible to tell whether it was invoked without arguments based on the +resulting string. + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`quote.m4')dnl +@result{}divert(`-1') +@result{}# quote(args) - convert args to single-quoted string +@result{}define(`quote', `ifelse(`$#', `0', `', ``$*'')') +@result{}# dquote(args) - convert args to quoted list of quoted strings +@result{}define(`dquote', ``$@@'') +@result{}# dquote_elt(args) - convert args to list of double-quoted strings +@result{}define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''', +@result{} ```$1'',$0(shift($@@))')') +@result{}divert`'dnl +@end example + +It is worth pointing out that @samp{quote(@var{args})} is more efficient +than @samp{joinall(`,', @var{args})} for producing the same output. + +@cindex nine arguments, more than +@cindex more than nine arguments +@cindex arguments, more than nine +One more useful macro based on @code{shift} allows portably selecting +an arbitrary argument (usually greater than the ninth argument), without +relying on the GNU extension of multi-digit arguments +(@pxref{Arguments}). + +@deffn Composite argn (@var{n}, @dots{}) +Expands to argument @var{n} out of the remaining arguments. @var{n} +must be a positive number. Usually invoked as +@samp{argn(`@var{n}',$@@)}. +@end deffn + +It is implemented as: + +@example +define(`argn', `ifelse(`$1', 1, ``$2'', + `argn(decr(`$1'), shift(shift($@@)))')') +@result{} +argn(`1', `a') +@result{}a +define(`foo', `argn(`11', $@@)') +@result{} +foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l') +@result{}k +@end example + +@node Forloop +@section Iteration by counting + +@cindex for loops +@cindex loops, counting +@cindex counting loops +Here is an example of a loop macro that implements a simple for loop. + +@deffn Composite forloop (@var{iterator}, @var{start}, @var{end}, @var{text}) +Takes the name in @var{iterator}, which must be a valid macro name, and +successively assign it each integer value from @var{start} to @var{end}, +inclusive. For each assignment to @var{iterator}, append @var{text} to +the expansion of the @code{forloop}. @var{text} may refer to +@var{iterator}. Any definition of @var{iterator} prior to this +invocation is restored. +@end deffn + +It can, for example, be used for simple counting: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`forloop.m4') +@result{} +forloop(`i', `1', `8', `i ') +@result{}1 2 3 4 5 6 7 8@w{ } +@end example + +For-loops can be nested, like: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`forloop.m4') +@result{} +forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)') +') +@result{} (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8) +@result{} (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8) +@result{} (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8) +@result{} (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8) +@result{} +@end example + +The implementation of the @code{forloop} macro is fairly +straightforward. The @code{forloop} macro itself is simply a wrapper, +which saves the previous definition of the first argument, calls the +internal macro @code{@w{_forloop}}, and re-establishes the saved +definition of the first argument. + +The macro @code{@w{_forloop}} expands the fourth argument once, and +tests to see if the iterator has reached the final value. If it has +not finished, it increments the iterator (using the predefined macro +@code{incr}, @pxref{Incr}), and recurses. + +Here is an actual implementation of @code{forloop}, distributed as +@file{m4-@value{VERSION}/@/examples/@/forloop.m4} in this package: + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`forloop.m4')dnl +@result{}divert(`-1') +@result{}# forloop(var, from, to, stmt) - simple version +@result{}define(`forloop', `pushdef(`$1', `$2')_forloop($@@)popdef(`$1')') +@result{}define(`_forloop', +@result{} `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@@)')') +@result{}divert`'dnl +@end example + +Notice the careful use of quotes. Certain macro arguments are left +unquoted, each for its own reason. Try to find out @emph{why} these +arguments are left unquoted, and see what happens if they are quoted. +(As presented, these two macros are useful but not very robust for +general use. They lack even basic error handling for cases like +@var{start} less than @var{end}, @var{end} not numeric, or +@var{iterator} not being a macro name. See if you can improve these +macros; or @pxref{Improved forloop, , Answers}). + +@node Foreach +@section Iteration by list contents + +@cindex for each loops +@cindex loops, list iteration +@cindex iterating over lists +Here is an example of a loop macro that implements list iteration. + +@deffn Composite foreach (@var{iterator}, @var{paren-list}, @var{text}) +@deffnx Composite foreachq (@var{iterator}, @var{quote-list}, @var{text}) +Takes the name in @var{iterator}, which must be a valid macro name, and +successively assign it each value from @var{paren-list} or +@var{quote-list}. In @code{foreach}, @var{paren-list} is a +comma-separated list of elements contained in parentheses. In +@code{foreachq}, @var{quote-list} is a comma-separated list of elements +contained in a quoted string. For each assignment to @var{iterator}, +append @var{text} to the overall expansion. @var{text} may refer to +@var{iterator}. Any definition of @var{iterator} prior to this +invocation is restored. +@end deffn + +As an example, this displays each word in a list inside of a sentence, +using an implementation of @code{foreach} distributed as +@file{m4-@value{VERSION}/@/examples/@/foreach.m4}, and @code{foreachq} +in @file{m4-@value{VERSION}/@/examples/@/foreachq.m4}. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreach.m4') +@result{} +foreach(`x', (foo, bar, foobar), `Word was: x +')dnl +@result{}Word was: foo +@result{}Word was: bar +@result{}Word was: foobar +include(`foreachq.m4') +@result{} +foreachq(`x', `foo, bar, foobar', `Word was: x +')dnl +@result{}Word was: foo +@result{}Word was: bar +@result{}Word was: foobar +@end example + +It is possible to be more complex; each element of the @var{paren-list} +or @var{quote-list} can itself be a list, to pass as further arguments +to a helper macro. This example generates a shell case statement: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreach.m4') +@result{} +define(`_case', ` $1) + $2=" $1";; +')dnl +define(`_cat', `$1$2')dnl +case $`'1 in +@result{}case $1 in +foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')', + `_cat(`_case', x)')dnl +@result{} a) +@result{} vara=" a";; +@result{} b) +@result{} varb=" b";; +@result{} c) +@result{} varc=" c";; +esac +@result{}esac +@end example + +The implementation of the @code{foreach} macro is a bit more involved; +it is a wrapper around two helper macros. First, @code{@w{_arg1}} is +needed to grab the first element of a list. Second, +@code{@w{_foreach}} implements the recursion, successively walking +through the original list. Here is a simple implementation of +@code{foreach}: + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`foreach.m4')dnl +@result{}divert(`-1') +@result{}# foreach(x, (item_1, item_2, ..., item_n), stmt) +@result{}# parenthesized list, simple version +@result{}define(`foreach', `pushdef(`$1')_foreach($@@)popdef(`$1')') +@result{}define(`_arg1', `$1') +@result{}define(`_foreach', `ifelse(`$2', `()', `', +@result{} `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')') +@result{}divert`'dnl +@end example + +Unfortunately, that implementation is not robust to macro names as list +elements. Each iteration of @code{@w{_foreach}} is stripping another +layer of quotes, leading to erratic results if list elements are not +already fully expanded. The first cut at implementing @code{foreachq} +takes this into account. Also, when using quoted elements in a +@var{paren-list}, the overall list must be quoted. A @var{quote-list} +has the nice property of requiring fewer characters to create a list +containing the same quoted elements. To see the difference between the +two macros, we attempt to pass double-quoted macro names in a list, +expecting the macro name on output after one layer of quotes is removed +during list iteration and the final layer removed during the final +rescan: + +@comment examples +@example +$ @kbd{m4 -I examples} +define(`a', `1')define(`b', `2')define(`c', `3') +@result{} +include(`foreach.m4') +@result{} +include(`foreachq.m4') +@result{} +foreach(`x', `(``a'', ``(b'', ``c)'')', `x +') +@result{}1 +@result{}(2)1 +@result{} +@result{}, x +@result{}) +foreachq(`x', ```a'', ``(b'', ``c)''', `x +')dnl +@result{}a +@result{}(b +@result{}c) +@end example + +Obviously, @code{foreachq} did a better job; here is its implementation: + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`foreachq.m4')dnl +@result{}include(`quote.m4')dnl +@result{}divert(`-1') +@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt) +@result{}# quoted list, simple version +@result{}define(`foreachq', `pushdef(`$1')_foreachq($@@)popdef(`$1')') +@result{}define(`_arg1', `$1') +@result{}define(`_foreachq', `ifelse(quote($2), `', `', +@result{} `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')') +@result{}divert`'dnl +@end example + +Notice that @code{@w{_foreachq}} had to use the helper macro +@code{quote} defined earlier (@pxref{Shift}), to ensure that the +embedded @code{ifelse} call does not go haywire if a list element +contains a comma. Unfortunately, this implementation of @code{foreachq} +has its own severe flaw. Whereas the @code{foreach} implementation was +linear, this macro is quadratic in the number of list elements, and is +much more likely to trip up the limit set by the command line option +@option{--nesting-limit} (or @option{-L}, @pxref{Limits control, , +Invoking m4}). Additionally, this implementation does not expand +@samp{defn(`@var{iterator}')} very well, when compared with +@code{foreach}. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreach.m4')include(`foreachq.m4') +@result{} +foreach(`name', `(`a', `b')', ` defn(`name')') +@result{} a b +foreachq(`name', ``a', `b'', ` defn(`name')') +@result{} _arg1(`a', `b') _arg1(shift(`a', `b')) +@end example + +It is possible to have robust iteration with linear behavior and sane +@var{iterator} contents for either list style. See if you can learn +from the best elements of both of these implementations to create robust +macros (or @pxref{Improved foreach, , Answers}). + +@node Stacks +@section Working with definition stacks + +@cindex definition stack +@cindex pushdef stack +@cindex stack, macro definition +Thanks to @code{pushdef}, manipulation of a stack is an intrinsic +operation in @code{m4}. Normally, only the topmost definition in a +stack is important, but sometimes, it is desirable to manipulate the +entire definition stack. + +@deffn Composite stack_foreach (@var{macro}, @var{action}) +@deffnx Composite stack_foreach_lifo (@var{macro}, @var{action}) +For each of the @code{pushdef} definitions associated with @var{macro}, +invoke the macro @var{action} with a single argument of that definition. +@code{stack_foreach} visits the oldest definition first, while +@code{stack_foreach_lifo} visits the current definition first. +@var{action} should not modify or dereference @var{macro}. There are a +few special macros, such as @code{defn}, which cannot be used as the +@var{macro} parameter. +@end deffn + +A sample implementation of these macros is distributed in the file +@file{m4-@value{VERSION}/@/examples/@/stack.m4}. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`stack.m4') +@result{} +pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') +@result{} +define(`show', ``$1' +') +@result{} +stack_foreach(`a', `show')dnl +@result{}1 +@result{}2 +@result{}3 +stack_foreach_lifo(`a', `show')dnl +@result{}3 +@result{}2 +@result{}1 +@end example + +Now for the implementation. Note the definition of a helper macro, +@code{_stack_reverse}, which destructively swaps the contents of one +stack of definitions into the reverse order in the temporary macro +@samp{tmp-$1}. By calling the helper twice, the original order is +restored back into the macro @samp{$1}; since the operation is +destructive, this explains why @samp{$1} must not be modified or +dereferenced during the traversal. The caller can then inject +additional code to pass the definition currently being visited to +@samp{$2}. The choice of helper names is intentional; since @samp{-} is +not valid as part of a macro name, there is no risk of conflict with a +valid macro name, and the code is guaranteed to use @code{defn} where +necessary. Finally, note that any macro used in the traversal of a +@code{pushdef} stack, such as @code{pushdef} or @code{defn}, cannot be +handled by @code{stack_foreach}, since the macro would temporarily be +undefined during the algorithm. + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`stack.m4')dnl +@result{}divert(`-1') +@result{}# stack_foreach(macro, action) +@result{}# Invoke ACTION with a single argument of each definition +@result{}# from the definition stack of MACRO, starting with the oldest. +@result{}define(`stack_foreach', +@result{}`_stack_reverse(`$1', `tmp-$1')'dnl +@result{}`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')') +@result{}# stack_foreach_lifo(macro, action) +@result{}# Invoke ACTION with a single argument of each definition +@result{}# from the definition stack of MACRO, starting with the newest. +@result{}define(`stack_foreach_lifo', +@result{}`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl +@result{}`_stack_reverse(`tmp-$1', `$1')') +@result{}define(`_stack_reverse', +@result{}`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@@)')') +@result{}divert`'dnl +@end example + +@node Composition +@section Building macros with macros + +@cindex macro composition +@cindex composing macros +Since m4 is a macro language, it is possible to write macros that +can build other macros. First on the list is a way to automate the +creation of blind macros. + +@cindex macro, blind +@cindex blind macro +@deffn Composite define_blind (@var{name}, @ovar{value}) +Defines @var{name} as a blind macro, such that @var{name} will expand to +@var{value} only when given explicit arguments. @var{value} should not +be the result of @code{defn} (@pxref{Defn}). This macro is only +recognized with parameters, and results in an empty string. +@end deffn + +Defining a macro to define another macro can be a bit tricky. We want +to use a literal @samp{$#} in the argument to the nested @code{define}. +However, if @samp{$} and @samp{#} are adjacent in the definition of +@code{define_blind}, then it would be expanded as the number of +arguments to @code{define_blind} rather than the intended number of +arguments to @var{name}. The solution is to pass the difficult +characters through extra arguments to a helper macro +@code{_define_blind}. When composing macros, it is a common idiom to +need a helper macro to concatenate text that forms parameters in the +composed macro, rather than interpreting the text as a parameter of the +composing macro. + +As for the limitation against using @code{defn}, there are two reasons. +If a macro was previously defined with @code{define_blind}, then it can +safely be renamed to a new blind macro using plain @code{define}; using +@code{define_blind} to rename it just adds another layer of +@code{ifelse}, occupying memory and slowing down execution. And if a +macro is a builtin, then it would result in an attempt to define a macro +consisting of both text and a builtin token; this is not supported, and +the builtin token is flattened to an empty string. + +With that explanation, here's the definition, and some sample usage. +Notice that @code{define_blind} is itself a blind macro. + +@example +$ @kbd{m4 -d} +define(`define_blind', `ifelse(`$#', `0', ``$0'', +`_$0(`$1', `$2', `$'`#', `$'`0')')') +@result{} +define(`_define_blind', `define(`$1', +`ifelse(`$3', `0', ``$4'', `$2')')') +@result{} +define_blind +@result{}define_blind +define_blind(`foo', `arguments were $*') +@result{} +foo +@result{}foo +foo(`bar') +@result{}arguments were bar +define(`blah', defn(`foo')) +@result{} +blah +@result{}blah +blah(`a', `b') +@result{}arguments were a,b +defn(`blah') +@result{}ifelse(`$#', `0', ``$0'', `arguments were $*') +@end example + +@cindex currying arguments +@cindex argument currying +Another interesting composition tactic is argument @dfn{currying}, or +factoring a macro that takes multiple arguments for use in a context +that provides exactly one argument. + +@deffn Composite curry (@var{macro}, @dots{}) +Expand to a macro call that takes exactly one argument, then appends +that argument to the original arguments and invokes @var{macro} with the +resulting list of arguments. +@end deffn + +A demonstration of currying makes the intent of this macro a little more +obvious. The macro @code{stack_foreach} mentioned earlier is an example +of a context that provides exactly one argument to a macro name. But +coupled with currying, we can invoke @code{reverse} with two arguments +for each definition of a macro stack. This example uses the file +@file{m4-@value{VERSION}/@/examples/@/curry.m4} included in the +distribution. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`curry.m4')include(`stack.m4') +@result{} +define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', + `reverse(shift($@@)), `$1'')') +@result{} +pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') +@result{} +stack_foreach(`a', `:curry(`reverse', `4')') +@result{}:1, 4:2, 4:3, 4 +curry(`curry', `reverse', `1')(`2')(`3') +@result{}3, 2, 1 +@end example + +Now for the implementation. Notice how @code{curry} leaves off with a +macro name but no open parenthesis, while still in the middle of +collecting arguments for @samp{$1}. The macro @code{_curry} is the +helper macro that takes one argument, then adds it to the list and +finally supplies the closing parenthesis. The use of a comma inside the +@code{shift} call allows currying to also work for a macro that takes +one argument, although it often makes more sense to invoke that macro +directly rather than going through @code{curry}. + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`curry.m4')dnl +@result{}divert(`-1') +@result{}# curry(macro, args) +@result{}# Expand to a macro call that takes one argument, then invoke +@result{}# macro(args, extra). +@result{}define(`curry', `$1(shift($@@,)_$0') +@result{}define(`_curry', ``$1')') +@result{}divert`'dnl +@end example + +Unfortunately, with M4 1.4.x, @code{curry} is unable to handle builtin +tokens, which are silently flattened to the empty string when passed +through another text macro. This limitation will be lifted in a future +release of M4. + +@cindex renaming macros +@cindex copying macros +@cindex macros, copying +Putting the last few concepts together, it is possible to copy or rename +an entire stack of macro definitions. + +@deffn Composite copy (@var{source}, @var{dest}) +@deffnx Composite rename (@var{source}, @var{dest}) +Ensure that @var{dest} is undefined, then define it to the same stack of +definitions currently in @var{source}. @code{copy} leaves @var{source} +unchanged, while @code{rename} undefines @var{source}. There are only a +few macros, such as @code{copy} or @code{defn}, which cannot be copied +via this macro. +@end deffn + +The implementation is relatively straightforward (although since it uses +@code{curry}, it is unable to copy builtin macros, such as the second +definition of @code{a} as a synonym for @code{divnum}. See if you can +design a version that works around this limitation, or @pxref{Improved +copy, , Answers}). + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`curry.m4')include(`stack.m4') +@result{} +define(`rename', `copy($@@)undefine(`$1')')dnl +define(`copy', `ifdef(`$2', `errprint(`$2 already defined +')m4exit(`1')', + `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl +pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2') +@result{} +copy(`a', `b') +@result{} +rename(`b', `c') +@result{} +a b c +@result{}2 b 2 +popdef(`a', `c')c a +@result{} 0 +popdef(`a', `c')a c +@result{}1 1 +@end example + +@node Debugging +@chapter How to debug macros and input + +@cindex debugging macros +@cindex macros, debugging +When writing macros for @code{m4}, they often do not work as intended on +the first try (as is the case with most programming languages). +Fortunately, there is support for macro debugging in @code{m4}. + +@menu +* Dumpdef:: Displaying macro definitions +* Trace:: Tracing macro calls +* Debug Levels:: Controlling debugging output +* Debug Output:: Saving debugging output +@end menu + +@node Dumpdef +@section Displaying macro definitions + +@cindex displaying macro definitions +@cindex macros, displaying definitions +@cindex definitions, displaying macro +@cindex standard error, output to +If you want to see what a name expands into, you can use the builtin +@code{dumpdef}: + +@deffn Builtin dumpdef (@ovar{names@dots{}}) +Accepts any number of arguments. If called without any arguments, +it displays the definitions of all known names, otherwise it displays +the definitions of the @var{names} given. The output is printed to the +current debug file (usually standard error), and is sorted by name. If +an unknown name is encountered, a warning is printed. + +The expansion of @code{dumpdef} is void. +@end deffn + +@example +$ @kbd{m4 -d} +define(`foo', `Hello world.') +@result{} +dumpdef(`foo') +@error{}foo:@tabchar{}`Hello world.' +@result{} +dumpdef(`define') +@error{}define:@tabchar{}<define> +@result{} +@end example + +The last example shows how builtin macros definitions are displayed. +The definition that is dumped corresponds to what would occur if the +macro were to be called at that point, even if other definitions are +still live due to redefining a macro during argument collection. + +@example +$ @kbd{m4 -d} +pushdef(`f', ``$0'1')pushdef(`f', ``$0'2') +@result{} +f(popdef(`f')dumpdef(`f')) +@error{}f:@tabchar{}``$0'1' +@result{}f2 +f(popdef(`f')dumpdef(`f')) +@error{}m4:stdin:3: undefined macro `f' +@result{}f1 +@end example + +@xref{Debug Levels}, for information on controlling the details of the +display. + +@node Trace +@section Tracing macro calls + +@cindex tracing macro expansion +@cindex macro expansion, tracing +@cindex expansion, tracing macro +@cindex standard error, output to +It is possible to trace macro calls and expansions through the builtins +@code{traceon} and @code{traceoff}: + +@deffn Builtin traceon (@ovar{names@dots{}}) +@deffnx Builtin traceoff (@ovar{names@dots{}}) +When called without any arguments, @code{traceon} and @code{traceoff} +will turn tracing on and off, respectively, for all currently defined +macros. + +When called with arguments, only the macros listed in @var{names} are +affected, whether or not they are currently defined. + +The expansion of @code{traceon} and @code{traceoff} is void. +@end deffn + +Whenever a traced macro is called and the arguments have been collected, +the call is displayed. If the expansion of the macro call is not void, +the expansion can be displayed after the call. The output is printed +to the current debug file (defaulting to standard error, @pxref{Debug +Output}). + +@example +$ @kbd{m4 -d} +define(`foo', `Hello World.') +@result{} +define(`echo', `$@@') +@result{} +traceon(`foo', `echo') +@result{} +foo +@error{}m4trace: -1- foo -> `Hello World.' +@result{}Hello World. +echo(`gnus', `and gnats') +@error{}m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats'' +@result{}gnus,and gnats +@end example + +The number between dashes is the depth of the expansion. It is one most +of the time, signifying an expansion at the outermost level, but it +increases when macro arguments contain unquoted macro calls. The +maximum number that will appear between dashes is controlled by the +option @option{--nesting-limit} (or @option{-L}, @pxref{Limits control, +, Invoking m4}). Additionally, the option @option{--trace} (or +@option{-t}) can be used to invoke @code{traceon(@var{name})} before +parsing input. + +@comment The explicit -dp neutralizes the testsuite default of -d. +@comment options: -dp -L3 -tifelse +@comment status: 1 +@example +$ @kbd{m4 -L 3 -t ifelse} +ifelse(`one level') +@error{}m4trace: -1- ifelse +@result{} +ifelse(ifelse(ifelse(`three levels'))) +@error{}m4trace: -3- ifelse +@error{}m4trace: -2- ifelse +@error{}m4trace: -1- ifelse +@result{} +ifelse(ifelse(ifelse(ifelse(`four levels')))) +@error{}m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it +@end example + +Tracing by name is an attribute that is preserved whether the macro is +defined or not. This allows the selection of macros to trace before +those macros are defined. + +@example +$ @kbd{m4 -d} +traceoff(`foo') +@result{} +traceon(`foo') +@result{} +foo +@result{}foo +defn(`foo') +@result{} +define(`foo', `bar') +@result{} +foo +@error{}m4trace: -1- foo -> `bar' +@result{}bar +undefine(`foo') +@result{} +ifdef(`foo', `yes', `no') +@result{}no +indir(`foo') +@error{}m4:stdin:9: undefined macro `foo' +@result{} +define(`foo', `blah') +@result{} +foo +@error{}m4trace: -1- foo -> `blah' +@result{}blah +traceoff +@result{} +foo +@result{}blah +@end example + +Tracing even works on builtins. However, @code{defn} (@pxref{Defn}) +does not transfer tracing status. + +@example +$ @kbd{m4 -d} +traceon(`traceon') +@result{} +traceon(`traceoff') +@error{}m4trace: -1- traceon(`traceoff') +@result{} +traceoff(`traceoff') +@error{}m4trace: -1- traceoff(`traceoff') +@result{} +traceoff(`traceon') +@result{} +traceon(`eval', `m4_divnum') +@result{} +define(`m4_eval', defn(`eval')) +@result{} +define(`m4_divnum', defn(`divnum')) +@result{} +eval(divnum) +@error{}m4trace: -1- eval(`0') -> `0' +@result{}0 +m4_eval(m4_divnum) +@error{}m4trace: -2- m4_divnum -> `0' +@result{}0 +@end example + +@xref{Debug Levels}, for information on controlling the details of the +display. The format of the trace output is not specified by +POSIX, and varies between implementations of @code{m4}. + +@ignore +@comment not worth including in the manual, but this tests a trace code +@comment path that was temporarily broken +@comment options: -de --trace ifelse +@example +$ @kbd{m4 -de --trace ifelse} +define(`e', `ifelse(`$1', `$2', `ifelse(`$1', `$2', `e(shift($@@))')')') +@result{} +e(`1', `1') +@error{}m4trace: -1- ifelse -> ifelse(`1', `1', `e(shift(`1',`1'))') +@error{}m4trace: -1- ifelse -> e(shift(`1',`1')) +@error{}m4trace: -1- ifelse +@result{} +@end example +@end ignore + +@node Debug Levels +@section Controlling debugging output + +@cindex controlling debugging output +@cindex debugging output, controlling +The @option{-d} option to @code{m4} (or @option{--debug}, +@pxref{Debugging options, , Invoking m4}) controls the amount of details +presented in three +categories of output. Trace output is requested by @code{traceon} +(@pxref{Trace}), and each line is prefixed by @samp{m4trace:} in +relation to a macro invocation. Debug output tracks useful events not +associated with a macro invocation, and each line is prefixed by +@samp{m4debug:}. Finally, @code{dumpdef} (@pxref{Dumpdef}) output is +affected, with no prefix added to the output lines. + +The @var{flags} following the option can be one or more of the +following: + +@table @code +@item a +In trace output, show the actual arguments that were collected before +invoking the macro. This applies to all macro calls if the @samp{t} +flag is used, otherwise only the macros covered by calls of +@code{traceon}. Arguments are subject to length truncation specified by +the command line option @option{--arglength} (or @option{-l}). + +@item c +In trace output, show several trace lines for each macro call. A line +is shown when the macro is seen, but before the arguments are collected; +a second line when the arguments have been collected and a third line +after the call has completed. + +@item e +In trace output, show the expansion of each macro call, if it is not +void. This applies to all macro calls if the @samp{t} flag is used, +otherwise only the macros covered by calls of @code{traceon}. The +expansion is subject to length truncation specified by the command line +option @option{--arglength} (or @option{-l}). + +@item f +In debug and trace output, include the name of the current input file in +the output line. + +@item i +In debug output, print a message each time the current input file is +changed. + +@item l +In debug and trace output, include the current input line number in the +output line. + +@item p +In debug output, print a message when a named file is found through the +path search mechanism (@pxref{Search Path}), giving the actual file name +used. + +@item q +In trace and dumpdef output, quote actual arguments and macro expansions +in the display with the current quotes. This is useful in connection +with the @samp{a} and @samp{e} flags above. + +@item t +In trace output, trace all macro calls made in this invocation of +@code{m4}, regardless of the settings of @code{traceon}. + +@item x +In trace output, add a unique `macro call id' to each line of the trace +output. This is useful in connection with the @samp{c} flag above. + +@item V +A shorthand for all of the above flags. +@end table + +If no flags are specified with the @option{-d} option, the default is +@samp{aeq}. The examples throughout this manual assume the default +flags. + +@cindex GNU extensions +There is a builtin macro @code{debugmode}, which allows on-the-fly control of +the debugging output format: + +@deffn Builtin debugmode (@ovar{flags}) +The argument @var{flags} should be a subset of the letters listed above. +As special cases, if the argument starts with a @samp{+}, the flags are +added to the current debug flags, and if it starts with a @samp{-}, they +are removed. If no argument is present, all debugging flags are cleared +(as if no @option{-d} was given), and with an empty argument the flags +are reset to the default of @samp{aeq}. + +The expansion of @code{debugmode} is void. +@end deffn + +@comment The explicit -dp neutralizes the testsuite default of -d. +@comment options: -dp +@example +$ @kbd{m4} +define(`foo', `FOO') +@result{} +traceon(`foo') +@result{} +debugmode() +@result{} +foo +@error{}m4trace: -1- foo -> `FOO' +@result{}FOO +debugmode +@result{} +foo +@error{}m4trace: -1- foo +@result{}FOO +debugmode(`+l') +@result{} +foo +@error{}m4trace:8: -1- foo +@result{}FOO +@end example + +The following example demonstrates the behavior of length truncation, +when specified on the command line. Note that each argument and the +final result are individually truncated. Also, the special tokens for +builtin functions are not truncated. + +@comment options: -l6 +@example +$ @kbd{m4 -d -l 6} +define(`echo', `$@@')debugmode(`+t') +@result{} +echo(`1', `long string') +@error{}m4trace: -1- echo(`1', `long s...') -> ``1',`l...' +@result{}1,long string +indir(`echo', defn(`changequote')) +@error{}m4trace: -2- defn(`change...') +@error{}m4trace: -1- indir(`echo', <changequote>) -> ``'' +@result{} +@end example + +This example shows the effects of the debug flags that are not related +to macro tracing. + +@comment examples +@comment options: -dip +@example +$ @kbd{m4 -dip -I examples} +@error{}m4debug: input read from stdin +include(`foo')dnl +@error{}m4debug: path search for `foo' found `examples/foo' +@error{}m4debug: input read from examples/foo +@result{}bar +@error{}m4debug: input reverted to stdin, line 1 +^D +@error{}m4debug: input exhausted +@end example + +@node Debug Output +@section Saving debugging output + +@cindex saving debugging output +@cindex debugging output, saving +@cindex output, saving debugging +@cindex GNU extensions +Debug and tracing output can be redirected to files using either the +@option{--debugfile} option to @code{m4} (@pxref{Debugging options, , +Invoking m4}), or with the builtin macro @code{debugfile}: + +@deffn Builtin debugfile (@ovar{file}) +Sends all further debug and trace output to @var{file}, opened in append +mode. If @var{file} is the empty string, debug and trace output are +discarded. If @code{debugfile} is called without any arguments, debug +and trace output are sent to standard error. This does not affect +warnings, error messages, or @code{errprint} output, which are +always sent to standard error. If @var{file} cannot be opened, the +current debug file is unchanged, and an error is issued. + +The expansion of @code{debugfile} is void. +@end deffn + +@example +$ @kbd{m4 -d} +traceon(`divnum') +@result{} +divnum(`extra') +@error{}m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored +@error{}m4trace: -1- divnum(`extra') -> `0' +@result{}0 +debugfile() +@result{} +divnum(`extra') +@error{}m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored +@result{}0 +debugfile +@result{} +divnum +@error{}m4trace: -1- divnum -> `0' +@result{}0 +@end example + +@node Input Control +@chapter Input control + +This chapter describes various builtin macros for controlling the input +to @code{m4}. + +@menu +* Dnl:: Deleting whitespace in input +* Changequote:: Changing the quote characters +* Changecom:: Changing the comment delimiters +* Changeword:: Changing the lexical structure of words +* M4wrap:: Saving text until end of input +@end menu + +@node Dnl +@section Deleting whitespace in input + +@cindex deleting whitespace in input +@cindex discarding input +@cindex input, discarding +The builtin @code{dnl} stands for ``Discard to Next Line'': + +@deffn Builtin dnl +All characters, up to and including the next newline, are discarded +without performing any macro expansion. A warning is issued if the end +of the file is encountered without a newline. + +The expansion of @code{dnl} is void. +@end deffn + +It is often used in connection with @code{define}, to remove the +newline that follows the call to @code{define}. Thus + +@example +define(`foo', `Macro `foo'.')dnl A very simple macro, indeed. +foo +@result{}Macro foo. +@end example + +The input up to and including the next newline is discarded, as opposed +to the way comments are treated (@pxref{Comments}). + +Usually, @code{dnl} is immediately followed by an end of line or some +other whitespace. GNU @code{m4} will produce a warning diagnostic if +@code{dnl} is followed by an open parenthesis. In this case, @code{dnl} +will collect and process all arguments, looking for a matching close +parenthesis. All predictable side effects resulting from this +collection will take place. @code{dnl} will return no output. The +input following the matching close parenthesis up to and including the +next newline, on whatever line containing it, will still be discarded. + +@example +dnl(`args are ignored, but side effects occur', +define(`foo', `like this')) while this text is ignored: undefine(`foo') +@error{}m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored +See how `foo' was defined, foo? +@result{}See how foo was defined, like this? +@end example + +If the end of file is encountered without a newline character, a +warning is issued and dnl stops consuming input. + +@example +m4wrap(`m4wrap(`2 hi +')0 hi dnl 1 hi') +@result{} +define(`hi', `HI') +@result{} +^D +@error{}m4:stdin:1: Warning: end of file treated as newline +@result{}0 HI 2 HI +@end example + +@node Changequote +@section Changing the quote characters + +@cindex changing quote delimiters +@cindex quote delimiters, changing +@cindex delimiters, changing +The default quote delimiters can be changed with the builtin +@code{changequote}: + +@deffn Builtin changequote (@dvar{start, `}, @dvar{end, '}) +This sets @var{start} as the new begin-quote delimiter and @var{end} as +the new end-quote delimiter. If both arguments are missing, the default +quotes (@code{`} and @code{'}) are used. If @var{start} is void, then +quoting is disabled. Otherwise, if @var{end} is missing or void, the +default end-quote delimiter (@code{'}) is used. The quote delimiters +can be of any length. + +The expansion of @code{changequote} is void. +@end deffn + +@example +changequote(`[', `]') +@result{} +define([foo], [Macro [foo].]) +@result{} +foo +@result{}Macro foo. +@end example + +The quotation strings can safely contain eight-bit characters. +@ignore +@comment Yuck. I know of no clean way to render an 8-bit character in +@comment both info and dvi. This example uses the `open-guillemot' and +@comment `close-guillemot' characters of the Latin-1 character set. + +@example +define(`a', `b') +@result{} +«a» +@result{}«b» +changequote(`«', `»') +@result{} +«a» +@result{}a +@end example +@end ignore +If no single character is appropriate, @var{start} and @var{end} can be +of any length. Other implementations cap the delimiter length to five +characters, but GNU has no inherent limit. + +@example +changequote(`[[[', `]]]') +@result{} +define([[[foo]]], [[[Macro [[[[[foo]]]]].]]]) +@result{} +foo +@result{}Macro [[foo]]. +@end example + +Calling @code{changequote} with @var{start} as the empty string will +effectively disable the quoting mechanism, leaving no way to quote text. +However, using an empty string is not portable, as some other +implementations of @code{m4} revert to the default quoting, while others +preserve the prior non-empty delimiter. If @var{start} is not empty, +then an empty @var{end} will use the default end-quote delimiter of +@samp{'}, as otherwise, it would be impossible to end a quoted string. +Again, this is not portable, as some other @code{m4} implementations +reuse @var{start} as the end-quote delimiter, while others preserve the +previous non-empty value. Omitting both arguments restores the default +begin-quote and end-quote delimiters; fortunately this behavior is +portable to all implementations of @code{m4}. + +@example +define(`foo', `Macro `FOO'.') +@result{} +changequote(`', `') +@result{} +foo +@result{}Macro `FOO'. +`foo' +@result{}`Macro `FOO'.' +changequote(`,) +@result{} +foo +@result{}Macro FOO. +@end example + +There is no way in @code{m4} to quote a string containing an unmatched +begin-quote, except using @code{changequote} to change the current +quotes. + +If the quotes should be changed from, say, @samp{[} to @samp{[[}, +temporary quote characters have to be defined. To achieve this, two +calls of @code{changequote} must be made, one for the temporary quotes +and one for the new quotes. + +Macros are recognized in preference to the begin-quote string, so if a +prefix of @var{start} can be recognized as part of a potential macro +name, the quoting mechanism is effectively disabled. Unless you use +@code{changeword} (@pxref{Changeword}), this means that @var{start} +should not begin with a letter, digit, or @samp{_} (underscore). +However, even though quoted strings are not recognized, the quote +characters can still be discerned in macro expansion and in trace +output. + +@example +define(`echo', `$@@') +@result{} +define(`hi', `HI') +@result{} +changequote(`q', `Q') +@result{} +q hi Q hi +@result{}q HI Q HI +echo(hi) +@result{}qHIQ +changequote +@result{} +changequote(`-', `EOF') +@result{} +- hi EOF hi +@result{} hi HI +changequote +@result{} +changequote(`1', `2') +@result{} +hi1hi2 +@result{}hi1hi2 +hi 1hi2 +@result{}HI hi +@end example + +Quotes are recognized in preference to argument collection. In +particular, if @var{start} is a single @samp{(}, then argument +collection is effectively disabled. For portability with other +implementations, it is a good idea to avoid @samp{(}, @samp{,}, and +@samp{)} as the first character in @var{start}. + +@example +define(`echo', `$#:$@@:') +@result{} +define(`hi', `HI') +@result{} +changequote(`(',`)') +@result{} +echo(hi) +@result{}0::hi +changequote +@result{} +changequote(`((', `))') +@result{} +echo(hi) +@result{}1:HI: +echo((hi)) +@result{}0::hi +changequote +@result{} +changequote(`,', `)') +@result{} +echo(hi,hi)bye) +@result{}1:HIhibye: +@end example + +However, if you are not worried about portability, using @samp{(} and +@samp{)} as quoting characters has an interesting property---you can use +it to compute a quoted string containing the expansion of any quoted +text, as long as the expansion results in both balanced quotes and +balanced parentheses. The trick is realizing @code{expand} uses +@samp{$1} unquoted, to trigger its expansion using the normal quoting +characters, but uses extra parentheses to group unquoted commas that +occur in the expansion without consuming whitespace following those +commas. Then @code{_expand} uses @code{changequote} to convert the +extra parentheses back into quoting characters. Note that it takes two +more @code{changequote} invocations to restore the original quotes. +Contrast the behavior on whitespace when using @samp{$*}, via +@code{quote}, to attempt the same task. + +@example +changequote(`[', `]')dnl +define([a], [1, (b)])dnl +define([b], [2])dnl +define([quote], [[$*]])dnl +define([expand], [_$0(($1))])dnl +define([_expand], + [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl +expand([a, a, [a, a], [[a, a]]]) +@result{}1, (2), 1, (2), a, a, [a, a] +quote(a, a, [a, a], [[a, a]]) +@result{}1,(2),1,(2),a, a,[a, a] +@end example + +If @var{end} is a prefix of @var{start}, the end-quote will be +recognized in preference to a nested begin-quote. In particular, +changing the quotes to have the same string for @var{start} and +@var{end} disables nesting of quotes. When quote nesting is disabled, +it is impossible to double-quote strings across macro expansions, so +using the same string is not done very often. + +@example +define(`hi', `HI') +@result{} +changequote(`""', `"') +@result{} +""hi"""hi" +@result{}hihi +""hi" ""hi" +@result{}hi hi +""hi"" "hi" +@result{}hi" "HI" +changequote +@result{} +`hi`hi'hi' +@result{}hi`hi'hi +changequote(`"', `"') +@result{} +"hi"hi"hi" +@result{}hiHIhi +@end example + +@ignore +@comment And another stress test, not worth documenting in the manual. +@example +define(`aaaaaaaaaaaaaaaaaaaa', `A')define(`q', `"$@@"') +@result{} +changequote(`"', `"') +@result{} +q(q("aaaaaaaaaaaaaaaaaaaa", "a")) +@result{}A,a +@end example +@end ignore + +It is an error if the end of file occurs within a quoted string. + +@comment status: 1 +@example +`hello world' +@result{}hello world +`dangling quote +^D +@error{}m4:stdin:2: ERROR: end of file in string +@end example + +@comment status: 1 +@example +ifelse(`dangling quote +^D +@error{}m4:stdin:1: ERROR: end of file in string +@end example + +@node Changecom +@section Changing the comment delimiters + +@cindex changing comment delimiters +@cindex comment delimiters, changing +@cindex delimiters, changing +The default comment delimiters can be changed with the builtin +macro @code{changecom}: + +@deffn Builtin changecom (@ovar{start}, @dvar{end, @key{NL}}) +This sets @var{start} as the new begin-comment delimiter and @var{end} +as the new end-comment delimiter. If both arguments are missing, or +@var{start} is void, then comments are disabled. Otherwise, if +@var{end} is missing or void, the default end-comment delimiter of +newline is used. The comment delimiters can be of any length. + +The expansion of @code{changecom} is void. +@end deffn + +@example +define(`comment', `COMMENT') +@result{} +# A normal comment +@result{}# A normal comment +changecom(`/*', `*/') +@result{} +# Not a comment anymore +@result{}# Not a COMMENT anymore +But: /* this is a comment now */ while this is not a comment +@result{}But: /* this is a comment now */ while this is not a COMMENT +@end example + +@cindex comments, copied to output +Note how comments are copied to the output, much as if they were quoted +strings. If you want the text inside a comment expanded, quote the +begin-comment delimiter. + +Calling @code{changecom} without any arguments, or with @var{start} as +the empty string, will effectively disable the commenting mechanism. To +restore the original comment start of @samp{#}, you must explicitly ask +for it. If @var{start} is not empty, then an empty @var{end} will use +the default end-comment delimiter of newline, as otherwise, it would be +impossible to end a comment. However, this is not portable, as some +other @code{m4} implementations preserve the previous non-empty +delimiters instead. + +@example +define(`comment', `COMMENT') +@result{} +changecom +@result{} +# Not a comment anymore +@result{}# Not a COMMENT anymore +changecom(`#', `') +@result{} +# comment again +@result{}# comment again +@end example + +The comment strings can safely contain eight-bit characters. +@ignore +@comment Yuck. I know of no clean way to render an 8-bit character in +@comment both info and dvi. This example uses the `open-guillemot' and +@comment `close-guillemot' characters of the Latin-1 character set. + +@example +define(`a', `b') +@result{} +«a» +@result{}«b» +changecom(`«', `»') +@result{} +«a» +@result{}«a» +@end example +@end ignore +If no single character is appropriate, @var{start} and @var{end} can be +of any length. Other implementations cap the delimiter length to five +characters, but GNU has no inherent limit. + +Comments are recognized in preference to macros. However, this is not +compatible with other implementations, where macros and even quoting +takes precedence over comments, so it may change in a future release. +For portability, this means that @var{start} should not begin with a +letter, digit, or @samp{_} (underscore), and that neither the +start-quote nor the start-comment string should be a prefix of the +other. + +@example +define(`hi', `HI') +@result{} +define(`hi1hi2', `hello') +@result{} +changecom(`q', `Q') +@result{} +q hi Q hi +@result{}q hi Q HI +changecom(`1', `2') +@result{} +hi1hi2 +@result{}hello +hi 1hi2 +@result{}HI 1hi2 +@end example + +Comments are recognized in preference to argument collection. In +particular, if @var{start} is a single @samp{(}, then argument +collection is effectively disabled. For portability with other +implementations, it is a good idea to avoid @samp{(}, @samp{,}, and +@samp{)} as the first character in @var{start}. + +@example +define(`echo', `$#:$*:$@@:') +@result{} +define(`hi', `HI') +@result{} +changecom(`(',`)') +@result{} +echo(hi) +@result{}0:::(hi) +changecom +@result{} +changecom(`((', `))') +@result{} +echo(hi) +@result{}1:HI:HI: +echo((hi)) +@result{}0:::((hi)) +changecom(`,', `)') +@result{} +echo(hi,hi)bye) +@result{}1:HI,hi)bye:HI,hi)bye: +changecom +@result{} +echo(hi,`,`'hi',hi) +@result{}3:HI,,HI,HI:HI,,`'hi,HI: +echo(hi,`,`'hi',hi`'changecom(`,,', `hi')) +@result{}3:HI,,`'hi,HI:HI,,`'hi,HI: +@end example + +It is an error if the end of file occurs within a comment. + +@comment status: 1 +@example +changecom(`/*', `*/') +@result{} +/*dangling comment +^D +@error{}m4:stdin:2: ERROR: end of file in comment +@end example + +@node Changeword +@section Changing the lexical structure of words + +@cindex lexical structure of words +@cindex words, lexical structure of +@cindex syntax, changing +@cindex changing syntax +@cindex regular expressions +@quotation +The macro @code{changeword} and all associated functionality is +experimental. It is only available if the @option{--enable-changeword} +option was given to @command{configure}, at GNU @code{m4} +installation +time. The functionality will go away in the future, to be replaced by +other new features that are more efficient at providing the same +capabilities. @emph{Do not rely on it}. Please direct your comments +about it the same way you would do for bugs. +@end quotation + +A file being processed by @code{m4} is split into quoted strings, words +(potential macro names) and simple tokens (any other single character). +Initially a word is defined by the following regular expression: + +@comment ignore +@example +[_a-zA-Z][_a-zA-Z0-9]* +@end example + +Using @code{changeword}, you can change this regular expression: + +@deffn {Optional builtin} changeword (@var{regex}) +Changes the regular expression for recognizing macro names to be +@var{regex}. If @var{regex} is empty, use +@samp{[_a-zA-Z][_a-zA-Z0-9]*}. @var{regex} must obey the constraint +that every prefix of the desired final pattern is also accepted by the +regular expression. If @var{regex} contains grouping parentheses, the +macro invoked is the portion that matched the first group, rather than +the entire matching string. + +The expansion of @code{changeword} is void. +The macro @code{changeword} is recognized only with parameters. +@end deffn + +Relaxing the lexical rules of @code{m4} might be useful (for example) if +you wanted to apply translations to a file of numbers: + +@example +ifdef(`changeword', `', `errprint(` skipping: no changeword support +')m4exit(`77')')dnl +changeword(`[_a-zA-Z0-9]+') +@result{} +define(`1', `0')1 +@result{}0 +@end example + +Tightening the lexical rules is less useful, because it will generally +make some of the builtins unavailable. You could use it to prevent +accidental call of builtins, for example: + +@example +ifdef(`changeword', `', `errprint(` skipping: no changeword support +')m4exit(`77')')dnl +define(`_indir', defn(`indir')) +@result{} +changeword(`_[_a-zA-Z0-9]*') +@result{} +esyscmd(`foo') +@result{}esyscmd(foo) +_indir(`esyscmd', `echo hi') +@result{}hi +@result{} +@end example + +Because @code{m4} constructs its words a character at a time, there +is a restriction on the regular expressions that may be passed to +@code{changeword}. This is that if your regular expression accepts +@samp{foo}, it must also accept @samp{f} and @samp{fo}. + +@example +ifdef(`changeword', `', `errprint(` skipping: no changeword support +')m4exit(`77')')dnl +define(`foo +', `bar +') +@result{} +dnl This example wants to recognize changeword, dnl, and `foo\n'. +dnl First, we check that our regexp will match. +regexp(`changeword', `[cd][a-z]*\|foo[ +]') +@result{}0 +regexp(`foo +', `[cd][a-z]*\|foo[ +]') +@result{}0 +regexp(`f', `[cd][a-z]*\|foo[ +]') +@result{}-1 +foo +@result{}foo +changeword(`[cd][a-z]*\|foo[ +]') +@result{} +dnl Even though `foo\n' matches, we forgot to allow `f'. +foo +@result{}foo +changeword(`[cd][a-z]*\|fo*[ +]?') +@result{} +dnl Now we can call `foo\n'. +foo +@result{}bar +@end example + +@ignore +@comment One more test of including newline in a macro name; but this +@comment does not need to be displayed in the manual. This ensures +@comment that line numbering is correct when dnl cuts across include +@comment file boundaries, and when __file__ or __line__ is the last +@comment token in an include file. + +@example +ifdef(`changeword', `', `errprint(` skipping: no changeword support +')m4exit(`77')')dnl +define(`bar +', defn(`dnl'))dnl +define(`baz', `dnl +include(`foo') ignored +dnl')dnl +changeword(`\([_a-zA-Z][_a-zA-Z0-9]*\|bar +\)') +@result{} +__file__:__line__ +@result{}stdin:10 +include(`foo') ignored +__file__:__line__ +@result{}stdin:12 +baz ignored +__file__:__line__ +@result{}stdin:14 +define(`bar +', defn(`__file__')) +@result{} +include(`foo') +@result{}examples/foo +define(`bar +', defn(`__line__')) +@result{} +include(`foo') +@result{}1 +__file__:__line__ +@result{}stdin:21 +@end example +@end ignore + +@code{changeword} has another function. If the regular expression +supplied contains any grouped subexpressions, then text outside +the first of these is discarded before symbol lookup. So: + +@example +ifdef(`changeword', `', `errprint(` skipping: no changeword support +')m4exit(`77')')dnl +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +changecom(`/*', `*/')dnl +define(`foo', `bar')dnl +changeword(`#\([_a-zA-Z0-9]*\)') +@result{} +#esyscmd(`echo foo \#foo') +@result{}foo bar +@result{} +@end example + +@code{m4} now requires a @samp{#} mark at the beginning of every +macro invocation, so one can use @code{m4} to preprocess plain +text without losing various words like @samp{divert}. + +In @code{m4}, macro substitution is based on text, while in @TeX{}, it +is based on tokens. @code{changeword} can throw this difference into +relief. For example, here is the same idea represented in @TeX{} and +@code{m4}. First, the @TeX{} version: + +@comment ignore +@example +\def\a@{\message@{Hello@}@} +\catcode`\@@=0 +\catcode`\\=12 +@@a +@@bye +@result{}Hello +@end example + +@noindent +Then, the @code{m4} version: + +@example +ifdef(`changeword', `', `errprint(` skipping: no changeword support +')m4exit(`77')')dnl +define(`a', `errprint(`Hello')')dnl +changeword(`@@\([_a-zA-Z0-9]*\)') +@result{} +@@a +@result{}errprint(Hello) +@end example + +In the @TeX{} example, the first line defines a macro @code{a} to +print the message @samp{Hello}. The second line defines @key{@@} to +be usable instead of @key{\} as an escape character. The third line +defines @key{\} to be a normal printing character, not an escape. +The fourth line invokes the macro @code{a}. So, when @TeX{} is run +on this file, it displays the message @samp{Hello}. + +When the @code{m4} example is passed through @code{m4}, it outputs +@samp{errprint(Hello)}. The reason for this is that @TeX{} does +lexical analysis of macro definition when the macro is @emph{defined}. +@code{m4} just stores the text, postponing the lexical analysis until +the macro is @emph{used}. + +You should note that using @code{changeword} will slow @code{m4} down +by a factor of about seven, once it is changed to something other +than the default regular expression. You can invoke @code{changeword} +with the empty string to restore the default word definition, and regain +the parsing speed. + +@node M4wrap +@section Saving text until end of input + +@cindex saving input +@cindex input, saving +@cindex deferring expansion +@cindex expansion, deferring +It is possible to `save' some text until the end of the normal input has +been seen. Text can be saved, to be read again by @code{m4} when the +normal input has been exhausted. This feature is normally used to +initiate cleanup actions before normal exit, e.g., deleting temporary +files. + +To save input text, use the builtin @code{m4wrap}: + +@deffn Builtin m4wrap (@var{string}, @dots{}) +Stores @var{string} in a safe place, to be reread when end of input is +reached. As a GNU extension, additional arguments are +concatenated with a space to the @var{string}. + +The expansion of @code{m4wrap} is void. +The macro @code{m4wrap} is recognized only with parameters. +@end deffn + +@example +define(`cleanup', `This is the `cleanup' action. +') +@result{} +m4wrap(`cleanup') +@result{} +This is the first and last normal input line. +@result{}This is the first and last normal input line. +^D +@result{}This is the cleanup action. +@end example + +The saved input is only reread when the end of normal input is seen, and +not if @code{m4exit} is used to exit @code{m4}. + +@comment FIXME: this contradicts POSIX, which requires that "If the +@comment m4wrap macro is used multiple times, the arguments specified +@comment shall be processed in the order in which the m4wrap macros were +@comment processed." +It is safe to call @code{m4wrap} from saved text, but then the order in +which the saved text is reread is undefined. If @code{m4wrap} is not used +recursively, the saved pieces of text are reread in the opposite order +in which they were saved (LIFO---last in, first out). However, this +behavior is likely to change in a future release, to match +POSIX, so you should not depend on this order. + +It is possible to emulate POSIX behavior even +with older versions of GNU M4 by including the file +@file{m4-@value{VERSION}/@/examples/@/wrapfifo.m4} from the +distribution: + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`wrapfifo.m4')dnl +@result{}dnl Redefine m4wrap to have FIFO semantics. +@result{}define(`_m4wrap_level', `0')dnl +@result{}define(`m4wrap', +@result{}`ifdef(`m4wrap'_m4wrap_level, +@result{} `define(`m4wrap'_m4wrap_level, +@result{} defn(`m4wrap'_m4wrap_level)`$1')', +@result{} `builtin(`m4wrap', `define(`_m4wrap_level', +@result{} incr(_m4wrap_level))dnl +@result{}m4wrap'_m4wrap_level)dnl +@result{}define(`m4wrap'_m4wrap_level, `$1')')')dnl +include(`wrapfifo.m4') +@result{} +m4wrap(`a`'m4wrap(`c +', `d')')m4wrap(`b') +@result{} +^D +@result{}abc +@end example + +It is likewise possible to emulate LIFO behavior without resorting to +the GNU M4 extension of @code{builtin}, by including the file +@file{m4-@value{VERSION}/@/examples/@/wraplifo.m4} from the +distribution. (Unfortunately, both examples shown here share some +subtle bugs. See if you can find and correct them; or @pxref{Improved +m4wrap, , Answers}). + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`wraplifo.m4')dnl +@result{}dnl Redefine m4wrap to have LIFO semantics. +@result{}define(`_m4wrap_level', `0')dnl +@result{}define(`_m4wrap', defn(`m4wrap'))dnl +@result{}define(`m4wrap', +@result{}`ifdef(`m4wrap'_m4wrap_level, +@result{} `define(`m4wrap'_m4wrap_level, +@result{} `$1'defn(`m4wrap'_m4wrap_level))', +@result{} `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl +@result{}m4wrap'_m4wrap_level)dnl +@result{}define(`m4wrap'_m4wrap_level, `$1')')')dnl +include(`wraplifo.m4') +@result{} +m4wrap(`a`'m4wrap(`c +', `d')')m4wrap(`b') +@result{} +^D +@result{}bac +@end example + +Here is an example of implementing a factorial function using +@code{m4wrap}: + +@example +define(`f', `ifelse(`$1', `0', `Answer: 0!=1 +', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1') +', `m4wrap(`f(decr(`$1'), `$2$1*')')')') +@result{} +f(`10') +@result{} +^D +@result{}Answer: 10*9*8*7*6*5*4*3*2*1=3628800 +@end example + +Invocations of @code{m4wrap} at the same recursion level are +concatenated and rescanned as usual: + +@example +define(`aa', `AA +') +@result{} +m4wrap(`a')m4wrap(`a') +@result{} +^D +@result{}AA +@end example + +@noindent +however, the transition between recursion levels behaves like an end of +file condition between two input files. + +@comment status: 1 +@example +m4wrap(`m4wrap(`)')len(abc') +@result{} +^D +@error{}m4:stdin:1: ERROR: end of file in argument list +@end example + +@node File Inclusion +@chapter File inclusion + +@cindex file inclusion +@cindex inclusion, of files +@code{m4} allows you to include named files at any point in the input. + +@menu +* Include:: Including named files +* Search Path:: Searching for include files +@end menu + +@node Include +@section Including named files + +There are two builtin macros in @code{m4} for including files: + +@deffn Builtin include (@var{file}) +@deffnx Builtin sinclude (@var{file}) +Both macros cause the file named @var{file} to be read by +@code{m4}. When the end of the file is reached, input is resumed from +the previous input file. + +The expansion of @code{include} and @code{sinclude} is therefore the +contents of @var{file}. + +If @var{file} does not exist, is a directory, or cannot otherwise be +read, the expansion is void, +and @code{include} will fail with an error while @code{sinclude} is +silent. The empty string counts as a file that does not exist. + +The macros @code{include} and @code{sinclude} are recognized only with +parameters. +@end deffn + +@comment status: 1 +@example +include(`none') +@error{}m4:stdin:1: cannot open `none': No such file or directory +@result{} +include() +@error{}m4:stdin:2: cannot open `': No such file or directory +@result{} +sinclude(`none') +@result{} +sinclude() +@result{} +@end example + +The rest of this section assumes that @code{m4} is invoked with the +@option{-I} option (@pxref{Preprocessor features, , Invoking m4}) +pointing to the @file{m4-@value{VERSION}/@/examples} +directory shipped as part of the GNU @code{m4} package. The +file @file{m4-@value{VERSION}/@/examples/@/incl.m4} in the distribution +contains the lines: + +@comment ignore +@example +$ @kbd{cat examples/incl.m4} +@result{}Include file start +@result{}foo +@result{}Include file end +@end example + +Normally file inclusion is used to insert the contents of a file +into the input stream. The contents of the file will be read by +@code{m4} and macro calls in the file will be expanded: + +@comment examples +@example +$ @kbd{m4 -I examples} +define(`foo', `FOO') +@result{} +include(`incl.m4') +@result{}Include file start +@result{}FOO +@result{}Include file end +@result{} +@end example + +The fact that @code{include} and @code{sinclude} expand to the contents +of the file can be used to define macros that operate on entire files. +Here is an example, which defines @samp{bar} to expand to the contents +of @file{incl.m4}: + +@comment examples +@example +$ @kbd{m4 -I examples} +define(`bar', include(`incl.m4')) +@result{} +This is `bar': >>bar<< +@result{}This is bar: >>Include file start +@result{}foo +@result{}Include file end +@result{}<< +@end example + +This use of @code{include} is not trivial, though, as files can contain +quotes, commas, and parentheses, which can interfere with the way the +@code{m4} parser works. GNU @code{m4} seamlessly concatenates +the file contents with the next character, even if the included file +ended in the middle of a comment, string, or macro call. These +conditions are only treated as end of file errors if specified as input +files on the command line. + +In GNU @code{m4}, an alternative method of reading files is +using @code{undivert} (@pxref{Undivert}) on a named file. + +@ignore +@comment Test that include(`file/') detects that file is not a +@comment directory; we can assume that the current directory contains a +@comment Makefile. mingw fails with EINVAL rather than ENOTDIR. + +@comment status: 1 +@comment xerr: ignore +@example +include(`Makefile/') +@error{}m4:stdin:1: cannot open `Makefile/': Not a directory +@result{} +@end example + +@comment POSIX allows, but doesn't require, failure on reading +@comment directories. But since they aren't text files, it never makes +@comment sense, so we globally forbid it even if fopen doesn't. mingw +@comment fails with EACCES rather than EISDIR. + +@comment status: 1 +@comment xerr: ignore +@example +include(`.') +@error{}m4:stdin:1: cannot open `.': Is a directory +@result{} +@end example + +@comment Meanwhile, ignore errors with sinclude. + +@example +sinclude(`Makefile/') +@result{} +sinclude(`.') +@result{} +@end example +@end ignore + +@node Search Path +@section Searching for include files + +@cindex search path for included files +@cindex included files, search path for +@cindex GNU extensions +GNU @code{m4} allows included files to be found in other directories +than the current working directory. + +@cindex @env{M4PATH} +If the @option{--prepend-include} or @option{-B} command-line option was +provided (@pxref{Preprocessor features, , Invoking m4}), those +directories are searched first, in reverse order that those options were +listed on the command line. Then @code{m4} looks in the current working +directory. Next comes the directories specified with the +@option{--include} or @option{-I} option, in the order found on the +command line. Finally, if the @env{M4PATH} environment variable is set, +it is expected to contain a colon-separated list of directories, which +will be searched in order. + +If the automatic search for include-files causes trouble, the @samp{p} +debug flag (@pxref{Debug Levels}) can help isolate the problem. + +@node Diversions +@chapter Diverting and undiverting output + +@cindex deferring output +Diversions are a way of temporarily saving output. The output of +@code{m4} can at any time be diverted to a temporary file, and be +reinserted into the output stream, @dfn{undiverted}, again at a later +time. + +@cindex @env{TMPDIR} +Numbered diversions are counted from 0 upwards, diversion number 0 +being the normal output stream. GNU +@code{m4} tries to keep diversions in memory. However, there is a +limit to the overall memory usable by all diversions taken together +(512K, currently). When this maximum is about to be exceeded, +a temporary file is opened to receive the contents of the biggest +diversion still in memory, freeing this memory for other diversions. +When creating the temporary file, @code{m4} honors the value of the +environment variable @env{TMPDIR}, and falls back to @file{/tmp}. +Thus, the amount of available disk space provides the only real limit on +the number and aggregate size of diversions. + +@ignore +@comment We need to test spilled diversions, but don't need to expose +@comment this highly repetitive test in the manual. + +@example +divert(`-1')define(`f', `.') +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +divert`'dnl +len(f) +@result{}1048576 +divert(`1') +f +divert(`2') +f +divert(`-1')undivert +divert(`1')bye +^D +@result{}bye +@end example + +@comment Another test of spilled diversions. + +@example +divert(`-1')define(`f', `.') +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +define(`f', defn(`f')defn(`f')) +divert`'dnl +len(f) +@result{}1048576 +divert(`1') +f +m4exit +@end example + +@comment Catch regression in 1.4.10 with spilled diversions. + +@example +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +changequote(`[', `]')dnl +syscmd([echo 'divert(1)hi +format(%1000000d, 1)' | ']__program__[' | sed -n 1p])dnl +@result{}hi +sysval +@result{}0 +@end example + +@comment Avoid quadratic copying time when transferring diversions; +@comment test both in-memory and spilled to file. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`forloop2.m4')dnl +divert(`1')format(`%10000s', `')dnl +forloop(`i', `1', `10000', + `divert(incr(i))undivert(i)')dnl +divert(`9001')format(`%1000000s', `')dnl +forloop(`i', `9001', `10000', + `divert(incr(i))undivert(i)')dnl +divert(`-1')undivert +@end example +@end ignore + +Diversions make it possible to generate output in a different order than +the input was read. It is possible to implement topological sorting +dependencies. For example, GNU Autoconf makes use of +diversions under the hood to ensure that the expansion of a prerequisite +macro appears in the output prior to the expansion of a dependent macro, +regardless of which order the two macros were invoked in the user's +input file. + +@menu +* Divert:: Diverting output +* Undivert:: Undiverting output +* Divnum:: Diversion numbers +* Cleardivert:: Discarding diverted text +@end menu + +@node Divert +@section Diverting output + +@cindex diverting output to files +@cindex output, diverting to files +@cindex files, diverting output to +Output is diverted using @code{divert}: + +@deffn Builtin divert (@dvar{number, 0}) +The current diversion is changed to @var{number}. If @var{number} is left +out or empty, it is assumed to be zero. If @var{number} cannot be +parsed, the diversion is unchanged. + +The expansion of @code{divert} is void. +@end deffn + +When all the @code{m4} input will have been processed, all existing +diversions are automatically undiverted, in numerical order. + +@example +divert(`1') +This text is diverted. +divert +@result{} +This text is not diverted. +@result{}This text is not diverted. +^D +@result{} +@result{}This text is diverted. +@end example + +Several calls of @code{divert} with the same argument do not overwrite +the previous diverted text, but append to it. Diversions are printed +after any wrapped text is expanded. + +@example +define(`text', `TEXT') +@result{} +divert(`1')`diverted text.' +divert +@result{} +m4wrap(`Wrapped text precedes ') +@result{} +^D +@result{}Wrapped TEXT precedes diverted text. +@end example + +@cindex discarding input +@cindex input, discarding +If output is diverted to a negative diversion, it is simply discarded. +This can be used to suppress unwanted output. A common example of +unwanted output is the trailing newlines after macro definitions. Here +is a common programming idiom in @code{m4} for avoiding them. + +@example +divert(`-1') +define(`foo', `Macro `foo'.') +define(`bar', `Macro `bar'.') +divert +@result{} +@end example + +@cindex GNU extensions +Traditional implementations only supported ten diversions. But as a +GNU extension, diversion numbers can be as large as positive +integers will allow, rather than treating a multi-digit diversion number +as a request to discard text. + +@example +divert(eval(`1<<28'))world +divert(`2')hello +^D +@result{}hello +@result{}world +@end example + +Note that @code{divert} is an English word, but also an active macro +without arguments. When processing plain text, the word might appear in +normal text and be unintentionally swallowed as a macro invocation. One +way to avoid this is to use the @option{-P} option to rename all +builtins (@pxref{Operation modes, , Invoking m4}). Another is to write +a wrapper that requires a parameter to be recognized. + +@example +We decided to divert the stream for irrigation. +@result{}We decided to the stream for irrigation. +define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@@)')') +@result{} +divert(`-1') +Ignored text. +divert(`0') +@result{} +We decided to divert the stream for irrigation. +@result{}We decided to divert the stream for irrigation. +@end example + +@node Undivert +@section Undiverting output + +Diverted text can be undiverted explicitly using the builtin +@code{undivert}: + +@deffn Builtin undivert (@ovar{diversions@dots{}}) +Undiverts the numeric @var{diversions} given by the arguments, in the +order given. If no arguments are supplied, all diversions are +undiverted, in numerical order. + +@cindex file inclusion +@cindex inclusion, of files +@cindex GNU extensions +As a GNU extension, @var{diversions} may contain non-numeric +strings, which are treated as the names of files to copy into the output +without expansion. A warning is issued if a file could not be opened. + +The expansion of @code{undivert} is void. +@end deffn + +@example +divert(`1') +This text is diverted. +divert +@result{} +This text is not diverted. +@result{}This text is not diverted. +undivert(`1') +@result{} +@result{}This text is diverted. +@result{} +@end example + +Notice the last two blank lines. One of them comes from the newline +following @code{undivert}, the other from the newline that followed the +@code{divert}! A diversion often starts with a blank line like this. + +When diverted text is undiverted, it is @emph{not} reread by @code{m4}, +but rather copied directly to the current output, and it is therefore +not an error to undivert into a diversion. Undiverting the empty string +is the same as specifying diversion 0; in either case nothing happens +since the output has already been flushed. + +@example +divert(`1')diverted text +divert +@result{} +undivert() +@result{} +undivert(`0') +@result{} +undivert +@result{}diverted text +@result{} +divert(`1')more +divert(`2')undivert(`1')diverted text`'divert +@result{} +undivert(`1') +@result{} +undivert(`2') +@result{}more +@result{}diverted text +@end example + +When a diversion has been undiverted, the diverted text is discarded, +and it is not possible to bring back diverted text more than once. + +@example +divert(`1') +This text is diverted first. +divert(`0')undivert(`1')dnl +@result{} +@result{}This text is diverted first. +undivert(`1') +@result{} +divert(`1') +This text is also diverted but not appended. +divert(`0')undivert(`1')dnl +@result{} +@result{}This text is also diverted but not appended. +@end example + +Attempts to undivert the current diversion are silently ignored. Thus, +when the current diversion is not 0, the current diversion does not get +rearranged among the other diversions. + +@example +divert(`1')one +divert(`2')two +divert(`3')three +divert(`2')undivert`'dnl +divert`'undivert`'dnl +@result{}two +@result{}one +@result{}three +@end example + +@cindex GNU extensions +@cindex file inclusion +@cindex inclusion, of files +GNU @code{m4} allows named files to be undiverted. Given a +non-numeric argument, the contents of the file named will be copied, +uninterpreted, to the current output. This complements the builtin +@code{include} (@pxref{Include}). To illustrate the difference, assume +the file @file{foo} contains: + +@comment ignore +@example +$ @kbd{cat foo} +bar +@end example + +@noindent +then + +@example +define(`bar', `BAR') +@result{} +undivert(`foo') +@result{}bar +@result{} +include(`foo') +@result{}BAR +@result{} +@end example + +If the file is not found (or cannot be read), an error message is +issued, and the expansion is void. It is possible to intermix files +and diversion numbers. + +@example +divert(`1')diversion one +divert(`2')undivert(`foo')dnl +divert(`3')diversion three +divert`'dnl +undivert(`1', `2', `foo', `3')dnl +@result{}diversion one +@result{}bar +@result{}bar +@result{}diversion three +@end example + +@node Divnum +@section Diversion numbers + +@cindex diversion numbers +The current diversion is tracked by the builtin @code{divnum}: + +@deffn Builtin divnum +Expands to the number of the current diversion. +@end deffn + +@example +Initial divnum +@result{}Initial 0 +divert(`1') +Diversion one: divnum +divert(`2') +Diversion two: divnum +^D +@result{} +@result{}Diversion one: 1 +@result{} +@result{}Diversion two: 2 +@end example + +@node Cleardivert +@section Discarding diverted text + +@cindex discarding diverted text +@cindex diverted text, discarding +Often it is not known, when output is diverted, whether the diverted +text is actually needed. Since all non-empty diversion are brought back +on the main output stream when the end of input is seen, a method of +discarding a diversion is needed. If all diversions should be +discarded, the easiest is to end the input to @code{m4} with +@samp{divert(`-1')} followed by an explicit @samp{undivert}: + +@example +divert(`1') +Diversion one: divnum +divert(`2') +Diversion two: divnum +divert(`-1') +undivert +^D +@end example + +@noindent +No output is produced at all. + +Clearing selected diversions can be done with the following macro: + +@deffn Composite cleardivert (@ovar{diversions@dots{}}) +Discard the contents of each of the listed numeric @var{diversions}. +@end deffn + +@example +define(`cleardivert', +`pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')') +@result{} +@end example + +It is called just like @code{undivert}, but the effect is to clear the +diversions, given by the arguments. (This macro has a nasty bug! You +should try to see if you can find it and correct it; or @pxref{Improved +cleardivert, , Answers}). + +@node Text handling +@chapter Macros for text handling + +There are a number of builtins in @code{m4} for manipulating text in +various ways, extracting substrings, searching, substituting, and so on. + +@menu +* Len:: Calculating length of strings +* Index macro:: Searching for substrings +* Regexp:: Searching for regular expressions +* Substr:: Extracting substrings +* Translit:: Translating characters +* Patsubst:: Substituting text by regular expression +* Format:: Formatting strings (printf-like) +@end menu + +@node Len +@section Calculating length of strings + +@cindex length of strings +@cindex strings, length of +The length of a string can be calculated by @code{len}: + +@deffn Builtin len (@var{string}) +Expands to the length of @var{string}, as a decimal number. + +The macro @code{len} is recognized only with parameters. +@end deffn + +@example +len() +@result{}0 +len(`abcdef') +@result{}6 +@end example + +@node Index macro +@section Searching for substrings + +@cindex substrings, locating +Searching for substrings is done with @code{index}: + +@deffn Builtin index (@var{string}, @var{substring}) +Expands to the index of the first occurrence of @var{substring} in +@var{string}. The first character in @var{string} has index 0. If +@var{substring} does not occur in @var{string}, @code{index} expands to +@samp{-1}. + +The macro @code{index} is recognized only with parameters. +@end deffn + +@example +index(`gnus, gnats, and armadillos', `nat') +@result{}7 +index(`gnus, gnats, and armadillos', `dag') +@result{}-1 +@end example + +Omitting @var{substring} evokes a warning, but still produces output; +contrast this with an empty @var{substring}. + +@example +index(`abc') +@error{}m4:stdin:1: Warning: too few arguments to builtin `index' +@result{}0 +index(`abc', `') +@result{}0 +index(`abc', `b') +@result{}1 +@end example + +@ignore +@comment Expose a bug in the strstr() algorithm present in glibc +@comment 2.9 through 2.12 and in gnulib up to Sep 2010. + +@example +index(`;:11-:12-:12-:12-:12-:12-:12-:12-:12.:12.:12.:12.:12.:12.:12.:12.:12-', +`:12-:12-:12-:12-:12-:12-:12-:12-') +@result{}-1 +@end example + +@comment Expose a bug in the gnulib replacement strstr() algorithm +@comment present from Jun 2010 to Feb 2011, including m4 1.4.15. + +@example +index(`..wi.d.', `.d.') +@result{}4 +@end example +@end ignore + +@node Regexp +@section Searching for regular expressions + +@cindex basic regular expressions +@cindex regular expressions +@cindex expressions, regular +@cindex GNU extensions +Searching for regular expressions is done with the builtin +@code{regexp}: + +@deffn Builtin regexp (@var{string}, @var{regexp}, @ovar{replacement}) +Searches for @var{regexp} in @var{string}. The syntax for regular +expressions is the same as in GNU Emacs, which is similar to +BRE, Basic Regular Expressions in POSIX. +@ifnothtml +@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs +Manual}. +@end ifnothtml +@ifhtml +See +@uref{http://www.gnu.org/@/software/@/emacs/@/manual/@/emacs.html#Regexps, +Syntax of Regular Expressions} in the GNU Emacs Manual. +@end ifhtml +Support for ERE, Extended Regular Expressions is not +available, but will be added in GNU M4 2.0. + +If @var{replacement} is omitted, @code{regexp} expands to the index of +the first match of @var{regexp} in @var{string}. If @var{regexp} does +not match anywhere in @var{string}, it expands to -1. + +If @var{replacement} is supplied, and there was a match, @code{regexp} +changes the expansion to this argument, with @samp{\@var{n}} substituted +by the text matched by the @var{n}th parenthesized sub-expression of +@var{regexp}, up to nine sub-expressions. The escape @samp{\&} is +replaced by the text of the entire regular expression matched. For +all other characters, @samp{\} treats the next character literally. A +warning is issued if there were fewer sub-expressions than the +@samp{\@var{n}} requested, or if there is a trailing @samp{\}. If there +was no match, @code{regexp} expands to the empty string. + +The macro @code{regexp} is recognized only with parameters. +@end deffn + +@example +regexp(`GNUs not Unix', `\<[a-z]\w+') +@result{}5 +regexp(`GNUs not Unix', `\<Q\w*') +@result{}-1 +regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***') +@result{}*** Unix *** nix *** +regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***') +@result{} +@end example + +Here are some more examples on the handling of backslash: + +@example +regexp(`abc', `\(b\)', `\\\10\a') +@result{}\b0a +regexp(`abc', `b', `\1\') +@error{}m4:stdin:2: Warning: sub-expression 1 not present +@error{}m4:stdin:2: Warning: trailing \ ignored in replacement +@result{} +regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6') +@error{}m4:stdin:3: Warning: sub-expression 4 not present +@error{}m4:stdin:3: Warning: sub-expression 5 not present +@error{}m4:stdin:3: Warning: sub-expression 6 not present +@result{}c +@end example + +Omitting @var{regexp} evokes a warning, but still produces output; +contrast this with an empty @var{regexp} argument. + +@example +regexp(`abc') +@error{}m4:stdin:1: Warning: too few arguments to builtin `regexp' +@result{}0 +regexp(`abc', `') +@result{}0 +regexp(`abc', `', `\\def') +@result{}\def +@end example + +@node Substr +@section Extracting substrings + +@cindex extracting substrings +@cindex substrings, extracting +Substrings are extracted with @code{substr}: + +@deffn Builtin substr (@var{string}, @var{from}, @ovar{length}) +Expands to the substring of @var{string}, which starts at index +@var{from}, and extends for @var{length} characters, or to the end of +@var{string}, if @var{length} is omitted. The starting index of a string +is always 0. The expansion is empty if there is an error parsing +@var{from} or @var{length}, if @var{from} is beyond the end of +@var{string}, or if @var{length} is negative. + +The macro @code{substr} is recognized only with parameters. +@end deffn + +@example +substr(`gnus, gnats, and armadillos', `6') +@result{}gnats, and armadillos +substr(`gnus, gnats, and armadillos', `6', `5') +@result{}gnats +@end example + +Omitting @var{from} evokes a warning, but still produces output. + +@example +substr(`abc') +@error{}m4:stdin:1: Warning: too few arguments to builtin `substr' +@result{}abc +substr(`abc',) +@error{}m4:stdin:2: empty string treated as 0 in builtin `substr' +@result{}abc +@end example + +@node Translit +@section Translating characters + +@cindex translating characters +@cindex characters, translating +Character translation is done with @code{translit}: + +@deffn Builtin translit (@var{string}, @var{chars}, @ovar{replacement}) +Expands to @var{string}, with each character that occurs in +@var{chars} translated into the character from @var{replacement} with +the same index. + +If @var{replacement} is shorter than @var{chars}, the excess characters +of @var{chars} are deleted from the expansion; if @var{chars} is +shorter, the excess characters in @var{replacement} are silently +ignored. If @var{replacement} is omitted, all characters in +@var{string} that are present in @var{chars} are deleted from the +expansion. If a character appears more than once in @var{chars}, only +the first instance is used in making the translation. Only a single +translation pass is made, even if characters in @var{replacement} also +appear in @var{chars}. + +As a GNU extension, both @var{chars} and @var{replacement} can +contain character-ranges, e.g., @samp{a-z} (meaning all lowercase +letters) or @samp{0-9} (meaning all digits). To include a dash @samp{-} +in @var{chars} or @var{replacement}, place it first or last in the +entire string, or as the last character of a range. Back-to-back ranges +can share a common endpoint. It is not an error for the last character +in the range to be `larger' than the first. In that case, the range +runs backwards, i.e., @samp{9-0} means the string @samp{9876543210}. +The expansion of a range is dependent on the underlying encoding of +characters, so using ranges is not always portable between machines. + +The macro @code{translit} is recognized only with parameters. +@end deffn + +@example +translit(`GNUs not Unix', `A-Z') +@result{}s not nix +translit(`GNUs not Unix', `a-z', `A-Z') +@result{}GNUS NOT UNIX +translit(`GNUs not Unix', `A-Z', `z-a') +@result{}tmfs not fnix +translit(`+,-12345', `+--1-5', `<;>a-c-a') +@result{}<;>abcba +translit(`abcdef', `aabdef', `bcged') +@result{}bgced +@end example + +In the @sc{ascii} encoding, the first example deletes all uppercase +letters, the second converts lowercase to uppercase, and the third +`mirrors' all uppercase letters, while converting them to lowercase. +The two first cases are by far the most common, even though they are not +portable to @sc{ebcdic} or other encodings. The fourth example shows a +range ending in @samp{-}, as well as back-to-back ranges. The final +example shows that @samp{a} is mapped to @samp{b}, not @samp{c}; the +resulting @samp{b} is not further remapped to @samp{g}; the @samp{d} and +@samp{e} are swapped, and the @samp{f} is discarded. + +@ignore +@comment No need to fight 8-bit characters, as it is difficult to get +@comment rendering right in both info and dvi. + +@example +translit(`«abc~', `~-»') +@result{}abc +@end example + +@comment Stress test short arguments, since they use a different code +@comment path. +@example +translit(`abcdeabcde', `a') +@result{}bcdebcde +translit(`abcdeabcde', `ab') +@result{}cdecde +translit(`abcdeabcde', `a', `f') +@result{}fbcdefbcde +translit(`abcdeabcde', `a', `f') +@result{}fbcdefbcde +translit(`abcdeabcde', `a', `fg') +@result{}fbcdefbcde +translit(`abcdeabcde', `ab', `f') +@result{}fcdefcde +translit(`abcdeabcde', `ab', `fg') +@result{}fgcdefgcde +translit(`abcdeabcde', `ab', `ba') +@result{}bacdebacde +translit(`abcdeabcde', `e', `f') +@result{}abcdfabcdf +translit(`abc', `', `cde') +@result{}abc +translit(`', `a', `bc') +@result{} +@end example +@end ignore + +Omitting @var{chars} evokes a warning, but still produces output. + +@example +translit(`abc') +@error{}m4:stdin:1: Warning: too few arguments to builtin `translit' +@result{}abc +@end example + +@node Patsubst +@section Substituting text by regular expression + +@cindex basic regular expressions +@cindex regular expressions +@cindex expressions, regular +@cindex pattern substitution +@cindex substitution by regular expression +@cindex GNU extensions +Global substitution in a string is done by @code{patsubst}: + +@deffn Builtin patsubst (@var{string}, @var{regexp}, @ovar{replacement}) +Searches @var{string} for matches of @var{regexp}, and substitutes +@var{replacement} for each match. The syntax for regular expressions +is the same as in GNU Emacs (@pxref{Regexp}). + +The parts of @var{string} that are not covered by any match of +@var{regexp} are copied to the expansion. Whenever a match is found, the +search proceeds from the end of the match, so a character from +@var{string} will never be substituted twice. If @var{regexp} matches a +string of zero length, the start position for the search is incremented, +to avoid infinite loops. + +When a replacement is to be made, @var{replacement} is inserted into +the expansion, with @samp{\@var{n}} substituted by the text matched by +the @var{n}th parenthesized sub-expression of @var{patsubst}, for up to +nine sub-expressions. The escape @samp{\&} is replaced by the text of +the entire regular expression matched. For all other characters, +@samp{\} treats the next character literally. A warning is issued if +there were fewer sub-expressions than the @samp{\@var{n}} requested, or +if there is a trailing @samp{\}. + +The @var{replacement} argument can be omitted, in which case the text +matched by @var{regexp} is deleted. + +The macro @code{patsubst} is recognized only with parameters. +@end deffn + +@example +patsubst(`GNUs not Unix', `^', `OBS: ') +@result{}OBS: GNUs not Unix +patsubst(`GNUs not Unix', `\<', `OBS: ') +@result{}OBS: GNUs OBS: not OBS: Unix +patsubst(`GNUs not Unix', `\w*', `(\&)') +@result{}(GNUs)() (not)() (Unix)() +patsubst(`GNUs not Unix', `\w+', `(\&)') +@result{}(GNUs) (not) (Unix) +patsubst(`GNUs not Unix', `[A-Z][a-z]+') +@result{}GN not@w{ } +patsubst(`GNUs not Unix', `not', `NOT\') +@error{}m4:stdin:6: Warning: trailing \ ignored in replacement +@result{}GNUs NOT Unix +@end example + +Here is a slightly more realistic example, which capitalizes individual +words or whole sentences, by substituting calls of the macros +@code{upcase} and @code{downcase} into the strings. + +@deffn Composite upcase (@var{text}) +@deffnx Composite downcase (@var{text}) +@deffnx Composite capitalize (@var{text}) +Expand to @var{text}, but with capitalization changed: @code{upcase} +changes all letters to upper case, @code{downcase} changes all letters +to lower case, and @code{capitalize} changes the first character of each +word to upper case and the remaining characters to lower case. +@end deffn + +First, an example of their usage, using implementations distributed in +@file{m4-@value{VERSION}/@/examples/@/capitalize.m4}. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`capitalize.m4') +@result{} +upcase(`GNUs not Unix') +@result{}GNUS NOT UNIX +downcase(`GNUs not Unix') +@result{}gnus not unix +capitalize(`GNUs not Unix') +@result{}Gnus Not Unix +@end example + +Now for the implementation. There is a helper macro @code{_capitalize} +which puts only its first word in mixed case. Then @code{capitalize} +merely parses out the words, and replaces them with an invocation of +@code{_capitalize}. (As presented here, the @code{capitalize} macro has +some subtle flaws. You should try to see if you can find and correct +them; or @pxref{Improved capitalize, , Answers}). + +@comment examples +@example +$ @kbd{m4 -I examples} +undivert(`capitalize.m4')dnl +@result{}divert(`-1') +@result{}# upcase(text) +@result{}# downcase(text) +@result{}# capitalize(text) +@result{}# change case of text, simple version +@result{}define(`upcase', `translit(`$*', `a-z', `A-Z')') +@result{}define(`downcase', `translit(`$*', `A-Z', `a-z')') +@result{}define(`_capitalize', +@result{} `regexp(`$1', `^\(\w\)\(\w*\)', +@result{} `upcase(`\1')`'downcase(`\2')')') +@result{}define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')') +@result{}divert`'dnl +@end example + +While @code{regexp} replaces the whole input with the replacement as +soon as there is a match, @code{patsubst} replaces each +@emph{occurrence} of a match and preserves non-matching pieces: + +@example +define(`patreg', +`patsubst($@@) +regexp($@@)')dnl +patreg(`bar foo baz Foo', `foo\|Foo', `FOO') +@result{}bar FOO baz FOO +@result{}FOO +patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2') +@result{}bab abb 212 +@result{}bab +@end example + +Omitting @var{regexp} evokes a warning, but still produces output; +contrast this with an empty @var{regexp} argument. + +@example +patsubst(`abc') +@error{}m4:stdin:1: Warning: too few arguments to builtin `patsubst' +@result{}abc +patsubst(`abc', `') +@result{}abc +patsubst(`abc', `', `\\-') +@result{}\-a\-b\-c\- +@end example + +@node Format +@section Formatting strings (printf-like) + +@cindex formatted output +@cindex output, formatted +@cindex GNU extensions +Formatted output can be made with @code{format}: + +@deffn Builtin format (@var{format-string}, @dots{}) +Works much like the C function @code{printf}. The first argument +@var{format-string} can contain @samp{%} specifications which are +satisfied by additional arguments, and the expansion of @code{format} is +the formatted string. + +The macro @code{format} is recognized only with parameters. +@end deffn + +Its use is best described by a few examples: + +@comment This test is a bit fragile, if someone tries to port to a +@comment platform without infinity. +@example +define(`foo', `The brown fox jumped over the lazy dog') +@result{} +format(`The string "%s" uses %d characters', foo, len(foo)) +@result{}The string "The brown fox jumped over the lazy dog" uses 38 characters +format(`%*.*d', `-1', `-1', `1') +@result{}1 +format(`%.0f', `56789.9876') +@result{}56790 +len(format(`%-*X', `5000', `1')) +@result{}5000 +ifelse(format(`%010F', `infinity'), ` INF', `success', + format(`%010F', `infinity'), ` INFINITY', `success', + format(`%010F', `infinity')) +@result{}success +ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success', + format(`%.1A', `1.999'), `0X2.0P+0', `success', + format(`%.1A', `1.999')) +@result{}success +format(`%g', `0xa.P+1') +@result{}20 +@end example + +Using the @code{forloop} macro defined earlier (@pxref{Forloop}), this +example shows how @code{format} can be used to produce tabular output. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`forloop.m4') +@result{} +forloop(`i', `1', `10', `format(`%6d squared is %10d +', i, eval(i**2))') +@result{} 1 squared is 1 +@result{} 2 squared is 4 +@result{} 3 squared is 9 +@result{} 4 squared is 16 +@result{} 5 squared is 25 +@result{} 6 squared is 36 +@result{} 7 squared is 49 +@result{} 8 squared is 64 +@result{} 9 squared is 81 +@result{} 10 squared is 100 +@result{} +@end example + +The builtin @code{format} is modeled after the ANSI C @samp{printf} +function, and supports these @samp{%} specifiers: @samp{c}, @samp{s}, +@samp{d}, @samp{o}, @samp{x}, @samp{X}, @samp{u}, @samp{a}, @samp{A}, +@samp{e}, @samp{E}, @samp{f}, @samp{F}, @samp{g}, @samp{G}, and +@samp{%}; it supports field widths and precisions, and the flags +@samp{+}, @samp{-}, @samp{ }, @samp{0}, @samp{#}, and @samp{'}. For +integer specifiers, the width modifiers @samp{hh}, @samp{h}, and +@samp{l} are recognized, and for floating point specifiers, the width +modifier @samp{l} is recognized. Items not yet supported include +positional arguments, the @samp{n}, @samp{p}, @samp{S}, and @samp{C} +specifiers, the @samp{z}, @samp{t}, @samp{j}, @samp{L} and @samp{ll} +modifiers, and any platform extensions available in the native +@code{printf}. For more details on the functioning of @code{printf}, +see the C Library Manual, or the POSIX specification (for +example, @samp{%a} is supported even on platforms that haven't yet +implemented C99 hexadecimal floating point output natively). + +Unrecognized specifiers result in a warning. It is anticipated that a +future release of GNU @code{m4} will support more specifiers, +and give better warnings when various problems such as overflow are +encountered. Likewise, escape sequences are not yet recognized. + +@example +format(`%p', `0') +@error{}m4:stdin:1: Warning: unrecognized specifier in `%p' +@result{} +@end example + +@ignore +@comment Expose a crash with a bad format string fixed in 1.4.15. +@comment Unfortuntely, 8-bit bytes are hard to check for; but the +@comment exit status is enough to sniff the crash in broken versions. + +@comment xerr: ignore +@example +format(`%'format(`%c', `128')) +@result{} +@end example +@end ignore + +@node Arithmetic +@chapter Macros for doing arithmetic + +@cindex arithmetic +@cindex integer arithmetic +Integer arithmetic is included in @code{m4}, with a C-like syntax. As +convenient shorthands, there are builtins for simple increment and +decrement operations. + +@menu +* Incr:: Decrement and increment operators +* Eval:: Evaluating integer expressions +@end menu + +@node Incr +@section Decrement and increment operators + +@cindex decrement operator +@cindex increment operator +Increment and decrement of integers are supported using the builtins +@code{incr} and @code{decr}: + +@deffn Builtin incr (@var{number}) +@deffnx Builtin decr (@var{number}) +Expand to the numerical value of @var{number}, incremented +or decremented, respectively, by one. Except for the empty string, the +expansion is empty if @var{number} could not be parsed. + +The macros @code{incr} and @code{decr} are recognized only with +parameters. +@end deffn + +@example +incr(`4') +@result{}5 +decr(`7') +@result{}6 +incr() +@error{}m4:stdin:3: empty string treated as 0 in builtin `incr' +@result{}1 +decr() +@error{}m4:stdin:4: empty string treated as 0 in builtin `decr' +@result{}-1 +@end example + +@node Eval +@section Evaluating integer expressions + +@cindex integer expression evaluation +@cindex evaluation, of integer expressions +@cindex expressions, evaluation of integer +Integer expressions are evaluated with @code{eval}: + +@deffn Builtin eval (@var{expression}, @dvar{radix, 10}, @ovar{width}) +Expands to the value of @var{expression}. The expansion is empty +if a problem is encountered while parsing the arguments. If specified, +@var{radix} and @var{width} control the format of the output. + +Calculations are done with 32-bit signed numbers. Overflow silently +results in wraparound. A warning is issued if division by zero is +attempted, or if @var{expression} could not be parsed. + +Expressions can contain the following operators, listed in order of +decreasing precedence. + +@table @samp +@item () +Parentheses +@item + - ~ ! +Unary plus and minus, and bitwise and logical negation +@item ** +Exponentiation +@item * / % +Multiplication, division, and modulo +@item + - +Addition and subtraction +@item << >> +Shift left or right +@item > >= < <= +Relational operators +@item == != +Equality operators +@item & +Bitwise and +@item ^ +Bitwise exclusive-or +@item | +Bitwise or +@item && +Logical and +@item || +Logical or +@end table + +The macro @code{eval} is recognized only with parameters. +@end deffn + +All binary operators, except exponentiation, are left associative. C +operators that perform variable assignment, such as @samp{+=} or +@samp{--}, are not implemented, since @code{eval} only operates on +constants, not variables. Attempting to use them results in an error. +However, since traditional implementations treated @samp{=} as an +undocumented alias for @samp{==} as opposed to an assignment operator, +this usage is supported as a special case. Be aware that a future +version of GNU M4 may support assignment semantics as an +extension when POSIX mode is not requested, and that using +@samp{=} to check equality is not portable. + +@comment status: 1 +@example +eval(`2 = 2') +@error{}m4:stdin:1: Warning: recommend ==, not =, for equality operator +@result{}1 +eval(`++0') +@error{}m4:stdin:2: invalid operator in eval: ++0 +@result{} +eval(`0 |= 1') +@error{}m4:stdin:3: invalid operator in eval: 0 |= 1 +@result{} +@end example + +Note that some older @code{m4} implementations use @samp{^} as an +alternate operator for the exponentiation, although POSIX +requires the C behavior of bitwise exclusive-or. The precedence of the +negation operators, @samp{~} and @samp{!}, was traditionally lower than +equality. The unary operators could not be used reliably more than once +on the same term without intervening parentheses. The traditional +precedence of the equality operators @samp{==} and @samp{!=} was +identical instead of lower than the relational operators such as +@samp{<}, even through GNU M4 1.4.8. Starting with version +1.4.9, GNU M4 correctly follows POSIX precedence +rules. M4 scripts designed to be portable between releases must be +aware that parentheses may be required to enforce C precedence rules. +Likewise, division by zero, even in the unused branch of a +short-circuiting operator, is not always well-defined in other +implementations. + +Following are some examples where the current version of M4 follows C +precedence rules, but where older versions and some other +implementations of @code{m4} require explicit parentheses to get the +correct result: + +@example +eval(`1 == 2 > 0') +@result{}1 +eval(`(1 == 2) > 0') +@result{}0 +eval(`! 0 * 2') +@result{}2 +eval(`! (0 * 2)') +@result{}1 +eval(`1 | 1 ^ 1') +@result{}1 +eval(`(1 | 1) ^ 1') +@result{}0 +eval(`+ + - ~ ! ~ 0') +@result{}1 +eval(`2 || 1 / 0') +@result{}1 +eval(`0 || 1 / 0') +@error{}m4:stdin:9: divide by zero in eval: 0 || 1 / 0 +@result{} +eval(`0 && 1 % 0') +@result{}0 +eval(`2 && 1 % 0') +@error{}m4:stdin:11: modulo by zero in eval: 2 && 1 % 0 +@result{} +@end example + +@cindex GNU extensions +As a GNU extension, the operator @samp{**} performs integral +exponentiation. The operator is right-associative, and if evaluated, +the exponent must be non-negative, and at least one of the arguments +must be non-zero, or a warning is issued. + +@example +eval(`2 ** 3 ** 2') +@result{}512 +eval(`(2 ** 3) ** 2') +@result{}64 +eval(`0 ** 1') +@result{}0 +eval(`2 ** 0') +@result{}1 +eval(`0 ** 0') +@result{} +@error{}m4:stdin:5: divide by zero in eval: 0 ** 0 +eval(`4 ** -2') +@error{}m4:stdin:6: negative exponent in eval: 4 ** -2 +@result{} +@end example + +Within @var{expression}, (but not @var{radix} or @var{width}), numbers +without a special prefix are decimal. A simple @samp{0} prefix +introduces an octal number. @samp{0x} introduces a hexadecimal number. +As GNU extensions, @samp{0b} introduces a binary number. +@samp{0r} introduces a number expressed in any radix between 1 and 36: +the prefix should be immediately followed by the decimal expression of +the radix, a colon, then the digits making the number. For radix 1, +leading zeros are ignored, and all remaining digits must be @samp{1}; +for all other radices, the digits are @samp{0}, @samp{1}, @samp{2}, +@dots{}. Beyond @samp{9}, the digits are @samp{a}, @samp{b} @dots{} up +to @samp{z}. Lower and upper case letters can be used interchangeably +in numbers prefixes and as number digits. + +Parentheses may be used to group subexpressions whenever needed. For the +relational operators, a true relation returns @code{1}, and a false +relation return @code{0}. + +Here are a few examples of use of @code{eval}. + +@example +eval(`-3 * 5') +@result{}-15 +eval(`-99 / 10') +@result{}-9 +eval(`-99 % 10') +@result{}-9 +eval(`99 % -10') +@result{}9 +eval(index(`Hello world', `llo') >= 0) +@result{}1 +eval(`0r1:0111 + 0b100 + 0r3:12') +@result{}12 +define(`square', `eval(`($1) ** 2')') +@result{} +square(`9') +@result{}81 +square(square(`5')` + 1') +@result{}676 +define(`foo', `666') +@result{} +eval(`foo / 6') +@error{}m4:stdin:11: bad expression in eval: foo / 6 +@result{} +eval(foo / 6) +@result{}111 +@end example + +As the last two lines show, @code{eval} does not handle macro +names, even if they expand to a valid expression (or part of a valid +expression). Therefore all macros must be expanded before they are +passed to @code{eval}. + +Some calculations are not portable to other implementations, since they +have undefined semantics in C, but GNU @code{m4} has +well-defined behavior on overflow. When shifting, an out-of-range shift +amount is implicitly brought into the range of 32-bit signed integers +using an implicit bit-wise and with 0x1f). + +@example +define(`max_int', eval(`0x7fffffff')) +@result{} +define(`min_int', incr(max_int)) +@result{} +eval(min_int` < 0') +@result{}1 +eval(max_int` > 0') +@result{}1 +ifelse(eval(min_int` / -1'), min_int, `overflow occurred') +@result{}overflow occurred +min_int +@result{}-2147483648 +eval(`0x80000000 % -1') +@result{}0 +eval(`-4 >> 1') +@result{}-2 +eval(`-4 >> 33') +@result{}-2 +@end example + +If @var{radix} is specified, it specifies the radix to be used in the +expansion. The default radix is 10; this is also the case if +@var{radix} is the empty string. A warning results if the radix is +outside the range of 1 through 36, inclusive. The result of @code{eval} +is always taken to be signed. No radix prefix is output, and for +radices greater than 10, the digits are lower case. The @var{width} +argument specifies the minimum output width, excluding any negative +sign. The result is zero-padded to extend the expansion to the +requested width. A warning results if the width is negative. If +@var{radix} or @var{width} is out of bounds, the expansion of +@code{eval} is empty. + +@example +eval(`666', `10') +@result{}666 +eval(`666', `11') +@result{}556 +eval(`666', `6') +@result{}3030 +eval(`666', `6', `10') +@result{}0000003030 +eval(`-666', `6', `10') +@result{}-0000003030 +eval(`10', `', `0') +@result{}10 +`0r1:'eval(`10', `1', `11') +@result{}0r1:01111111111 +eval(`10', `16') +@result{}a +eval(`1', `37') +@error{}m4:stdin:9: radix 37 in builtin `eval' out of range +@result{} +eval(`1', , `-1') +@error{}m4:stdin:10: negative width to builtin `eval' +@result{} +eval() +@error{}m4:stdin:11: empty string treated as 0 in builtin `eval' +@result{}0 +@end example + +@node Shell commands +@chapter Macros for running shell commands + +@cindex UNIX commands, running +@cindex executing shell commands +@cindex running shell commands +@cindex shell commands, running +@cindex commands, running shell +There are a few builtin macros in @code{m4} that allow you to run shell +commands from within @code{m4}. + +Note that the definition of a valid shell command is system dependent. +On UNIX systems, this is the typical @command{/bin/sh}. But on other +systems, such as native Windows, the shell has a different syntax of +commands that it understands. Some examples in this chapter assume +@command{/bin/sh}, and also demonstrate how to quit early with a known +exit value if this is not the case. + +@menu +* Platform macros:: Determining the platform +* Syscmd:: Executing simple commands +* Esyscmd:: Reading the output of commands +* Sysval:: Exit status +* Mkstemp:: Making temporary files +@end menu + +@node Platform macros +@section Determining the platform + +@cindex platform macros +Sometimes it is desirable for an input file to know which platform +@code{m4} is running on. GNU @code{m4} provides several +macros that are predefined to expand to the empty string; checking for +their existence will confirm platform details. + +@deffn {Optional builtin} __gnu__ +@deffnx {Optional builtin} __os2__ +@deffnx {Optional builtin} os2 +@deffnx {Optional builtin} __unix__ +@deffnx {Optional builtin} unix +@deffnx {Optional builtin} __windows__ +@deffnx {Optional builtin} windows +Each of these macros is conditionally defined as needed to describe the +environment of @code{m4}. If defined, each macro expands to the empty +string. For now, these macros silently ignore all arguments, but in a +future release of M4, they might warn if arguments are present. +@end deffn + +When GNU extensions are in effect (that is, when you did not +use the @option{-G} option, @pxref{Limits control, , Invoking m4}), +GNU @code{m4} will define the macro @code{@w{__gnu__}} to +expand to the empty string. + +@example +$ @kbd{m4} +__gnu__ +@result{} +__gnu__(`ignored') +@result{} +Extensions are ifdef(`__gnu__', `active', `inactive') +@result{}Extensions are active +@end example + +@comment options: -G +@example +$ @kbd{m4 -G} +__gnu__ +@result{}__gnu__ +__gnu__(`ignored') +@result{}__gnu__(ignored) +Extensions are ifdef(`__gnu__', `active', `inactive') +@result{}Extensions are inactive +@end example + +On UNIX systems, GNU @code{m4} will define @code{@w{__unix__}} +by default, or @code{unix} when the @option{-G} option is specified. + +On native Windows systems, GNU @code{m4} will define +@code{@w{__windows__}} by default, or @code{windows} when the +@option{-G} option is specified. + +On OS/2 systems, GNU @code{m4} will define @code{@w{__os2__}} +by default, or @code{os2} when the @option{-G} option is specified. + +If GNU @code{m4} does not provide a platform macro for your system, +please report that as a bug. + +@example +define(`provided', `0') +@result{} +ifdef(`__unix__', `define(`provided', incr(provided))') +@result{} +ifdef(`__windows__', `define(`provided', incr(provided))') +@result{} +ifdef(`__os2__', `define(`provided', incr(provided))') +@result{} +provided +@result{}1 +@end example + +@node Syscmd +@section Executing simple commands + +Any shell command can be executed, using @code{syscmd}: + +@deffn Builtin syscmd (@var{shell-command}) +Executes @var{shell-command} as a shell command. + +The expansion of @code{syscmd} is void, @emph{not} the output from +@var{shell-command}! Output or error messages from @var{shell-command} +are not read by @code{m4}. @xref{Esyscmd}, if you need to process the +command output. + +Prior to executing the command, @code{m4} flushes its buffers. +The default standard input, output and error of @var{shell-command} are +the same as those of @code{m4}. + +By default, the @var{shell-command} will be used as the argument to the +@option{-c} option of the @command{/bin/sh} shell (or the version of +@command{sh} specified by @samp{command -p getconf PATH}, if your system +supports that). If you prefer a different shell, the +@command{configure} script can be given the option +@option{--with-syscmd-shell=@var{location}} to set the location of an +alternative shell at GNU @code{m4} installation; the +alternative shell must still support @option{-c}. + +The macro @code{syscmd} is recognized only with parameters. +@end deffn + +@example +define(`foo', `FOO') +@result{} +syscmd(`echo foo') +@result{}foo +@result{} +@end example + +Note how the expansion of @code{syscmd} keeps the trailing newline of +the command, as well as using the newline that appeared after the macro. + +The following is an example of @var{shell-command} using the same +standard input as @code{m4}: + +@comment ignore +@example +$ @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4} +@result{} +@end example + +@ignore +@comment If the user types the example below with stdin being an +@comment interactive terminal, then cat will hang waiting for additional +@comment input after m4 has exited. But the testsuite is using a pipe +@comment for stdin. Hence, we have two versions - the one we feed the +@comment testsuite below, and the one we display to the user above that +@comment more accurately shows what the testsuite is really doing but +@comment which the testsuite cannot parse. + +@example +m4wrap(`syscmd(`cat')') +@result{} +^D +@end example +@end ignore + +It tells @code{m4} to read all of its input before executing the wrapped +text, then hand a valid (albeit emptied) pipe as standard input for the +@code{cat} subcommand. Therefore, you should be careful when using +standard input (either by specifying no files, or by passing @samp{-} as +a file name on the command line, @pxref{Command line files, , Invoking +m4}), and also invoking subcommands via @code{syscmd} or @code{esyscmd} +that consume data from standard input. When standard input is a +seekable file, the subprocess will pick up with the next character not +yet processed by @code{m4}; when it is a pipe or other non-seekable +file, there is no guarantee how much data will already be buffered by +@code{m4} and thus unavailable to the child. + +@node Esyscmd +@section Reading the output of commands + +@cindex GNU extensions +If you want @code{m4} to read the output of a shell command, use +@code{esyscmd}: + +@deffn Builtin esyscmd (@var{shell-command}) +Expands to the standard output of the shell command +@var{shell-command}. + +Prior to executing the command, @code{m4} flushes its buffers. +The default standard input and standard error of @var{shell-command} are +the same as those of @code{m4}. The error output of @var{shell-command} +is not a part of the expansion: it will appear along with the error +output of @code{m4}. + +By default, the @var{shell-command} will be used as the argument to the +@option{-c} option of the @command{/bin/sh} shell (or the version of +@command{sh} specified by @samp{command -p getconf PATH}, if your system +supports that). If you prefer a different shell, the +@command{configure} script can be given the option +@option{--with-syscmd-shell=@var{location}} to set the location of an +alternative shell at GNU @code{m4} installation; the +alternative shell must still support @option{-c}. + +The macro @code{esyscmd} is recognized only with parameters. +@end deffn + +@example +define(`foo', `FOO') +@result{} +esyscmd(`echo foo') +@result{}FOO +@result{} +@end example + +Note how the expansion of @code{esyscmd} keeps the trailing newline of +the command, as well as using the newline that appeared after the macro. + +Just as with @code{syscmd}, care must be exercised when sharing standard +input between @code{m4} and the child process of @code{esyscmd}. + +@node Sysval +@section Exit status + +@cindex UNIX commands, exit status from +@cindex exit status from shell commands +@cindex shell commands, exit status from +@cindex commands, exit status from shell +@cindex status of shell commands +To see whether a shell command succeeded, use @code{sysval}: + +@deffn Builtin sysval +Expands to the exit status of the last shell command run with +@code{syscmd} or @code{esyscmd}. Expands to 0 if no command has been +run yet. +@end deffn + +@example +sysval +@result{}0 +syscmd(`false') +@result{} +ifelse(sysval, `0', `zero', `non-zero') +@result{}non-zero +syscmd(`exit 2') +@result{} +sysval +@result{}2 +syscmd(`true') +@result{} +sysval +@result{}0 +esyscmd(`false') +@result{} +ifelse(sysval, `0', `zero', `non-zero') +@result{}non-zero +esyscmd(`echo dnl && exit 127') +@result{} +sysval +@result{}127 +esyscmd(`true') +@result{} +sysval +@result{}0 +@end example + +@code{sysval} results in 127 if there was a problem executing the +command, for example, if the system-imposed argument length is exceeded, +or if there were not enough resources to fork. It is not possible to +distinguish between failed execution and successful execution that had +an exit status of 127, unless there was output from the child process. + +On UNIX platforms, where it is possible to detect when command execution +is terminated by a signal, rather than a normal exit, the result is the +signal number shifted left by eight bits. + +@comment This test has difficulties being portable, even on platforms +@comment where syscmd invokes /bin/sh. Kill is not portable with signal +@comment names. According to autoconf, the only portable signal numbers +@comment are 1 (HUP), 2 (INT), 9 (KILL), 13 (PIPE) and 15 (TERM). But +@comment all shells handle SIGINT, and ksh handles HUP (as in, the shell +@comment exits normally rather than letting the signal terminate it). +@comment Also, TERM is flaky, as it can also kill the running m4 on +@comment systems where /bin/sh does not create its own process group. +@comment And PIPE is unreliable, since people tend to run with it +@comment ignored, with m4 inheriting that choice. That leaves KILL as +@comment the only signal we can reliably test. +@example +dnl This test assumes kill is a shell builtin, and that signals are +dnl recognizable. +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +syscmd(`kill -9 $$') +@result{} +sysval +@result{}2304 +syscmd() +@result{} +sysval +@result{}0 +esyscmd(`kill -9 $$') +@result{} +sysval +@result{}2304 +@end example + +@node Mkstemp +@section Making temporary files + +@cindex temporary file names +@cindex files, names of temporary +Commands specified to @code{syscmd} or @code{esyscmd} might need a +temporary file, for output or for some other purpose. There is a +builtin macro, @code{mkstemp}, for making a temporary file: + +@deffn Builtin mkstemp (@var{template}) +@deffnx Builtin maketemp (@var{template}) +Expands to the quoted name of a new, empty file, made from the string +@var{template}, which should end with the string @samp{XXXXXX}. The six +@samp{X} characters are then replaced with random characters matching +the regular expression @samp{[a-zA-Z0-9._-]}, in order to make the file +name unique. If fewer than six @samp{X} characters are found at the end +of @code{template}, the result will be longer than the template. The +created file will have access permissions as if by @kbd{chmod =rw,go=}, +meaning that the current umask of the @code{m4} process is taken into +account, and at most only the current user can read and write the file. + +The traditional behavior, standardized by POSIX, is that +@code{maketemp} merely replaces the trailing @samp{X} with the process +id, without creating a file or quoting the expansion, and without +ensuring that the resulting +string is a unique file name. In part, this means that using the same +@var{template} twice in the same input file will result in the same +expansion. This behavior is a security hole, as it is very easy for +another process to guess the name that will be generated, and thus +interfere with a subsequent use of @code{syscmd} trying to manipulate +that file name. Hence, POSIX has recommended that all new +implementations of @code{m4} provide the secure @code{mkstemp} builtin, +and that users of @code{m4} check for its existence. + +The expansion is void and an error issued if a temporary file could +not be created. + +The macros @code{mkstemp} and @code{maketemp} are recognized only with +parameters. +@end deffn + +If you try this next example, you will most likely get different output +for the two file names, since the replacement characters are randomly +chosen: + +@comment ignore +@example +$ @kbd{m4} +define(`tmp', `oops') +@result{} +maketemp(`/tmp/fooXXXXXX') +@result{}/tmp/fooa07346 +ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))', + `define(`mkstemp', defn(`maketemp'))dnl +errprint(`warning: potentially insecure maketemp implementation +')') +@result{} +mkstemp(`doc') +@result{}docQv83Uw +@end example + +@cindex GNU extensions +Unless you use the @option{--traditional} command line option (or +@option{-G}, @pxref{Limits control, , Invoking m4}), the GNU +version of @code{maketemp} is secure. This means that using the same +template to multiple calls will generate multiple files. However, we +recommend that you use the new @code{mkstemp} macro, introduced in +GNU M4 1.4.8, which is secure even in traditional mode. Also, +as of M4 1.4.11, the secure implementation quotes the resulting file +name, so that you are guaranteed to know what file was created even if +the random file name happens to match an existing macro. Notice that +this example is careful to use @code{defn} to avoid unintended expansion +of @samp{foo}. + +@example +$ @kbd{m4} +define(`foo', `errprint(`oops')') +@result{} +syscmd(`rm -f foo-??????')sysval +@result{}0 +define(`file1', maketemp(`foo-XXXXXX'))dnl +ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ', + `no file', `created') +@result{}created +define(`file2', maketemp(`foo-XX'))dnl +define(`file3', mkstemp(`foo-XXXXXX'))dnl +ifelse(len(defn(`file1')), len(defn(`file2')), + `same length', `different') +@result{}same length +ifelse(defn(`file1'), defn(`file2'), `same', `different file') +@result{}different file +ifelse(defn(`file2'), defn(`file3'), `same', `different file') +@result{}different file +ifelse(defn(`file1'), defn(`file3'), `same', `different file') +@result{}different file +syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3')) +@result{} +sysval +@result{}0 +@end example + +@ignore +@c Not worth documenting, but make sure we don't leave trailing NUL in +@c the expansion. + +@example +syscmd(`rm -rf foodir')sysval +@result{}0 +syscmd(`mkdir foodir')sysval +@result{}0 +len(mkstemp(`foodir/fooXXXXX')) +@result{}16 +syscmd(`rm -r foodir')sysval +@result{}0 +@end example + +@c Likewise, and ensure that traditional mode leaves the result unquoted +@c without creating a file. + +@comment options: -G +@example +syscmd(`rm -f foo-*')sysval +@result{}0 +len(maketemp(`foo-XXXXX')) +@error{}m4:stdin:2: recommend using mkstemp instead +@result{}9 +define(`abc', `def') +@result{} +maketemp(`foo-abc') +@result{}foo-def +@error{}m4:stdin:4: recommend using mkstemp instead +syscmd(`test -f foo-*')ifelse(sysval, `0', `0', `1') +@result{}1 +@end example +@end ignore + +@node Miscellaneous +@chapter Miscellaneous builtin macros + +This chapter describes various builtins, that do not really belong in +any of the previous chapters. + +@menu +* Errprint:: Printing error messages +* Location:: Printing current location +* M4exit:: Exiting from @code{m4} +@end menu + +@node Errprint +@section Printing error messages + +@cindex printing error messages +@cindex error messages, printing +@cindex messages, printing error +@cindex standard error, output to +You can print error messages using @code{errprint}: + +@deffn Builtin errprint (@var{message}, @dots{}) +Prints @var{message} and the rest of the arguments to standard error, +separated by spaces. Standard error is used, regardless of the +@option{--debugfile} option (@pxref{Debugging options, , Invoking m4}). + +The expansion of @code{errprint} is void. +The macro @code{errprint} is recognized only with parameters. +@end deffn + +@example +errprint(`Invalid arguments to forloop +') +@error{}Invalid arguments to forloop +@result{} +errprint(`1')errprint(`2',`3 +') +@error{}12 3 +@result{} +@end example + +A trailing newline is @emph{not} printed automatically, so it should be +supplied as part of the argument, as in the example. Unfortunately, the +exact output of @code{errprint} is not very portable to other @code{m4} +implementations: POSIX requires that all arguments be printed, +but some implementations of @code{m4} only print the first. +Furthermore, some BSD implementations always append a newline +for each @code{errprint} call, regardless of whether the last argument +already had one, and POSIX is silent on whether this is +acceptable. + +@node Location +@section Printing current location + +@cindex location, input +@cindex input location +To make it possible to specify the location of an error, three +utility builtins exist: + +@deffn Builtin __file__ +@deffnx Builtin __line__ +@deffnx Builtin __program__ +Expand to the quoted name of the current input file, the +current input line number in that file, and the quoted name of the +current invocation of @code{m4}. +@end deffn + +@example +errprint(__program__:__file__:__line__: `input error +') +@error{}m4:stdin:1: input error +@result{} +@end example + +Line numbers start at 1 for each file. If the file was found due to the +@option{-I} option or @env{M4PATH} environment variable, that is +reflected in the file name. The syncline option (@option{-s}, +@pxref{Preprocessor features, , Invoking m4}), and the +@samp{f} and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}), +also use this notion of current file and line. Redefining the three +location macros has no effect on syncline, debug, warning, or error +message output. + +This example reuses the file @file{incl.m4} mentioned earlier +(@pxref{Include}): + +@comment examples +@example +$ @kbd{m4 -I examples} +define(`foo', ``$0' called at __file__:__line__') +@result{} +foo +@result{}foo called at stdin:2 +include(`incl.m4') +@result{}Include file start +@result{}foo called at examples/incl.m4:2 +@result{}Include file end +@result{} +@end example + +The location of macros invoked during the rescanning of macro expansion +text corresponds to the location in the file where the expansion was +triggered, regardless of how many newline characters the expansion text +contains. As of GNU M4 1.4.8, the location of text wrapped +with @code{m4wrap} (@pxref{M4wrap}) is the point at which the +@code{m4wrap} was invoked. Previous versions, however, behaved as +though wrapped text came from line 0 of the file ``''. + +@example +define(`echo', `$@@') +@result{} +define(`foo', `echo(__line__ +__line__)') +@result{} +echo(__line__ +__line__) +@result{}4 +@result{}5 +m4wrap(`foo +') +@result{} +foo(errprint(__line__ +__line__ +)) +@error{}8 +@error{}9 +@result{}8 +@result{}8 +__line__ +@result{}11 +m4wrap(`__line__ +') +@result{} +^D +@result{}12 +@result{}6 +@result{}6 +@end example + +The @code{@w{__program__}} macro behaves like @samp{$0} in shell +terminology. If you invoke @code{m4} through an absolute path or a link +with a different spelling, rather than by relying on a @env{PATH} search +for plain @samp{m4}, it will affect how @code{@w{__program__}} expands. +The intent is that you can use it to produce error messages with the +same formatting that @code{m4} produces internally. It can also be used +within @code{syscmd} (@pxref{Syscmd}) to pick the same version of +@code{m4} that is currently running, rather than whatever version of +@code{m4} happens to be first in @env{PATH}. It was first introduced in +GNU M4 1.4.6. + +@node M4exit +@section Exiting from @code{m4} + +@cindex exiting from @code{m4} +@cindex status, setting @code{m4} exit +If you need to exit from @code{m4} before the entire input has been +read, you can use @code{m4exit}: + +@deffn Builtin m4exit (@dvar{code, 0}) +Causes @code{m4} to exit, with exit status @var{code}. If @var{code} is +left out, the exit status is zero. If @var{code} cannot be parsed, or +is outside the range of 0 to 255, the exit status is one. No further +input is read, and all wrapped and diverted text is discarded. +@end deffn + +@example +m4wrap(`This text is lost due to `m4exit'.') +@result{} +divert(`1') So is this. +divert +@result{} +m4exit And this is never read. +@end example + +A common use of this is to abort processing: + +@deffn Composite fatal_error (@var{message}) +Abort processing with an error message and non-zero status. Prefix +@var{message} with details about where the error occurred, and print the +resulting string to standard error. +@end deffn + +@comment status: 1 +@example +define(`fatal_error', + `errprint(__program__:__file__:__line__`: fatal error: $* +')m4exit(`1')') +@result{} +fatal_error(`this is a BAD one, buster') +@error{}m4:stdin:4: fatal error: this is a BAD one, buster +@end example + +After this macro call, @code{m4} will exit with exit status 1. This macro +is only intended for error exits, since the normal exit procedures are +not followed, i.e., diverted text is not undiverted, and saved text +(@pxref{M4wrap}) is not reread. (This macro could be made more robust +to earlier versions of @code{m4}. You should try to see if you can find +weaknesses and correct them; or @pxref{Improved fatal_error, , Answers}). + +Note that it is still possible for the exit status to be different than +what was requested by @code{m4exit}. If @code{m4} detects some other +error, such as a write error on standard output, the exit status will be +non-zero even if @code{m4exit} requested zero. + +If standard input is seekable, then the file will be positioned at the +next unread character. If it is a pipe or other non-seekable file, +then there are no guarantees how much data @code{m4} might have read +into buffers, and thus discarded. + +@node Frozen files +@chapter Fast loading of frozen state + +Some bigger @code{m4} applications may be built over a common base +containing hundreds of definitions and other costly initializations. +Usually, the common base is kept in one or more declarative files, +which files are listed on each @code{m4} invocation prior to the +user's input file, or else each input file uses @code{include}. + +Reading the common base of a big application, over and over again, may +be time consuming. GNU @code{m4} offers some machinery to +speed up the start of an application using lengthy common bases. + +@menu +* Using frozen files:: Using frozen files +* Frozen file format:: Frozen file format +@end menu + +@node Using frozen files +@section Using frozen files + +@cindex fast loading of frozen files +@cindex frozen files for fast loading +@cindex initialization, frozen state +@cindex dumping into frozen file +@cindex reloading a frozen file +@cindex GNU extensions +Suppose a user has a library of @code{m4} initializations in +@file{base.m4}, which is then used with multiple input files: + +@comment ignore +@example +$ @kbd{m4 base.m4 input1.m4} +$ @kbd{m4 base.m4 input2.m4} +$ @kbd{m4 base.m4 input3.m4} +@end example + +Rather than spending time parsing the fixed contents of @file{base.m4} +every time, the user might rather execute: + +@comment ignore +@example +$ @kbd{m4 -F base.m4f base.m4} +@end example + +@noindent +once, and further execute, as often as needed: + +@comment ignore +@example +$ @kbd{m4 -R base.m4f input1.m4} +$ @kbd{m4 -R base.m4f input2.m4} +$ @kbd{m4 -R base.m4f input3.m4} +@end example + +@noindent +with the varying input. The first call, containing the @option{-F} +option, only reads and executes file @file{base.m4}, defining +various application macros and computing other initializations. +Once the input file @file{base.m4} has been completely processed, GNU +@code{m4} produces in @file{base.m4f} a @dfn{frozen} file, that is, a +file which contains a kind of snapshot of the @code{m4} internal state. + +Later calls, containing the @option{-R} option, are able to reload +the internal state of @code{m4}, from @file{base.m4f}, +@emph{prior} to reading any other input files. This means +instead of starting with a virgin copy of @code{m4}, input will be +read after having effectively recovered the effect of a prior run. +In our example, the effect is the same as if file @file{base.m4} has +been read anew. However, this effect is achieved a lot faster. + +Only one frozen file may be created or read in any one @code{m4} +invocation. It is not possible to recover two frozen files at once. +However, frozen files may be updated incrementally, through using +@option{-R} and @option{-F} options simultaneously. For example, if +some care is taken, the command: + +@comment ignore +@example +$ @kbd{m4 file1.m4 file2.m4 file3.m4 file4.m4} +@end example + +@noindent +could be broken down in the following sequence, accumulating the same +output: + +@comment ignore +@example +$ @kbd{m4 -F file1.m4f file1.m4} +$ @kbd{m4 -R file1.m4f -F file2.m4f file2.m4} +$ @kbd{m4 -R file2.m4f -F file3.m4f file3.m4} +$ @kbd{m4 -R file3.m4f file4.m4} +@end example + +Some care is necessary because not every effort has been made for +this to work in all cases. In particular, the trace attribute of +macros is not handled, nor the current setting of @code{changeword}. +Currently, @code{m4wrap} and @code{sysval} also have problems. +Also, interactions for some options of @code{m4}, being used in one call +and not in the next, have not been fully analyzed yet. On the other +end, you may be confident that stacks of @code{pushdef} definitions +are handled correctly, as well as undefined or renamed builtins, and +changed strings for quotes or comments. And future releases of +GNU M4 will improve on the utility of frozen files. + +@ignore +@c This example is not worth putting in the manual, but caused core +@c dumps in all versions prior to 1.4.11. + +@comment options: -F /dev/null +@example +traceon(`undefined')dnl +@end example + +@c Make sure freezing is successful. + +@example +ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics +')m4exit(`77')')dnl +changequote(`[', `]')dnl +syscmd([echo 'changequote([,])pushdef([divnum],[hi])dnl' \ + | ']__program__[' -F in.m4f \ + && echo 'divnum popdef([divnum])divnum' \ + | ']__program__[' -R in.m4f \ + && rm in.m4f])status sysval +@result{}hi 0 +@result{}status 0 +@end example + +@c Detect inability to freeze. +@c Some systems harden /, and fail with EACCES rather than ENOENT. + +@comment options: -F /none/such +@comment xerr: ignore +@comment status: 1 +@example +$ @kbd{m4 -F /none/such} +^D +@error{}m4: cannot open `/none/such': No such file or directory +@end example +@end ignore + +When an @code{m4} run is to be frozen, the automatic undiversion +which takes place at end of execution is inhibited. Instead, all +positively numbered diversions are saved into the frozen file. +The active diversion number is also transmitted. + +A frozen file to be reloaded need not reside in the current directory. +It is looked up the same way as an @code{include} file (@pxref{Search +Path}). + +If the frozen file was generated with a newer version of @code{m4}, and +contains directives that an older @code{m4} cannot parse, attempting to +load the frozen file with option @option{-R} will cause @code{m4} to +exit with status 63 to indicate version mismatch. + +@node Frozen file format +@section Frozen file format + +@cindex frozen file format +@cindex file format, frozen file +Frozen files are sharable across architectures. It is safe to write +a frozen file on one machine and read it on another, given that the +second machine uses the same or newer version of GNU @code{m4}. +It is conventional, but not required, to give a frozen file the suffix +of @code{.m4f}. + +These are simple (editable) text files, made up of directives, +each starting with a capital letter and ending with a newline +(@key{NL}). Wherever a directive is expected, the character +@samp{#} introduces a comment line; empty lines are also ignored if they +are not part of an embedded string. +In the following descriptions, each @var{len} refers to the length of +the corresponding strings @var{str} in the next line of input. Numbers +are always expressed in decimal. There are no escape characters. The +directives are: + +@table @code +@item C @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL} +Uses @var{str1} and @var{str2} as the begin-comment and +end-comment strings. If omitted, then @samp{#} and @key{NL} are the +comment delimiters. + +@item D @var{number}, @var{len} @key{NL} @var{str} @key{NL} +Selects diversion @var{number}, making it current, then copy +@var{str} in the current diversion. @var{number} may be a negative +number for a non-existing diversion. To merely specify an active +selection, use this command with an empty @var{str}. With 0 as the +diversion @var{number}, @var{str} will be issued on standard output +at reload time. GNU @code{m4} will not produce the @samp{D} +directive with non-zero length for diversion 0, but this can be done +with manual edits. This directive may +appear more than once for the same diversion, in which case the +diversion is the concatenation of the various uses. If omitted, then +diversion 0 is current. + +@item F @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL} +Defines, through @code{pushdef}, a definition for @var{str1} +expanding to the function whose builtin name is @var{str2}. If the +builtin does not exist (for example, if the frozen file was produced by +a copy of @code{m4} compiled with changeword support, but the version +of @code{m4} reloading was compiled without it), the reload is silent, +but any subsequent use of the definition of @var{str1} will result in +a warning. This directive may appear more than once for the same name, +and its order, along with @samp{T}, is important. If omitted, you will +have no access to any builtins. + +@item Q @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL} +Uses @var{str1} and @var{str2} as the begin-quote and end-quote +strings. If omitted, then @samp{`} and @samp{'} are the quote +delimiters. + +@item T @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL} +Defines, though @code{pushdef}, a definition for @var{str1} +expanding to the text given by @var{str2}. This directive may appear +more than once for the same name, and its order, along with @samp{F}, is +important. + +@item V @var{number} @key{NL} +Confirms the format of the file. @code{m4} @value{VERSION} only creates +and understands frozen files where @var{number} is 1. This directive +must be the first non-comment in the file, and may not appear more than +once. +@end table + +@node Compatibility +@chapter Compatibility with other versions of @code{m4} + +@cindex compatibility +This chapter describes the many of the differences between this +implementation of @code{m4}, and of other implementations found under +UNIX, such as System V Release 3, Solaris, and BSD flavors. +In particular, it lists the known differences and extensions to +POSIX. However, the list is not necessarily comprehensive. + +At the time of this writing, POSIX 2001 (also known as IEEE +Std 1003.1-2001) is the latest standard, although a new version of +POSIX is under development and includes several proposals for +modifying what @code{m4} is required to do. The requirements for +@code{m4} are shared between SUSv3 and POSIX, and +can be viewed at +@uref{http://www.opengroup.org/onlinepubs/@/000095399/@/utilities/@/m4.html}. + +@menu +* Extensions:: Extensions in GNU M4 +* Incompatibilities:: Facilities in System V m4 not in GNU M4 +* Other Incompatibilities:: Other incompatibilities +@end menu + +@node Extensions +@section Extensions in GNU M4 + +@cindex GNU extensions +@cindex POSIX +This version of @code{m4} contains a few facilities that do not exist +in System V @code{m4}. These extra facilities are all suppressed by +using the @option{-G} command line option (@pxref{Limits control, , +Invoking m4}), unless overridden by other command line options. + +@itemize @bullet +@item +In the @code{$@var{n}} notation for macro arguments, @var{n} can contain +several digits, while the System V @code{m4} only accepts one digit. +This allows macros in GNU @code{m4} to take any number of +arguments, and not only nine (@pxref{Arguments}). + +This means that @code{define(`foo', `$11')} is ambiguous between +implementations. To portably choose between grabbing the first +parameter and appending 1 to the expansion, or grabbing the eleventh +parameter, you can do the following: + +@example +define(`a1', `A1') +@result{} +dnl First argument, concatenated with 1 +define(`_1', `$1')define(`first1', `_1($@@)1') +@result{} +dnl Eleventh argument, portable +define(`_9', `$9')define(`eleventh', `_9(shift(shift($@@)))') +@result{} +dnl Eleventh argument, GNU style +define(`Eleventh', `$11') +@result{} +first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') +@result{}A1 +eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') +@result{}k +Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') +@result{}k +@end example + +@noindent +Also see the @code{argn} macro (@pxref{Shift}). + +@item +The @code{divert} (@pxref{Divert}) macro can manage more than 9 +diversions. GNU @code{m4} treats all positive numbers as valid +diversions, rather than discarding diversions greater than 9. + +@item +Files included with @code{include} and @code{sinclude} are sought in a +user specified search path, if they are not found in the working +directory. The search path is specified by the @option{-I} option and the +@env{M4PATH} environment variable (@pxref{Search Path}). + +@item +Arguments to @code{undivert} can be non-numeric, in which case the named +file will be included uninterpreted in the output (@pxref{Undivert}). + +@item +Formatted output is supported through the @code{format} builtin, which +is modeled after the C library function @code{printf} (@pxref{Format}). + +@item +Searches and text substitution through basic regular expressions are +supported by the @code{regexp} (@pxref{Regexp}) and @code{patsubst} +(@pxref{Patsubst}) builtins. Some BSD implementations use +extended regular expressions instead. + +@item +The output of shell commands can be read into @code{m4} with +@code{esyscmd} (@pxref{Esyscmd}). + +@item +There is indirect access to any builtin macro with @code{builtin} +(@pxref{Builtin}). + +@item +Macros can be called indirectly through @code{indir} (@pxref{Indir}). + +@item +The name of the program, the current input file, and the current input +line number are accessible through the builtins @code{@w{__program__}}, +@code{@w{__file__}}, and @code{@w{__line__}} (@pxref{Location}). + +@item +The format of the output from @code{dumpdef} and macro tracing can be +controlled with @code{debugmode} (@pxref{Debug Levels}). + +@item +The destination of trace and debug output can be controlled with +@code{debugfile} (@pxref{Debug Output}). + +@item +The @code{maketemp} (@pxref{Mkstemp}) macro behaves like @code{mkstemp}, +creating a new file with a unique name on every invocation, rather than +following the insecure behavior of replacing the trailing @samp{X} +characters with the @code{m4} process id. + +@item +POSIX only requires support for the command line options +@option{-s}, @option{-D}, and @option{-U}, so all other options accepted +by GNU M4 are extensions. @xref{Invoking m4}, for a +description of these options. + +The debugging and tracing facilities in GNU @code{m4} are much +more extensive than in most other versions of @code{m4}. +@end itemize + +@node Incompatibilities +@section Facilities in System V @code{m4} not in GNU @code{m4} + +The version of @code{m4} from System V contains a few facilities that +have not been implemented in GNU @code{m4} yet. Additionally, +POSIX requires some behaviors that GNU @code{m4} has not +implemented yet. Relying on these behaviors is non-portable, as a +future release of GNU @code{m4} may change. + +@itemize @bullet +@item +POSIX requires support for multiple arguments to @code{defn}, +without any clarification on how @code{defn} behaves when one of the +multiple arguments names a builtin. System V @code{m4} and some other +implementations allow mixing builtins and text macros into a single +macro. GNU @code{m4} only supports joining multiple text +arguments, although a future implementation may lift this restriction to +behave more like System V@. The only portable way to join text macros +with builtins is via helper macros and implicit concatenation of macro +results. + +@item +POSIX requires an application to exit with non-zero status if +it wrote an error message to stderr. This has not yet been consistently +implemented for the various builtins that are required to issue an error +(such as @code{eval} (@pxref{Eval}) when an argument cannot be parsed). + +@item +Some traditional implementations only allow reading standard input +once, but GNU @code{m4} correctly handles multiple instances +of @samp{-} on the command line. + +@item +POSIX requires @code{m4wrap} (@pxref{M4wrap}) to act in FIFO +(first-in, first-out) order, but GNU @code{m4} currently uses +LIFO order. Furthermore, POSIX states that only the first +argument to @code{m4wrap} is saved for later evaluation, but +GNU @code{m4} saves and processes all arguments, with output +separated by spaces. + +@item +POSIX states that builtins that require arguments, but are +called without arguments, have undefined behavior. Traditional +implementations simply behave as though empty strings had been passed. +For example, @code{a`'define`'b} would expand to @code{ab}. But +GNU @code{m4} ignores certain builtins if they have missing +arguments, giving @code{adefineb} for the above example. + +@item +Traditional implementations handle @code{define(`f',`1')} (@pxref{Define}) +by undefining the entire stack of previous definitions, and if doing +@code{undefine(`f')} first. GNU @code{m4} replaces just the top +definition on the stack, as if doing @code{popdef(`f')} followed by +@code{pushdef(`f',`1')}. POSIX allows either behavior. + +@item +POSIX 2001 requires @code{syscmd} (@pxref{Syscmd}) to evaluate +command output for macro expansion, but this was a mistake that is +anticipated to be corrected in the next version of POSIX. +GNU @code{m4} follows traditional behavior in @code{syscmd} +where output is not rescanned, and provides the extension @code{esyscmd} +that does scan the output. + +@item +At one point, POSIX required @code{changequote(@var{arg})} +(@pxref{Changequote}) to use newline as the close quote, but this was a +bug, and the next version of POSIX is anticipated to state +that using empty strings or just one argument is unspecified. +Meanwhile, the GNU @code{m4} behavior of treating an empty +end-quote delimiter as @samp{'} is not portable, as Solaris treats it as +repeating the start-quote delimiter, and BSD treats it as leaving the +previous end-quote delimiter unchanged. For predictable results, never +call changequote with just one argument, or with empty strings for +arguments. + +@item +At one point, POSIX required @code{changecom(@var{arg},)} +(@pxref{Changecom}) to make it impossible to end a comment, but this is +a bug, and the next version of POSIX is anticipated to state +that using empty strings is unspecified. Meanwhile, the GNU +@code{m4} behavior of treating an empty end-comment delimiter as newline +is not portable, as BSD treats it as leaving the previous end-comment +delimiter unchanged. It is also impossible in BSD implementations to +disable comments, even though that is required by POSIX. For +predictable results, never call changecom with empty strings for +arguments. + +@item +Most implementations of @code{m4} give macros a higher precedence than +comments when parsing, meaning that if the start delimiter given to +@code{changecom} (@pxref{Changecom}) starts with a macro name, comments +are effectively disabled. POSIX does not specify what the +precedence is, so this version of GNU @code{m4} parser +recognizes comments, then macros, then quoted strings. + +@item +Traditional implementations allow argument collection, but not string +and comment processing, to span file boundaries. Thus, if @file{a.m4} +contains @samp{len(}, and @file{b.m4} contains @samp{abc)}, +@kbd{m4 a.m4 b.m4} outputs @samp{3} with traditional @code{m4}, but +gives an error message that the end of file was encountered inside a +macro with GNU @code{m4}. On the other hand, traditional +implementations do end of file processing for files included with +@code{include} or @code{sinclude} (@pxref{Include}), while GNU +@code{m4} seamlessly integrates the content of those files. Thus +@code{include(`a.m4')include(`b.m4')} will output @samp{3} instead of +giving an error. + +@item +Traditional @code{m4} treats @code{traceon} (@pxref{Trace}) without +arguments as a global variable, independent of named macro tracing. +Also, once a macro is undefined, named tracing of that macro is lost. +On the other hand, when GNU @code{m4} encounters +@code{traceon} without +arguments, it turns tracing on for all existing definitions at the time, +but does not trace future definitions; @code{traceoff} without arguments +turns tracing off for all definitions regardless of whether they were +also traced by name; and tracing by name, such as with @option{-tfoo} at +the command line or @code{traceon(`foo')} in the input, is an attribute +that is preserved even if the macro is currently undefined. + +Additionally, while POSIX requires trace output, it makes no +demands on the formatting of that output. Parsing trace output is not +guaranteed to be reliable, even between different releases of +GNU M4; however, the intent is that any future changes in +trace output will only occur under the direction of additional +@code{debugmode} flags (@pxref{Debug Levels}). + +@item +POSIX requires @code{eval} (@pxref{Eval}) to treat all +operators with the same precedence as C@. However, earlier versions of +GNU @code{m4} followed the traditional behavior of other +@code{m4} implementations, where bitwise and logical negation (@samp{~} +and @samp{!}) have lower precedence than equality operators; and where +equality operators (@samp{==} and @samp{!=}) had the same precedence as +relational operators (such as @samp{<}). Use explicit parentheses to +ensure proper precedence. As extensions to POSIX, +GNU @code{m4} gives well-defined semantics to operations that +C leaves undefined, such as when overflow occurs, when shifting negative +numbers, or when performing division by zero. POSIX also +requires @samp{=} to cause an error, but many traditional +implementations allowed it as an alias for @samp{==}. + +@item +POSIX 2001 requires @code{translit} (@pxref{Translit}) to +treat each character of the second and third arguments literally. +However, it is anticipated that the next version of POSIX will +allow the GNU @code{m4} behavior of treating @samp{-} as a +range operator. + +@item +POSIX requires @code{m4} to honor the locale environment +variables of @env{LANG}, @env{LC_ALL}, @env{LC_CTYPE}, +@env{LC_MESSAGES}, and @env{NLSPATH}, but this has not yet been +implemented in GNU @code{m4}. + +@item +POSIX states that only unquoted leading newlines and blanks +(that is, space and tab) are ignored when collecting macro arguments. +However, this appears to be a bug in POSIX, since most +traditional implementations also ignore all whitespace (formfeed, +carriage return, and vertical tab). GNU @code{m4} follows +tradition and ignores all leading unquoted whitespace. + +@item +@cindex @env{POSIXLY_CORRECT} +A strictly-compliant POSIX client is not allowed to use +command-line arguments not specified by POSIX. However, since +this version of M4 ignores @env{POSIXLY_CORRECT} and enables the option +@code{--gnu} by default (@pxref{Limits control, , Invoking m4}), a +client desiring to be strictly compliant has no way to disable +GNU extensions that conflict with POSIX when +directly invoking the compiled @code{m4}. A future version of +@code{GNU} M4 will honor the environment variable @env{POSIXLY_CORRECT}, +implicitly enabling @option{--traditional} if it is set, in order to +allow a strictly-compliant client. In the meantime, a client needing +strict POSIX compliance can use the workaround of invoking a +shell script wrapper, where the wrapper then adds @option{--traditional} +to the arguments passed to the compiled @code{m4}. +@end itemize + +@node Other Incompatibilities +@section Other incompatibilities + +There are a few other incompatibilities between this implementation of +@code{m4}, and the System V version. + +@itemize @bullet +@item +GNU @code{m4} implements sync lines differently from System V +@code{m4}, when text is being diverted. GNU @code{m4} outputs +the sync lines when the text is being diverted, and System V @code{m4} +when the diverted text is being brought back. + +The problem is which lines and file names should be attached to text +that is being, or has been, diverted. System V @code{m4} regards all +the diverted text as being generated by the source line containing the +@code{undivert} call, whereas GNU @code{m4} regards the +diverted text as being generated at the time it is diverted. + +The sync line option is used mostly when using @code{m4} as +a front end to a compiler. If a diverted line causes a compiler error, +the error messages should most probably refer to the place where the +diversion was made, and not where it was inserted again. + +@comment options: -s +@example +divert(2)2 +divert(1)1 +divert`'0 +@result{}#line 3 "stdin" +@result{}0 +^D +@result{}#line 2 "stdin" +@result{}1 +@result{}#line 1 "stdin" +@result{}2 +@end example + +The current @code{m4} implementation has a limitation that the syncline +output at the start of each diversion occurs no matter what, even if the +previous diversion did not end with a newline. This goes contrary to +the claim that synclines appear on a line by themselves, so this +limitation may be corrected in a future version of @code{m4}. In the +meantime, when using @option{-s}, it is wisest to make sure all +diversions end with newline. + +@item +GNU @code{m4} makes no attempt at prohibiting self-referential +definitions like: + +@example +define(`x', `x') +@result{} +define(`x', `x ') +@result{} +@end example + +@cindex rescanning +There is nothing inherently wrong with defining @samp{x} to +return @samp{x}. The wrong thing is to expand @samp{x} unquoted, +because that would cause an infinite rescan loop. +In @code{m4}, one might use macros to hold strings, as we do for +variables in other programming languages, further checking them with: + +@comment ignore +@example +ifelse(defn(`@var{holder}'), `@var{value}', @dots{}) +@end example + +@noindent +In cases like this one, an interdiction for a macro to hold its own name +would be a useless limitation. Of course, this leaves more rope for the +GNU @code{m4} user to hang himself! Rescanning hangs may be +avoided through careful programming, a little like for endless loops in +traditional programming languages. +@end itemize + +@node Answers +@chapter Correct version of some examples + +Some of the examples in this manuals are buggy or not very robust, for +demonstration purposes. Improved versions of these composite macros are +presented here. + +@menu +* Improved exch:: Solution for @code{exch} +* Improved forloop:: Solution for @code{forloop} +* Improved foreach:: Solution for @code{foreach} +* Improved copy:: Solution for @code{copy} +* Improved m4wrap:: Solution for @code{m4wrap} +* Improved cleardivert:: Solution for @code{cleardivert} +* Improved capitalize:: Solution for @code{capitalize} +* Improved fatal_error:: Solution for @code{fatal_error} +@end menu + +@node Improved exch +@section Solution for @code{exch} + +The @code{exch} macro (@pxref{Arguments}) as presented requires clients +to double quote their arguments. A nicer definition, which lets +clients follow the rule of thumb of one level of quoting per level of +parentheses, involves adding quotes in the definition of @code{exch}, as +follows: + +@example +define(`exch', ``$2', `$1'') +@result{} +define(exch(`expansion text', `macro')) +@result{} +macro +@result{}expansion text +@end example + +@node Improved forloop +@section Solution for @code{forloop} + +The @code{forloop} macro (@pxref{Forloop}) as presented earlier can go +into an infinite loop if given an iterator that is not parsed as a macro +name. It does not do any sanity checking on its numeric bounds, and +only permits decimal numbers for bounds. Here is an improved version, +shipped as @file{m4-@value{VERSION}/@/examples/@/forloop2.m4}; this +version also optimizes overhead by calling four macros instead of six +per iteration (excluding those in @var{text}), by not dereferencing the +@var{iterator} in the helper @code{@w{_forloop}}. + +@comment examples +@example +$ @kbd{m4 -d -I examples} +undivert(`forloop2.m4')dnl +@result{}divert(`-1') +@result{}# forloop(var, from, to, stmt) - improved version: +@result{}# works even if VAR is not a strict macro name +@result{}# performs sanity check that FROM is larger than TO +@result{}# allows complex numerical expressions in TO and FROM +@result{}define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1', +@result{} `pushdef(`$1')_$0(`$1', eval(`$2'), +@result{} eval(`$3'), `$4')popdef(`$1')')') +@result{}define(`_forloop', +@result{} `define(`$1', `$2')$4`'ifelse(`$2', `$3', `', +@result{} `$0(`$1', incr(`$2'), `$3', `$4')')') +@result{}divert`'dnl +include(`forloop2.m4') +@result{} +forloop(`i', `2', `1', `no iteration occurs') +@result{} +forloop(`', `1', `2', ` odd iterator name') +@result{} odd iterator name odd iterator name +forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')') +@result{} 0xa 0xb 0xc +forloop(`i', `a', `b', `non-numeric bounds') +@error{}m4:stdin:6: bad expression in eval (bad input): (a) <= (b) +@result{} +@end example + +One other change to notice is that the improved version used @samp{_$0} +rather than @samp{_foreach} to invoke the helper routine. In general, +this is a good practice to follow, because then the set of macros can be +uniformly transformed. The following example shows a transformation +that doubles the current quoting and appends a suffix @samp{2} to each +transformed macro. If @code{foreach} refers to the literal +@samp{_foreach}, then @code{foreach2} invokes @code{_foreach} instead of +the intended @code{_foreach2}, and the mixing of quoting paradigms leads +to an infinite recursion loop in this example. + +@comment options: -L9 +@comment status: 1 +@comment examples +@example +$ @kbd{m4 -d -L 9 -I examples} +define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4') +@result{} +define(`double', `define(`$1'`2', + arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))') +@result{} +double(`forloop')double(`_forloop')defn(`forloop2') +@result{}ifelse(eval(``($2) <= ($3)''), ``1'', +@result{} ``pushdef(``$1'')_$0(``$1'', eval(``$2''), +@result{} eval(``$3''), ``$4'')popdef(``$1'')'') +forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)') +@result{} +changequote(`[', `]')changequote([``], ['']) +@result{} +forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'') +@result{} +changequote`'include(`forloop.m4') +@result{} +double(`forloop')double(`_forloop')defn(`forloop2') +@result{}pushdef(``$1'', ``$2'')_forloop($@@)popdef(``$1'') +forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)') +@result{} +changequote(`[', `]')changequote([``], ['']) +@result{} +forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'') +@error{}m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it +@end example + +One more optimization is still possible. Instead of repeatedly +assigning a variable then invoking or dereferencing it, it is possible +to pass the current iterator value as a single argument. Coupled with +@code{curry} if other arguments are needed (@pxref{Composition}), or +with helper macros if the argument is needed in more than one place in +the expansion, the output can be generated with three, rather than four, +macros of overhead per iteration. Notice how the file +@file{m4-@value{VERSION}/@/examples/@/forloop3.m4} rearranges the +arguments of the helper @code{_forloop} to take two arguments that are +placed around the current value. By splitting a balanced set of +parantheses across multiple arguments, the helper macro can now be +shared by @code{forloop} and the new @code{forloop_arg}. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`forloop3.m4') +@result{} +undivert(`forloop3.m4')dnl +@result{}divert(`-1') +@result{}# forloop_arg(from, to, macro) - invoke MACRO(value) for +@result{}# each value between FROM and TO, without define overhead +@result{}define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1', +@result{} `_forloop(`$1', eval(`$2'), `$3(', `)')')') +@result{}# forloop(var, from, to, stmt) - refactored to share code +@result{}define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1', +@result{} `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'), +@result{} `define(`$1',', `)$4')popdef(`$1')')') +@result{}define(`_forloop', +@result{} `$3`$1'$4`'ifelse(`$1', `$2', `', +@result{} `$0(incr(`$1'), `$2', `$3', `$4')')') +@result{}divert`'dnl +forloop(`i', `1', `3', ` i') +@result{} 1 2 3 +define(`echo', `$@@') +@result{} +forloop_arg(`1', `3', ` echo') +@result{} 1 2 3 +include(`curry.m4') +@result{} +forloop_arg(`1', `3', `curry(`pushdef', `a')') +@result{} +a +@result{}3 +popdef(`a')a +@result{}2 +popdef(`a')a +@result{}1 +popdef(`a')a +@result{}a +@end example + +Of course, it is possible to make even more improvements, such as +adding an optional step argument, or allowing iteration through +descending sequences. GNU Autoconf provides some of these +additional bells and whistles in its @code{m4_for} macro. + +@node Improved foreach +@section Solution for @code{foreach} + +The @code{foreach} and @code{foreachq} macros (@pxref{Foreach}) as +presented earlier each have flaws. First, we will examine and fix the +quadratic behavior of @code{foreachq}: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreachq.m4') +@result{} +traceon(`shift')debugmode(`aq') +@result{} +foreachq(`x', ``1', `2', `3', `4'', `x +')dnl +@result{}1 +@error{}m4trace: -3- shift(`1', `2', `3', `4') +@error{}m4trace: -2- shift(`1', `2', `3', `4') +@result{}2 +@error{}m4trace: -4- shift(`1', `2', `3', `4') +@error{}m4trace: -3- shift(`2', `3', `4') +@error{}m4trace: -3- shift(`1', `2', `3', `4') +@error{}m4trace: -2- shift(`2', `3', `4') +@result{}3 +@error{}m4trace: -5- shift(`1', `2', `3', `4') +@error{}m4trace: -4- shift(`2', `3', `4') +@error{}m4trace: -3- shift(`3', `4') +@error{}m4trace: -4- shift(`1', `2', `3', `4') +@error{}m4trace: -3- shift(`2', `3', `4') +@error{}m4trace: -2- shift(`3', `4') +@result{}4 +@error{}m4trace: -6- shift(`1', `2', `3', `4') +@error{}m4trace: -5- shift(`2', `3', `4') +@error{}m4trace: -4- shift(`3', `4') +@error{}m4trace: -3- shift(`4') +@end example + +@cindex quadratic behavior, avoiding +@cindex avoiding quadratic behavior +Each successive iteration was adding more quoted @code{shift} +invocations, and the entire list contents were passing through every +iteration. In general, when recursing, it is a good idea to make the +recursion use fewer arguments, rather than adding additional quoted +uses of @code{shift}. By doing so, @code{m4} uses less memory, invokes +fewer macros, is less likely to run into machine limits, and most +importantly, performs faster. The fixed version of @code{foreachq} can +be found in @file{m4-@value{VERSION}/@/examples/@/foreachq2.m4}: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreachq2.m4') +@result{} +undivert(`foreachq2.m4')dnl +@result{}include(`quote.m4')dnl +@result{}divert(`-1') +@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt) +@result{}# quoted list, improved version +@result{}define(`foreachq', `pushdef(`$1')_$0($@@)popdef(`$1')') +@result{}define(`_arg1q', ``$1'') +@result{}define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@@))')') +@result{}define(`_foreachq', `ifelse(`$2', `', `', +@result{} `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')') +@result{}divert`'dnl +traceon(`shift')debugmode(`aq') +@result{} +foreachq(`x', ``1', `2', `3', `4'', `x +')dnl +@result{}1 +@error{}m4trace: -3- shift(`1', `2', `3', `4') +@result{}2 +@error{}m4trace: -3- shift(`2', `3', `4') +@result{}3 +@error{}m4trace: -3- shift(`3', `4') +@result{}4 +@end example + +Note that the fixed version calls unquoted helper macros in +@code{@w{_foreachq}} to trim elements immediately; those helper macros +in turn must re-supply the layer of quotes lost in the macro invocation. +Contrast the use of @code{@w{_arg1q}}, which quotes the first list +element, with @code{@w{_arg1}} of the earlier implementation that +returned the first list element directly. Additionally, by calling the +helper method immediately, the @samp{defn(`@var{iterator}')} no longer +contains unexpanded macros. + +The astute m4 programmer might notice that the solution above still uses +more memory and macro invocations, and thus more time, than strictly +necessary. Note that @samp{$2}, which contains an arbitrarily long +quoted list, is expanded and rescanned three times per iteration of +@code{_foreachq}. Furthermore, every iteration of the algorithm +effectively unboxes then reboxes the list, which costs a couple of macro +invocations. It is possible to rewrite the algorithm for a bit more +speed by swapping the order of the arguments to @code{_foreachq} in +order to operate on an unboxed list in the first place, and by using the +fixed-length @samp{$#} instead of an arbitrary length list as the key to +end recursion. The result is an overhead of six macro invocations per +loop (excluding any macros in @var{text}), instead of eight. This +alternative approach is available as +@file{m4-@value{VERSION}/@/examples/@/foreach3.m4}: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreachq3.m4') +@result{} +undivert(`foreachq3.m4')dnl +@result{}divert(`-1') +@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt) +@result{}# quoted list, alternate improved version +@result{}define(`foreachq', `ifelse(`$2', `', `', +@result{} `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')') +@result{}define(`_foreachq', `ifelse(`$#', `3', `', +@result{} `define(`$1', `$4')$2`'$0(`$1', `$2', +@result{} shift(shift(shift($@@))))')') +@result{}divert`'dnl +traceon(`shift')debugmode(`aq') +@result{} +foreachq(`x', ``1', `2', `3', `4'', `x +')dnl +@result{}1 +@error{}m4trace: -4- shift(`x', `x +@error{}', `', `1', `2', `3', `4') +@error{}m4trace: -3- shift(`x +@error{}', `', `1', `2', `3', `4') +@error{}m4trace: -2- shift(`', `1', `2', `3', `4') +@result{}2 +@error{}m4trace: -4- shift(`x', `x +@error{}', `1', `2', `3', `4') +@error{}m4trace: -3- shift(`x +@error{}', `1', `2', `3', `4') +@error{}m4trace: -2- shift(`1', `2', `3', `4') +@result{}3 +@error{}m4trace: -4- shift(`x', `x +@error{}', `2', `3', `4') +@error{}m4trace: -3- shift(`x +@error{}', `2', `3', `4') +@error{}m4trace: -2- shift(`2', `3', `4') +@result{}4 +@error{}m4trace: -4- shift(`x', `x +@error{}', `3', `4') +@error{}m4trace: -3- shift(`x +@error{}', `3', `4') +@error{}m4trace: -2- shift(`3', `4') +@end example + +In the current version of M4, every instance of @samp{$@@} is rescanned +as it is encountered. Thus, the @file{foreachq3.m4} alternative uses +much less memory than @file{foreachq2.m4}, and executes as much as 10% +faster, since each iteration encounters fewer @samp{$@@}. However, the +implementation of rescanning every byte in @samp{$@@} is quadratic in +the number of bytes scanned (for example, making the broken version in +@file{foreachq.m4} cubic, rather than quadratic, in behavior). A future +release of M4 will improve the underlying implementation by reusing +results of previous scans, so that both styles of @code{foreachq} can +become linear in the number of bytes scanned. Notice how the +implementation injects an empty argument prior to expanding @samp{$2} +within @code{foreachq}; the helper macro @code{_foreachq} then ignores +the third argument altogether, and ends recursion when there are three +arguments left because there was nothing left to pass through +@code{shift}. Thus, each iteration only needs one @code{ifelse}, rather +than the two conditionals used in the version from @file{foreachq2.m4}. + +@cindex nine arguments, more than +@cindex more than nine arguments +@cindex arguments, more than nine +So far, all of the implementations of @code{foreachq} presented have +been quadratic with M4 1.4.x. But @code{forloop} is linear, because +each iteration parses a constant amount of arguments. So, it is +possible to design a variant that uses @code{forloop} to do the +iteration, then uses @samp{$@@} only once at the end, giving a linear +result even with older M4 implementations. This implementation relies +on the GNU extension that @samp{$10} expands to the tenth +argument rather than the first argument concatenated with @samp{0}. The +trick is to define an intermediate macro that repeats the text +@code{m4_define(`$1', `$@var{n}')$2`'}, with @samp{n} set to successive +integers corresponding to each argument. The helper macro +@code{_foreachq_} is needed in order to generate the literal sequences +such as @samp{$1} into the intermediate macro, rather than expanding +them as the arguments of @code{_foreachq}. With this approach, no +@code{shift} calls are even needed! Even though there are seven macros +of overhead per iteration instead of six in @file{foreachq3.m4}, the +linear scaling is apparent at relatively small list sizes. However, +this approach will need adjustment when a future version of M4 follows +POSIX by no longer treating @samp{$10} as the tenth argument; +the anticipation is that @samp{$@{10@}} can be used instead, although +that alternative syntax is not yet supported. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreachq4.m4') +@result{} +undivert(`foreachq4.m4')dnl +@result{}include(`forloop2.m4')dnl +@result{}divert(`-1') +@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt) +@result{}# quoted list, version based on forloop +@result{}define(`foreachq', +@result{}`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')') +@result{}define(`_foreachq', +@result{}`pushdef(`$1', forloop(`$1', `3', `$#', +@result{} `$0_(`1', `2', indir(`$1'))')`popdef( +@result{} `$1')')indir(`$1', $@@)') +@result{}define(`_foreachq_', +@result{}``define(`$$1', `$$3')$$2`''') +@result{}divert`'dnl +traceon(`shift')debugmode(`aq') +@result{} +foreachq(`x', ``1', `2', `3', `4'', `x +')dnl +@result{}1 +@result{}2 +@result{}3 +@result{}4 +@end example + +For yet another approach, the improved version of @code{foreach}, +available in @file{m4-@value{VERSION}/@/examples/@/foreach2.m4}, simply +overquotes the arguments to @code{@w{_foreach}} to begin with, using +@code{dquote_elt}. Then @code{@w{_foreach}} can just use +@code{@w{_arg1}} to remove the extra layer of quoting that was added up +front: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreach2.m4') +@result{} +undivert(`foreach2.m4')dnl +@result{}include(`quote.m4')dnl +@result{}divert(`-1') +@result{}# foreach(x, (item_1, item_2, ..., item_n), stmt) +@result{}# parenthesized list, improved version +@result{}define(`foreach', `pushdef(`$1')_$0(`$1', +@result{} (dquote(dquote_elt$2)), `$3')popdef(`$1')') +@result{}define(`_arg1', `$1') +@result{}define(`_foreach', `ifelse(`$2', `(`')', `', +@result{} `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')') +@result{}divert`'dnl +traceon(`shift')debugmode(`aq') +@result{} +foreach(`x', `(`1', `2', `3', `4')', `x +')dnl +@error{}m4trace: -4- shift(`1', `2', `3', `4') +@error{}m4trace: -4- shift(`2', `3', `4') +@error{}m4trace: -4- shift(`3', `4') +@result{}1 +@error{}m4trace: -3- shift(``1'', ``2'', ``3'', ``4'') +@result{}2 +@error{}m4trace: -3- shift(``2'', ``3'', ``4'') +@result{}3 +@error{}m4trace: -3- shift(``3'', ``4'') +@result{}4 +@error{}m4trace: -3- shift(``4'') +@end example + +It is likewise possible to write a variant of @code{foreach} that +performs in linear time on M4 1.4.x; the easiest method is probably +writing a version of @code{foreach} that unboxes its list, then invokes +@code{_foreachq} as previously defined in @file{foreachq4.m4}. + +In summary, recursion over list elements is trickier than it appeared at +first glance, but provides a powerful idiom within @code{m4} processing. +As a final demonstration, both list styles are now able to handle +several scenarios that would wreak havoc on one or both of the original +implementations. This points out one other difference between the +list styles. @code{foreach} evaluates unquoted list elements only once, +in preparation for calling @code{@w{_foreach}}, similary for +@code{foreachq} as provided by @file{foreachq3.m4} or +@file{foreachq4.m4}. But +@code{foreachq}, as provided by @file{foreachq2.m4}, +evaluates unquoted list elements twice while visiting the first list +element, once in @code{@w{_arg1q}} and once in @code{@w{_rest}}. When +deciding which list style to use, one must take into account whether +repeating the side effects of unquoted list elements will have any +detrimental effects. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`foreach2.m4') +@result{} +include(`foreachq2.m4') +@result{} +dnl 0-element list: +foreach(`x', `', `<x>') / foreachq(`x', `', `<x>') +@result{} /@w{ } +dnl 1-element list of empty element +foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>') +@result{}<> / <> +dnl 2-element list of empty elements +foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>') +@result{}<><> / <><> +dnl 1-element list of a comma +foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>') +@result{}<,> / <,> +dnl 2-element list of unbalanced parentheses +foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>') +@result{}<(><)> / <(><)> +define(`ab', `oops')dnl using defn(`iterator') +foreach(`x', `(`a', `b')', `defn(`x')') /dnl + foreachq(`x', ``a', `b'', `defn(`x')') +@result{}ab / ab +define(`active', `ACT, IVE') +@result{} +traceon(`active') +@result{} +dnl list of unquoted macros; expansion occurs before recursion +foreach(`x', `(active, active)', `<x> +')dnl +@error{}m4trace: -4- active -> `ACT, IVE' +@error{}m4trace: -4- active -> `ACT, IVE' +@result{}<ACT> +@result{}<IVE> +@result{}<ACT> +@result{}<IVE> +foreachq(`x', `active, active', `<x> +')dnl +@error{}m4trace: -3- active -> `ACT, IVE' +@error{}m4trace: -3- active -> `ACT, IVE' +@result{}<ACT> +@error{}m4trace: -3- active -> `ACT, IVE' +@error{}m4trace: -3- active -> `ACT, IVE' +@result{}<IVE> +@result{}<ACT> +@result{}<IVE> +dnl list of quoted macros; expansion occurs during recursion +foreach(`x', `(`active', `active')', `<x> +')dnl +@error{}m4trace: -1- active -> `ACT, IVE' +@result{}<ACT, IVE> +@error{}m4trace: -1- active -> `ACT, IVE' +@result{}<ACT, IVE> +foreachq(`x', ``active', `active'', `<x> +')dnl +@error{}m4trace: -1- active -> `ACT, IVE' +@result{}<ACT, IVE> +@error{}m4trace: -1- active -> `ACT, IVE' +@result{}<ACT, IVE> +dnl list of double-quoted macro names; no expansion +foreach(`x', `(``active'', ``active'')', `<x> +')dnl +@result{}<active> +@result{}<active> +foreachq(`x', ```active'', ``active''', `<x> +')dnl +@result{}<active> +@result{}<active> +@end example + +@ignore +@comment Not worth putting in the manual, but make sure that foreach +@comment implementations behave, and that final implementation is +@comment linear. + +@comment boxed recursion + +@comment examples +@comment options: -Dlimit=10 -Dverbose +@example +$ @kbd {m4 -I examples -Dlimit=10 -Dverbose} +include(`loop.m4')dnl +@result{} 1 2 3 4 5 6 7 8 9 10 +@end example + +@comment unboxed recursion + +@comment examples +@comment options: -Dlimit=10 -Dverbose -Dalt +@example +$ @kbd {m4 -I examples -Dlimit=10 -Dverbose -Dalt} +include(`loop.m4')dnl +@result{} 1 2 3 4 5 6 7 8 9 10 +@end example + +@comment foreach via forloop recursion + +@comment examples +@comment options: -Dlimit=10 -Dverbose -Dalt=4 +@example +$ @kbd {m4 -I examples -Dlimit=10 -Dverbose -Dalt=4} +include(`loop.m4')dnl +@result{} 1 2 3 4 5 6 7 8 9 10 +@end example + +@comment examples +@comment options: -Dlimit=2500 -Dalt=4 +@example +$ @kbd {m4 -I examples -Dlimit=2500 -Dalt=4} +include(`loop.m4')dnl +@end example + +@comment examples +@comment options: -Dlimit=10000 -Dalt=4 +@example +$ @kbd {m4 -I examples -Dlimit=10000 -Dalt=4} +define(`foo', `divert`'len(popdef(`_foreachq')_foreachq($@@))')dnl +define(`debug', `pushdef(`_foreachq', defn(`foo'))') +@result{} +include(`loop.m4')dnl +@result{}48894 +@end example + +@end ignore + +@node Improved copy +@section Solution for @code{copy} + +The macro @code{copy} presented above +is unable to handle builtin tokens with M4 1.4.x, because it tries to +pass the builtin token through the macro @code{curry}, where it is +silently flattened to an empty string (@pxref{Composition}). Rather +than using the problematic @code{curry} to work around the limitation +that @code{stack_foreach} expects to invoke a macro that takes exactly +one argument, we can write a new macro that lets us form the exact +two-argument @code{pushdef} call sequence needed, so that we are no +longer passing a builtin token through a text macro. + +@deffn Composite stack_foreach_sep (@var{macro}, @var{pre}, @var{post}, @ + @var{sep}) +@deffnx Composite stack_foreach_sep_lifo (@var{macro}, @var{pre}, @ + @var{post}, @var{sep}) +For each of the @code{pushdef} definitions associated with @var{macro}, +expand the sequence @samp{@var{pre}`'definition`'@var{post}}. +Additionally, expand @var{sep} between definitions. +@code{stack_foreach_sep} visits the oldest definition first, while +@code{stack_foreach_sep_lifo} visits the current definition first. The +expansion may dereference @var{macro}, but should not modify it. There +are a few special macros, such as @code{defn}, which cannot be used as +the @var{macro} parameter. +@end deffn + +Note that @code{stack_foreach(`@var{macro}', `@var{action}')} is +equivalent to @code{stack_foreach_sep(`@var{macro}', `@var{action}(', +`)')}. By supplying explicit parentheses, split among the @var{pre} and +@var{post} arguments to @code{stack_foreach_sep}, it is now possible to +construct macro calls with more than one argument, without passing +builtin tokens through a macro call. It is likewise possible to +directly reference the stack definitions without a macro call, by +leaving @var{pre} and @var{post} empty. Thus, in addition to fixing +@code{copy} on builtin tokens, it also executes with fewer macro +invocations. + +The new macro also adds a separator that is only output after the first +iteration of the helper @code{_stack_reverse_sep}, implemented by +prepending the original @var{sep} to @var{pre} and omitting a @var{sep} +argument in subsequent iterations. Note that the empty string that +separates @var{sep} from @var{pre} is provided as part of the fourth +argument when originally calling @code{_stack_reverse_sep}, and not by +writing @code{$4`'$3} as the third argument in the recursive call; while +the other approach would give the same output, it does so at the expense +of increasing the argument size on each iteration of +@code{_stack_reverse_sep}, which results in quadratic instead of linear +execution time. The improved stack walking macros are available in +@file{m4-@value{VERSION}/@/examples/@/stack_sep.m4}: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`stack_sep.m4') +@result{} +define(`copy', `ifdef(`$2', `errprint(`$2 already defined +')m4exit(`1')', + `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl +pushdef(`a', `1')pushdef(`a', defn(`divnum')) +@result{} +copy(`a', `b') +@result{} +b +@result{}0 +popdef(`b') +@result{} +b +@result{}1 +pushdef(`c', `1')pushdef(`c', `2') +@result{} +stack_foreach_sep_lifo(`c', `', `', `, ') +@result{}2, 1 +undivert(`stack_sep.m4')dnl +@result{}divert(`-1') +@result{}# stack_foreach_sep(macro, pre, post, sep) +@result{}# Invoke PRE`'defn`'POST with a single argument of each definition +@result{}# from the definition stack of MACRO, starting with the oldest, and +@result{}# separated by SEP between definitions. +@result{}define(`stack_foreach_sep', +@result{}`_stack_reverse_sep(`$1', `tmp-$1')'dnl +@result{}`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')') +@result{}# stack_foreach_sep_lifo(macro, pre, post, sep) +@result{}# Like stack_foreach_sep, but starting with the newest definition. +@result{}define(`stack_foreach_sep_lifo', +@result{}`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl +@result{}`_stack_reverse_sep(`tmp-$1', `$1')') +@result{}define(`_stack_reverse_sep', +@result{}`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0( +@result{} `$1', `$2', `$4$3')')') +@result{}divert`'dnl +@end example + +@ignore +@comment Not worth putting in the manual, but make sure that +@comment stack_foreach_sep has linear performance. + +@comment examples +@example +$ @kbd {m4 -I examples} +include(`forloop3.m4')include(`stack_sep.m4')dnl +forloop(`i', `1', `10000', `pushdef(`s', i)') +@result{} +define(`colon', `:')define(`dash', `-') +@result{} +len(stack_foreach_sep(`s', `dash', `', `colon')) +@result{}58893 +@end example +@end ignore + +@node Improved m4wrap +@section Solution for @code{m4wrap} + +The replacement @code{m4wrap} versions presented above, designed to +guarantee FIFO or LIFO order regardless of the underlying M4 +implementation, share a bug when dealing with wrapped text that looks +like parameter expansion. Note how the invocation of +@code{m4wrap@var{n}} interprets these parameters, while using the +builtin preserves them for their intended use. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`wraplifo.m4') +@result{} +m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') +') +@result{} +builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b') +') +@result{} +^D +@result{}bar:-a-a,b-2- +@result{}m4wrap0:---0- +@end example + +Additionally, the computation of @code{_m4wrap_level} and creation of +multiple @code{m4wrap@var{n}} placeholders in the original examples is +more expensive in time and memory than strictly necessary. Notice how +the improved version grabs the wrapped text via @code{defn} to avoid +parameter expansion, then undefines @code{_m4wrap_text}, before +stripping a level of quotes with @code{_arg1} to expand the text. That +way, each level of wrapping reuses the single placeholder, which starts +each nesting level in an undefined state. + +Finally, it is worth emulating the GNU M4 extension of saving +all arguments to @code{m4wrap}, separated by a space, rather than saving +just the first argument. This is done with the @code{join} macro +documented previously (@pxref{Shift}). The improved LIFO example is +shipped as @file{m4-@value{VERSION}/@/examples/@/wraplifo2.m4}, and can +easily be converted to a FIFO solution by swapping the adjacent +invocations of @code{joinall} and @code{defn}. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`wraplifo2.m4') +@result{} +undivert(`wraplifo2.m4')dnl +@result{}dnl Redefine m4wrap to have LIFO semantics, improved example. +@result{}include(`join.m4')dnl +@result{}define(`_m4wrap', defn(`m4wrap'))dnl +@result{}define(`_arg1', `$1')dnl +@result{}define(`m4wrap', +@result{}`ifdef(`_$0_text', +@result{} `define(`_$0_text', joinall(` ', $@@)defn(`_$0_text'))', +@result{} `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl +@result{}define(`_$0_text', joinall(` ', $@@))')')dnl +m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') +') +@result{} +m4wrap(`lifo text +m4wrap(`nested', `', `$@@ +')') +@result{} +^D +@result{}lifo text +@result{}foo:-a-a,b-2- +@result{}nested $@@ +@end example + +@node Improved cleardivert +@section Solution for @code{cleardivert} + +The @code{cleardivert} macro (@pxref{Cleardivert}) cannot, as it stands, be +called without arguments to clear all pending diversions. That is +because using undivert with an empty string for an argument is different +than using it with no arguments at all. Compare the earlier definition +with one that takes the number of arguments into account: + +@example +define(`cleardivert', + `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')') +@result{} +divert(`1')one +divert +@result{} +cleardivert +@result{} +undivert +@result{}one +@result{} +define(`cleardivert', + `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0', + `undivert`'', `undivert($@@)')divert(_num)popdef(`_num')') +@result{} +divert(`2')two +divert +@result{} +cleardivert +@result{} +undivert +@result{} +@end example + +@node Improved capitalize +@section Solution for @code{capitalize} + +The @code{capitalize} macro (@pxref{Patsubst}) as presented earlier does +not allow clients to follow the quoting rule of thumb. Consider the +three macros @code{active}, @code{Active}, and @code{ACTIVE}, and the +difference between calling @code{capitalize} with the expansion of a +macro, expanding the result of a case change, and changing the case of a +double-quoted string: + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`capitalize.m4')dnl +define(`active', `act1, ive')dnl +define(`Active', `Act2, Ive')dnl +define(`ACTIVE', `ACT3, IVE')dnl +upcase(active) +@result{}ACT1,IVE +upcase(`active') +@result{}ACT3, IVE +upcase(``active'') +@result{}ACTIVE +downcase(ACTIVE) +@result{}act3,ive +downcase(`ACTIVE') +@result{}act1, ive +downcase(``ACTIVE'') +@result{}active +capitalize(active) +@result{}Act1 +capitalize(`active') +@result{}Active +capitalize(``active'') +@result{}_capitalize(`active') +define(`A', `OOPS') +@result{} +capitalize(active) +@result{}OOPSct1 +capitalize(`active') +@result{}OOPSctive +@end example + +First, when @code{capitalize} is called with more than one argument, it +was throwing away later arguments, whereas @code{upcase} and +@code{downcase} used @samp{$*} to collect them all. The fix is simple: +use @samp{$*} consistently. + +Next, with single-quoting, @code{capitalize} outputs a single character, +a set of quotes, then the rest of the characters, making it impossible +to invoke @code{Active} after the fact, and allowing the alternate macro +@code{A} to interfere. Here, the solution is to use additional quoting +in the helper macros, then pass the final over-quoted output string +through @code{_arg1} to remove the extra quoting and finally invoke the +concatenated portions as a single string. + +Finally, when passed a double-quoted string, the nested macro +@code{_capitalize} is never invoked because it ended up nested inside +quotes. This one is the toughest to fix. In short, we have no idea how +many levels of quotes are in effect on the substring being altered by +@code{patsubst}. If the replacement string cannot be expressed entirely +in terms of literal text and backslash substitutions, then we need a +mechanism to guarantee that the helper macros are invoked outside of +quotes. In other words, this sounds like a job for @code{changequote} +(@pxref{Changequote}). By changing the active quoting characters, we +can guarantee that replacement text injected by @code{patsubst} always +occurs in the middle of a string that has exactly one level of +over-quoting using alternate quotes; so the replacement text closes the +quoted string, invokes the helper macros, then reopens the quoted +string. In turn, that means the replacement text has unbalanced quotes, +necessitating another round of @code{changequote}. + +In the fixed version below, (also shipped as +@file{m4-@value{VERSION}/@/examples/@/capitalize2.m4}), @code{capitalize} +uses the alternate quotes of @samp{<<[} and @samp{]>>} (the longer +strings are chosen so as to be less likely to appear in the text being +converted). The helpers @code{_to_alt} and @code{_from_alt} merely +reduce the number of characters required to perform a +@code{changequote}, since the definition changes twice. The outermost +pair means that @code{patsubst} and @code{_capitalize_alt} are invoked +with alternate quoting; the innermost pair is used so that the third +argument to @code{patsubst} can contain an unbalanced +@samp{]>>}/@samp{<<[} pair. Note that @code{upcase} and @code{downcase} +must be redefined as @code{_upcase_alt} and @code{_downcase_alt}, since +they contain nested quotes but are invoked with the alternate quoting +scheme in effect. + +@comment examples +@example +$ @kbd{m4 -I examples} +include(`capitalize2.m4')dnl +define(`active', `act1, ive')dnl +define(`Active', `Act2, Ive')dnl +define(`ACTIVE', `ACT3, IVE')dnl +define(`A', `OOPS')dnl +capitalize(active; `active'; ``active''; ```actIVE''') +@result{}Act1,Ive; Act2, Ive; Active; `Active' +undivert(`capitalize2.m4')dnl +@result{}divert(`-1') +@result{}# upcase(text) +@result{}# downcase(text) +@result{}# capitalize(text) +@result{}# change case of text, improved version +@result{}define(`upcase', `translit(`$*', `a-z', `A-Z')') +@result{}define(`downcase', `translit(`$*', `A-Z', `a-z')') +@result{}define(`_arg1', `$1') +@result{}define(`_to_alt', `changequote(`<<[', `]>>')') +@result{}define(`_from_alt', `changequote(<<[`]>>, <<[']>>)') +@result{}define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)') +@result{}define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)') +@result{}define(`_capitalize_alt', +@result{} `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>, +@result{} <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)') +@result{}define(`capitalize', +@result{} `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>, +@result{} _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())') +@result{}divert`'dnl +@end example + +@node Improved fatal_error +@section Solution for @code{fatal_error} + +The @code{fatal_error} macro (@pxref{M4exit}) is not robust to versions +of GNU M4 earlier than 1.4.8, where invoking +@code{@w{__file__}} (@pxref{Location}) inside @code{m4wrap} would result +in an empty string, and @code{@w{__line__}} resulted in @samp{0} even +though all files start at line 1. Furthermore, versions earlier than +1.4.6 did not support the @code{@w{__program__}} macro. If you want +@code{fatal_error} to work across the entire 1.4.x release series, a +better implementation would be: + +@comment status: 1 +@example +define(`fatal_error', + `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl +`:ifelse(__line__, `0', `', + `__file__:__line__:')` fatal error: $* +')m4exit(`1')') +@result{} +m4wrap(`divnum(`demo of internal message') +fatal_error(`inside wrapped text')') +@result{} +^D +@error{}m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored +@result{}0 +@error{}m4:stdin:6: fatal error: inside wrapped text +@end example + +@c ========================================================== Appendices + +@node Copying This Package +@appendix How to make copies of the overall M4 package +@cindex License, code + +This appendix covers the license for copying the source code of the +overall M4 package. This manual is under a different set of +restrictions, covered later (@pxref{Copying This Manual}). + +@menu +* GNU General Public License:: License for copying the M4 package +@end menu + +@node GNU General Public License +@appendixsec License for copying the M4 package +@cindex GPL, GNU General Public License +@cindex GNU General Public License +@cindex General Public License (GPL), GNU +@include gpl-3.0.texi + +@node Copying This Manual +@appendix How to make copies of this manual +@cindex License, manual + +This appendix covers the license for copying this manual. Note that +some of the longer examples in this manual are also distributed in the +directory @file{m4-@value{VERSION}/@/examples/}, where a more +permissive license is in effect when copying just the examples. + +@menu +* GNU Free Documentation License:: License for copying this manual +@end menu + +@node GNU Free Documentation License +@appendixsec License for copying this manual +@cindex FDL, GNU Free Documentation License +@cindex GNU Free Documentation License +@cindex Free Documentation License (FDL), GNU +@include fdl-1.3.texi + +@node Indices +@appendix Indices of concepts and macros + +@menu +* Macro index:: Index for all @code{m4} macros +* Concept index:: Index for many concepts +@end menu + +@node Macro index +@appendixsec Index for all @code{m4} macros + +This index covers all @code{m4} builtins, as well as several useful +composite macros. References are exclusively to the places where a +macro is introduced the first time. + +@printindex fn + +@node Concept index +@appendixsec Index for many concepts + +@printindex cp + +@bye + +@c Local Variables: +@c coding: iso-8859-1 +@c fill-column: 72 +@c ispell-local-dictionary: "american" +@c indent-tabs-mode: nil +@c whitespace-check-buffer-indent: nil +@c End: diff --git a/doc/stamp-vti b/doc/stamp-vti new file mode 100644 index 0000000..75abce4 --- /dev/null +++ b/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 28 February 2011 +@set UPDATED-MONTH February 2011 +@set EDITION 1.4.16 +@set VERSION 1.4.16 diff --git a/doc/version.texi b/doc/version.texi new file mode 100644 index 0000000..75abce4 --- /dev/null +++ b/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 28 February 2011 +@set UPDATED-MONTH February 2011 +@set EDITION 1.4.16 +@set VERSION 1.4.16 |