Filter functions

A filter function is an idiom that comes up often in OmniMark programs: it is a function that transforms data from one form to another. In OmniMark, filter functions can be implemented as data sources that can be scanned, or as data targets that can be written to.

Two types are allowed to be specified for function arguments types and function return types: string source and string sink.

A string source argument can be passed anything that can be scanned, including calls to other string source functions. A string source argument allows read-in data to be converted by the function, and the converted data to be used as an input. Amongst other things, it can be passed to another filter function: they can be chained together.

A string sink argument does the same thing as a string source argument in the other direction: it can be any use of file or a call to a string sink function of the sort that is allowed on the right-hand-side of an open action, following as.

string source and string sink arguments must be value arguments.

Whether a given filter is written as a string source function or as a string sink filter is largely a matter of preference, although occasionally the transformation is more obvious or simpler in one form versus the other. However, given any filter function of one form, an equivalent filter function of the other form can readily be written. For example, given

  define string source function 
     reader (value string source s)
  as
     ; ...

we can write a string sink version as

  define string sink function
     writer (value string sink s)
  as
     using output as s
        output reader (#current-input)

Similarly, given

  define string sink function
     writer (value string sink s)
  as
     ; ...

we can write a string source version as

  define string source function
     reader (value string source s)
  as
     using output as writer (#current-output)
        output s

So, although the implementation of a transformation may lend itself more to one form versus the other, in reality the two forms are equivalent, and the above re-writings can be used to provide the other form given the one.