B. Understanding Filter Interfaces

B.1. Overview

General Syntax

The general syntax for using each filter is shown first. By convention, the filter is shown using the block and endblock macros, although filters can also be used with other macros, including include and execute.

Parameters

If a filter has one or more optional parameters, these are listed in a table containing the following columns:

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

Parameter Types and Rules

Parameter types and rules follow the same conventions as macro argument types and rules. Refer to Understanding Macro Interfaces for details.

B.2. Data Tables

Table Fields

Providing data to a filter via a table is a common idiom in SDF as using tables makes it easy to add additional columns later on.

If a filter expects a table of data in TBL format, the fields in the table of data are listed in a table containing the following columns:

Field - the field name
Category - key, mandatory or optional
Rule - the pattern, if any, used to validate the value.

Table Field Categories

The supported table field categories are explained below.

Category	Description
key	a unique value must be provided for each row
mandatory	a value must be provided for each row
optional	a value is optional

Validating Table Fields

As validating table fields can reduce performance quite a bit, the sdf program doesn't validate them by default. To enable table field validation, use the -v option like this:

  sdf -v99 ...

Typically, this is only needed when a filter isn't working as you'd expect.