org.apache.tapestry.parse
Class TemplateParser

java.lang.Object
  org.apache.tapestry.parse.TemplateParser

public class TemplateParser
extends Object

Parses Tapestry templates, breaking them into a series of tokens. Although often referred to as an "HTML template", there is no real requirement that the template be HTML. This parser can handle any reasonable SGML derived markup (including XML), but specifically works around the ambiguities of HTML reasonably.

Dynamic markup in Tapestry attempts to be invisible. Components are arbitrary tags containing a jwcid attribute. Such components must be well balanced (have a matching close tag, or end the tag with "/>".

Generally, the id specified in the template is matched against an component defined in the specification. However, implicit components are also possible. The jwcid attribute uses the syntax "@Type" for implicit components. Type is the component type, and may include a library id prefix. Such a component is anonymous (but is given a unique id).

(The unique ids assigned start with a dollar sign, which is normally no allowed for component ids ... this helps to make them stand out and assures that they do not conflict with user-defined component ids. These ids tend to propagate into URLs and become HTML element names and even JavaScript variable names ... the dollar sign is acceptible in these contexts as well).

Implicit component may also be given a name using the syntax "componentId:@Type". Such a component should not be defined in the specification, but may still be accessed via IComponent.getComponent(String).

Both defined and implicit components may have additional attributes defined, simply by including them in the template. They set formal or informal parameters of the component to static strings. IComponentSpecification.getAllowInformalParameters(), if false, will cause such attributes to be simply ignored. For defined components, conflicting values defined in the template are ignored.

Attributes in component tags will become formal and informal parameters of the corresponding component. Most attributes will be

The parser removes the body of some tags (when the corresponding component doesn't allow a body, and allows portions of the template to be completely removed.

The parser does a pretty thorough lexical analysis of the template, and reports a great number of errors, including improper nesting of tags.

The parser supports invisible localization: The parser recognizes HTML of the form: <span key="value"> ... </span> and converts them into a TokenType.LOCALIZATION token. You may also specifify a raw attribute ... if the value is true, then the localized value is sent to the client without filtering, which is appropriate if the value has any markup that should not be escaped.

Version:

$Id: TemplateParser.java 244412 2005-07-23 03:32:35Z glongman $

Author:

Howard Lewis Ship, Geoff Longman

Nested Class Summary

protected static class

TemplateParser.TemplateTokenFactory A Factory used by TemplateParser to create TemplateToken objects.

Field Summary

protected TemplateParser.TemplateTokenFactory	_factory A factory used to create template tokens.
static String	IMPLICIT_ID_PATTERN Pattern used to recognize implicit components (whose type is defined in the template).
static String	JWCID_ATTRIBUTE_NAME Attribute used to identify components.
static String	LOCALIZATION_KEY_ATTRIBUTE_NAME The attribute, checked for in <span> tags, that signfies that the span is being used as an invisible localization.
static String	LOCALIZATION_KEY_PREFIX Attribute value prefix indicating that the attribute is a localization key.
static String	OGNL_EXPRESSION_PREFIX Attribute value prefix indicating that the attribute is an OGNL expression.
static String	RAW_ATTRIBUTE_NAME Used with LOCALIZATION_KEY_ATTRIBUTE_NAME to indicate a string that should be rendered "raw" (without escaping HTML).
static String	SIMPLE_ID_PATTERN Pattern used to recognize ordinary components (defined in the specification).

Constructor Summary

TemplateParser()

Method Summary

protected void	afterParse() Perform default cleanup after parsing completes.
protected void	attributeBeginEvent(String attributeName, int startLine, int cursorPosition) Notify that the beginning of an attribute value has been detected.
protected void	attributeEndEvent(int cursorPosition) Notify that the end of the current attribute value has been detected.
protected void	beforeParse(char[] templateData, ITemplateParserDelegate delegate, IResourceLocation resourceLocation) perform default initialization of the parser.
protected String	findValueCaselessly(String key, Map map) Searches a Map for given key, caselessly.
protected ILocation	getCurrentLocation() Gets the current location within the file.
protected List	getTokens() Give subclasses access to the parse results.
protected void	parse()
TemplateToken[]	parse(char[] templateData, ITemplateParserDelegate delegate, IResourceLocation resourceLocation) Parses the template data into an array of TemplateTokens.
protected void	tagBeginEvent(int startLine, int cursorPosition) Notify that the beginning of a tag has been detected.
protected void	tagEndEvent(int cursorPosition) Notify that the end of the current tag has been detected.
protected void	templateParseProblem(ApplicationRuntimeException exception, int line, int cursor) Used by the parser to report tapestry runtime specific problems in the parse.
protected void	templateParseProblem(String message, ILocation location, int line, int cursor) Used by the parser to report problems in the parse.

Methods inherited from class java.lang.Object

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

Field Detail

OGNL_EXPRESSION_PREFIX

public static final String OGNL_EXPRESSION_PREFIX

Attribute value prefix indicating that the attribute is an OGNL expression.

Since:

3.0

See Also:

Constant Field Values

LOCALIZATION_KEY_PREFIX

public static final String LOCALIZATION_KEY_PREFIX

Attribute value prefix indicating that the attribute is a localization key.

Since:

3.0

See Also:

Constant Field Values

LOCALIZATION_KEY_ATTRIBUTE_NAME

public static final String LOCALIZATION_KEY_ATTRIBUTE_NAME

The attribute, checked for in <span> tags, that signfies that the span is being used as an invisible localization.

Since:

2.0.4

See Also:

Constant Field Values

RAW_ATTRIBUTE_NAME

public static final String RAW_ATTRIBUTE_NAME

Used with LOCALIZATION_KEY_ATTRIBUTE_NAME to indicate a string that should be rendered "raw" (without escaping HTML). If not specified, defaults to "false". The value must equal "true" (caselessly).

Since:

2.3

See Also:

Constant Field Values

JWCID_ATTRIBUTE_NAME

public static final String JWCID_ATTRIBUTE_NAME

Attribute used to identify components.

Since:

2.3

See Also:

Constant Field Values

SIMPLE_ID_PATTERN

public static final String SIMPLE_ID_PATTERN

Pattern used to recognize ordinary components (defined in the specification).

Since:

3.0

See Also:

Constant Field Values

IMPLICIT_ID_PATTERN

public static final String IMPLICIT_ID_PATTERN

Pattern used to recognize implicit components (whose type is defined in the template). Subgroup 1 is the id (which may be null) and subgroup 2 is the type (which may be qualified with a library prefix). Subgroup 4 is the library id, Subgroup 5 is the simple component type.

Since:

3.0

See Also:

Constant Field Values

_factory

protected TemplateParser.TemplateTokenFactory _factory

A factory used to create template tokens.

author glongman@intelligentworks.com

Constructor Detail

TemplateParser

public TemplateParser()

Method Detail

parse

public TemplateToken[] parse(char[] templateData,
                             ITemplateParserDelegate delegate,
                             IResourceLocation resourceLocation)
                      throws TemplateParseException

Parses the template data into an array of TemplateTokens.

The parser is decidedly not threadsafe, so care should be taken that only a single thread accesses it.

Parameters:

templateData - the HTML template to parse. Some tokens will hold a reference to this array.

delegate - object that "knows" about defined components

resourceLocation - a description of where the template originated from, used with error messages.

Throws:

TemplateParseException

beforeParse

protected void beforeParse(char[] templateData,
                           ITemplateParserDelegate delegate,
                           IResourceLocation resourceLocation)

perform default initialization of the parser.

author glongman@intelligentworks.com

afterParse

protected void afterParse()

Perform default cleanup after parsing completes.

author glongman@intelligentworks.com

templateParseProblem

protected void templateParseProblem(String message,
                                    ILocation location,
                                    int line,
                                    int cursor)
                             throws TemplateParseException

Used by the parser to report problems in the parse. Parsing must stop when a problem is reported.

The default implementation simply throws an exception that contains the message and location parameters.

Subclasses may override but must ensure they throw the required exception.

author glongman@intelligentworks.com

Parameters:

message -

location -

line - ignored by the default impl

cursor - ignored by the default impl

Throws:

TemplateParseException - always thrown in order to terminate the parse.

templateParseProblem

protected void templateParseProblem(ApplicationRuntimeException exception,
                                    int line,
                                    int cursor)
                             throws ApplicationRuntimeException

Used by the parser to report tapestry runtime specific problems in the parse. Parsing must stop when a problem is reported.

The default implementation simply rethrows the exception.

Subclasses may override but must ensure they rethrow the exception.

author glongman@intelligentworks.com

Parameters:

exception -

line - ignored by the default impl

cursor - ignored by the default impl

Throws:

ApplicationRuntimeException - always rethrown in order to terminate the parse.

getTokens

protected List getTokens()

Give subclasses access to the parse results.

author glongman@intelligentworks.com

parse

protected void parse()
              throws TemplateParseException

Throws:

TemplateParseException

tagBeginEvent

protected void tagBeginEvent(int startLine,
                             int cursorPosition)

Notify that the beginning of a tag has been detected.

Default implementation does nothing.

author glongman@intelligentworks.com

tagEndEvent

protected void tagEndEvent(int cursorPosition)

Notify that the end of the current tag has been detected.

Default implementation does nothing.

author glongman@intelligentworks.com

attributeBeginEvent

protected void attributeBeginEvent(String attributeName,
                                   int startLine,
                                   int cursorPosition)

Notify that the beginning of an attribute value has been detected.

Default implementation does nothing.

author glongman@intelligentworks.com

attributeEndEvent

protected void attributeEndEvent(int cursorPosition)

Notify that the end of the current attribute value has been detected.

Default implementation does nothing.

author glongman@intelligentworks.com

findValueCaselessly

protected String findValueCaselessly(String key,
                                     Map map)

Searches a Map for given key, caselessly. The Map is expected to consist of Strings for keys and values. Returns the value for the first key found that matches (caselessly) the input key. Returns null if no value found.

getCurrentLocation

protected ILocation getCurrentLocation()

Gets the current location within the file. This allows the location to be created only as needed, and multiple objects on the same line can share the same Location instance.

Since:

3.0