 |
 |
|
|
       |
|||
|
|||||||||
|
|
|||||||||
| 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
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
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
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.
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:
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.
do xml-parse and do sgml-parse in an input function or in any functions or find rules fired as a result of an input function.
using nested-referents in one domain at a time. In no circumstance can you output referents to the parser itself.
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.
element is test.
#markup-parser stream, which is the destination of the output scope created by input), except as follows.
repeat over loop or a using block applied to the attributes shelf, the data-attributes shelf, or a list-valued attributes shelf.
|
Related Syntax do sgml-parse do xml-parse |
| ---- |
