declaration/definition
macro macro-name ( (arg argument-name delimiter) | (token argument-name delimiter?))* is macro-body macro-end
Argument definitions
Defines a macro.
Macros are used for two purposes -- to define constants and to extend the language. Defining constants is simple:
macro five is 5 macro-end macro mary is "Mary had a little lamb%n" macro-end macro tom tom is "Tom, Tom, the piper's son.%n" macro-end find mary local integer x initial {five} output "%d(x)%n" output tom tom
Notice that a macro name can contain spaces, as in "tom tom" above.
The sample above shows that a constant defined by a macro can be used either as a text or number replacement or as a pattern. You can also include patterns in a constant to form a new pattern. This is the simplest form of extending the language. Here the pattern for finding valid SGML names is encapsulated by a macro:
macro sgml-name is (letter [letter | digit | "-."]*) macro-end
Note the parentheses around the pattern elements in the macro. These are not required to define the macro, but they are a useful idea because they ensure that the new pattern will be treated as a single unit when the macro is expanded. Among other benefits, this ensures that sgml-name => name will work as you expect.
Extending the language becomes a little more complex if you need to add parameters to your macros. One extension is the "delimited-string" macro which finds a string between two delimiters that you specify. It is defined:
; delimited-string.xom
macro delimited-string (arg open-d, arg close-d) is
((open-d) any** (close-d))
macro-end
process
submit "[we dropped freddy (the rat) off the fire escape] into the alley with military honors."
find delimited-string("[", "]") => body
output "Body = " || body || "END-OF-STRING%n"
; Output: "Body = [we dropped freddy (the rat) off the fire escape]END-OF-STRING
; into the alley with military honors.']
This macro illustrates several important points about macros. First of all, the name of this macro is not actually "delimited-string", but "delimited-string(". The parentheses are not part of OmniMark's syntax for defining macros, they are actually part of the syntax of the macro being defined.
So what about the closing parenthesis? It is the delimiter of the second parameter, close-d, which is defined by the keyword arg. In the case of the delimited-string macro a delimiter is needed, since the pattern passed to it could be complex and contain spaces:
delimited-string("[START QUOTE]", "[END QUOTE]")
If you define a macro with multiple parameters you can do it like this, using traditional parentheses and commas for delimiters:
macro sum ( arg n1, arg n2, arg n3) is
n1 + n2 + n3
macro-end
process
local integer n
set n to sum (1, 2, 3)
But you can also define a macro using any delimiters you like, including ones that contain spaces:
macro sum > arg n1 big dog arg n2 / arg n3 ! is n1 + n2 + n3 macro-end process local integer n set n to sum >1 big dog 2/ 3!
The above code works but its meaning is not very clear. There are ways to make your language extensions clearer by using appropriate words or punctuation as delimiters:
macro sum arg n1 and arg n2 and token n3 is (n1 + n2 + n3) macro-end process local integer n set n to sum 12 and 52 and 37This code introduces a new way to parameterize a macro -- the
token keyword. When using "and" as a delimiter you obviously don't want a delimiter after the last parameter. To define a macro without a following delimiter, you can use token instead of arg.
As its name implies, a token parameter can only be a single token -- a sequence of characters with no spaces, or a quoted string. The purpose of providing both "token" and "arg" parameterization is to allow you maximum flexibility in defining your language extensions. It has no effect on what kind on parameter you pass to a macro or how that parameter is used in the body of the macro. You are not prohibited from using a delimiter with a "token" argument, but it is not required.
There is one other important difference between "arg" and "token" parameterization. Parameters declared with arg may contain names of other macros, which will be expanded in the present macro. Parameters declared with token may be macro names, but will not be treated as such. Thus, you could pass a macro that expressed a complex pattern to the "upto" macro:
macro at-dollar is ("@" letter+ "$") macro-end
find "xyz" upto ( at-dollar )
But if "upto" were defined (less usefully) as taking a token argument, this would not work:
macro upto token pat is
((lookahead not (pat)) any)+
macro-end
macro at-dollar is "@" letter+ "$" macro-end
find "xyz" upto at-dollar ;error!
You can use a format item to insert a macro argument into a string using the "@" format command:
macro discontent token season is
"Now is the %@(season) of our discontent"
macro-end
process
output discontent "winter"
You can use the format modifiers "u" and "l" to force the text of the argument to uppercase and lowercase respectively.
The following restrictions apply to macro use:
Where two macros have names which start with the same word or words, the longer name will always be matched if possible. Thus, given:
macro go ... macro sleep ... macro go to ... macro to sleep ... process go to sleep go sleepthe sequence
go to sleep will invoke the "go to" macro, followed by the "sleep" macro, not "go" followed by "to sleep". The sequence go sleep will invoke the "go" macro followed by the "sleep" macro.
Macros cannot represent partial names. Consider a program that uses long integer names like chapternumber, figurenumber, and contains the following macro definitions:
macro chp is chapter macro-end macro num is number macro-end
The name chpnum is not a substitute for chapternumber.
Macros cannot be redefined. Once a macro name has been defined, another macro cannot be defined with the same name in the same OmniMark program. Attention has been paid to this requirement when an include declaration is used to combine macro definitions from different sources in a single OmniMark program.