freemarker.template.compiler
Class StandardTemplateParser

java.lang.Object
  |
  +--freemarker.template.compiler.StandardTemplateParser
All Implemented Interfaces:
TemplateParser

public class StandardTemplateParser
extends java.lang.Object
implements TemplateParser

Parses standard template language and generates Instructions. Uses ExpressionBuilder to build expressions.

Version:
$Id: StandardTemplateParser.java,v 1.64 2003/11/27 08:10:38 run2000 Exp $

Field Summary
protected static java.lang.String ASSIGN_TAG
           
protected static char BOOLEAN_ESCAPE_CHAR
           
protected static java.lang.String BREAK_TAG
           
protected static java.lang.String CALL_TAG
           
protected static java.lang.String CASE_TAG
           
protected static java.lang.String COMMENT_END_TAG
           
protected static java.lang.String COMMENT_TAG
           
protected static java.lang.String DEFAULT_TAG
           
protected static char DOUBLE_QUOTE_CHAR
           
protected static java.lang.String ELSE_IF_TAG
           
protected static java.lang.String ELSE_TAG
           
protected static char END_TAG_START_CHAR
           
protected static char ESCAPE_CHAR
           
protected static java.lang.String FALSE_LITERAL
           
protected static java.lang.String FOREACH_END_TAG
           
protected static java.lang.String FOREACH_INDEX_KEYWORD
           
protected static java.lang.String FOREACH_TAG
           
protected  int foundPos
          The position at which the current instruction was found.
protected static java.lang.String FUNCTION_END_TAG
           
protected static java.lang.String FUNCTION_TAG
           
protected static char HASH_LITERAL_END_CHAR
           
protected static char HASH_LITERAL_START_CHAR
           
protected static java.lang.String IF_END_TAG
           
protected static java.lang.String IF_TAG
           
protected static java.lang.String INCLUDE_TAG
           
protected static java.lang.String LIST_END_TAG
           
protected static java.lang.String LIST_INDEX_KEYWORD
           
protected static char LIST_LITERAL_END_CHAR
           
protected static java.lang.String LIST_LITERAL_RANGE
           
protected static char LIST_LITERAL_START_CHAR
           
protected static java.lang.String LIST_TAG
           
protected static int LONG_OPERATOR_LENGTH
          Length of operators that are more than one character long.
protected  Instruction nextFMInstruction
          The next non-text instruction found by the parser.
protected static java.lang.String NOPARSE_TAG
           
protected static java.lang.String NOPARSE_TAG_END
           
protected  int parsePos
          The current parse position.
protected  int previousParsePos
          The parse position before the current instruction was found.
protected static char QUOTE_CHAR
           
protected static java.lang.String SWITCH_END_TAG
           
protected static java.lang.String SWITCH_TAG
           
protected static char TAG_END_CHAR
           
protected static char TAG_START_CHAR
           
protected  FunctionTemplateProcessor template
          The Template being parsed.
protected  java.lang.String text
          The text to be parsed.
protected  int textLen
          The number of characters in the text.
protected static java.lang.String TRANSFORM_END_TAG
           
protected static java.lang.String TRANSFORM_TAG
           
protected static java.lang.String TRUE_LITERAL
           
protected static char VAR_INSTR_END_CHAR
           
protected static char VAR_INSTR_START_CHAR
           
protected static java.lang.String VAR_INSTR_START_CHARS
           
 
Constructor Summary
StandardTemplateParser()
          Default constructor.
StandardTemplateParser(FunctionTemplateProcessor template, java.lang.String text)
          Constructs a new StandardTemplateParser with the given template and text to be parsed.
 
Method Summary
 java.lang.String atChar()
          Adds text to an error message indicating the line number where the error was found.
protected  java.lang.String atChar(int pos)
          Adds text to an error message indicating the line number where the error was found.
protected  boolean findTagEnd()
          Requires a TAG_END_CHAR, optionally preceded by whitespace, and advances parsePos after the TAG_END_CHAR.
protected  void findTagNameEnd()
          Advances parsePos through any remaining alphanumeric characters.
 Instruction getNextInstruction()
          Searches the text for an instruction, starting at the current parse position.
protected  Instruction getNextInstructionTag()
          Searches the text for a tagged instruction, starting at the current parse position.
protected  boolean isIdentifierStartChar(char c)
          Determines whether a character is legal at the start of an identifier.
 boolean isMoreInstructions()
          Are there any more instructions left to be parsed?
protected  AssignInstruction parseAssign()
          Parses an AssignInstruction's tag.
protected  boolean parseBinaryElement(java.util.List elements)
          Parse an optional binary element.
protected  BooleanLiteral parseBooleanLiteral()
          Parses a BooleanLiteral.
protected  CallInstruction parseCall()
          Parses a CallInstruction's tag.
protected  CaseInstruction parseCase()
          Parses a CaseInstruction's tag.
protected  CommentInstruction parseComment()
          Parses a CommentInstruction's tag.
protected  DefaultCaseInstruction parseDefault()
          Parses a default CaseInstruction's tag.
protected  Dot parseDot()
          Parses the Dot operator.
protected  DynamicKeyName parseDynamicKeyName()
          Parses a DynamicKeyName.
protected  java.util.List parseElements()
          Retrieve the next ExpressionElement(s) following parsePos.
protected  ElseInstruction parseElse()
          Parses an IfInstruction <else> tag.
protected  IfInstruction parseElseIf()
          Parses an IfInstruction <elseif> tag.
protected  Expression parseExpression()
          Parses and builds an Expression, which may also be a sub-expression.
protected  ListInstruction parseForeachStart()
          Parses a ListInstruction's start tag with the "foreach" keyword.
protected  FunctionInstruction parseFunction()
          Parses a FunctionInstruction's tag.
protected  HashLiteral parseHashLiteral()
          Parses a HashLiteral.
protected  Identifier parseIdentifier()
          Tries to parse an Identifier.
protected  IfElseInstruction parseIfStart()
          Parses an IfElseInstruction's start tag.
protected  IncludeInstruction parseInclude()
          Parses an IncludeInstruction's tag.
protected  Expression parseListLiteral()
          Parses a ListLiteral.
protected  ListInstruction parseListStart()
          Parses a ListInstruction's start tag.
protected  MethodCall parseMethodCall()
          Parses a MethodCall.
protected  NoParseInstruction parseNoparseStart()
          Parses a NoParseInstruction's tag.
protected  NumberLiteral parseNumberLiteral()
          Parses a NumberLiteral.
protected  StringLiteral parseStringLiteral()
          Parses a StringLiteral.
protected  SwitchInstruction parseSwitch()
          Parses a SwitchInstruction's tag.
protected  TransformInstruction parseTransformStart()
          Parses a TransformInstruction's tag.
protected  Variable parseVariable()
          Parses an Expression and ensures that it's a Variable.
protected  ExpressionElement parseVariableElement()
          Retrieve the next ExpressionElement following parsePos, and ensure its a Variable.
protected  VariableInstruction parseVariableInstruction()
          Parses a VariableInstruction.
protected  Expression parseVariableOrList()
          Parses either a variable name or a list literal.
protected  void requireChar(char c)
          Requires a given character, optionally preceded by by whitespace.
protected  void requireWhitespace()
          Advances parsePos beyond required whitespace.
 void setTemplate(FunctionTemplateProcessor template)
          Sets the template to receive the parsed instructions.
 void setText(java.lang.String text)
          Sets the text to be parsed.
protected  boolean skipChar(char c)
          Advances beyond any whitespace; then, if the next character matches a given character, advances beyond it and returns true, otherwise returns false.
protected  boolean skipKeyword(java.lang.String keyword)
          Skip over a given keyword.
 java.lang.String skipToEndInstruction(ContainerInstruction beginInstruction)
          Searches the text for a matching end instruction, starting at the current parse position.
protected  void skipWhitespace()
          Advances parsePos beyond any whitespace.
 java.lang.String toString()
          Returns a string representation of the object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

text

protected java.lang.String text
The text to be parsed.

textLen

protected int textLen
The number of characters in the text.

template

protected FunctionTemplateProcessor template
The Template being parsed.

parsePos

protected int parsePos
The current parse position.

previousParsePos

protected int previousParsePos
The parse position before the current instruction was found.

foundPos

protected int foundPos
The position at which the current instruction was found.

nextFMInstruction

protected Instruction nextFMInstruction
The next non-text instruction found by the parser.

VAR_INSTR_START_CHARS

protected static final java.lang.String VAR_INSTR_START_CHARS

VAR_INSTR_START_CHAR

protected static final char VAR_INSTR_START_CHAR

VAR_INSTR_END_CHAR

protected static final char VAR_INSTR_END_CHAR

LIST_TAG

protected static final java.lang.String LIST_TAG

LIST_INDEX_KEYWORD

protected static final java.lang.String LIST_INDEX_KEYWORD

LIST_END_TAG

protected static final java.lang.String LIST_END_TAG

IF_TAG

protected static final java.lang.String IF_TAG

ELSE_TAG

protected static final java.lang.String ELSE_TAG

ELSE_IF_TAG

protected static final java.lang.String ELSE_IF_TAG

IF_END_TAG

protected static final java.lang.String IF_END_TAG

SWITCH_TAG

protected static final java.lang.String SWITCH_TAG

SWITCH_END_TAG

protected static final java.lang.String SWITCH_END_TAG

CASE_TAG

protected static final java.lang.String CASE_TAG

BREAK_TAG

protected static final java.lang.String BREAK_TAG

DEFAULT_TAG

protected static final java.lang.String DEFAULT_TAG

ASSIGN_TAG

protected static final java.lang.String ASSIGN_TAG

INCLUDE_TAG

protected static final java.lang.String INCLUDE_TAG

FUNCTION_TAG

protected static final java.lang.String FUNCTION_TAG

FUNCTION_END_TAG

protected static final java.lang.String FUNCTION_END_TAG

CALL_TAG

protected static final java.lang.String CALL_TAG

TAG_START_CHAR

protected static final char TAG_START_CHAR

TAG_END_CHAR

protected static final char TAG_END_CHAR

END_TAG_START_CHAR

protected static final char END_TAG_START_CHAR

QUOTE_CHAR

protected static final char QUOTE_CHAR

DOUBLE_QUOTE_CHAR

protected static final char DOUBLE_QUOTE_CHAR

ESCAPE_CHAR

protected static final char ESCAPE_CHAR

BOOLEAN_ESCAPE_CHAR

protected static final char BOOLEAN_ESCAPE_CHAR

LIST_LITERAL_START_CHAR

protected static final char LIST_LITERAL_START_CHAR

LIST_LITERAL_END_CHAR

protected static final char LIST_LITERAL_END_CHAR

HASH_LITERAL_START_CHAR

protected static final char HASH_LITERAL_START_CHAR

HASH_LITERAL_END_CHAR

protected static final char HASH_LITERAL_END_CHAR

LIST_LITERAL_RANGE

protected static final java.lang.String LIST_LITERAL_RANGE

COMMENT_TAG

protected static final java.lang.String COMMENT_TAG

COMMENT_END_TAG

protected static final java.lang.String COMMENT_END_TAG

NOPARSE_TAG

protected static final java.lang.String NOPARSE_TAG

NOPARSE_TAG_END

protected static final java.lang.String NOPARSE_TAG_END

FOREACH_TAG

protected static final java.lang.String FOREACH_TAG

FOREACH_INDEX_KEYWORD

protected static final java.lang.String FOREACH_INDEX_KEYWORD

FOREACH_END_TAG

protected static final java.lang.String FOREACH_END_TAG

TRANSFORM_TAG

protected static final java.lang.String TRANSFORM_TAG

TRANSFORM_END_TAG

protected static final java.lang.String TRANSFORM_END_TAG

TRUE_LITERAL

protected static final java.lang.String TRUE_LITERAL

FALSE_LITERAL

protected static final java.lang.String FALSE_LITERAL

LONG_OPERATOR_LENGTH

protected static final int LONG_OPERATOR_LENGTH
Length of operators that are more than one character long.
Constructor Detail

StandardTemplateParser

public StandardTemplateParser()
Default constructor.

StandardTemplateParser

public StandardTemplateParser(FunctionTemplateProcessor template,
                              java.lang.String text)
Constructs a new StandardTemplateParser with the given template and text to be parsed.
Parameters:
template - a new template that will received the parsed instructions
text - the text to be parsed
Method Detail

setText

public void setText(java.lang.String text)
Sets the text to be parsed.
Parameters:
text - the text to be parsed.

setTemplate

public void setTemplate(FunctionTemplateProcessor template)
Sets the template to receive the parsed instructions.
Parameters:
template - the template being parsed.

getNextInstruction

public Instruction getNextInstruction()
                               throws ParseException

Searches the text for an instruction, starting at the current parse position. If one is found, parses it into an Instruction. Before changing parsePos, sets previousParsePos = parsePos.

If no instruction is found, leaves parsePos unchanged.

Specified by:
getNextInstruction in interface TemplateParser
Returns:
a Instruction representing the next instruction following parsePos, or null if none is found.
Throws:
ParseException - the next instruction couldn't be parsed

getNextInstructionTag

protected Instruction getNextInstructionTag()
                                     throws ParseException

Searches the text for a tagged instruction, starting at the current parse position. If one is found, parses it into a Instruction. Before changing parsePos, sets previousParsePos = parsePos.

If no instruction is found, parsePos will be equal to textLen, which will be equal to foundPos.

Returns:
a Instruction representing the next instruction following parsePos, or null if none is found.
Throws:
ParseException - the next instruction couldn't be parsed

isMoreInstructions

public boolean isMoreInstructions()
Are there any more instructions left to be parsed?
Specified by:
isMoreInstructions in interface TemplateParser
Returns:
true if there is more text to parse, otherwise false

skipToEndInstruction

public java.lang.String skipToEndInstruction(ContainerInstruction beginInstruction)

Searches the text for a matching end instruction, starting at the current parse position. If we find it, parse it and return. Before changing parsePos, should set previousParsePos = parsePos.

If no instruction is found, set parsePos to textLen which equals foundPos.

Specified by:
skipToEndInstruction in interface TemplateParser
Returns:
a String containing the intermediate text if we find the end instruction we're after, otherwise null

atChar

public java.lang.String atChar()
Adds text to an error message indicating the line number where the error was found.
Specified by:
atChar in interface TemplateParser
Returns:
a String containing the message.

findTagNameEnd

protected void findTagNameEnd()
Advances parsePos through any remaining alphanumeric characters. Leaves parsePos unchanged if not found.

findTagEnd

protected boolean findTagEnd()
                      throws ParseException
Requires a TAG_END_CHAR, optionally preceded by whitespace, and advances parsePos after the TAG_END_CHAR.
Returns:
true if we found the end of the tag, otherwise false
Throws:
ParseException - an error occurred while scanning for the end tag

atChar

protected java.lang.String atChar(int pos)
Adds text to an error message indicating the line number where the error was found.
Returns:
a String containing the message.

parseExpression

protected Expression parseExpression()
                              throws ParseException
Parses and builds an Expression, which may also be a sub-expression. An expression in parenthesis is considered a sub-expression.
Returns:
the completed Expression.

parseElements

protected java.util.List parseElements()
                                throws ParseException
Retrieve the next ExpressionElement(s) following parsePos.
Returns:
a List of ExpressionElements containing any elements encountered
Throws:
ParseException - something went wrong during parsing

parseBinaryElement

protected boolean parseBinaryElement(java.util.List elements)
                              throws ParseException
Parse an optional binary element. If one is found, it is parsed and added to the list of elements.
Parameters:
elements - a list of elements to which we add any elements parsed
Returns:
true if a binary operator was found, otherwise false
Throws:
ParseException - something went wrong during parsing

parseDynamicKeyName

protected DynamicKeyName parseDynamicKeyName()
                                      throws ParseException
Parses a DynamicKeyName. Expects parsePos to be on the open bracket.
Returns:
a DynamicKeyName.

parseDot

protected Dot parseDot()
                throws ParseException
Parses the Dot operator. Expects parsePos to be one character beyond the dot itself.
Returns:
a Dot.

parseStringLiteral

protected StringLiteral parseStringLiteral()
                                    throws ParseException
Parses a StringLiteral. Expects parsePos to be on the open quote. This is so we can determine whether a single- or double-quote was used to open the String, and thus what close quote we should look for.
Returns:
a StringLiteral.

parseListLiteral

protected Expression parseListLiteral()
                               throws ParseException
Parses a ListLiteral. Expects parsePos to be just beyond open square bracket.
Returns:
a ListLiteral.

parseHashLiteral

protected HashLiteral parseHashLiteral()
                                throws ParseException
Parses a HashLiteral. Expects parsePos to be just beyond the open brace.
Returns:
a HashLiteral.

parseNumberLiteral

protected NumberLiteral parseNumberLiteral()
                                    throws ParseException
Parses a NumberLiteral. Expects parsePos to be on the first digit or optional minus sign.
Returns:
a NumberLiteral.

parseBooleanLiteral

protected BooleanLiteral parseBooleanLiteral()
                                      throws ParseException
Parses a BooleanLiteral. Expects parsePos to be immediately following the '#' symbol.
Returns:
a BooleanLiteral.

parseVariable

protected Variable parseVariable()
                          throws ParseException
Parses an Expression and ensures that it's a Variable.
Returns:
a Variable.

parseVariableElement

protected ExpressionElement parseVariableElement()
                                          throws ParseException
Retrieve the next ExpressionElement following parsePos, and ensure its a Variable.
Returns:
a new ExpressionElement, or null if none is found.

parseIdentifier

protected Identifier parseIdentifier()
                              throws ParseException
Tries to parse an Identifier. Skips any whitespace prior to the identifier.
Returns:
an Identifier.

isIdentifierStartChar

protected boolean isIdentifierStartChar(char c)

Determines whether a character is legal at the start of an identifier. An identifier is either something like a tag name, such as "foreach", or a variable name, such as "myHash".

In this implementation, an identifier can only start with either a letter or an underscore.

Note that this method does not affect identifiers inside a dynamic key name.


parseMethodCall

protected MethodCall parseMethodCall()
                              throws ParseException
Parses a MethodCall.
Returns:
a new MethodCall object initialized with the arguments.

parseVariableOrList

protected Expression parseVariableOrList()
                                  throws ParseException
Parses either a variable name or a list literal. This used by the <list> and <foreach> tags.
Returns:
an Expression representing either a variable or a list literal
Throws:
ParseException - the next expression element couldn't be parsed

parseVariableInstruction

protected VariableInstruction parseVariableInstruction()
                                                throws ParseException
Parses a VariableInstruction. Expects parsePos to be at the beginning of the VAR_INSTR_START_CHARS.
Returns:
a VariableInstruction.

parseListStart

protected ListInstruction parseListStart()
                                  throws ParseException
Parses a ListInstruction's start tag.
Returns:
a ListInstruction initialized with the values from the tag.

parseForeachStart

protected ListInstruction parseForeachStart()
                                     throws ParseException
Parses a ListInstruction's start tag with the "foreach" keyword.
Returns:
a ListInstruction initialized with the values from the tag.

parseIfStart

protected IfElseInstruction parseIfStart()
                                  throws ParseException
Parses an IfElseInstruction's start tag.
Returns:
an IfElseInstruction initialized with the expression in the tag.

parseElseIf

protected IfInstruction parseElseIf()
                             throws ParseException
Parses an IfInstruction <elseif> tag.
Returns:
an IfInstruction initialised with the expression in the tag.

parseElse

protected ElseInstruction parseElse()
                             throws ParseException
Parses an IfInstruction <else> tag.
Returns:
an IfInstruction initialised with the constant expression true.

parseAssign

protected AssignInstruction parseAssign()
                                 throws ParseException
Parses an AssignInstruction's tag.
Returns:
an AssignInstruction initialized with the values from the tag.

parseInclude

protected IncludeInstruction parseInclude()
                                   throws ParseException
Parses an IncludeInstruction's tag.
Returns:
an IncludeInstruction initialized with the name in the tag.

parseSwitch

protected SwitchInstruction parseSwitch()
                                 throws ParseException
Parses a SwitchInstruction's tag.
Returns:
a SwitchInstruction initialized with the expression in the tag.

parseCase

protected CaseInstruction parseCase()
                             throws ParseException
Parses a CaseInstruction's tag.
Returns:
a CaseInstruction initialized with the expression in the tag.

parseDefault

protected DefaultCaseInstruction parseDefault()
                                       throws ParseException
Parses a default CaseInstruction's tag.
Returns:
a CaseInstruction with default status set to true.

parseFunction

protected FunctionInstruction parseFunction()
                                     throws ParseException
Parses a FunctionInstruction's tag.
Returns:
a FunctionInstruction intialized with the argument names in the tag.

parseCall

protected CallInstruction parseCall()
                             throws ParseException
Parses a CallInstruction's tag. This essentially looks like a method call, so we parse it the same way.
Returns:
a CallInstruction initialized with the arguments in the tag.

parseComment

protected CommentInstruction parseComment()
                                   throws ParseException
Parses a CommentInstruction's tag.
Returns:
a CommentInstruction

parseNoparseStart

protected NoParseInstruction parseNoparseStart()
                                        throws ParseException
Parses a NoParseInstruction's tag.
Returns:
a NoParseInstruction

parseTransformStart

protected TransformInstruction parseTransformStart()
                                            throws ParseException
Parses a TransformInstruction's tag. This tag consists of one parameter: the variable representing the TemplateTransformModel to be used for the transformation.
Returns:
a TransformInstruction

skipChar

protected boolean skipChar(char c)
                    throws ParseException
Advances beyond any whitespace; then, if the next character matches a given character, advances beyond it and returns true, otherwise returns false.
Returns:
true if the character was found, otherwise false

requireChar

protected void requireChar(char c)
                    throws ParseException
Requires a given character, optionally preceded by by whitespace.
Throws:
ParseException - the required character couldn't be found

skipKeyword

protected boolean skipKeyword(java.lang.String keyword)
                       throws ParseException
Skip over a given keyword. Skips over any whitespace prior to the keyword itself.
Parameters:
keyword - the keyword to skip over
Returns:
whether we found the keyword
Throws:
ParseException - there are no more characters before the keyword is expected.

skipWhitespace

protected void skipWhitespace()
                       throws ParseException
Advances parsePos beyond any whitespace.
Throws:
ParseException - there are no more characters after whitespace has been skipped.

requireWhitespace

protected void requireWhitespace()
                          throws ParseException
Advances parsePos beyond required whitespace.
Throws:
ParseException - there are no more characters after whitespace has been skipped, or if no whitespace could be found.

toString

public java.lang.String toString()
Returns a string representation of the object.
Overrides:
toString in class java.lang.Object
Returns:
a String representation of the object