swirl
Guide to OmniMark 9   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesLegacy LibrariesErrors
 
  Related Syntax   Related Concepts  
declaration/definition  

define string source function

 
 

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
 
 

Top [ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]

OmniMark 9.1.0 Documentation Generated: September 2, 2010 at 1:51:21 pm
If you have any comments about this section of the documentation, please use this form.

Copyright © Stilo International plc, 1988-2010.