org.webmacro.engine
Interface Parser

All Known Implementing Classes:
NullParser, TextParser, WMParser

public interface Parser

A parser turns an input stream into a BlockBuilder, using any parsing mechanism that it chooses. It closes the input stream after parsing its contents.

A Parser must also have a single argument constructor, where the single argument is an object of type Broker. This allows the parser to query the broker for any modules or other things it may need to load (for example, Directives). The constructor signature must look like this:

    public SomeParser(Broker broker) throws InitException
 
. A Parser may throw an InitException if it cannot load things it needs using the Broker.

At runtime, a Parser may be used many times, simultaneously, to parse many templates. It must therefore be threadsafe. The recommended way to make a parser threadsafe is to have it not use any class variables, but rely completely on passing data it needs through arguments--this can be done fairly conveniently in a recursive decent parser.

When designing a Parser and its corresponding Builders, bear in mind the following WebMacro design decision: It is acceptable to sacrifice parsing speed in order to speed up runtime execution of a block, since a template is typically parsed just once, but executed manyt imes. Thus, do not optimize your parser in ways that make it difficult to optimize the resulting execution tree.


Method Summary
 BlockBuilder parseBlock(java.lang.String name, java.io.Reader in)
          Parse the input in ParseTool as far as the grammar for this parser allows, but no farther.
 

Method Detail

parseBlock

public BlockBuilder parseBlock(java.lang.String name,
                               java.io.Reader in)
                        throws ParseException,
                               java.io.IOException
Parse the input in ParseTool as far as the grammar for this parser allows, but no farther.

Throws:
ParseException
java.io.IOException