Top Description Inners Fields Constructors Methods
uk.ac.ed.ph.snuggletex.internal

public final Class DOMBuilder

extends Object
Class Inheritance
Imports
org.w3c.dom.*, uk.ac.ed.ph.snuggletex.*, .DOMOutputOptions.ErrorOutputOptions, uk.ac.ed.ph.snuggletex.definitions.*, .ComputedStyle.FontFamily, .ComputedStyle.FontSize, uk.ac.ed.ph.snuggletex.dombuilding.CommandHandler, .EnvironmentHandler, .EqnArrayHandler, uk.ac.ed.ph.snuggletex.internal.util.ArrayListStack, .StringUtilities, .XMLUtilities, uk.ac.ed.ph.snuggletex.semantics.*, uk.ac.ed.ph.snuggletex.tokens.*, uk.ac.ed.ph.snuggletex.utilities.CSSUtilities, .MessageFormatter, java.net.URI, .URISyntaxException, java.util.EnumMap, .List, .Properties

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.

Author
David McKain
Version
$Revision$
See Also
TokenFixer, DOMBuildingController

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
DOMBuilder.MathContentBuilderCallback

Internal callback interface that specifies how to build the real content of a MathML element.

public static enum
DOMBuilder.OutputContext

Trivial enumeration to keep track of where we are in the outgoing DOM.

Field Summary

Modifier and TypeField and Description
private final Element
buildRootElement

Element that we're building into

private Properties
currentInlineCSSProperties

CSS Properties, used for inlining and created lazily as required

private Element
private DOMBuilder.OutputContext
private final DOMBuilder.MathContentBuilderCallback
defaultMathContentBuilderCallback

Trivial instance of MathContentBuilderCallback that simply descends into child tokens, handling the annotated/non-annotated case as required.

private final Document
private final String
private final ArrayListStack<MathVariantMap>
private final DOMOutputOptions
options

Build options specified by user

private final SessionContext
private final ArrayListStack<ComputedStyle>
private final VariableManager
variableManager

Helper to manage variables

Constructor Summary

AccessConstructor and Description
public
DOMBuilder(final SessionContext sessionContext, final Element buildRootElement, final DOMOutputOptions options)

Method Summary

Modifier and TypeMethod and Description
public Element
appendErrorElement(final Element parentElement, final ErrorToken errorToken)

public void
appendMathCharacter(Element parentElement, MathCharacter character)

public Element
appendMathMLElement(Element parentElement, String elementLocalName)

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").

public Element
appendMathMLNumberElement(Element parentElement, String number)

public Element
appendMathMLOperatorElement(Element parentElement, String content)

public Element
appendMathMLSpace(Element parentElement, String width)

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

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

public void
appendSimpleMathElement(Element parentElement, Token token)

public Element
appendSnuggleElement(Element parentElement, String elementLocalName)

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

public Element
appendXHTMLElement(Element parentElement, String elementLocalName)

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

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

public void
buildDOMSubtree(final List<FlowToken> fixedTokens)

This is the external entry point used by SnuggleSession only.

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

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

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

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

private void
buildStringValue(StringBuilder resultBuilder, NodeList nodes)

public ComputedStyle
public NodeList
public 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).

public Element
private Properties
public Document
getDocument()

Gets at the underlying DOM Document.

public ArrayListStack<MathVariantMap>
public DOMOutputOptions
public DOMBuilder.OutputContext
public SessionContext
public VariableManager
public void
public void
public void
handleTextToken(Element parentElement, SimpleToken textToken)

public void
handleToken(Element parentElement, FlowToken token)

Creates a single Node from the given token.

public void
handleTokens(Element parentElement, ArgumentContainerToken containerToken, boolean
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.
trimWhitespace
)

public void
handleTokens(Element parentElement, List<FlowToken> siblingTokens, boolean
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.
trimWhitespace
)

public boolean
isBuildingMathMLIsland()

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

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

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

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

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

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

public String
validateXMLId(final Element parentElement, final Token nameToken, final 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.

public String
validateXMLName(final Element parentElement, final Token nameToken, final String rawName)

Checks the given raw XML Name to ensure that it confirms to the correct syntax, returning it unchanged if successful.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

buildRootElementback to summary
private final Element buildRootElement

Element that we're building into

currentInlineCSSPropertiesback to summary
private Properties currentInlineCSSProperties

CSS Properties, used for inlining and created lazily as required

currentMathOwnerElementback to summary
private Element currentMathOwnerElement
currentOutputContextback to summary
private DOMBuilder.OutputContext currentOutputContext
defaultMathContentBuilderCallbackback to summary
private final DOMBuilder.MathContentBuilderCallback defaultMathContentBuilderCallback

Trivial instance of MathContentBuilderCallback that simply descends into child tokens, handling the annotated/non-annotated case as required.

documentback to summary
private final Document document

Document owning buildRootElement

lineSeparatorback to summary
private final String lineSeparator
mathVariantMapStackback to summary
private final ArrayListStack<MathVariantMap> mathVariantMapStack

Stack of active MathVariantMaps.

optionsback to summary
private final DOMOutputOptions options

Build options specified by user

sessionContextback to summary
private final SessionContext sessionContext

Underlying SessionContext

textStyleStackback to summary
private final ArrayListStack<ComputedStyle> textStyleStack
variableManagerback to summary
private final VariableManager variableManager

Helper to manage variables

Constructor Detail

DOMBuilderback to summary
public DOMBuilder(final SessionContext sessionContext, final Element buildRootElement, final DOMOutputOptions options)

Method Detail

appendErrorElementback to summary
public Element appendErrorElement(final Element parentElement, final ErrorToken errorToken)
appendMathCharacterback to summary
public void appendMathCharacter(Element parentElement, MathCharacter character)
appendMathMLElementback to summary
public Element appendMathMLElement(Element parentElement, String elementLocalName)
appendMathMLIdentifierElementback to summary
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.

See Also
DOMOutputOptions#isMathVariantMapping()
appendMathMLNumberElementback to summary
public Element appendMathMLNumberElement(Element parentElement, String number)
appendMathMLOperatorElementback to summary
public Element appendMathMLOperatorElement(Element parentElement, String content)
appendMathMLSpaceback to summary
public Element appendMathMLSpace(Element parentElement, String width)
appendMathMLTextElementback to summary
public Element appendMathMLTextElement(Element parentElement, String elementLocalName, String content, boolean trim)
appendOrThrowErrorback to summary
public Element appendOrThrowError(final Element parentElement, final Token token, final ErrorCode errorCode, final Object... arguments) throws SnuggleParseException
appendSimpleMathElementback to summary
public void appendSimpleMathElement(Element parentElement, Token token)
appendSnuggleElementback to summary
public Element appendSnuggleElement(Element parentElement, String elementLocalName)
appendTextNodeback to summary
public Node appendTextNode(Element parentElement, String content, boolean trim)
appendXHTMLElementback to summary
public Element appendXHTMLElement(Element parentElement, String elementLocalName)
appendXHTMLTextElementback to summary
public Element appendXHTMLTextElement(Element parentElement, String elementLocalName, String content, boolean trim)
applyCSSStyleback to summary
public void applyCSSStyle(Element xhtmlElement, String... cssClassNames)
buildDOMSubtreeback to summary
public void buildDOMSubtree(final 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.

buildMathElementback to summary
public void buildMathElement(final Element parentElement, final Token token, final ArgumentContainerToken mathContentToken, final 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.

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

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

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

buildStringValueback to summary
private void buildStringValue(StringBuilder resultBuilder, NodeList nodes)
closeStyleback to summary
public ComputedStyle closeStyle()
extractNodeListValueback to summary
public NodeList extractNodeListValue(ArgumentContainerToken token) throws SnuggleParseException
extractStringValueback to summary
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).

findNearestXHTMLAncestorOrSelfback to summary
public Element findNearestXHTMLAncestorOrSelf(final Element element)
getCurrentInlineCSSPropertiesback to summary
private Properties getCurrentInlineCSSProperties()
getDocumentback to summary
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.

getMathVariantMapStackback to summary
public ArrayListStack<MathVariantMap> getMathVariantMapStack()
getOptionsback to summary
public DOMOutputOptions getOptions()
getOutputContextback to summary
public DOMBuilder.OutputContext getOutputContext()
getSessionContextback to summary
public SessionContext getSessionContext()
getVariableManagerback to summary
public VariableManager getVariableManager()
handleMathTokensAsSingleElementback to summary
public void handleMathTokensAsSingleElement(Element parentElement, ArgumentContainerToken containerToken) throws SnuggleParseException
handleMathTokensAsSingleElementback to summary
public void handleMathTokensAsSingleElement(Element parentElement, List<FlowToken> tokens) throws SnuggleParseException
handleTextTokenback to summary
public void handleTextToken(Element parentElement, SimpleToken textToken)
handleTokenback to summary
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>

handleTokensback to summary
public void handleTokens(Element parentElement, ArgumentContainerToken containerToken, boolean trimWhitespace) throws SnuggleParseException
Parameters
trimWhitespace:boolean

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.

handleTokensback to summary
public void handleTokens(Element parentElement, List<FlowToken> siblingTokens, boolean trimWhitespace) throws SnuggleParseException
Parameters
trimWhitespace:boolean

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.

isBuildingMathMLIslandback to summary
public boolean isBuildingMathMLIsland()

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

isParentElementback to summary
public boolean isParentElement(final Element parentElement, final String requiredNamespaceUri, final String... requiredLocalNames)
openStyleback to summary
public Element openStyle(Element parentElement, ComputedStyle newStyle, boolean hasBlockContent, boolean hasEmptyContent)
setOutputContextback to summary
public void setOutputContext(Element parentElement, DOMBuilder.OutputContext outputContext)
validateURIback to summary
public URI validateURI(final Element parentElement, final Token token, final 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.

validateXMLIdback to summary
public String validateXMLId(final Element parentElement, final Token nameToken, final 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.

validateXMLNameback to summary
public String validateXMLName(final Element parentElement, final Token nameToken, final 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.

uk.ac.ed.ph.snuggletex.internal back to summary

public Interface DOMBuilder.MathContentBuilderCallback


Internal callback interface that specifies how to build the real content of a MathML element.

Method Summary

Modifier and TypeMethod and Description
public void
buildMathElementContent(final Element contentContainerElement, final ArgumentContainerToken mathContentToken, final boolean isAnnotated)

Method Detail

buildMathElementContentback to summary
public void buildMathElementContent(final Element contentContainerElement, final ArgumentContainerToken mathContentToken, final boolean isAnnotated) throws SnuggleParseException
uk.ac.ed.ph.snuggletex.internal back to summary

public final Enum DOMBuilder.OutputContext

extends Enum<DOMBuilder.OutputContext>
Class Inheritance

Trivial enumeration to keep track of where we are in the outgoing DOM. This makes life a bit easier when handling certain types of tokens. Use the DOMBuilder#getOutputContext(), DOMBuilder#setOutputContext(Element, OutputContext) to manage the current status.

Field Summary

Modifier and TypeField and Description
public static final DOMBuilder.OutputContext
public static final DOMBuilder.OutputContext
public static final DOMBuilder.OutputContext

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static DOMBuilder.OutputContext
public static DOMBuilder.OutputContext[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

MATHML_BLOCKback to summary
public static final DOMBuilder.OutputContext MATHML_BLOCK
MATHML_INLINEback to summary
public static final DOMBuilder.OutputContext MATHML_INLINE
XHTMLback to summary
public static final DOMBuilder.OutputContext XHTML

Constructor Detail

OutputContextback to summary
private OutputContext()

Method Detail

valueOfback to summary
public static DOMBuilder.OutputContext valueOf(String name)
valuesback to summary
public static DOMBuilder.OutputContext[] values()