File: autoconf.info,  Node: Common Shell Constructs,  Next: Polymorphic Variables,  Up: Programming in M4sh

9.1 Common Shell Constructs
===========================

M4sh provides portable alternatives for some common shell constructs
that unfortunately are not portable in practice.

 -- Macro: AS_BOX (TEXT, [CHAR = -])
     Expand into shell code that will output TEXT surrounded by a box
     with CHAR in the top and bottom border.  TEXT should not contain a
     newline, but may contain shell expansions valid for unquoted
     here-documents.  CHAR defaults to ‘-’, but can be any character
     except ‘/’, ‘'’, ‘"’, ‘\’, ‘&’, or ‘`’.  This is useful for
     outputting a comment box into log files to separate distinct phases
     of script operation.

 -- Macro: AS_CASE (WORD, [PATTERN1], [IF-MATCHED1], ..., [DEFAULT])
     Expand into a shell ‘case’ statement, where WORD is matched against
     one or more patterns.  IF-MATCHED is run if the corresponding
     pattern matched WORD, else DEFAULT is run.  *Note Prerequisite
     Macros:: for why this macro should be used instead of plain ‘case’
     in code outside of an ‘AC_DEFUN’ macro, when the contents of the
     ‘case’ use ‘AC_REQUIRE’ directly or indirectly.  *Note Limitations
     of Shell Builtins: case, for how this macro avoids some portability
     issues.  *Note Balancing Parentheses:: for how this macro lets you
     write code with balanced parentheses even if your code must run on
     obsolescent shells.

 -- Macro: AS_DIRNAME (FILE-NAME)
     Output the directory portion of FILE-NAME.  For example, if ‘$file’
     is ‘/one/two/three’, the command ‘dir=`AS_DIRNAME(["$file"])`’ sets
     ‘dir’ to ‘/one/two’.

     ‘AS_DIRNAME’ was designed long ago when the ‘dirname’ command was
     not universally supported.  Nowadays one can safely use
     ‘dir=`dirname -- "$file"`’ instead.  This interface may be improved
     in the future to avoid forks and losing trailing newlines.

 -- Macro: AS_ECHO (WORD)
     Emits WORD to the standard output, followed by a newline.  WORD
     must be a single shell word (typically a quoted string).  The bytes
     of WORD are output as-is, even if it starts with "-" or contains
     "\".  Redirections can be placed outside the macro invocation.
     This is much more portable than using ‘echo’ (*note Limitations of
     Shell Builtins: echo.).

 -- Macro: AS_ECHO_N (WORD)
     Emits WORD to the standard output, without a following newline.
     WORD must be a single shell word (typically a quoted string) and,
     for portability, should not include more than one newline.  The
     bytes of WORD are output as-is, even if it starts with "-" or
     contains "\".  Redirections can be placed outside the macro
     invocation.

 -- Macro: AS_ESCAPE (STRING, [CHARS = `\"$])
     Expands to STRING, with any characters in CHARS escaped with a
     backslash (‘\’).  CHARS should be at most four bytes long, and only
     contain characters from the set ‘`\"$’; however, characters may be
     safely listed more than once in CHARS for the sake of syntax
     highlighting editors.  The current implementation expands STRING
     after adding escapes; if STRING contains macro calls that in turn
     expand to text needing shell quoting, you can use
     ‘AS_ESCAPE(m4_dquote(m4_expand([string])))’.

     The default for CHARS (‘\"$`’) is the set of characters needing
     escapes when STRING will be used literally within double quotes.
     One common variant is the set of characters to protect when STRING
     will be used literally within back-ticks or an unquoted
     here-document (‘\$`’).  Another common variant is ‘""’, which can
     be used to form a double-quoted string containing the same
     expansions that would have occurred if STRING were expanded in an
     unquoted here-document; however, when using this variant, care must
     be taken that STRING does not use double quotes within complex
     variable expansions (such as ‘${foo-`echo "hi"`}’) that would be
     broken with improper escapes.

     This macro is often used with ‘AS_ECHO’.  For an example, observe
     the output generated by the shell code generated from this snippet:

          foo=bar
          AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"])
          ⇒"$foo" = "bar"
          m4_define([macro], [a, [\b]])
          AS_ECHO(["AS_ESCAPE([[macro]])"])
          ⇒macro
          AS_ECHO(["AS_ESCAPE([macro])"])
          ⇒a, b
          AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"])
          ⇒a, \b

     To escape a string that will be placed within single quotes, use:

          m4_bpatsubst([[STRING]], ['], ['\\''])

 -- Macro: AS_EXECUTABLE_P (FILE)
     Emit code to probe whether FILE is a regular file with executable
     permissions (and not a directory with search permissions).  The
     caller is responsible for quoting FILE.

 -- Macro: AS_EXIT ([STATUS = $?])
     Emit code to exit the shell with STATUS, defaulting to ‘$?’.  This
     macro works around shells that see the exit status of the command
     prior to ‘exit’ inside a ‘trap 0’ handler (*note Limitations of
     Shell Builtins: trap.).

 -- Macro: AS_IF (TEST1, [RUN-IF-TRUE1], ..., [RUN-IF-FALSE])
     Run shell code TEST1.  If TEST1 exits with a zero status then run
     shell code RUN-IF-TRUE1, else examine further tests.  If no test
     exits with a zero status, run shell code RUN-IF-FALSE, with
     simplifications if either RUN-IF-TRUE1 or RUN-IF-FALSE is empty.
     For example,

          AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])],
                [test "x$foo" != xno], [HANDLE_FOO([maybe])],
                [echo foo not specified])

     ensures any required macros of ‘HANDLE_FOO’ are expanded before the
     first test.

     This macro should be used instead of plain ‘if’ in code outside of
     an ‘AC_DEFUN’ macro, when the contents of the ‘if’ use ‘AC_REQUIRE’
     directly or indirectly (*note Prerequisite Macros::).

 -- Macro: AS_MKDIR_P (FILE-NAME)
     Make the directory FILE-NAME, including intervening directories as
     necessary.  This is equivalent to ‘mkdir -p -- FILE-NAME’.  If
     creation of FILE-NAME fails, exit the script.

     Also see the ‘AC_PROG_MKDIR_P’ macro (*note Particular Programs::).

 -- Macro: AS_SET_STATUS (STATUS)
     Emit shell code to set the value of ‘$?’ to STATUS, as efficiently
     as possible.  However, this is not guaranteed to abort a shell
     running with ‘set -e’ (*note Limitations of Shell Builtins: set.).
     This should also be used at the end of a complex shell function
     instead of ‘return’ (*note Shell Functions::) to avoid a DJGPP
     shell bug.

 -- Macro: AS_TR_CPP (EXPRESSION)
     Transform EXPRESSION into a valid right-hand side for a C
     ‘#define’.  For example:

          # This outputs "#define HAVE_CHAR_P 1".
          # Notice the m4 quoting around #, to prevent an m4 comment
          type="char *"
          echo "[#]define AS_TR_CPP([HAVE_$type]) 1"

 -- Macro: AS_TR_SH (EXPRESSION)
     Transform EXPRESSION into shell code that generates a valid shell
     variable name.  The result is literal when possible at m4 time, but
     must be used with ‘eval’ if EXPRESSION causes shell indirections.
     For example:

          # This outputs "Have it!".
          header="sys/some file.h"
          eval AS_TR_SH([HAVE_$header])=yes
          if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi

 -- Macro: AS_SET_CATFILE (VAR, DIR, FILE)
     Set the polymorphic shell variable VAR to DIR/FILE, but optimizing
     the common cases (DIR or FILE is ‘.’, FILE is absolute, etc.).

 -- Macro: AS_UNSET (VAR)
     Unsets the shell variable VAR, working around bugs in older shells
     (*note Limitations of Shell Builtins: unset.).  VAR can be a
     literal or indirect variable name.

 -- Macro: AS_VERSION_COMPARE (VERSION-1, VERSION-2, [ACTION-IF-LESS],
          [ACTION-IF-EQUAL], [ACTION-IF-GREATER])
     Compare two strings VERSION-1 and VERSION-2, possibly containing
     shell variables, as version strings, and expand ACTION-IF-LESS,
     ACTION-IF-EQUAL, or ACTION-IF-GREATER depending upon the result.
     The algorithm to compare is similar to the one used by strverscmp
     in glibc (*note String/Array Comparison: (libc)String/Array
     Comparison.).