C. Understanding Macro Interfaces

C.1. Overview

General Syntax

The general syntax for using this macro is shown first, including the order of the arguments, if any.

Arguments

If a macro has one or more arguments, these are listed in a table containing the following columns:

Name - the argument name
Type - the argument type
Default - the default value, if any
Rule - the pattern, if any, used to validate the value.

Argument Types

The supported set of argument types are:

Type	Description
Common:
string	a string
integer	an integer
boolean	either 1 or 0
Special:
symbol	a symbolic name
filter	a filter name
rest	the rest of the arguments
eventid	an event tag
condition	a logical expression

The special types are needed for some of SDF's built-in macros including define, include, on and if - they are rarely needed for normal macros.

Default Values

For default values within argument tables:

the empty string means there is no default
the symbol _NULL_ means the default is the empty string.

C.2. Rules

Rule Types

If you wish, arguments can be validated using a rule. Rules are either:

A pattern is a Perl regular expression which the argument value is matched against. Patterns are enclosed in angle brackets to differentiate them from normal Perl expressions. Typical patterns are given in the table below.

Pattern	Explanation
<\w+>	one or more characters in A-Z, a-z, 0-9 and '_'
<\d{4}>	a 4 digit number
<on\|off>	a string which is either "on" or "off"
<XMIT-.*>	a string which begins with "XMIT-"

General Perl Expressions

More complex rules are required when:

the regular expression does not apply to the whole value
the regular expression is case-insensitive.

In these cases, a general Perl expression can be used as the rule. Within the expression, $_ is the value of the argument. Examples are:

Expression	Explanation
/\d/	a digit exists somewhere in the string
/^(on\|off)$/i	value is either "on" or "off" (case insensitive)

Note: A pattern is simply a short-hand notation for the general Perl expression below:

        /^(pattern)$/

Pattern notation is provided as it makes rules easier to read and write. (Pattern-style validation typically covers 80% or more of validation rules so improving the readability of patterns has a large impact on the overall readability.)