swirl Guide to OmniMark 5   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesOMX VariablesErrors
 
    Related Syntax  
Input functions

You can use the keyword input in a do xml-parse or do sgml-parse to make the parser take its input from the output of a function:

  do xml-parse instance
   scan input parser-feeder
     output "%c"
  done

The function specified by input must not return a value. It must feed the parser by outputting markup. A new output scope is created for the function. That output scope is bound to the input of the parser. Anything output by the function, or by any code executed as a result of the function, goes to the parser (unless you change the current output scope). A function specified by input is called an "input function". Here is a sample:

  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 instance
      scan input parser-feeder
        output "<html><body>%c"
            || "</body></html>"
     done

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

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

In this example, the 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.

What is the advantage of using input over simply using a value returning function? Consider the following rewrite of the program above:

  define stream function parser-feeder as
     local stream parser-input
     open parser-input as buffer
     using output as parser-input
      do
        output "<greeting>"
        submit "Hello world."
        output "</greeting>"
      done
     close parser-input
     return parser-input

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

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

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

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

The function parser-feeder has become much more complex, and the entire text of the XML document is now being generated and buffered before parsing begins. Using input not only simplifies your input function, but it causes the input function to run cooperatively with the parser. That is, the parser asks the process started by the input function for a chunk of data, parses that data, and then asks for more. This continues until the parsing is complete. The full text generated by the input function is not buffered, which means you can process very large amounts of data without running into resource problems.

Other advantages of using input functions include:

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 rare cases you may experience problems with the use of input functions because of the way OmniMark coordinates the activities of the parser and the input function.

When you use an input function, 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:

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.

      Related Syntax
   do sgml-parse
   do xml-parse
 
----

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

Generated: August 11, 2000 at 3:06:22 pm
If you have any comments about this section of the documentation, send email to docerrors@omnimark.com

Copyright © OmniMark Technologies Corporation, 1988-2000.