m4: Pushdef

1 
1 5.6 Temporarily redefining macros
1 =================================
1 
1 It is possible to redefine a macro temporarily, reverting to the
1 previous definition at a later time.  This is done with the builtins
1 'pushdef' and 'popdef':
1 
1  -- Builtin: pushdef (NAME, [EXPANSION])
1  -- Builtin: popdef (NAME...)
1      Analogous to 'define' and 'undefine'.
1 
1      These macros work in a stack-like fashion.  A macro is temporarily
1      redefined with 'pushdef', which replaces an existing definition of
1      NAME, while saving the previous definition, before the new one is
1      installed.  If there is no previous definition, 'pushdef' behaves
1      exactly like 'define'.
1 
1      If a macro has several definitions (of which only one is
1      accessible), the topmost definition can be removed with 'popdef'.
1      If there is no previous definition, 'popdef' behaves like
1      'undefine'.
1 
1      The expansion of both 'pushdef' and 'popdef' is void.  The macros
1      'pushdef' and 'popdef' are recognized only with parameters.
1 
1      define(`foo', `Expansion one.')
1      =>
1      foo
1      =>Expansion one.
1      pushdef(`foo', `Expansion two.')
1      =>
1      foo
1      =>Expansion two.
1      pushdef(`foo', `Expansion three.')
1      =>
1      pushdef(`foo', `Expansion four.')
1      =>
1      popdef(`foo')
1      =>
1      foo
1      =>Expansion three.
1      popdef(`foo', `foo')
1      =>
1      foo
1      =>Expansion one.
1      popdef(`foo')
1      =>
1      foo
1      =>foo
1 
1    If a macro with several definitions is redefined with 'define', the
1 topmost definition is _replaced_ with the new definition.  If it is
1 removed with 'undefine', _all_ the definitions are removed, and not only
1 the topmost one.  However, POSIX allows other implementations that treat
1 'define' as replacing an entire stack of definitions with a single new
1 definition, so to be portable to other implementations, it may be worth
1 explicitly using 'popdef' and 'pushdef' rather than relying on the GNU
1 behavior of 'define'.
1 
1      define(`foo', `Expansion one.')
1      =>
1      foo
1      =>Expansion one.
1      pushdef(`foo', `Expansion two.')
1      =>
1      foo
1      =>Expansion two.
1      define(`foo', `Second expansion two.')
1      =>
1      foo
1      =>Second expansion two.
1      undefine(`foo')
1      =>
1      foo
1      =>foo
1 
1    Local variables within macros are made with 'pushdef' and 'popdef'.
1 At the start of the macro a new definition is pushed, within the macro
1 it is manipulated and at the end it is popped, revealing the former
1 definition.
1 
1    It is possible to temporarily redefine a builtin with 'pushdef' and
1 'defn'.
1