Macro Programming

Modern Syntax

The traditional WordPerfect macro language works really well for keystroke macros.

For advanced macro programs, it can be hard to read and error prone.

The mactool utility introduces an optional new macro syntax that attempts to solve some of these problems. It provides convenience functions that workaround known problems, and a more familiar syntax.

It also allows you to use a regular text editor, rather than using the limited built-in editor.

Statement	Is equivalent to...
$(name)	{VARIABLE}name~
require(STATE_NORMAL)	{IF}{STATE}&4=0~{QUIT}{END IF}
msgpos(x,y)	{^P}♪♣
attron(MSG_BOLD)	{^N}{^L}
$inc(name)	{ASSIGN}name~{VARIABLE}name~+1~

Examples

#include "macro.h"

#pragma title WordPerfect Sample Macro

/* Write out the digits 1 to 5 */
for (i, 1, 5, 1)
    `The value of i is $(i).`
    {enter}
endfor

/* Write out the numbers one to five */
foreach (i, `one`, `two`, `three`, `four`, `five`)
    `The value of i is $(i).`
    {enter}
endfor

/* Obligatory FizzBuzz */
for (i, 1, 100, 1)
    if ($(i) % 3 = 0)
        `Fizz`
    endif

    if ($(i) % 5 = 0)
        `Buzz`
    endif

    if (($(i) % 3 != 0) & ($(i) % 5 != 0))
        `$(i)`
    endif

    {enter}
endfor

There are more examples available in the macrotool directory.

Functions

In traditional macros, functions exist but there is no concept of return code or parameters, and although they can be declared anywhere, they're usually declared at the end to avoid an unwanted initial execution.

These problems have been mitigated in the modern syntax, where call() now allows parameters, and return() can include a value.

function(myfunction,
    $pop(message)
    `You passed: $(message)`
)

call(myfunction, `test`)

Quoting Rules

Whitespace

Space is not a whitespace character in traditional WordPerfect macros, but the new syntax changes that.

You can use spaces, tabs and newlines to format your code.

If you want a single literal space, you can write { }, if you want to spaces to be special again for a string, you can quote it in graves.

For example, `The spaces in this string will not be removed, $(variables) will be expanded`.

Parameters

If you want to pass a parameter to a function that contains commas, put extra parentheses around the argument.

For example, the call assign(var, hello, world) is incorrect because assign() only accepts two parameters.

The solution is to use extra parentheses around single parameters, assign(var, (hello, world)).

Comments

In traditional WordPerfect comments, the comment or ; command would be used. These are parsed on every invocation and have confusing quoting rules.

In the new rules, you can use standard c-style comments, /* */. These are removed at compile time.

Special Characters

To pass characters with special meaning, use braces. For example, {"}, {`}, {{}.

If you need to balance quotes to appease cpp, {""} is equivalent to {"}, they will both be replaced with " when compiled.

Pragma

You can set the macro title with #pragma title Macro Title.

Standard Library

If you want to use the modern syntax, you must #include "macro.h".

There are headers defining various constants and helper functions, such as system.h for working with {SYSTEM}, and keycodes.h for working with {KTON}.