Warning:
This wiki has been archived and is now read-only.
MicroLarkApi
This is a view of the as yet unreleased MicroLark 0.9 parser API. Comments are welcome.
A Reader is a class which provides pull events representing a MicroXML document. Each call to next() advances to the next point within the document and returns a code representing what is available at this point (or, if there is an error, what it is). Parser objects do push parsing of a Reader (character stream) or InputStream (byte stream). By specifying a Factory, Parsers can be made to return a subclass of Element.
interface Reader { // advance to next point int next(); // retrieve the current state at this point Element getElement(); String getData(); int getLineNumber(); int getColumnNumber() // static method to translate error codes to error messages static String getErrorMessage(int event); }
class Parser implements Reader { // start pull parsing void parse(InputStream stream); void parse(Reader input); // factory control void setFactory(Factory factory); Factory getFactory(); }
interface Factory { Element newElement(String name, Element parent); }
Element objects are the universal representation of MicroXML elements. The mutation methods are only safe to use after a tree has been built.
class Element { // constructor Element(String name); // basic accessors String getName(); Element getParent(); int children(); int attributes(); // child accessors Object getChild(int index); int findElement(String name); int findElement(String name, int index); Element getElement(String name); Element getChildElement(int n); Element getChildElement(String name, int n); // attribute accessors String getAttributeName(int index); String getAttributeValue(int index); int findAttribute(String name); String getAttributeValue(String name); // convenience accessors Element getRoot(); String getInheritedAttributeValue(String name); String getLanguage(); String getId(); String getBase(); // mutators void setParent(Element parent); void detach(); boolean appendChild(Element element); boolean appendChild(String data); boolean removeChild(Object child); boolean removeChild(int index); boolean insertChild(Element element, int index); boolean insertChild(String data, int index); void setAttributeValue(int index, String value); boolean removeAttribute(String name); void addAttribute(String name, String value); // static methods for local validation boolean isLegalName(String name, boolean attribute); boolean isLegalString(String string); }
ContentHandler is an interface which must be implemented by any class that wishes to have parsing events pushed to it.
interface ContentHandler { void startDocument(); void startElement(Element e); void characters(Element e, String s); void error(Element e, int errorCode, String errorMessage, void endElement(Element e); void endDocument(); }
ElementWriter recursively outputs an element to a Writer (character stream) or OutputStream (byte stream). Features allow control of the details of output.
class ElementWriter { // start writing void startWriting(OutputStream stream); void startWriting(Writer writer); // write an element void write(Element element); // feature control boolean getSingleQuoteFeature(); boolean getIndentationFeature(); boolean getAsciiFeature(); void setSingleQuoteFeature(boolean singleQuoteFeature); void setIndentationFeature(boolean indentationFeature); void setAsciiFeature(boolean asciiOnlyFeature); }
Connect is a static-only class that connects instances of the other classes to provide easy push parsing and tree building.
class Connect { // dispatch events to a content handler void dispatchEvents(Parser parser, ContentHandler contentHandler); void dispatchEvents(Element element, ContentHandler handler); void dispatchEvents(InputStream stream, ContentHandler handler); void dispatchEvents(Reader input, ContentHandler handler) // build an element tree from a parser Element buildTree(Parser parser); Element buildTree(InputStream stream); Element buildTree(Reader input); // write directly from a parser void write(Parser parser, ElementWriter writer); // content handler that writes ContentHandler writerHandler(ElementWriter writer); }