Chapter 4. Invisible XML

4.1. InvisibleXml

The org.nineml.coffeefilter.InvisibleXml class.

4.1.1. Field summary

Public fields for the org.nineml.coffeefilter.InvisibleXml class.

public static final String logcategory = "InvisibleXml": The category name used for InvisibleXml log messages.
public static final String IXML_10 = "1.0"
public static final String IXML_10_NINEML = "1.0-nineml"
public static final String IXML_11 = "1.1"
public static final String IXML_11_NINEML = "1.1-nineml"
public static final String XMLNS_ATTRIBUTE = "https://coffeefilter.nineml.org/attr/xmlns": The internal name for the xmlns parser attribute.
public static final String NAME_ATTRIBUTE = "https://coffeefilter.nineml.org/attr/name": The internal name for the name parser attribute.
public static final String MARK_ATTRIBUTE = "https://coffeefilter.nineml.org/attr/mark": The internal name for the mark parser attribute.
public static final String TMARK_ATTRIBUTE = "https://coffeefilter.nineml.org/attr/tmark": The internal name for the tmark parser attribute.
public static final String INSERTION_ATTRIBUTE = "https://coffeefilter.nineml.org/attr/insertion": The internal name for the insertion parser attribute.
public static final String DISCARD_ATTRIBUTE = "https://coffeefilter.nineml.org/attr/discard": The internal name for the discard parser attribute.
public static final String ixml_prefix = "ixml": The namespace prefix for the Invisilble XML namespace.
public static final String ixml_ns = "http://invisiblexml.org/NS": The Invisible XML namespace URI.
public static final String nineml_prefix = "n": The namespace prefix for the NineML namespace.
public static final String nineml_ns = "https://nineml.org/ns/": THe NineML namespace URI.
public static final String AMBIGUOUS = "ambiguous": The iXML “ambiguous” state .
public static final String VERSION_MISMATCH = "version-mismatch": The iXML “version-mismatch” state.

4.1.2. Constructor summary

Public constructors for the org.nineml.coffeefilter.InvisibleXml class.

public InvisibleXml()

throws IxmlException if the Invisible XML parser for Invisible XML cannot be loaded

Creates a new InvisibleXml object (with default options) from which parsers can be constructed.

Attempts to load the Invisible XML parser for Invisible XML from resources. This constructor uses default options.

public InvisibleXml(ParserOptions options)

throws IxmlException if the Invisible XML parser for Invisible XML cannot be loaded

Creates a new InvisibleXml object (with custom options) from which parsers can be constructed.

Attempts to load the Invisible XML parser for Invisible XML from resources.

4.1.3. Method summary

Public methods on the org.nineml.coffeefilter.InvisibleXml class.

public ParserOptions getOptions()

Get the parser options currently being used to construct parsers.

Changing properties on the options will only effect subsequently constructed parsers. Each parser gets its own copy of the options.

public InvisibleXmlParser getParser()

The parser for ixml grammars.

public InvisibleXmlParser getParser(File source)

throws IOException if attempting to open or read the source fails

throws IxmlException if the source cannot be identified or is not a valid grammar

Get a parser from a file.

Sniffs the first 4095 bytes of the input to identify the input as an ixml grammar, a vxml grammar, or a compiled grammar. Assumes the input is in UTF-8.

public InvisibleXmlParser getParser(File source String encoding)

throws IOException if attempting to open or read the source fails

throws IxmlException if the source cannot be identified or is not a valid grammar

Get a parser from a file with an explicit encoding.

Sniffs the first 4095 bytes of the input to identify the input as an ixml grammar, a vxml grammar, or a compiled grammar.The encoding is irrelevant for vxml or compiled grammars.

public InvisibleXmlParser getParser(InputStream stream String systemId)

throws IOException if attempting to read the source fails

throws IxmlException if the source cannot be identified or is not a valid grammar

Get a parser from an input stream.

Sniffs the first 4095 bytes of the input stream to identify the input as an ixml grammar, a vxml grammar, or a compiled grammar. Assumes the input is in UTF-8.

public InvisibleXmlParser getParser(InputStream stream String systemId String encoding)

throws IOException if attempting to open or read the source fails

throws IxmlException if the source cannot be identified or is not a valid grammar

Get a parser from an input stream with an explicit encoding.

Sniffs the first 4095 bytes of the input stream to identify the input as an ixml grammar, a vxml grammar, or a compiled grammar. The encoding is irrelevant for vxml or compiled grammars.

public InvisibleXmlParser getParser(URI source)

throws IOException if attempting to open or read the source fails

throws IxmlException if the source cannot be identified or is not a valid grammar

Get a parser from a URI.

Attempts to read from the URI with source.toURL().openConnection(). Sniffs the first 4095 bytes of the input to identify the input as an ixml grammar, a vxml grammar, or a compiled grammar. Assumes the input is in UTF-8.

public InvisibleXmlParser getParser(URI source String encoding)

throws IOException if attempting to open or read the source fails

throws IxmlException if the source cannot be identified or is not a valid grammar

Get a parser from a URI with an explicit encoding.

public InvisibleXmlParser getParserFromIxml(InputStream stream String charset)

throws IOException If an error occurs reading the stream or if the character set is unsupported.

throws IxmlException if the input is not an ixml grammar

Constructs a parser from an ixml grammar.

public InvisibleXmlParser getParserFromIxml(String input)

throws IxmlException if the input is not an ixml grammar

Constructs a parser from an ixml grammar.

public InvisibleXmlParser getParserFromVxml(InputStream stream String systemId)

throws IOException if the input cannot be read

throws IxmlException if the input is not an ixml grammar

Construct a parser from an XML representation (vxml) of an ixml grammar

public List<String> knownPragmas()

The known pragma names.

public List<String> knownStates()

The known states.

public boolean satisfiesVersion10(String version)

Is this version a valid “1.0” version?

The valid 1.0 versions are “1.0” and “1.0-nineml”.

public boolean satisfiesVersion11(String version)

Is this version a valid “1.1” version?

The valid 1.1 versions are “1.1” and “1.1-nineml”.

4.2. InvisibleXmlParser

The org.nineml.coffeefilter.InvisibleXmlParser class.

4.2.1. Field summary

Public fields for the org.nineml.coffeefilter.InvisibleXmlParser class.

public static final String logcategory = "InvisibleXml"

4.2.2. Method summary

Public methods on the org.nineml.coffeefilter.InvisibleXmlParser class.

public boolean constructed()

Did the grammar parse succeed?

public Exception getException()

Return the exception that caused an attempt to build a parser to fail.

If the attempt was successful, or if failure did not raise an exception, null will be returned.

public InvisibleXmlDocument getFailedParse()

If the attempt to parse the grammar failed, return a representation of that failure.

public SourceGrammar getGrammar()

throws NullPointerException if this parser has no grammar

Get the underlying grammar

public HygieneReport getHygieneReport()

Get the hygiene report for this parser’s grammar

public String getIxmlVersion()

public Map<String, List> getMetadata()

Get metadata.

Pragmas in the prolog that aren’t recognized by the processor are returned as “data” pragmas associating a URI with (a list of) values.

public ParserOptions getOptions()

Get the parser options.

public long getParseTime()

Get the time spent parsing the input grammar.

This returns the number of milliseconds of “wall clock time” spent by the processor constructing this parser.

public InvisibleXmlDocument parse(File source)

throws IOException If the source cannot be read

throws NullPointerException if this parser has no grammar

Get a document from a file.

Assumes the input is in UTF-8.

public InvisibleXmlDocument parse(File source String encoding)

throws IOException If the stream cannot be read or if the character set is unsupported.

throws NullPointerException if this parser has no grammar

Get a document from a file with an explicit encoding.

public InvisibleXmlDocument parse(InputStream stream String encoding)

throws IOException If the stream cannot be read or if the character set is unsupported.

throws NullPointerException if this parser has no grammar

Get a document from a stream.

public InvisibleXmlDocument parse(String input)

throws NullPointerException if this parser has no grammar

Get a document from a string.

public InvisibleXmlDocument parse(URI source)

throws IOException If the source cannot be read

throws NullPointerException if this parser has no grammar

Get a document from a URI.

Attempts to read from the URI with source.toURL().openConnection(). Assumes the input is in UTF-8.

public InvisibleXmlDocument parse(URI source String encoding)

throws IOException If the stream cannot be read or if the character set is unsupported.

throws NullPointerException if this parser has no grammar

Get a document from a URI with an explicit encoding.

Attempts to read from the URI with source.toURL().openConnection().

public InvisibleXmlDocument parse(Token[] input)

throws NullPointerException if this parser has no grammar

Get a document from an array of tokens.

public String readInputStream(InputStream stream String charset)

4.3. InvisibleXmlDocument

The org.nineml.coffeefilter.InvisibleXmlDocument class.

From this object, you can obtain the parsed representation(s) of the document. For ambiguous grammars, there may be more than one.

4.3.1. Method summary

Public methods on the org.nineml.coffeefilter.InvisibleXmlDocument class.

public TreeBuilder getAdapter(ContentHandler handler)

Returns an adapter for SAX ContentHandlers.

public int getColumnNumber()

Get the column number of the last line processed.

If the parse failed, this will be the position of the character in the last line where the error occurred.

public int getLineNumber()

Get the line number of the last line processed.

If the parse failed, this will be the line on which the error occurred. Lines are counted by occurrence of ’\n’.

public long getNumberOfParses()

Return the number of available parses of this document.

Will return 0 if there are no successful parses.

public int getOffset()

Get the offset of the last character processed.

If the parse failed, this will be the position of the character in the input stream.

public ParserOptions getOptions()

Get the parser options.

public ParserType getParserType()

Return the parser type.

public String getParserVersion()

Get the parser version.

public GearleyResult getResult()

Return the underlying GearleyResult result for this parse.

public String getTree()

throws org.nineml.coffeefilter.exceptions.IxmlException if the parse failed

Return an XML representation of the current parse.

public void getTree(PrintStream output)

Write an XML representation of the current parse to the stream.

public void getTree(TreeBuilder builder)

Process the result with your own TreeBuilder.

This API needs work.

public void getTree(ContentHandler handler)

Write an XML representation of the current parse to a SAX ContentHandler.

public void getTree(ContentHandler handler ParserOptions options)

Write an XML representation of the current parse to a SAX ContentHandler using a different set of options.

public boolean isAmbiguous()

Is this document ambiguous?

The return value is arbitrary if the parse did not succeed.

public boolean isInfinitelyAmbiguous()

Is this document infinitely ambiguous?

The return value is arbitrary if the parse did not succeed.

public long parseTime()

Returns the amount of time (roughly) spent parsing.

public boolean succeeded()

Did the parse succeed?