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.