2.3.1.7 Define Macro ($$x)

Traditionally, a macro is a piece of code that looks like a function call but which is actually replaced by the code it represents before the program is processed. A Cogsys macro is not replaced in-line; rather it is a true function that is actually called with a return value pushed onto a call stack. However, the name "macro" was used in earlier versions, and it has stuck.

This command defines a Cogsys macro. A macro definition associates a sequence of Cogsys commands with a macro identifier. The macro identifier is a single character which can then be called by the Run Macro command. Cogsys then executes the code for that macro. This provides an easy mechanism for encapsulating commonly used code in a testlist.

Starting with Cogsys version 3.0.9, macros may take arguments. Arguments name are listed in square brackets immediately following the identifier, and are then embedded in the body in any order at any location. When the macro is called with arguments, Cogsys replaces the ocurrence of the argument name in the body with the text actually passed. Up to MACRO_ARG_NUM macros may be specified, of MACRO_ARG_LEN characters each.

For example:

$$a[arg]The value is arg.$$ ... $a[5]

Here, Cogsys will replace the string `arg' in the body definition with the passed argument, `5'. The resulting output will be:

The value is 5.

Note that for an argument to be replaced in the body text, it must occur as a separate word, bounded by non-letters. For example:

$$a[arg]The value of the argument is arg.$$ ... $a[5]

Here, the string `arg' actually appears twice, first in the word `argument', and then at the end of the sentence. However, the macro definition only replaces the second occurence:

The value of the argument is 5.

Normally, this is exactly the desired behavior. It is important to understand, however, that this makes it impossible to define macros where the argument is embedded as part of a word. To work around such cases, use a second macro, or just pass more text in the argument itself.

For example, this macro definition:

$$a[x]I go to Northxern University.$$ ... $$a[west]

does not work as expected, and yields this:

I go to Northxern University.

A second macro solves the problem:

$$east$$Northeastern$$ $$west$$Northwestern$$ $$a[x]I go to $x University.$$ ... $$a[west]

Or, you could just pass the full text in the argument:

$$a[x]I go to $x University.$$ ... $$a[Northwestern]

Macros may be redefined at any time. They may be nested up to MACRO_NEST levels deep. Each individual macro can not exceed MACRO_SIZE characters. See Run Macro, for details.

A macro body definition must be under MACRO_CORE characters long. Cogsys reserves an extra buffer, slightly larger than MACRO_CORE, for the expanded macro (MACRO_EXPANDS. If these bounds are exceeded, a run time error results.

Name:

Define Macro

Class:

Control

Code:

$$

Syntax:

$$macro-idmacro-body$$
$$macro-id[arg1,arg2,...]macro-body...arg1...arg2$$
macro-id is a single character from the set `0' -- `9' , `a' -- `j'.
macro-body is any sequence of Cogsys commands
arg1, ... are macro arguments

System:

Defines the macro macro-id to be macro-body.

Test Files:

`MCDF_T01.IN'

tests basic operation

Examples:

input

$$aPress <return> to continue: #R$$ ... $a

cogsys

Defines the macro a. At the $a macro call, Cogsys prints `Press <return> to continue:' and waits for keypress.

input

$$1assigned$$ $$2given$$ $$a[name,num,mac]hello, name! You have been $mac number num.$$ ... $a[usman,3,2]#R

cogsys

Defines three maros, 1, 2, and a. The macro A takes three arguments, `name', `num', and `mac'. The `$a' call invokes the macro with the values `usman', `3' and `2', respectively. The expanded $a macro is:

hello, usman! You have been $2 number 3.

When Cogsys reaches the `$2', it will expand that into the the body of the $2 macro, `given'. Thus, the final output of Cogsys:

hello, usman! You have been given number 3.

This illustrates how parametric macros and nesting are a powerful combination that let you describe complex strings with only a few characters.