The MathTools package was designed as an aid in preparing and formatting math questions for printed tests. Its classes and methods are optimized for that. The targeted technologies are the OpenOffice.org Equation Editor and, where feasible, MathML Presentation. MathTools is NOT designed to solve out-there level higher math problems. Rather, MathTools provides a way to quickly prepare and format questions common to arithmetic and algebra tests.
The core tools were designed with scripting in mind. An implementation of this is provided via the ScriptPanel in MTDemo, the JAR's Main-Class. This makes
MathTools usable 'out of the JAR' and without any modification. Each core class has a demonstration Panel in MTDemo. The scripting framework is via
javax.script and provision is made to access any file or URL, thus making scripting possible in any language with a compliant API and JAR file.
The default scripting language is JavaScript but this is easy to change.
All MathTools core classes with the exception of CapCom are designed for script exposure. Toward this end CapCom has a static method, installStandardObjects(),
whose sole purpose is to expose MathTools classes. For custom scripting applications this may be the only method required. In simpler cases, ScriptPanel should
suffice.
Besides being designed for scripting, the MathTools are designed to work together. The most common presentation unit is the Question. A Question consists of an ID (problem number), a Problem component and an Answer component. The class provides machinery to format the data several different ways, including user-defined. The MathEngine class provides fundamental problem-creating equipment, a pseudo-random number generator, several flavors of random-number-generating methods, and a powerful formatting method. The Arithmetic class deals mostly with creating numbers with single-digit granularity, place values, and the names of numbers. Polynomial provides an easy way to format and present polynomials and can be used for that and factoring problems. The Percent class goes past convenience methods and into laziness! It presents machinery to solve a percent problem for any of the three quantities along with an easy way to format the Question (using MathEngine equipment!). MFraction deals with manipulating, presenting and formatting fractions. MMatrix and MMatrixBuilder do the same for matrices and systems of equations or inequalities. MEquation simplifies generating common 'solve-it test' flavors of equations and inequalities. MRadical deals with creating and presenting radical expressions. MathStat offers a way to quickly perform common statistical calculations and format them for presentation.
Many MathTools classes are designed around static methods. This makes them easy to use and cuts down on superfluous instantiation. Unfortunately, not all scripting language implementations expose static methods to their scripts. MathTools overcomes this two ways: shadowing methods and SCROBS. Classes that represent actual mathematical things meant to be manipulated (MFraction, Polynomial) or with few intrinsic static methods 'shadow' these methods with instance methods that reflect to them. Most static methods of the form 'create__()' have a 'new__()' instance method connected to them. Others might alter the method name slightly.
MathTools classes consisting only of static methods implement a specific instance method: getSCROB(). A SCROB (SCRiptable OBject) is a class that
implements instance methods exactly matching the static methods of the MathTools class it SCROBs. If a script begins throwing Exceptions of the form
'Cannot find method blah()' where blah() is some static method, call getSCROB() on that tool and use the SCROB in its place.
Note on SCROB Documentation: SCROBs don't have documentation. They exactly duplicate static classes that DO!
MathTools' logging and communication capability comes courtesy of two things: the MathPrinter interface and the static CapCom class.
MathPrinter is a very light interface, three methods and three constants, used to define communication between MathTools and the outside world. One method is a
logging method with three levels: Debug for tracing program flow and reporting minor problems, Info for things of interest but not necessarily critical to the
application's health, and Error for reporting serious problems or possible crashes. The mathPrintln() method provides a way for programs to communicate
outside the logging framework. This method is useful for output and non-logging messages. The MathPrinter is bi-directional via the processMathObject()
method which gives programs (or scripts!) a way to communicate with the scripting application at runtime.
CapCom, or Capsule Command (NASA) is at the other end of the communication chain. All MathTools classes relay communications through CapCom. CapCom itself makes
provision for setting a MathPrinter to receive these communications. This MathPrinter, the Global Printer, is set by the application using MathTools. This
application can either implement the MathPrinter interface manually or use the BasicMathPrinter class, which provides a GUI and level-filtering capability.
Along with the Global Printer, CapCom maintains a Shelf (Hashtable<String, Object>) for classes to store, retrieve and remove Objects. CapCom
also has a place to store the Global Pizza, a Properties object that can be set before the script starts and accessed by it during execution.
Communication on the script side is via the MathConsole class. MathConsole exists solely to provide communication and logging services to scripts. It defines
convenience methods for all three logging levels, mathPrintln() and a plain println() aliased to it, and access to the MathPrinter's
processMathObject() method. The MathConsole also allows scripts to pull properties from the Global Pizza, and limited access to CapCom's Shelf.
Applications embedding MathTools can use its logging system through the CCLogHandler and CCLogErrorManager classes. These classes
are built around the java.util.logging.* package and they allow its integration into MathTools. The former class extends Handler (in
Java's logging package) and maps logging messages to CapCom. It also provides internal log-system error management. The latter class exists to allow other
(non-MathTools) Handler instances to use CapCom for log-system error management. Since most third-party logging applications make provision for
using Java's built-in framework these classes also allow them to be used with MathTools!
MathTools provides basic equipment for dealing with MathML and XML. The MathXML class (core) provides convenient methods for generating some of the more common
MathML Presentation markup. For more complex needs, its parseMathML() method can transform a space-separated String into MathML. Special formatting
tokens can also be used to insert MathML tags and Unicode escapes as needed. One important note: MathXML is not intended as the ultimate MathML package; it
merely provides MathTools the MathML equipment it requires.
Many core MathTools classes have a toXML() method. This generates a simpler and more compact flavor than MathML; one specialized for MathTools.
Most of these tags have an optional 'id=' attribute and all of them contain sufficient data to re-construct the class instances from their XML. The MTXProcessor
class (util) does exactly that: it can parse MathTools XML from a File, String, or InputSource and generate a List of MathTools class instances. It can be used
by itself, from within a script, or as a DefaultHandler for a SAXParser. MTXPro is not designed to be the end-all XML processing powerhouse; rather, it is meant
to fulfill the MathTools XML processing requirements.
For generating XML past what MathXML can do, MTXPro provides a way to parse an XML file or String into a DOM tree. The DOM tree can then be manipulated using all the standard DOM methods and Objects. There is a method to create a blank DOM Document which can be used to generate any other DOM entity. This allows XML documents to be constructed without requiring awkward String concatenation and other unpleasantness.
One last piece of equipment MTXPro supplies: basic XSLT. XML data from a file or String can be transformed by an XSLT Stylesheet, from a file or String, with the result returned as a String. Although not required by MathTools per se, it is a handy capability to have around!
MTXErrorHandler, the base class for both MTXProcessor and GraphHandler reports SAX and transformation errors through CapCom's logging
framework. It can be used as-is to check XML documents for errors or subclasses for other flavors of XML processing.
Five of the MathTools core classes have LaTeX formatting built in: MEquation, MFraction, MMatrix, MRadical and Polynomial. These
classes can format LaTeX natively or via the usual formatting means.
The MathTools.markup.latex.* package furnishes classes to generate basic LaTeX markup. LaTeX is a math typesetting language with open-source
implementations for all operating systems and it does an excellent job with simple and complex math notation. The star of the package is LaDocument
which represents a LaTeX document. To generate LaTeX first create a document, add things to it then call its toString() method. The result is markup
ready to be rendered.
For those interested in LaTeX and using a MS-based operating system, MiKTeX Portable is an excellent (and gentle!) way to enter the world of LaTeX.
No math package would be complete without some sort of graphing component. The cox.jmatt.java.MathTools.graphing package supplies one. The base
package contains interfaces for the necessary components plus several concrete classes. The most important of these latter is GraphEngineFactory.
The GraphEngineFactory produces GraphEngine instances, RenderEngines, and Constraints.
GraphEngines generate the necessary components to put on a graph: instances of Axis, Graphable, Polygon, and
GraphPaper. Each of these implements the Renderable interface, meaning it can be rendered onto a graph.
The base package forms a framework, which is then implemented for specific technology. MathTools is at heart a text-generating package and its graphing component is no different. The intent is to allow implementers sufficient structure to provide the machinery required to implement graph generators for other software packages that consume text and produce images.
From the Java (or scripting) viewpoint, the metaphor used is of a student looking at a 'Graph this...' problem and a sheet of graph paper. The machinery is designed to provide as flexible an interface as possible while still allowing room for implementations to accomplish what they must.
While the graphing.* provides ample infrastructure for generating mathematical graphs, MathTools also has a drawing component. This is in the
form of the cox.jmatt.java.MathTools.markup.svg package. SVG, or Scalable Vector Graphics, is an XML standard for drawing. MathTools has a fairly
comprehensive implementation as far as simple (methematical) requirements are concerned. The SVG package was originally intended as a way to create (actual
on-paper) graph paper but it is easily used for simple geometric, algebraic, or trigonometric diagrams.
The SVG classes closely mirror actual SVG tags. This is intentional as the tags themselves are fairly intuitive. A <line> tag results in a line, an
<ellipse> tag results in an ellipse, and so on. All 'tag' classes are ultimately contained in a class named SVGTag, whose toString()
method results in an SVG document.
From there the SVG can be rendered (externally!) into a variety of formats. The Apache Foundation's Batik project can transform SVG into PNG, JPEG, and PDF to name only a few. Other packages also exist. As stated previously, the original intent was plain old graph paper but things started growing on their own!
The cox.jmatt.java.MathTools.markup.* package is minimal but provides two base classes for developing subpackages. The abstract Tag
class provides foundational machinery for developing markup tools for any XML standard. It provides a container for a tag's name, attributes and content along
with static and instance methods for presenting that data. The StyleInfo class encapsulates CSS or attribute styling. The SVG implementation both
illustrates how to do this and it provides a solid set of tools for generating SVG via script.
MathFileIO provides basic file manipulation capabilities to the MathTools packages. The class itself wraps Readers, Writers, InputStreams and
OutputStreams and provides methods to interact with them. Exceptions are caught and reported gracefully, so handling basic filesystem access is fairly
straightforward. Scripts and applications have access to this class but, since Applets seldom have filesystem priviliges, MTApplet does not. When
using ScriptPanel and the default environment all open streams, Readers, and Writers are closed when script execution ends, normally or otherwise.
Custom apps using MathFileIO can implement this with the MathFileIO.closeAll() method.
More advanced (and less-protected) file manipulation is possible through the newRandomAccessFile() method. As implied by the name, it creates and
returns a live java.io.RandomAccessFile. The only protection provided is automatic closing. Use with care!
Typical uses for MathFileIO are text generation straight to the filesystem and, possibly, file formatting for graphing.* implementations. Still,
other uses are possible and MathFileIO should be flexible enough to provide them.
The MAuthenticator interface provides a flexible in-place way to authenticate users for independent distributed MathTools applications. It defines
three levels of authentication and provides the framework to verify them while leaving the mechanics of it open to customization. CapCom also makes provision
to support it offering authentication services to all the MathTools classes.
The cox.jmatt.java.MathTools.demo package contains Panels designed to show off the MathTools core classes and their methods. MTDemo is the overall container and boss. It allows experimentation on specific classes and methods without requiring specialty test classes. The PizzaPanel provides a flexible way to call methods and supply parameters, along with an extension method for actually embedding the classes and the tests.
The star of the demo package is ScriptPanel, which implements a simple scripting framework. It allows the creation of an URLClassLoader, filling and setting the GlobalPizza, and automatic installation of all MathTools core classes. Scripts can be written in any scripting language with a JAR file or accessible URL.
Besides ScriptPanel the demos include several classes that 'demonstrate' very well but also serve as powerful and useful tools on their own.
GPGenerator consists of individual panels devoted to the generation of graph paper. Square-grid, polar, log and semilog are built in as is a panel
to generate blank columnar tables with headings (think grade rosters or ledger sheets). The MathDBC demo can be used to load and execute raw
SQL statements and, with the appropriate JDBC driver, build and manipulate databases. MTFormatterDemo can fill a template (from a file or in its
own internal area!) with data from a file, from its internal Properties panel (including the Global Pizza, if it is set elsewhere), or from data fed into its
Regular Expression processor.
The util package contains support classes for the core package and utilities for programs embedding them. QuickRPNCalculator provides a GUI-ready calculator
based on MathEngine's parseRPN() method. The MathPrinter interface lives here, as do the BasicMathPrinter and MathConsole. Rounding out the package
is MTApplet, an Applet designed to allow HTML-page scripting of MathTools. (Not necessarily web-based, though there is certainly no restriction. Firefox and
MTApplet work very well with HTML documents on a hard drive!)
The MathToolsAccessory interface offers a truly painless way to extend MathTools. Classes implementing this interface can be loaded by CapCom with
a single method call. Likewise the COFormatter interface and its companion COFormatterFactory provide a simple way to provide custom
Object formatting.
MathTools also presents the Noteworthy markup scheme and its processing class NoteworthyParser. Simply stated, Noteworthy markup allows
parts of a text document to be extracted and turned into HTML documents. Less simply stated, Noteworthy provides an easy way to prepare structured lecture
notes around and including simply-formatted HTML content thus reducing duplication of effort in producing lecture notes and the HTML slides meant
to accompany them.
The true power of Noteworthy lies in the fact that the extractable parts of the document are made so by simple, logical and minimal formatting sequences. All Noteworthy markup begins with a double-quote and everything is trimmed of excess whitespace before it is processed. This allows hard-formatting of the text into whatever best suits the human using it while retaining the ability to extract the HTML for use with a projector or similar technology. Also, since it is a presentation technology Noteworthy concentrates on a logical structure for its documents: divisions, paragraphs, lists and tables. Noteworthy uses ordered and unordered lists but also includes definition lists ('<dl>'), and the Noteworthy formatting mirrors plain-text formatting that makes the structuring apparent.
For producing HTML markup NoteworthyParser uses the MathTools.markup.html.* package. It accepts a MathGenHTML (or creates
its own) for producing HTML tag classes and returns a HTMLTag instance. This allows full configuration and default-setting options before the
Noteworthy document is parsed.
Noteworthy is similar in philosophy and structure to Markdown, but differs in optimization. Noteworthy is specifically designed to allow the HTML content and the (non-parsed) notes concerning it to be mixed, to be combined in the same document.
The easiest way to explore MathTools is by double-clicking its JAR and playing with the demo panels. The easiest way to explore scripting is through ScriptPanel. Type in some JavaScript and click the [RunScript] button. Experiment with the different tools until you find what works. Despite its austere interface ScriptPanel offers a lot of power and flexibility. If JavaScript doesn't appeal, point the URL Loader to your favorite language's JAR file and start scripting. If the output appears on the BasicMathPrinter it should also be on the clipboard. Paste it into an OpenOffice document and convert the notation.
Subclass ScriptPanel and override its extension methods. Customize the ClassLoader and ScriptEngine as needed. Design a basic GUI, add the new ScriptPanel and a BasicMathPrinter and you're ready to go.
For stricter requirements, where subclassing ScriptEngine just won't do, MathTools is easy to embed. Implement MathPrinter manually and define its processMathObject() method. Then design the GUI (or command-line app), set your MathPrinter in CapCom and start running. Make sure the output is accessible as this is how MathTools reports error conditions!
So your Java doesn't come with JavaScript pre-installed and you can't find a JAR. MTApplet to the rescue. As stated previously, MathTools absolutely works with
Firefox 3.0.5 and should work with any browser that supports connecting Applets and scripts. Write a bare-bones HTML document, include MTApplet, and obtain a
reference to in the browser's scripting language. MTApplet is a MathPrinter but does not set itself as the Global Printer automatically; rather, its
setAsPrinter() method does that.
Once you have a reference to MTApplet you have access to all MathTools classes and MathConsole. MTApplet provides methods for obtaining an instance of each, and there are plenty of ways to get more from there! Although it doesn't provide easy access to the clipboard, sending output into the HTML page is as easy as including an empty <div> tag with an 'id=' attribute.
MathTools is a Java package written in Java and packed in a Java JAR. If you are a Java programmer and already have tools to help generate math questions, put the MathTools JAR in your classpath and start using them. In Java.
Interesting, but none of the other ways will quite do the trick. Download the source code and modify it as needed! 'Nuff said.
By default MathTools is released under the Apache License. If this is not adequate, MathTools may be released under any Open Source license subject to the following conditions:
GPL, LGPL, MIT, BSD, et. al. Any license that encourages use and redistribution is fine with me PROVIDED it does not 'close' or 'proprietize' the MathTools package! I designed MathTools to be useful and to encourage efficient test-making, and that is what I want to happen! If you make money with it you can buy me a pizza someday. If you make a LOT of money with it, make a contribution toward education. Math and CSCI scholarships can always use funding! If you get a lot of MathTools mileage but DON'T make a lot of money from it, consider contributing time, development, debugging, or cool scripts to the project!
Finally, as a matter of courtesy, please give credit due (to me and any other contributors) if you redistribute the package!
MathTools is a result of three major things. First, Java with its power and flexibility. Second, the Rhino JavaScript engine written in Java. These two tools allowed me to design programs that made designing tests for my students quicker and more efficient. Finally, the OpenOffice suite with its easy text-based Equation Editor and powerful word processor made preparing and formatting simple.
The MathTools package itself evolved over many nights of programming and trying to add 'just one more thing' to the toolbox I already had. The first formal MathTools worked wonderfully but it was a disjointed collection of disconnected applications. When I finally upgraded to the new Java (1.6, most of what I did was 1.4 with some tools stretching back to 1.2!) I decided to break it in by re-writing my MathTools for greater consistency and flexibility. And a more uniform way of presenting demonstrations of the tools themselves!
I am a college math professor specializing in developmental and transitional studies, so most of my MathTools are designed with that in mind. Still, what works for Intermediate Algebra also works handily for College Algebra and beyond. I've tried to make the tools easy to use but, when conflict occurs, I chose flexibility and potential. As of now I am still a MathML novice so that capability is somewhat lacking but as I improve my skill there I'll also improve my MathTools.
As far as JavaDoc goes, I've tried to provide sufficient documentation of how to use things and what to use them on. If that isn't enough, double-click MathTools.jar and play with the demos! That's why they are there. These tools are as unbreakable as possible; and, where not possible I've tried to document the fragile parts.
With that said, I hope you enjoy using MathTools as much as I enjoyed writing them!