uk.ac.ed.ph.snuggletex.internal

Class DOMBuilder

java.lang.Object

uk.ac.ed.ph.snuggletex.internal.DOMBuilder

public final class DOMBuilder
extends Object

This takes a List of (fixed) Tokens and builds a (raw) XHTML + MathML DOM tree branch from them.

Usage

Clients should not normally have to use this class directly - call SnuggleSession.buildDOMSubtree(Element, DOMOutputOptions) and friends.

An instance of this class is intended to be used once and then discarded so can be stateful.

This contains a number of callbacks that CommandHandlers and EnvironmentHandlers can use to do their magic.

Version:

$Revision$

Author:

David McKain

See Also:

TokenFixer, DOMBuildingController

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	DOMBuilder.MathContentBuilderCallback Internal callback interface that specifies how to build the real content of a MathML element.
static class	DOMBuilder.OutputContext Trivial enumeration to keep track of where we are in the outgoing DOM.

Constructor Summary

Constructors

Constructor and Description
DOMBuilder(SessionContext sessionContext, Element buildRootElement, DOMOutputOptions options)

Method Summary

Modifier and Type	Method and Description
Element	appendErrorElement(Element parentElement, ErrorToken errorToken)
void	appendMathCharacter(Element parentElement, MathCharacter character)
Element	appendMathMLElement(Element parentElement, String elementLocalName)
Element	appendMathMLIdentifierElement(Element parentElement, String name) Creates a MathML identifier element, which may either be a single character or multiple characters (e.g.
Element	appendMathMLNumberElement(Element parentElement, String number)
Element	appendMathMLOperatorElement(Element parentElement, String content)
Element	appendMathMLSpace(Element parentElement, String width)
Element	appendMathMLTextElement(Element parentElement, String elementLocalName, String content, boolean trim)
Element	appendOrThrowError(Element parentElement, Token token, ErrorCode errorCode, Object... arguments)
void	appendSimpleMathElement(Element parentElement, Token token)
Element	appendSnuggleElement(Element parentElement, String elementLocalName)
Node	appendTextNode(Element parentElement, String content, boolean trim)
Element	appendXHTMLElement(Element parentElement, String elementLocalName)
Element	appendXHTMLTextElement(Element parentElement, String elementLocalName, String content, boolean trim)
void	applyCSSStyle(Element xhtmlElement, String... cssClassNames)
void	buildDOMSubtree(List<FlowToken> fixedTokens) This is the external entry point used by SnuggleSession only.
void	buildMathElement(Element parentElement, Token token, ArgumentContainerToken mathContentToken, boolean isDisplayMath) Builds a MathML math element for the given Token token, using contentToken to provide the content, descending into child Nodes as normal.
void	buildMathElement(Element parentElement, Token token, ArgumentContainerToken mathContentToken, boolean isDisplayMath, DOMBuilder.MathContentBuilderCallback mathContentBuilderCallback) Builds a MathML math element for the given Token token, using contentToken to provide the content, using the given DOMBuilder.MathContentBuilderCallback to supply the content.
ComputedStyle	closeStyle()
NodeList	extractNodeListValue(ArgumentContainerToken token)
String	extractStringValue(ArgumentContainerToken token) This "converts" the given token to a String by performing {handleTokens(Element, ArgumentContainerToken, boolean)} with a fake root element and then extracting the String value of the resulting Text Node(s).
Element	findNearestXHTMLAncestorOrSelf(Element element)
Document	getDocument() Gets at the underlying DOM Document.
ArrayListStack<MathVariantMap>	getMathVariantMapStack()
DOMOutputOptions	getOptions()
DOMBuilder.OutputContext	getOutputContext()
SessionContext	getSessionContext()
VariableManager	getVariableManager()
void	handleMathTokensAsSingleElement(Element parentElement, ArgumentContainerToken containerToken)
void	handleMathTokensAsSingleElement(Element parentElement, List<FlowToken> tokens)
void	handleTextToken(Element parentElement, SimpleToken textToken)
void	handleToken(Element parentElement, FlowToken token) Creates a single Node from the given token.
void	handleTokens(Element parentElement, ArgumentContainerToken containerToken, boolean trimWhitespace)
void	handleTokens(Element parentElement, List<FlowToken> siblingTokens, boolean trimWhitespace)
boolean	isBuildingMathMLIsland() Returns whether or not we're building a MathML island by checking the current DOMBuilder.OutputContext.
boolean	isParentElement(Element parentElement, String requiredNamespaceUri, String... requiredLocalNames)
Element	openStyle(Element parentElement, ComputedStyle newStyle, boolean hasBlockContent, boolean hasEmptyContent)
URI	resolveLink(Element parentElement, Token token, String rawHref)
void	setOutputContext(Element parentElement, DOMBuilder.OutputContext outputContext)
URI	validateURI(Element parentElement, Token token, String rawURI) Checks the given raw URI to ensure that it is valid, returning a URI Object if valid or null if not.
String	validateXMLId(Element parentElement, Token nameToken, String rawName) Checks the given XML Name as in validateXMLName(Element, Token, String), additionally checking that an ID of the same name is not already in use in the output DOM.
String	validateXMLName(Element parentElement, Token nameToken, String rawName) Checks the given raw XML Name to ensure that it confirms to the correct syntax, returning it unchanged if successful.

Methods inherited from class java.lang.Object

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

Constructor Detail

DOMBuilder

public DOMBuilder(SessionContext sessionContext,
                  Element buildRootElement,
                  DOMOutputOptions options)

Method Detail

buildDOMSubtree

public void buildDOMSubtree(List<FlowToken> fixedTokens)
                     throws SnuggleParseException

This is the external entry point used by SnuggleSession only. If you are using DOMBuilder as a callback to implementing your own built-in commands and environments, then you shouldn't call this method.

Throws:

SnuggleParseException

DOMException

getSessionContext

public SessionContext getSessionContext()

getOptions

public DOMOutputOptions getOptions()

getDocument

public Document getDocument()

Gets at the underlying DOM Document. Use this to do exotic things not covered elsewhere. To append XHTML and/or MathML elements, you should use the alternatives methods listed here to ensure correct namespace handling.

getVariableManager

public VariableManager getVariableManager()

getMathVariantMapStack

public ArrayListStack<MathVariantMap> getMathVariantMapStack()

getOutputContext

public DOMBuilder.OutputContext getOutputContext()

setOutputContext

public void setOutputContext(Element parentElement,
                             DOMBuilder.OutputContext outputContext)

isBuildingMathMLIsland

public boolean isBuildingMathMLIsland()

Returns whether or not we're building a MathML island by checking the current DOMBuilder.OutputContext.

handleTokens

public void handleTokens(Element parentElement,
                         ArgumentContainerToken containerToken,
                         boolean trimWhitespace)
                  throws SnuggleParseException

Parameters:

trimWhitespace - removes leading whitespace from the first resulting Node if it is a Text Node and removes trailing whitespace from the last Node if it is a Text Node.

Throws:

SnuggleParseException

handleTokens

public void handleTokens(Element parentElement,
                         List<FlowToken> siblingTokens,
                         boolean trimWhitespace)
                  throws SnuggleParseException

Parameters:

trimWhitespace - removes leading whitespace from the first resulting Node if it is a Text Node and removes trailing whitespace from the last Node if it is a Text Node.

Throws:

SnuggleParseException

handleToken

public void handleToken(Element parentElement,
                        FlowToken token)
                 throws SnuggleParseException

Creates a single Node from the given token. If the token is a container then it will be wrapped into a container element if required, depending on context. Example: \msub{1+2}{3-\mrow{4*5}} -> <msup<mrow>...</mrow><mrow>...</mrow></msup>

Parameters:

parentElement -

token -

Throws:

DOMException

SnuggleParseException

handleTextToken

public void handleTextToken(Element parentElement,
                            SimpleToken textToken)

appendMathCharacter

public void appendMathCharacter(Element parentElement,
                                MathCharacter character)

appendSimpleMathElement

public void appendSimpleMathElement(Element parentElement,
                                    Token token)

appendTextNode

public Node appendTextNode(Element parentElement,
                           String content,
                           boolean trim)

appendSnuggleElement

public Element appendSnuggleElement(Element parentElement,
                                    String elementLocalName)

appendXHTMLElement

public Element appendXHTMLElement(Element parentElement,
                                  String elementLocalName)

appendXHTMLTextElement

public Element appendXHTMLTextElement(Element parentElement,
                                      String elementLocalName,
                                      String content,
                                      boolean trim)

appendMathMLElement

public Element appendMathMLElement(Element parentElement,
                                   String elementLocalName)

appendMathMLTextElement

public Element appendMathMLTextElement(Element parentElement,
                                       String elementLocalName,
                                       String content,
                                       boolean trim)

appendMathMLSpace

public Element appendMathMLSpace(Element parentElement,
                                 String width)

appendMathMLOperatorElement

public Element appendMathMLOperatorElement(Element parentElement,
                                           String content)

appendMathMLNumberElement

public Element appendMathMLNumberElement(Element parentElement,
                                         String number)

appendMathMLIdentifierElement

public Element appendMathMLIdentifierElement(Element parentElement,
                                             String name)

Creates a MathML identifier element, which may either be a single character or multiple characters (e.g. "sin"). The single-character case is interesting if we are currently applying a "mathvariant" in that it may or may not then be mapped into a corresponding target character.

Parameters:

parentElement -

name -

See Also:

DOMOutputOptions.isMathVariantMapping()

handleMathTokensAsSingleElement

public void handleMathTokensAsSingleElement(Element parentElement,
                                            ArgumentContainerToken containerToken)
                                     throws SnuggleParseException

Throws:

SnuggleParseException

handleMathTokensAsSingleElement

public void handleMathTokensAsSingleElement(Element parentElement,
                                            List<FlowToken> tokens)
                                     throws SnuggleParseException

Throws:

SnuggleParseException

extractNodeListValue

public NodeList extractNodeListValue(ArgumentContainerToken token)
                              throws SnuggleParseException

Throws:

SnuggleParseException

extractStringValue

public String extractStringValue(ArgumentContainerToken token)
                          throws SnuggleParseException

This "converts" the given token to a String by performing {handleTokens(Element, ArgumentContainerToken, boolean)} with a fake root element and then extracting the String value of the resulting Text Node(s).

Throws:

DOMException

SnuggleParseException

openStyle

public Element openStyle(Element parentElement,
                         ComputedStyle newStyle,
                         boolean hasBlockContent,
                         boolean hasEmptyContent)

closeStyle

public ComputedStyle closeStyle()

applyCSSStyle

public void applyCSSStyle(Element xhtmlElement,
                          String... cssClassNames)

buildMathElement

public void buildMathElement(Element parentElement,
                             Token token,
                             ArgumentContainerToken mathContentToken,
                             boolean isDisplayMath)
                      throws SnuggleParseException

Builds a MathML math element for the given Token token, using contentToken to provide the content, descending into child Nodes as normal.

Throws:

SnuggleParseException

buildMathElement

public void buildMathElement(Element parentElement,
                             Token token,
                             ArgumentContainerToken mathContentToken,
                             boolean isDisplayMath,
                             DOMBuilder.MathContentBuilderCallback mathContentBuilderCallback)
                      throws SnuggleParseException

Builds a MathML math element for the given Token token, using contentToken to provide the content, using the given DOMBuilder.MathContentBuilderCallback to supply the content.

This is useful for things like EqnArrayHandler which generate a rather specific structure.

Throws:

SnuggleParseException

findNearestXHTMLAncestorOrSelf

public Element findNearestXHTMLAncestorOrSelf(Element element)

isParentElement

public boolean isParentElement(Element parentElement,
                               String requiredNamespaceUri,
                               String... requiredLocalNames)

validateXMLName

public String validateXMLName(Element parentElement,
                              Token nameToken,
                              String rawName)
                       throws SnuggleParseException

Checks the given raw XML Name to ensure that it confirms to the correct syntax, returning it unchanged if successful. If not valid, the CoreErrorCode.TDEX03 is recorded.

Throws:

SnuggleParseException

validateXMLId

public String validateXMLId(Element parentElement,
                            Token nameToken,
                            String rawName)
                     throws SnuggleParseException

Checks the given XML Name as in validateXMLName(Element, Token, String), additionally checking that an ID of the same name is not already in use in the output DOM. If it is, CoreErrorCode.TDEX05 is recorded. Returns non-null on success, null on error.

Throws:

SnuggleParseException

validateURI

public URI validateURI(Element parentElement,
                       Token token,
                       String rawURI)
                throws SnuggleParseException

Checks the given raw URI to ensure that it is valid, returning a URI Object if valid or null if not. If not valid, the CoreErrorCode.TDEX04 is recorded.

Throws:

SnuggleParseException

resolveLink

public URI resolveLink(Element parentElement,
                       Token token,
                       String rawHref)
                throws SnuggleParseException

Throws:

SnuggleParseException

appendOrThrowError

public Element appendOrThrowError(Element parentElement,
                                  Token token,
                                  ErrorCode errorCode,
                                  Object... arguments)
                           throws SnuggleParseException

Throws:

SnuggleParseException

appendErrorElement

public Element appendErrorElement(Element parentElement,
                                  ErrorToken errorToken)