Input functions and the markup parser

You can use an input function to generate or pre-process markup that is to be sent to a parser. When an input function is called in a parse context, the input function and the parser run as co-routines. That is, the input function is executed incrementally and streams its output to the parser incrementally. Execution passes back and forth between the parser and the input function until the entire input has been processed. This avoids buffering the entire output of the input function before the parser starts. This saves computer resources and improves performance. You can process very large amounts of data without running into resource problems.

In the following example, the input function parser-feeder generates an XML document by submitting a source. The markup is generated partly in the function itself and partly by find rules fired as a result of the submit statement. The output of the function and the find rules becomes the input to the parser. Element rules then transform the XML into HTML.

  define input function parser-feeder as
     output "<greeting>"
     submit "Hello world."
     output "</greeting>"

  find "world" => planet-name
     output "<planet>"
         || planet-name
         || "</planet>"

  process
     do xml-parse
      scan parser-feeder
        output "<html><body>%c"
            || "</body></html>"
     done

  element "greeting"
     output "<P>%c</P>"

  element "planet"
     output "<B>%c</B>"

Other advantages of using input functions include:

It allows the parser to report errors in generated markup as that markup is generated, allowing you to use the parser to simplify error detection and correction in programs that generate markup.
It allows you to use the current state of the parse tree (as expressed in the execution state of the markup rules) to guide markup generation, allowing you to do context-sensitive markup building.

The aided translation types up-translate and context-translate both involve the use of implicit input functions to feed data generated by find rules to the parser.

Debugging input functions in a parser context

In rare cases you may experience problems with the use of input functions in a parser context because of the way OmniMark coordinates the activities of the parser and the input function.

When you use an input function to feed the parser, you have two processes running cooperatively within a single program. OmniMark runs each process in a separate processing domain. Some resources are owned by one domain or the other, while others are shared between the two domains.

If you experience an error in a program that uses input functions, the answer may be found in the following:

Each domain has its own groups. Changing groups in one domain does not affect the active groups in the other domain.
save and save-clear operations must nest properly. Because domains are parallel, and not nested within each other, a save in one domain may not be properly nested with respect to a save of the same variable in the other domain.
The domain of the input function cannot invoke the parser. Thus you must use do xml-parse and do sgml-parse in an input function called in a parser context or in any functions or find rules fired as a result of the input function.
You can only use using nested-referents in one domain at a time. In no circumstance can you output referents to the parser itself.
Stream variables are opened only in the domain that opened them. If you want the domain of the input function to be able to write to a stream opened in the domain of the parser (or vice versa), you need to open that stream with the domain-free modifier.

Note that it may not always be obvious which co-routine a certain piece of code is running in. For instance, a find rule could be fired either by a submit in an input function or by a submit in an element rule. That rule would be running in one domain in the first case and in the other domain in the second case.

If you write code that depends on the timing of the switching between the input function and the parser, you may need to be aware of the rules OmniMark uses when switching domains.

In general, OmniMark switches domains at its own discretion. You cannot control the switch, but you may be able to write a test in one domain to see where the other domain is up to. For instance, in the input function, you can test to determine what the current element is in the domain of the parser using the element is test.
There is guaranteed to be a domain switch at the end of an output statement that writes to the stream bound to the parser (the #markup-parser stream, which is the destination of the output scope created by input), except as follows.
There is guaranteed not to be a domain switch in the domain of the input function for the duration of a repeat over loop or a using block applied to the attributes shelf, the data-attributes shelf, or a list-valued attributes shelf.

The old form of input function

In versions of OmniMark prior to version 7, an input function was an action function which was called as an input function by adding the keyword input to the parser invocation:

  define function parser-feeder as
     output "<greeting>"
     submit "Hello world."
     output "</greeting>"

  find "world" => planet-name
     output "<planet>"
         || planet-name
         || "</planet>"

  process
     do xml-parse
      scan input parser-feeder
        output "<html><body>%c"
            || "</body></html>"
     done

  element "greeting"
     output "<P>%c</P>"

  element "planet"
     output "<B>%c</B>"

This form is deprecated but is supported for backward compatibility.

Prerequisite Concepts
   Data types
   Functions
Related Syntax
   do markup-parse
   do sgml-parse
   do xml-parse

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]

OmniMark 7.1.2 Documentation Generated: June 28, 2005 at 5:44:37 pm
If you have any comments about this section of the documentation, send email to [email protected]

Copyright © Stilo Corporation, 1988-2005.