Functions

[Previous] [Next]

Like most languages, OmniMark supports functions. Unlike many languages, however, an OmniMark program is not simply a hierarchy of functions. Rules are the principal structural element of OmniMark programs; functions are supplementary structures. Functions cannot contain rules (though functions can invoke rules through submit, do xml-parse, and do sgml-parse). You can use functions to encapsulate code that you use commonly within different rule bodies. You can also use functions as pattern-matching functions or within patterns to dynamically define a pattern you want to match.

Functions isolate sections of code, but they don't isolate you from the current environment, in particular from the current output scope. Output in a function goes to the current output scope. If a function has a return value, that value goes to the calling action. If a function changes the destination of the current output scope (with output-to), this destination change carries over to the calling environment.

A function that returns a value is defined as follows:

 define integer function add (value integer x, value integer y) as return x + y 

The return type of the function is declared following the define keyword. The return type can be any OmniMark variable type or any OMX component type. The value is returned using the return keyword, which also exits the function.

Here is how you can call the add function.

 process output "d" format add(2,3) 

Functions can generate output. The following function outputs the value it generates rather than returning it to the calling action. Note that this function has no return type in the definition; no return is required.

 define function output-sum (value integer x, value integer y )as output "d" format (x + y) 

This function is called as if it were a regular OmniMark action.

 process output-sum(2, 3) 

You can also write functions that both return a value and do output.

 define integer function add (value integer x, value integer y )as output "I will add %d(x) and %d(y)%n" return x + y process local integer z set z to add(2,3) output "%d(z)%n" 

While it is certainly possible to program this way, I recommend that you avoid writing functions that both do output and return a value. Not only do they make it hard to follow your code, but they can also have unexpected results. For example, if the return value is directed to current output, you might not get the function's return values nor output in the order you expect.

You can also write functions that neither return a value nor create output. The following function clears all the switches on a switch shelf that is passed to it as a modifiable argument:

 define function clear-flags (modifiable switch the-flags ) as repeat over the-flags set the-flags to false again 

Everything that you can do in the rule that calls a function you can do in the function itself. For example, a function can use the %c parse continuation operator when called from a markup rule. The most useful application of this feature is the ability to write a function that does generic processing on a class of markup element types.

The current input and output scopes apply to code within a function just as they apply to code in the rule (or function) that called the function.