com.codemesh.terp.eval
Class TerpParser

java.lang.Object
  com.codemesh.terp.eval.TerpParser

All Implemented Interfaces:

NodeTypes, TokenTypes

public class TerpParser
extends java.lang.Object
implements TokenTypes, NodeTypes

The parser that converts expression and template sources into abstract syntax trees. The TerpParser type is one of the central types you will interact with programmatically. Every source string/file/URI/URL/stream/reader needs to be parsed before it can be evaluated. Parsing is a costly activity. You should therefore try to ensure that you don't parse unnecessarily. You do not have to parse a template a thousand times if you expand it a thousand times with different variables; once is enough. You only need to reparse a template if the template contents have changed.

The TerpParser type maintains a relationship to the source of parsed content. It acts as both a utility type for the creation of parsed content and as a holder for the parsed content.

To improve performance further, you can avail yourself of its caching features by using one of its getParser() factory methods rather than a constructor. When you use a factory method and you use an input source with a quantifiable modification time or constant contents (e.g. String), TerpParser will check an internal cache for an already parsed copy. It will then return that copy rather than creating a new one. This can result in significant performance improvements when dealing with relatively constant template sources that might be used more than once but you cannot hold on to the parser instance in your own code.

The TerpParser type comes with plenty of convenience constructors to make instantiation as easy as possible. Normally, you will use TextTokenStreams to tokenize the text, so that is what all these convenience constructors will use internally. If you need to use a different tokenizer type you will need to use the general purpose constructor TerpParser(TokenStream).

Field Summary

protected TokenStream	input
protected Node	root
protected static java.util.Set<java.lang.String>	SCOPED_IDS
protected java.util.Stack<java.lang.String>	stackClosing
protected java.util.Stack<Node>	stackForeachParents
protected java.util.Stack<Node>	stackIfParents
protected java.util.Stack<Node>	stackSwitchParents

Fields inherited from interface com.codemesh.terp.api.TokenTypes

AMPER, ASS, AT, BACKSLASH, BEGIN_EMBEDDED, BOOLEAN, CHAR_LITERAL, CIRCON, COLON, COMMA, DIV, DIV_ASS, DOT, DOT2, DQUOTE, END_EMBEDDED, EOF, EQUALS, ERROR, EXCLAM, FILESEP, GE, GT, HASH, HIDDEN, ID, LBRACE, LCURLY, LE, LOG_AND, LOG_OR, LPAREN, LT, MATCH, MINUS, MINUS_ASS, MINUS2, MOD, MOD_ASS, MULT, MULT_ASS, NORMAL, NOT_EQ, NOT_MATCH, NULL, NUMERIC_LITERAL, PATHSEP, PLUS, PLUS_ASS, PLUS2, QUEST, QUOTE, RBRACE, RCURLY, RPAREN, SEMI, STATE_EMBEDDED, STATE_START, STRING_LITERAL, TEXT, TILDE, VERT, WS

Fields inherited from interface com.codemesh.terp.api.NodeTypes

ALTERNATIVE_NODE, ARGUMENTS_NODE, BITOP_AND, BITOP_NOT, BITOP_OR, BITOP_XOR, BLOCK_NODE, BOOLEAN_NODE, CHAR_NODE, COLLECTION_NODE, EMBEDDED_NODE, EMPTY_NODE, ERROR_NODE, EXPRESSION_NODE, FILESEP_NODE, FILTER_NODE, FOREACH_NODE, FORMATTER_NODE, FUNC_NODE, ID_NODE, IF_NODE, LOGOP_AND, LOGOP_NOT, LOGOP_OR, LVALUE_NODE, MACRO_NODE, MAP_NODE, METADATA_NODE, NAMED_NODE, NESTED_NODE, NULL_NODE, NUMERIC_NODE, OP_ASS, OP_CONDITIONAL, OP_DIV, OP_DIV_ASS, OP_MINUS, OP_MINUS_ASS, OP_MODULO, OP_MODULO_ASS, OP_MULT, OP_MULT_ASS, OP_NEG, OP_PLUS, OP_PLUS_ASS, OP_POSTDEC, OP_POSTINC, OP_PREDEC, OP_PREINC, PATHSEP_NODE, PROPERTY_NODE, QUALIFIER_NODE, RANGE_NODE, RELOP_EQ, RELOP_GE, RELOP_GT, RELOP_LE, RELOP_LT, RELOP_MATCH, RELOP_NE, RELOP_NOMATCH, ROOT_NODE, SCRIPT_KEEP_LAST_NODE, SCRIPT_NODE, SORTER_NODE, STRING_NODE, SWITCH_NODE, TEXT_NODE, TYPE_NODE

Constructor Summary

TerpParser(java.io.File source)
Creates a parser that reads from the given file and starts out in TokenizerState.TEXT state.

TerpParser(java.io.File source, java.lang.String encoding)
Creates a parser that reads from the given file in the given encoding and starts out in TokenizerState.TEXT state.

TerpParser(java.io.File source, java.lang.String encoding, TokenizerState state)
Creates a parser that reads from the given file in the given encoding.

TerpParser(java.io.File source, TokenizerState state)
Creates a parser that reads from the given file.

TerpParser(java.io.InputStream is)
Creates a parser that reads from the given stream and starts out in TokenizerState.TEXT state.

TerpParser(java.io.InputStream is, java.lang.String encoding)
Creates a parser that reads from the given stream in the given encoding and starts out in TokenizerState.TEXT state.

TerpParser(java.io.InputStream is, java.lang.String encoding, TokenizerState state)
Creates a parser that reads from the given stream in the given encoding.

TerpParser(java.io.InputStream is, TokenizerState state)
Creates a parser that reads from the given stream.

TerpParser(java.io.Reader r)
Creates a parser that reads from the given reader and starts out in TokenizerState.TEXT state.

TerpParser(java.io.Reader r, TokenizerState state)
Creates a parser that reads from the given reader.

TerpParser(java.lang.String input)
Creates a parser that reads from the given string and starts out in TokenizerState.TEXT state.

TerpParser(java.lang.String input, TokenizerState state)
Creates a parser that reads from the given string and starts out in the given tokenizer state.

TerpParser(TokenStream input)
The general purpose constructor that allows you to use any type of token stream, not just the default TextTokenStream.

TerpParser(java.net.URI sourceUri)
Creates a parser that reads from the given uri and starts out in TokenizerState.TEXT state.

TerpParser(java.net.URI sourceUri, java.lang.String encoding)
Creates a parser that reads from the given uri in the given encoding and starts out in TokenizerState.TEXT state.

TerpParser(java.net.URI sourceUri, java.lang.String encoding, TokenizerState state)
Creates a parser that reads from the given uri in the given encoding.

TerpParser(java.net.URI sourceUri, TokenizerState state)
Creates a parser that reads from the given uri.

TerpParser(java.net.URL sourceUrl)
Creates a parser that reads from the given url and starts out in TokenizerState.TEXT state.

TerpParser(java.net.URL sourceUrl, java.lang.String encoding)
Creates a parser that reads from the given url in the given encoding and starts out in TokenizerState.TEXT state.

TerpParser(java.net.URL sourceUrl, java.lang.String encoding, TokenizerState state)
Creates a parser that reads from the given url in the given encoding.

TerpParser(java.net.URL sourceUrl, TokenizerState state)
Creates a parser that reads from the given url.

Method Summary

protected Node	additive_expression()
protected Node	arguments()
protected Node	assignment_expression()
protected Node	bitwise_expression()
static void	clearCache() Forgets all cached parsers that had been acquired via one of the getParser() factory methods.
protected Node	comparison_expression()
protected Node	conditional_expression()
Node	createNode(int type, Token start, Token end)
protected boolean	embedded(Node parent, Token tokStart)
Node	evaluate()
Node	expand()
protected Node	expand(Node parent)
protected Node	expression_list()
protected Node	expression()
static TerpParser	getParser(java.io.File source) Returns a cached or newly created parser for the given file.
static TerpParser	getParser(java.io.File source, java.lang.String encoding) Returns a cached or newly created parser for the given file.
static TerpParser	getParser(java.io.File source, java.lang.String encoding, TokenizerState state) Returns a cached or newly created parser for the given file.
static TerpParser	getParser(java.io.File source, TokenizerState state) Returns a cached or newly created parser for the given file.
static TerpParser	getParser(java.lang.Object source, java.lang.String encoding, TokenizerState state, boolean bDummy)
static TerpParser	getParser(java.lang.String input) Returns a cached or newly created parser for the given input string.
static TerpParser	getParser(java.lang.String input, TokenizerState state) Returns a cached or newly created parser for the given input string.
static TerpParser	getParser(java.net.URI source) Returns a cached or newly created parser for the given uri.
static TerpParser	getParser(java.net.URI source, java.lang.String encoding) Returns a cached or newly created parser for the given uri.
static TerpParser	getParser(java.net.URI source, java.lang.String encoding, TokenizerState state) Returns a cached or newly created parser for the given uri.
static TerpParser	getParser(java.net.URI source, TokenizerState state) Returns a cached or newly created parser for the given uri.
Node	getRoot()
InputSource	getSource()
int	getTokenEnd()
protected boolean	isClosing(java.lang.String id)
protected Node	literal()
protected Node	logicalAnd_expression()
protected Node	logicalOr_expression()
protected Node	metadata()
protected Node	multiplicative_expression()
protected Node	named()
protected Node	parenthesized_expression()
protected Node	qualifiable()
protected Node	qualified()
protected Node	qualifier()
void	reset()
protected Node	unary_expression()
protected Node	unary()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

input

protected TokenStream input

root

protected Node root

stackClosing

protected final java.util.Stack<java.lang.String> stackClosing

stackIfParents

protected final java.util.Stack<Node> stackIfParents

stackForeachParents

protected final java.util.Stack<Node> stackForeachParents

stackSwitchParents

protected final java.util.Stack<Node> stackSwitchParents

SCOPED_IDS

protected static final java.util.Set<java.lang.String> SCOPED_IDS

Constructor Detail

TerpParser

public TerpParser(java.lang.String input)

Creates a parser that reads from the given string and starts out in TokenizerState.TEXT state.

Parameters:

input - the string to read from.

TerpParser

public TerpParser(java.lang.String input,
                  TokenizerState state)

Creates a parser that reads from the given string and starts out in the given tokenizer state.

Parameters:

input - the string to read from.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.io.File source)

Creates a parser that reads from the given file and starts out in TokenizerState.TEXT state.

Parameters:

source - the file to read from.

TerpParser

public TerpParser(java.io.File source,
                  TokenizerState state)

Creates a parser that reads from the given file.

Parameters:

source - the file to read from.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.io.File source,
                  java.lang.String encoding)

Creates a parser that reads from the given file in the given encoding and starts out in TokenizerState.TEXT state.

Parameters:

source - the file to read from.

encoding - the file encoding.

TerpParser

public TerpParser(java.io.File source,
                  java.lang.String encoding,
                  TokenizerState state)

Creates a parser that reads from the given file in the given encoding.

Parameters:

source - the file to read from.

encoding - the file encoding.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.net.URI sourceUri)

Creates a parser that reads from the given uri and starts out in TokenizerState.TEXT state.

Parameters:

sourceUri - the URI to read from.

TerpParser

public TerpParser(java.net.URI sourceUri,
                  TokenizerState state)

Creates a parser that reads from the given uri.

Parameters:

sourceUri - the URI to read from.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.net.URI sourceUri,
                  java.lang.String encoding)

Creates a parser that reads from the given uri in the given encoding and starts out in TokenizerState.TEXT state.

Parameters:

sourceUri - the URI to read from.

encoding - the content encoding.

TerpParser

public TerpParser(java.net.URI sourceUri,
                  java.lang.String encoding,
                  TokenizerState state)

Creates a parser that reads from the given uri in the given encoding.

Parameters:

sourceUri - the URI to read from.

encoding - the content encoding.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.net.URL sourceUrl)

Creates a parser that reads from the given url and starts out in TokenizerState.TEXT state.

Parameters:

sourceUrl - the URL to read from.

TerpParser

public TerpParser(java.net.URL sourceUrl,
                  TokenizerState state)

Creates a parser that reads from the given url.

Parameters:

sourceUrl - the URL to read from.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.net.URL sourceUrl,
                  java.lang.String encoding)

Creates a parser that reads from the given url in the given encoding and starts out in TokenizerState.TEXT state.

Parameters:

sourceUrl - the URL to read from.

encoding - the content encoding.

TerpParser

public TerpParser(java.net.URL sourceUrl,
                  java.lang.String encoding,
                  TokenizerState state)

Creates a parser that reads from the given url in the given encoding.

Parameters:

sourceUrl - the URL to read from.

encoding - the content encoding.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.io.InputStream is)

Creates a parser that reads from the given stream and starts out in TokenizerState.TEXT state.

Parameters:

is - the stream to read from.

TerpParser

public TerpParser(java.io.InputStream is,
                  TokenizerState state)

Creates a parser that reads from the given stream.

Parameters:

is - the stream to read from.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.io.InputStream is,
                  java.lang.String encoding)

Creates a parser that reads from the given stream in the given encoding and starts out in TokenizerState.TEXT state.

Parameters:

is - the stream to read from.

encoding - the content encoding.

TerpParser

public TerpParser(java.io.InputStream is,
                  java.lang.String encoding,
                  TokenizerState state)

Creates a parser that reads from the given stream in the given encoding.

Parameters:

is - the stream to read from.

encoding - the content encoding.

state - the tokenizer state to start in.

TerpParser

public TerpParser(java.io.Reader r)

Creates a parser that reads from the given reader and starts out in TokenizerState.TEXT state.

Parameters:

r - the reader to read from.

TerpParser

public TerpParser(java.io.Reader r,
                  TokenizerState state)

Creates a parser that reads from the given reader.

Parameters:

r - the reader to read from.

state - the tokenizer state to start in.

TerpParser

public TerpParser(TokenStream input)

The general purpose constructor that allows you to use any type of token stream, not just the default TextTokenStream.

Parameters:

input - the tokenizer that provides the parser with a stream of tokens.

Method Detail

getParser

public static TerpParser getParser(java.lang.String input)

Returns a cached or newly created parser for the given input string.

Parameters:

input - the string to read from.

Returns:

a cached or newly created parser for the string.

See Also:

an "overloaded" alternative for strings., to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.lang.String input,
                                   TokenizerState state)

Returns a cached or newly created parser for the given input string.

Parameters:

input - the string to read from.

state - the tokenizer state.

Returns:

a cached or newly created parser for the string.

See Also:

an "overloaded" alternative for strings., to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.io.File source)

Returns a cached or newly created parser for the given file.

Parameters:

source - the file to read from.

Returns:

a cached or newly created parser for the file.

See Also:

an "overloaded" alternative for files., to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.io.File source,
                                   TokenizerState state)

Returns a cached or newly created parser for the given file.

Parameters:

source - the file to read from.

state - the tokenizer state we start in.

Returns:

a cached or newly created parser for the file.

See Also:

to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.io.File source,
                                   java.lang.String encoding)

Returns a cached or newly created parser for the given file.

Parameters:

source - the file to read from.

encoding - the content encoding of the file.

Returns:

a cached or newly created parser for the file.

See Also:

to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.io.File source,
                                   java.lang.String encoding,
                                   TokenizerState state)

Returns a cached or newly created parser for the given file.

Parameters:

source - the file to read from.

encoding - the content encoding.

state - the tokenizer state we start in.

Returns:

a cached or newly created parser for the file.

See Also:

to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.net.URI source)

Returns a cached or newly created parser for the given uri.

Parameters:

source - the uri to read from.

Returns:

a cached or newly created parser for the uri.

See Also:

an "overloaded" alternative for uris., to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.net.URI source,
                                   TokenizerState state)

Returns a cached or newly created parser for the given uri.

Parameters:

source - the uri to read from.

state - the tokenizer state we start in.

Returns:

a cached or newly created parser for the uri.

See Also:

to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.net.URI source,
                                   java.lang.String encoding)

Returns a cached or newly created parser for the given uri.

Parameters:

source - the uri to read from.

encoding - the content encoding of the uri.

Returns:

a cached or newly created parser for the uri.

See Also:

to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.net.URI source,
                                   java.lang.String encoding,
                                   TokenizerState state)

Returns a cached or newly created parser for the given uri.

Parameters:

source - the uri to read from.

encoding - the content encoding.

state - the tokenizer state we start in.

Returns:

a cached or newly created parser for the uri.

See Also:

to clear the cache of remembered parsers.

getParser

public static TerpParser getParser(java.lang.Object source,
                                   java.lang.String encoding,
                                   TokenizerState state,
                                   boolean bDummy)

clearCache

public static void clearCache()

Forgets all cached parsers that had been acquired via one of the getParser() factory methods.

See Also:

getParser(String), getParser(String,TokenizerState)

getTokenEnd

public int getTokenEnd()

createNode

public Node createNode(int type,
                       Token start,
                       Token end)

getRoot

public Node getRoot()

isClosing

protected boolean isClosing(java.lang.String id)

reset

public void reset()

evaluate

public Node evaluate()

expand

public Node expand()

expand

protected Node expand(Node parent)

embedded

protected boolean embedded(Node parent,
                           Token tokStart)

metadata

protected Node metadata()

expression_list

protected Node expression_list()

expression

protected Node expression()

parenthesized_expression

protected Node parenthesized_expression()

assignment_expression

protected Node assignment_expression()

conditional_expression

protected Node conditional_expression()

logicalOr_expression

protected Node logicalOr_expression()

logicalAnd_expression

protected Node logicalAnd_expression()

comparison_expression

protected Node comparison_expression()

additive_expression

protected Node additive_expression()

multiplicative_expression

protected Node multiplicative_expression()

bitwise_expression

protected Node bitwise_expression()

unary_expression

protected Node unary_expression()

unary

protected Node unary()

qualified

protected Node qualified()

qualifier

protected Node qualifier()

qualifiable

protected Node qualifiable()

literal

protected Node literal()

arguments

protected Node arguments()

named

protected Node named()

getSource

public InputSource getSource()