Conceptual guide

This page gives a conceptual guide to the omath API. It's not necessarily the best place to start hacking: see the Hacker's guide. On the other hand, if you get confused by something, try reading this.

The two most important interfaces in the omath API are  and. Amongst other things,  has a method public Expression evaluate(Expression), which takes an expression, repeatedly applies 'rules' stored in the internal state of the Kernel instance, and returns the fixed point of this process.

The Expression interface
Corresponding to every omath expression is an instance of the Expression interface. There are many different implementations of the Expression interface, and indeed extensions to omath, residing in the 'core libraries' or in external libraries can provide their own implementations.

The important methods are
 * Expression head
 * returns the 'head' of the expression.


 * List leaves
 * returns the 'arguments' or 'leaves' of the expression.


 * String fullFormString
 * return the 'FullForm' representation of the expression as a string.

Using these methods you can 'drill down' to examine the constituent pieces of an expression. has a subinterface. It has no extra methods, but the contract for RawExpression objects demands that leaves return null. Conversely, any Expression instance which does not implement RawExpression may not return null from leaves, although it may return an empty List. The API defines 4 subinterfaces of RawExpression, namely SymbolExpression, StringExpression, IntegerExpression and RealExpression.

Further, the contract for Expression insists that all instances are immutable; that is, they cannot change in any way after instantiation. In particular, if you're writing an implementation of the Expression interface, you should make sure that the Lists returned from leaves are immutable, or, if they are, changes do not change the internal state of the Expression they came from. Mutable instances should be considered serious bugs.

Mostly as 'convenience' methods for building other Expressions, Expression also has methods  and. These should return Expression instances with the current Expression as the head, and the passed arguments as the leaves; mostly you don't need to worry about implementing these methods, as abstract implementations take care of them for you.

TODO: explain substituteSymbols, topHead, and substitutingTransformer

The Kernel interface
The Kernel interface is quite complicated