File: autoconf.info,  Node: Conditional constructs,  Next: Looping constructs,  Prev: Diversion support,  Up: Programming in M4sugar

8.3.4 Conditional constructs
----------------------------

The following macros provide additional conditional constructs as
convenience wrappers around ‘m4_if’.

 -- Macro: m4_bmatch (STRING, REGEX-1, VALUE-1, [REGEX-2], [VALUE-2],
          ..., [DEFAULT])
     The string STRING is repeatedly compared against a series of REGEX
     arguments; if a match is found, the expansion is the corresponding
     VALUE, otherwise, the macro moves on to the next REGEX.  If no
     REGEX match, then the result is the optional DEFAULT, or nothing.

 -- Macro: m4_bpatsubsts (STRING, REGEX-1, SUBST-1, [REGEX-2],
          [SUBST-2], ...)
     The string STRING is altered by REGEX-1 and SUBST-1, as if by:
          m4_bpatsubst([[STRING]], [REGEX], [SUBST])

     The result of the substitution is then passed through the next set
     of REGEX and SUBST, and so forth.  An empty SUBST implies deletion
     of any matched portions in the current string.  Note that this
     macro over-quotes STRING; this behavior is intentional, so that the
     result of each step of the recursion remains as a quoted string.
     However, it means that anchors (‘^’ and ‘$’ in the REGEX will line
     up with the extra quotations, and not the characters of the
     original string.  The overquoting is removed after the final
     substitution.

 -- Macro: m4_case (STRING, VALUE-1, IF-VALUE-1, [VALUE-2],
          [IF-VALUE-2], ..., [DEFAULT])
     Test STRING against multiple VALUE possibilities, resulting in the
     first IF-VALUE for a match, or in the optional DEFAULT.  This is
     shorthand for:
          m4_if([STRING], [VALUE-1], [IF-VALUE-1],
                [STRING], [VALUE-2], [IF-VALUE-2], ...,
                [DEFAULT])

 -- Macro: m4_cond (TEST-1, VALUE-1, IF-VALUE-1, [TEST-2], [VALUE-2],
          [IF-VALUE-2], ..., [DEFAULT])
     This macro was introduced in Autoconf 2.62.  Similar to ‘m4_if’,
     except that each TEST is expanded only when it is encountered.
     This is useful for short-circuiting expensive tests; while ‘m4_if’
     requires all its strings to be expanded up front before doing
     comparisons, ‘m4_cond’ only expands a TEST when all earlier tests
     have failed.

     For an example, these two sequences give the same result, but in
     the case where ‘$1’ does not contain a backslash, the ‘m4_cond’
     version only expands ‘m4_index’ once, instead of five times, for
     faster computation if this is a common case for ‘$1’.  Notice that
     every third argument is unquoted for ‘m4_if’, and quoted for
     ‘m4_cond’:

          m4_if(m4_index([$1], [\]), [-1], [$2],
                m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
                m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
                m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
                m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
                [$2])
          m4_cond([m4_index([$1], [\])], [-1], [$2],
                  [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
                  [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
                  [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
                  [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
                  [$2])

 -- Macro: m4_default (EXPR-1, EXPR-2)
 -- Macro: m4_default_quoted (EXPR-1, EXPR-2)
 -- Macro: m4_default_nblank (EXPR-1, [EXPR-2])
 -- Macro: m4_default_nblank_quoted (EXPR-1, [EXPR-2])
     If EXPR-1 contains text, use it.  Otherwise, select EXPR-2.
     ‘m4_default’ expands the result, while ‘m4_default_quoted’ does
     not.  Useful for providing a fixed default if the expression that
     results in EXPR-1 would otherwise be empty.  The difference between
     ‘m4_default’ and ‘m4_default_nblank’ is whether an argument
     consisting of just blanks (space, tab, newline) is significant.
     When using the expanding versions, note that an argument may
     contain text but still expand to an empty string.

          m4_define([active], [ACTIVE])dnl
          m4_define([empty], [])dnl
          m4_define([demo1], [m4_default([$1], [$2])])dnl
          m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl
          m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl
          m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl
          demo1([active], [default])
          ⇒ACTIVE
          demo1([], [active])
          ⇒ACTIVE
          demo1([empty], [text])
          ⇒
          -demo1([ ], [active])-
          ⇒- -
          demo2([active], [default])
          ⇒active
          demo2([], [active])
          ⇒active
          demo2([empty], [text])
          ⇒empty
          -demo2([ ], [active])-
          ⇒- -
          demo3([active], [default])
          ⇒ACTIVE
          demo3([], [active])
          ⇒ACTIVE
          demo3([empty], [text])
          ⇒
          -demo3([ ], [active])-
          ⇒-ACTIVE-
          demo4([active], [default])
          ⇒active
          demo4([], [active])
          ⇒active
          demo4([empty], [text])
          ⇒empty
          -demo4([ ], [active])-
          ⇒-active-

 -- Macro: m4_define_default (MACRO, [DEFAULT-DEFINITION])
     If MACRO does not already have a definition, then define it to
     DEFAULT-DEFINITION.

 -- Macro: m4_ifblank (COND, [IF-BLANK], [IF-TEXT])
 -- Macro: m4_ifnblank (COND, [IF-TEXT], [IF-BLANK])
     If COND is empty or consists only of blanks (space, tab, newline),
     then expand IF-BLANK; otherwise, expand IF-TEXT.  Two variants
     exist, in order to make it easier to select the correct logical
     sense when using only two parameters.  Note that this is more
     efficient than the equivalent behavior of:
          m4_ifval(m4_normalize([COND]), IF-TEXT, IF-BLANK)

 -- Macro: m4_ifndef (MACRO, IF-NOT-DEFINED, [IF-DEFINED])
     This is shorthand for:
          m4_ifdef([MACRO], [IF-DEFINED], [IF-NOT-DEFINED])

 -- Macro: m4_ifset (MACRO, [IF-TRUE], [IF-FALSE])
     If MACRO is undefined, or is defined as the empty string, expand to
     IF-FALSE.  Otherwise, expands to IF-TRUE.  Similar to:
          m4_ifval(m4_defn([MACRO]), [IF-TRUE], [IF-FALSE])
     except that it is not an error if MACRO is undefined.

 -- Macro: m4_ifval (COND, [IF-TRUE], [IF-FALSE])
     Expands to IF-TRUE if COND is not empty, otherwise to IF-FALSE.
     This is shorthand for:
          m4_if([COND], [], [IF-FALSE], [IF-TRUE])

 -- Macro: m4_ifvaln (COND, [IF-TRUE], [IF-FALSE])
     Similar to ‘m4_ifval’, except guarantee that a newline is present
     after any non-empty expansion.  Often followed by ‘dnl’.

 -- Macro: m4_n (TEXT)
     Expand to TEXT, and add a newline if TEXT is not empty.  Often
     followed by ‘dnl’.