MACROS(3X)

NAME
macros - macro expansion of colon definitions

SYNOPSIS
#include macros.f83

macros

DESCRIPTION
Allows definition of macro colon definitions to reduce the overhead of procedure calls at run-time to the price of memory. The macro package may be used, after profiling of an application, to mark the most critical low level definitions and hereby increase performance. Macro definition may also be used to create alias names for definitions.

: .macro ( -- )
    Used in the following form:
    .macro <macro-name>
    to display the internal information about the macro definition. The information is displayed in the following form:
    macro# <macro-address> size: <macro-size> body: <macro-body-address>
    Use mainly for debugging and code verification purpose.

: macro ( -- )
    Used in the following form to mark the latest colon definition as a macro:
    : <macro-name> ( ... ) ... <macro-definition> ... ; macro
    Used in the same way as "immediate" and other mode classifiers. The code section is not restricted to sequential code. Control structures, condition and iteration statements, are allowed as all branches are relative. Special care should be taken if the macro definition contains "exit", "tail-recurse" or "recurse" as the result is unpredictable when expanded.

vocabulary macros ( -- )
    Vocabulary containing the macro extension definitions. Include into the vocabulary search chain, "context", to gain access to this library.

INTERNALS
Private definitions in the macros vocabulary;

ptr +body ( macro -- addr) private
    Returns address of field in "MACRO" structure to pointer to code section of the macro.

long +size ( macro -- addr) private
    Returns address of field in "MACRO" structure to byte size of macro code.

struct.type MACRO ( body size -- ) private
    Structure definition used by "macro" to keep information about a macro code definition. Internal fields are "+body" and "+size". An instance of this structure will perform the run-time action for a macro definitions. If compilation state the macro body is expanded into the current definition otherwise the macro body is executed. All macro definitions are "immediate". The "MACRO" structure type contains the fields "+body" and "+size".

SEE ALSO
tile(1), forth(3X), internals(3X), structures(3X).

EXAMPLES
An example showing how to create macros for some additional relational operators:

    #include macros.f83

    macros

    : <> ( x y -- bool) = not ; macro
    : >= ( x y -- bool) < not ; macro
    : <= ( x y -- bool) > not ; macro

The "macro" function may also be used to the allow simple aliasing and renaming at very low execution cost.

NOTE
The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect.

WARNING
A "macro" definition containing "exit" will work correctly in execution mode but expanded in a colon definition the "macro" will cause the definition to be exited. This is in most case not the wanted behavior. Special care should be taken for "macro" definitions which contain "exit", "recurse", and "tail-recurse". Also argument and local variables, and exception blocks should not be part of a macro colon definition.

COPYING
Copyright (C) 1990 Mikael R.K. Patel

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR
Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se