uk.ac.ed.ph.snuggletex.utilities

Class MathMLUtilities

java.lang.Object

uk.ac.ed.ph.snuggletex.utilities.MathMLUtilities

public final class MathMLUtilities
extends Object

Some general utility methods for manipulating MathML via the DOM.

Version:

$Revision$

Author:

David McKain

Field Summary

Fields

Modifier and Type	Field and Description
static String	ANNOTATION_LOCAL_NAME
static String	ANNOTATION_XML_LOCAL_NAME

Constructor Summary

Constructors

Constructor and Description
MathMLUtilities()

Method Summary

Modifier and Type	Method and Description
static void	convertExplicitFencesToMfenced(Document document) Converts explicit fences generated by SnuggleTeX back to mfenced.
static void	convertMfencedToExplicitFences(Document document) Replaces every deprecated MathML mfenced element in the supplied document with its explicit mrow/mo equivalent.
static void	ensureMathMLContainer(Element mathElement)
static Element	ensureMathMLDocument(Document document) Checks that the given DOM Document contains a single MathML math Element.
static String	extractAnnotationString(Element mathElement, String encodingAttribute) Extracts the first textual annotation found having the given encoding attribute from the given MathML math element, if such an annotation is found.
static NodeList	extractAnnotationXML(Element mathElement, String encodingAttribute) Extracts the first XML-based annotation having the given encoding attribute from the given MathML math element, if such an annotation is found.
static Element	extractFirstSemanticsBranch(Element mathElement)
static boolean	isMathMLElement(Node node) Convenience method to test whether the given DOM Node node is a MathML element having any localName.
static boolean	isMathMLElement(Node node, String localName) Convenience method to test whether the given DOM Node node is a MathML element having the given localName.
static Document	isolateAnnotationXML(Element mathElement, String encodingAttribute) "Isolates" the XML annotation having the given encoding by producing a copy of the MathML element with only the given annotation contents as children.
static Document	isolateAnnotationXML(UnwrappedParallelMathMLDOM unwrappedDOM, String encodingAttribute) Version of isolateAnnotationXML(Element, String) that works on an UnwrappedParallelMathMLDOM.
static Document	isolateFirstSemanticsBranch(Element mathElement) "Isolates" the first <semantics/> branch of an annotation MathML element by producing a copy of the MathML element with a single child containing only the first child of the <semantics/> element.
static Document	isolateFirstSemanticsBranch(UnwrappedParallelMathMLDOM unwrappedDOM) Version of isolateFirstSemanticsBranch(Element) that works on an UnwrappedParallelMathMLDOM.
static Document	parseMathMLDocumentString(String mathmlDocument) Convenience method that parses a MathML document specified as a UTF-8-encoded String.
static String	serializeDocument(Document document) Convenience method that serializes the given DOM Document as a String (encoded in UTF-8), indenting the results and omitting the XML declaration, which is a reasonable way of serializing a MathML document.
static String	serializeDocument(Document document, boolean indent, boolean omitXMLDeclaration) Deprecated. Use one of the alternative methods, including serializeDocument(Document, SerializationSpecifier) for ultimate control.
static String	serializeDocument(Document document, SerializationSpecifier serializationOptions) Convenience method that serializes the given DOM Document as a String, using the specified SerializationSpecifier, creating any XSLT stylesheet required for serialization on an ad hoc basis.
static String	serializeDocument(Document document, SerializationSpecifier serializationOptions, StylesheetManager stylesheetManager) Convenience method that serializes the given DOM Document as a String, using the specified SerializationSpecifier and given StylesheetManager to manage any XSLT stylesheets required to serialize properly.
static String	serializeDocument(Document document, String encoding) Convenience method that serializes the given DOM Document as a String, using the specified encoding, indenting the results and omitting the XML declaration, which is a reasonable way of serializing a MathML document.
static String	serializeDocument(Document document, String encoding, boolean indent) Convenience method that serializes the given DOM Document as a String, using the specified encoding and indentation options and omitting the XML declaration, which is a reasonable way of serializing a MathML document.
static String	serializeDocument(Document document, String encoding, boolean indent, boolean omitXMLDeclaration) Deprecated. Use one of the alternative methods, including serializeDocument(Document, SerializationSpecifier) for ultimate control.
static String	serializeElement(Element element) Convenience method that serializes the given DOM Element as a String (encoded in UTF-8), indenting the results and omitting the XML declaration, which is a reasonable way of serializing MathML.
static String	serializeElement(Element element, boolean indent) Convenience method that serializes the given DOM Element as a String, indenting if specified and omitting the XML declaration which is a reasonable way of serializing MathML.
static String	serializeElement(Element element, boolean indent, boolean omitXMLDeclaration) Deprecated. Use one of the alternative methods, including serializeElement(Element, SerializationSpecifier) for ultimate control.
static String	serializeElement(Element element, SerializationSpecifier serializationOptions) Convenience method that serializes the given DOM Element as a String, using the given SerializationSpecifier, creating any XSLT stylesheet required for serialization on an ad hoc basis.
static String	serializeElement(Element element, SerializationSpecifier serializationOptions, StylesheetManager stylesheetManager) Convenience method that serializes the given DOM Element as a String, using the given SerializationSpecifier and given StylesheetManager to manage any XSLT stylesheets required to serialize properly.
static String	serializeElement(Element element, String encoding) Convenience method that serializes the given DOM Element as a String, using the given encoding, indenting the results and omitting the XML declaration, which is a reasonable way of serializing MathML.
static String	serializeElement(Element element, String encoding, boolean indent) Convenience method that serializes the given DOM Element as a String, using the given parameters.
static String	serializeElement(Element element, String encoding, boolean indent, boolean omitXMLDeclaration) Deprecated. Use serializeElement(Element, SerializationSpecifier) or serializeElement(Element, SerializationSpecifier, StylesheetManager)
static UnwrappedParallelMathMLDOM	unwrapParallelMathMLDOM(Element mathElement) Convenience method to unwrap at MathML DOM Object containing top-level parallel markup, as defined Section 5.3.1 of the MathML 2.0 specification.

Methods inherited from class java.lang.Object

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

Field Detail

ANNOTATION_LOCAL_NAME

public static final String ANNOTATION_LOCAL_NAME

See Also:

Constant Field Values

ANNOTATION_XML_LOCAL_NAME

public static final String ANNOTATION_XML_LOCAL_NAME

See Also:

Constant Field Values

Constructor Detail

MathMLUtilities

public MathMLUtilities()

Method Detail

parseMathMLDocumentString

public static Document parseMathMLDocumentString(String mathmlDocument)
                                          throws IOException,
                                                 SAXException

Convenience method that parses a MathML document specified as a UTF-8-encoded String.

Throws:

IOException

SAXException

convertMfencedToExplicitFences

public static void convertMfencedToExplicitFences(Document document)

Replaces every deprecated MathML mfenced element in the supplied document with its explicit mrow/mo equivalent. The document is modified in place.

convertExplicitFencesToMfenced

public static void convertExplicitFencesToMfenced(Document document)

Converts explicit fences generated by SnuggleTeX back to mfenced. This exists for compatibility with the legacy up-conversion stylesheets and modifies the document in place.

serializeDocument

public static String serializeDocument(Document document)

Convenience method that serializes the given DOM Document as a String (encoded in UTF-8), indenting the results and omitting the XML declaration, which is a reasonable way of serializing a MathML document.

Parameters:

document - DOM document to serialize, must not be null

serializeDocument

public static String serializeDocument(Document document,
                                       SerializationSpecifier serializationOptions)

Convenience method that serializes the given DOM Document as a String, using the specified SerializationSpecifier, creating any XSLT stylesheet required for serialization on an ad hoc basis.

Parameters:

document - DOM document to serialize, must not be null

serializationOptions - desired SerializationOptions, may be null.

Since:

1.2.0

serializeDocument

public static String serializeDocument(Document document,
                                       SerializationSpecifier serializationOptions,
                                       StylesheetManager stylesheetManager)

Convenience method that serializes the given DOM Document as a String, using the specified SerializationSpecifier and given StylesheetManager to manage any XSLT stylesheets required to serialize properly.

Parameters:

document - DOM document to serialize, must not be null

serializationOptions - desired SerializationOptions, may be null.

Since:

1.2.0

serializeDocument

public static String serializeDocument(Document document,
                                       String encoding)

Convenience method that serializes the given DOM Document as a String, using the specified encoding, indenting the results and omitting the XML declaration, which is a reasonable way of serializing a MathML document.

Parameters:

document - DOM document to serialize, must not be null

encoding - desired encoding, null is interpreted as UTF-8.

serializeDocument

public static String serializeDocument(Document document,
                                       String encoding,
                                       boolean indent)

Convenience method that serializes the given DOM Document as a String, using the specified encoding and indentation options and omitting the XML declaration, which is a reasonable way of serializing a MathML document.

Parameters:

document - DOM document to serialize, must not be null

encoding - desired encoding, null is interpreted as UTF-8.

serializeDocument

@Deprecated
public static String serializeDocument(Document document,
                                                    boolean indent,
                                                    boolean omitXMLDeclaration)

Deprecated. Use one of the alternative methods, including serializeDocument(Document, SerializationSpecifier) for ultimate control.

Convenience method that serializes the given DOM Document as a String (encoded in UTF-8).

Parameters:

document - DOM element to serialize

indent - whether to indent the results or not

omitXMLDeclaration - whether to omit the XML declaration or not.

serializeDocument

@Deprecated
public static String serializeDocument(Document document,
                                                    String encoding,
                                                    boolean indent,
                                                    boolean omitXMLDeclaration)

Deprecated. Use one of the alternative methods, including serializeDocument(Document, SerializationSpecifier) for ultimate control.

Convenience method that serializes the given DOM Document as a String, using the specified encoding.

Parameters:

document - DOM element to serialize

encoding - desired encoding, null is interpreted as UTF-8.

indent - whether to indent the results or not

omitXMLDeclaration - whether to omit the XML declaration or not.

serializeElement

public static String serializeElement(Element element)

Convenience method that serializes the given DOM Element as a String (encoded in UTF-8), indenting the results and omitting the XML declaration, which is a reasonable way of serializing MathML.

Parameters:

element - DOM element to serialize, must not be null.

serializeElement

public static String serializeElement(Element element,
                                      SerializationSpecifier serializationOptions)

Convenience method that serializes the given DOM Element as a String, using the given SerializationSpecifier, creating any XSLT stylesheet required for serialization on an ad hoc basis.

Parameters:

element - DOM element to serialize, must not be null.

serializationOptions - SerializationSpecifier, may be null.

Since:

1.2.0

serializeElement

public static String serializeElement(Element element,
                                      SerializationSpecifier serializationOptions,
                                      StylesheetManager stylesheetManager)

Convenience method that serializes the given DOM Element as a String, using the given SerializationSpecifier and given StylesheetManager to manage any XSLT stylesheets required to serialize properly.

Parameters:

element - DOM element to serialize, must not be null.

serializationOptions - SerializationSpecifier, may be null.

stylesheetManager - StylesheetManager, must not be null

Since:

1.2.0

serializeElement

public static String serializeElement(Element element,
                                      String encoding)

Convenience method that serializes the given DOM Element as a String, using the given encoding, indenting the results and omitting the XML declaration, which is a reasonable way of serializing MathML.

Parameters:

element - DOM element to serialize

encoding - desired encoding, null is interpreted as UTF-8.

serializeElement

public static String serializeElement(Element element,
                                      boolean indent)

Convenience method that serializes the given DOM Element as a String, indenting if specified and omitting the XML declaration which is a reasonable way of serializing MathML.

Parameters:

element - DOM element to serialize

indent - whether to indent or not

serializeElement

@Deprecated
public static String serializeElement(Element element,
                                                   boolean indent,
                                                   boolean omitXMLDeclaration)

Deprecated. Use one of the alternative methods, including serializeElement(Element, SerializationSpecifier) for ultimate control.

Convenience method that serializes the given DOM Element as a String (encoded in UTF-8).

Parameters:

element - DOM element to serialize

indent - whether to indent the results or not

omitXMLDeclaration - whether to omit the XML declaration or not.

serializeElement

@Deprecated
public static String serializeElement(Element element,
                                                   String encoding,
                                                   boolean indent,
                                                   boolean omitXMLDeclaration)

Deprecated. Use serializeElement(Element, SerializationSpecifier) or serializeElement(Element, SerializationSpecifier, StylesheetManager)

Convenience method that serializes the given DOM Element as a String, using the given parameters.

Parameters:

element - DOM element to serialize

encoding - desired encoding, null is interpreted as UTF-8.

indent - whether to indent the results or not

omitXMLDeclaration - whether to omit the XML declaration or not.

serializeElement

public static String serializeElement(Element element,
                                      String encoding,
                                      boolean indent)

Convenience method that serializes the given DOM Element as a String, using the given parameters.

(This can be used in more general cases than MathML, through experienced programmers may want more control over what happens here.)

Parameters:

element - DOM element to serialize

encoding - desired encoding, null is interpreted as UTF-8.

indent - whether to indent the results or not

isMathMLElement

public static boolean isMathMLElement(Node node)

Convenience method to test whether the given DOM Node node is a MathML element having any localName.

Parameters:

node - Node to test

Throws:

IllegalArgumentException - if node is null.

isMathMLElement

public static boolean isMathMLElement(Node node,
                                      String localName)

Convenience method to test whether the given DOM Node node is a MathML element having the given localName.

Parameters:

node - Node to test

localName - MathML local name to test for, such as mi or math, or null to indicate "any name in the MathML namespace".

Throws:

IllegalArgumentException - if node is null.

ensureMathMLContainer

public static void ensureMathMLContainer(Element mathElement)

ensureMathMLDocument

public static Element ensureMathMLDocument(Document document)

Checks that the given DOM Document contains a single MathML math Element. If so, the Element is returned. Otherwise, an IllegalArgumentException is thrown.

unwrapParallelMathMLDOM

public static UnwrappedParallelMathMLDOM unwrapParallelMathMLDOM(Element mathElement)

Convenience method to unwrap at MathML DOM Object containing top-level parallel markup, as defined Section 5.3.1 of the MathML 2.0 specification.

If there is no parallel markup detected then null if returned.

If the given element is null or is not a MathML "math" element, then an IllegalArgumentException is thrown.

extractFirstSemanticsBranch

public static Element extractFirstSemanticsBranch(Element mathElement)

extractAnnotationString

public static String extractAnnotationString(Element mathElement,
                                             String encodingAttribute)

Extracts the first textual annotation found having the given encoding attribute from the given MathML math element, if such an annotation is found.

This assumes the following structure:

 <math>
   <semantics>
     ...
     <annotation encoding="...">text</annotation>
   </semantics>
 </math>
 

Parameters:

mathElement -

Returns:

first matching annotation, or null if not present.

extractAnnotationXML

public static NodeList extractAnnotationXML(Element mathElement,
                                            String encodingAttribute)

Extracts the first XML-based annotation having the given encoding attribute from the given MathML math element, if such an annotation is found.

This assumes the following structure:

 <math>
   <semantics>
     ...
     <annotation-xml encoding="...">XML annotation</annotation>
   </semantics>
 </math>
 

Parameters:

mathElement -

Returns:

DOM NodeList corresponding to the child Nodes of the first matching annotation-xml element, or null if no such annotation found.

isolateFirstSemanticsBranch

public static Document isolateFirstSemanticsBranch(Element mathElement)

"Isolates" the first <semantics/> branch of an annotation MathML element by producing a copy of the MathML element with a single child containing only the first child of the <semantics/> element.

For example:

   <math>
     <semantics>
       <mi>x</mi>
       <annotation-xml encoding='blah'><x/></annotation-xml>
     </semantics>
   </math>
   

results in:

   <math>
     <mi>x</mi>
   </math>
   

Returns:

new MathML Document with the given structure or null if the given math element is not annotated.

Throws:

IllegalArgumentException - if passed null or the given element is not a math element.

isolateFirstSemanticsBranch

public static Document isolateFirstSemanticsBranch(UnwrappedParallelMathMLDOM unwrappedDOM)

Version of isolateFirstSemanticsBranch(Element) that works on an UnwrappedParallelMathMLDOM.

Returns:

new MathML Document with the given structure or null if the given wrapper has no first branch.

Throws:

IllegalArgumentException - if passed null.

isolateAnnotationXML

public static Document isolateAnnotationXML(Element mathElement,
                                            String encodingAttribute)

"Isolates" the XML annotation having the given encoding by producing a copy of the MathML element with only the given annotation contents as children.

For example:

   <math>
     <semantics>
       <mi>x</mi>
       <annotation-xml encoding='blah'><x/></annotation-xml>
     </semantics>
   </math>
   

results in:

   <math>
     <x/>
   </math>
   

Returns:

new MathML Document with the given structure or null if the given math element is not annotated or does not have the required annotation.

Throws:

IllegalArgumentException - if passed null or the given element is not a math element.

isolateAnnotationXML

public static Document isolateAnnotationXML(UnwrappedParallelMathMLDOM unwrappedDOM,
                                            String encodingAttribute)

Version of isolateAnnotationXML(Element, String) that works on an UnwrappedParallelMathMLDOM.

Returns:

new MathML Document with the given structure or null if the given wrapper does not have the required annotation.

Throws:

IllegalArgumentException - if passed null.