define string source function

declaration/definition

Syntax
define string source function 
     function-name  function-argument-list
  (as function-body | elsewhere)

or

  define external string source function 
     function-name function-argument-list
  as external-name (in function-library library-name)?


Purpose

Defines a function that serves as a source of strings. This replaces define input function and define external source function from previous versions of OmniMark; those forms are now deprecated.

A string source function is like an ordinary action function, in that it does not return a value to its calling context. Instead, it generates strings by outputting them to the scope it is invoked from.

A return action without a value can be used to end a string source function; alternatively, the function can be allowed to fall off its end.

There is only one restriction on what can be done in the body of an internal string source function: #current-input is not attached at the beginning of the function. Most other operations are available.

Unlike an ordinary function, a string source function executes concurrently with its caller: its output is streamed incrementally to the calling context, without being buffered.

Invoking string source functions

A string source function is invoked by calling it in a context that requires a source of strings: output, using input repeat scan, submit, do xml-parse, and so on. For example, given a string source function called uppercase, it can be invoked as follows: 

       define string source function uppercase (value string source s) elsewhere
  
       process
          repeat scan uppercase (file "input.txt")
          match white-space+
             output "%n"
  
          match [any \ white-space]+ => t
             output t
          again

String source functions as filters

A filter can be written using a string source function that takes an argument of type value string source. The string source function scans its value string source argument, performs any filtering operations necessary, and outputs the filtered data on its #current-output.

For example, the string source function uppercase mentioned above might be implemented as 

       define string source function
          uppercase (value string source s)
       as
          repeat scan s
          match letter+ => t
             output "ug" % t
  
          match [any \ letter]+ => t
             output t
          again

uppercase filters its value string source argument s using a repeat scan loop, generating an uppercased version of the same string, which can, in turn, be used in pattern matching by the caller.

Related Syntax
Related Concepts