cox.jmatt.java.MathTools
Class MathXML

java.lang.Object
  extended by cox.jmatt.java.MathTools.MathXML

public class MathXML
extends java.lang.Object

This class provides XML and MathML Presentation markup utilities to the other MathTools classes. It contains quick methods to wrap number, operator, and identifier (variable) tags around single terms, as well as a method to wrap content in <mrow> tags. It contains two methods for generating fraction markup and the wrapMath() method which generates <math> tags complete with the MathML xmlns URI.

The uber-method here is parseMathML(). It takes a String, optionally containing special formatting characters, and turns it into MathML. It can distinguish between numbers, operators, and identifiers and will tag them appropriately. For multiplication it uses the Unicode 'dot operator' sequence, and for division, the 'division sign' sequence. The wrapXML() method can generate any tagged content and the escapeXML() method replaces certain common characters with their XML entity representations.

Note on Method Naming: Methods beginning with 'wrap' DO NOT parse their input before formatting. Methods named directly after MathML tags, e.g. mSub, mRoot, DO parseMathML() their parameters before adding them. This is done primarily because the parseMathML() method makes use of some of the 'wrap__()' methods. If subclassing, take this into account!

The name of this class, MathXML, was chosen to avoid possible conflict and confusion with other objects that might bear the name 'MathML.' This class is not and was not designed to be the end-all XML class. Rather, it provides sufficient XML/MathML to support the other MathTools classes. As with them, MathXML contains only static methods but provides a constructor for scripting applications.


Nested Class Summary
static class MathXML.MathSymbol
          This enum is used to hold Unicode math symbols and to provide them and their values in an easily accessible way.
 
Field Summary
static java.lang.String NSURI
          String containing the MathML namespace URI.
 
Constructor Summary
MathXML()
          Constructor provided for exposing to scripts.
 
Method Summary
static java.lang.String escapeXML(java.lang.String pData)
          Replace certain characters with their XML escapes.
static java.lang.String formatMonomial(java.lang.String pCoef, java.lang.String pVar, java.lang.String pExp, boolean pSmart)
          Format a monomial (single polynomial term).
static java.lang.String getEntity(java.lang.String pSymbol)
          This method returns a Unicode/XML entity escape for the requested symbol.
 MathXML_SCROB getSCROB()
          Return a SCROB instance of this class.
static MathXML.MathSymbol getSymbol(java.lang.String pSymbol)
          Look up a MathSymbol constant based on a String.
static java.lang.String mFrac(java.lang.String pNumerator, java.lang.String pDenominator)
          Convenience method for mFrac(null, pNumerator, pDenominator).
static java.lang.String mFrac(java.lang.String pWhole, java.lang.String pNumerator, java.lang.String pDenominator)
          This method generates an <mfrac> expression.
static java.lang.String mOver(java.lang.String pBase, java.lang.String pOver)
          Overscript a term.
static java.lang.String mRoot(java.lang.String pRadicand, java.lang.String pIndex)
          Create a <mroot> tag.
static java.lang.String mSqrt(java.lang.String pRadicand)
          Create a <msqrt> tag.
static java.lang.String mSub(java.lang.String pBase, java.lang.String pSub)
          Subscript a term.
static java.lang.String mSubSup(java.lang.String pBase, java.lang.String pSub, java.lang.String pSuper)
          Create a <msubsup> element.
static java.lang.String mSup(java.lang.String pBase, java.lang.String pSuper)
          Superscript a term.
static java.lang.String mUnder(java.lang.String pBase, java.lang.String pUnder)
          Underscript a term.
static java.lang.String mUnderOver(java.lang.String pBase, java.lang.String pUnder, java.lang.String pOver)
          Under- and overscript a term.
static java.lang.String parseMathML(java.lang.String pData)
          This is MathXML's power method.
static java.lang.String wrapMath(java.lang.String pContent, java.lang.String pDisplay)
          Wrap the <math> tags around MathML content.
static java.lang.String wrapMI(java.lang.String pData)
          Wrap something in identifier tags, <mi>.
static java.lang.String wrapMN(java.lang.String pData)
          Wrap something in number tags, <mn>.
static java.lang.String wrapMO(java.lang.String pData)
          Wrap something in operator tags, <mo>.
static java.lang.String wrapRow(java.lang.String pData)
          Wrap a math row, <mrow>.
static java.lang.String wrapTag(java.lang.String pTag, java.lang.String pContent)
          Create an XML tag around the supplied content.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NSURI

public static final java.lang.String NSURI
String containing the MathML namespace URI.

See Also:
Constant Field Values
Constructor Detail

MathXML

public MathXML()
Constructor provided for exposing to scripts.

Method Detail

escapeXML

public static java.lang.String escapeXML(java.lang.String pData)
Replace certain characters with their XML escapes. This method replaces <, >, &, " and ' only. If pData is null or empty it is returned unaltered.

Parameters:
pData - The String to XML-escape.
Returns:
The same String with all dangerous characters replaced.

getSymbol

public static MathXML.MathSymbol getSymbol(java.lang.String pSymbol)
Look up a MathSymbol constant based on a String. This is an error-save way to do a lookup; if the symbol is not found the result is the constant 'NOT_EXIST'. Any errors are reported at Debug level.

Parameters:
pSymbol - The name of the MathSymbol to retrieve. It must EXACTLY MATCH the name of the symbol.
Returns:
The requested symbol or 'NOT_EXIST' if it could not be found.

getEntity

public static java.lang.String getEntity(java.lang.String pSymbol)
This method returns a Unicode/XML entity escape for the requested symbol. Basically it wraps the (decimal) value between '&#' and a semicolon.

Parameters:
pSymbol - The symbol to look up.
Returns:
The XML-entity value as a String.

wrapMath

public static java.lang.String wrapMath(java.lang.String pContent,
                                        java.lang.String pDisplay)
Wrap the <math> tags around MathML content. The content itself is not escaped, so that should be done before calling this method. The full 'xmlns=' namespace URI is supplied. If pContent is null or empty an empty tag with a unique ID attribute is returned. The display should be 'block', 'inline', or null. If null it is ignored, otherwise it is added exactly as it is passed. Use with care!

Parameters:
pContent - XML content to be wrapped in math tags.
pDisplay - The 'display=' attribute: 'inline', 'block', or null.
Returns:
The content wrapped in <math> tags.

wrapTag

public static java.lang.String wrapTag(java.lang.String pTag,
                                       java.lang.String pContent)
Create an XML tag around the supplied content. If the tag name is null or empty the method returns null or empty. If the content is null or empty it returns an empty tag of the type specified with a unique ID attribute. All wrap_() methods except wrapMath() echo back to this one.

Parameters:
pTag - The name of the tag to create.
pContent - The content to include in the tag.

wrapMN

public static java.lang.String wrapMN(java.lang.String pData)
Wrap something in number tags, <mn>. This is the MathML tag used to enclose a number.


wrapMI

public static java.lang.String wrapMI(java.lang.String pData)
Wrap something in identifier tags, <mi>. This is the MathML tag used to enclose an identifier (variable).


wrapMO

public static java.lang.String wrapMO(java.lang.String pData)
Wrap something in operator tags, <mo>. This is the MathML tag used to enclose an operation symbol.


wrapRow

public static java.lang.String wrapRow(java.lang.String pData)
Wrap a math row, <mrow>. This is used for multiple terms that should be written in a horizontal row.


parseMathML

public static java.lang.String parseMathML(java.lang.String pData)

This is MathXML's power method. It parses a String containing one or more formatting characters and generates a MathML expression. The data String is broken down into space-separated tokens and parsed from left to right. The MathML is generated dynamically as the tokens are iterated.

The formatting characters are:

Tokens that start with a letter are assumed to be identifiers (variables).

If the input String is null or empty an empty <mrow> tag with a unique ID is returned.

CAUTION:Using more than one space to separate the tokens may confuse the parser!

Parameters:
pData - The data String containing raw data to be parsed.
Returns:
MathML per formatting characters and the rules cited above.

mFrac

public static java.lang.String mFrac(java.lang.String pWhole,
                                     java.lang.String pNumerator,
                                     java.lang.String pDenominator)

This method generates an <mfrac> expression. If the whole part is not null or empty, the resulting expression is in a row. If so, just the <mfrac> tag is generated. All three parts are sent to parseMathML() before being included: if one of the components should be in a row it must be enclosed in '@r' and '@R' to ensure proper parsing. The whole part need not be 'rowed' as it is automatically a part of a mrow tag.

NOTE: This method should not be confused with the 'MFraction' class. The former is a MathXML method for formatting fractions per MathML Presentation specification. The latter is a MathTools class encompassing the behavior AND presentation of fractions.

Parameters:
pWhole - The whole part of the fraction. May be null or empty.
pNumerator - The numerator of the fraction.
pDenominator - The denominator of the fraction.
Returns:
A freshly-created mfrac expression.

mFrac

public static java.lang.String mFrac(java.lang.String pNumerator,
                                     java.lang.String pDenominator)
Convenience method for mFrac(null, pNumerator, pDenominator).


mSup

public static java.lang.String mSup(java.lang.String pBase,
                                    java.lang.String pSuper)
Superscript a term. Both operands are fed to parseMathML() before processing, so parser markup is allowed. If the superscript is null or empty it is ignored and only pBase is parsed.

Parameters:
pBase - The base to which the superscript is attached.
pSuper - The superscript to attach.
Returns:
A properly parsed and formatted <msup> element.

mSub

public static java.lang.String mSub(java.lang.String pBase,
                                    java.lang.String pSub)
Subscript a term. Both operands are fed to parseMathML() before processing, so parser markup is allowed. If the subscript is null or empty it is ignored and only pBase is parsed.

Parameters:
pBase - The base to which the subscript is attached.
pSub - The subscript to attach.
Returns:
A properly parsed and formatted <msub> element.

mSubSup

public static java.lang.String mSubSup(java.lang.String pBase,
                                       java.lang.String pSub,
                                       java.lang.String pSuper)
Create a <msubsup> element. If either the subscript or superscript is null or empty the other is sent to the appropriate method. All parameter Strings are parsed before adding so parser markup will be valid.

Parameters:
pBase - The base to which the super- and subscript are attached.
pSub - The subscript to attach. Ignored if null or blank.
pSuper - The superscript to attach. Ignored if null or blank.
Returns:
A fresh <msubsup> element.

formatMonomial

public static java.lang.String formatMonomial(java.lang.String pCoef,
                                              java.lang.String pVar,
                                              java.lang.String pExp,
                                              boolean pSmart)
Format a monomial (single polynomial term). This method operates one of two ways. In 'raw' mode everything present is a part of the result. The only things omitted are things that are null or blank. In 'smart' mode exponents of 1 are excluded and the exponent (0) and variable are excluded from the constant term. Neither mode encloses the monomial in <mrow> tags as it is assumed the monomial is in fact part of a polynomial which will be wrapped in its entirety. All entries are parsed before being tagged, so parser markup is supported.

Parameters:
pCoef - The coefficient of the term.
pVar - The variable of the term. If it is null or blank both it and the exponent are ignored.
pExp - The exponent of the variable. If this can't be parsed as an int, the method reverts to 'raw' mode.
pSmart - true to activate 'smart' mode, false for 'raw' mode.
Returns:
A freshly-formatted and parsed monomial term.

mOver

public static java.lang.String mOver(java.lang.String pBase,
                                     java.lang.String pOver)
Overscript a term. Both operands are fed to parseMathML() before processing, so parser markup is allowed. If the overscript is null or empty it is ignored and only pBase is parsed.

Parameters:
pBase - The base to which the overscript is attached.
pOver - The overscript to attach.
Returns:
A properly parsed and formatted <mover> element.

mUnder

public static java.lang.String mUnder(java.lang.String pBase,
                                      java.lang.String pUnder)
Underscript a term. Both operands are fed to parseMathML() before processing, so parser markup is allowed. If the underscript is null or empty it is ignored and only pBase is parsed.

Parameters:
pBase - The base to which the underscript is attached.
pUnder - The underscript to attach.
Returns:
A properly parsed and formatted <munder> element.

mUnderOver

public static java.lang.String mUnderOver(java.lang.String pBase,
                                          java.lang.String pUnder,
                                          java.lang.String pOver)
Under- and overscript a term. All operands are fed to parseMathML() before processing, so parser markup is allowed. If either *script is null or empty the other is processed normally.

Parameters:
pBase - The base to which the underscript is attached.
pUnder - The underscript to attach.
Returns:
A properly parsed and formatted <munderover> element.

mSqrt

public static java.lang.String mSqrt(java.lang.String pRadicand)
Create a <msqrt> tag. The radicand is parsed but does NOT need to be 'rowed' since the tag allows multiple children.


mRoot

public static java.lang.String mRoot(java.lang.String pRadicand,
                                     java.lang.String pIndex)
Create a <mroot> tag. Both parameters are parsed and MUST be rowed if they contain more than one element.

Parameters:
pRadicand - The radicand of the resulting radical.
pIndex - The value of the root to be taken.
Returns:
A freshly-formed <mroot> tag.

getSCROB

public MathXML_SCROB getSCROB()
Return a SCROB instance of this class.