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);
}