Simple API for NMR-STAR.

Package Details

SANS (Simple API for NMR-STAR) is modelled after Simple API for XML (SAX). Like SAX parsers, SANS parses input line-by-line and calls user-defined methods (callbacks) for each element of NMR-STAR syntax it encouters.

SANS is much faster, and requires far less memory than the DOM-like STAR parser: starlib. Of course, SANS comes with all limitations of SAX parsers.

Classes

{@link EDU.bmrb.sansj.SansParser SansParser}

This validating NMR-STAR parser returns tag/value pairs as DataItemNode objects for free tags and loop tags.

Callbacks are defined by two interfaces (similar to the ones in org.xml.sax):

{@link EDU.bmrb.sansj.DataItemNode DataItemNode}: tag/value pair returned by the parser. This object is somewhat different from starlib's DataItemNode.

{@link EDU.bmrb.sansj.SimpleStarParser SimpleStarParser}

This validatong NMR-STAR parser has separate callbacks for tag and values, so it uses a different callback interface. Tokens are returned as StarNodes similar to those in starlib. Comments are not returned as separate tokens, instead they are returned with StarNode that follows them.

Callback interfaces:

StarNodes for this parser are in {@link EDU.bmrb.sansj.starlib starlib} sub-package.

{@link EDU.bmrb.sansj.CifParser CifParser}

This is a parser for CIF files. The difference between it and SansParser above is that CIF files contain no saveframes and no end-of-loop (stop_) markers; SansParser will report those as errors.

{@link EDU.bmrb.sansj.STARLexer STARLexer}

Scanner generated by JFlex. The scanner returns STAR tokens as int constants.
Note that scanner closes input stream on EOF -- you cannot rewind input stream and parse it again, you need to create a new scanner/parser for that.

{@link EDU.bmrb.sansj.IntStringPair IntStringPair}

Utility class to store tag name and line in the parser.

Usage

Basic usage:

  1. Create an object that implements ContentHandler and ErrorHandler interfaces (e.g. myClass).
  2. Create a STARLexer object on an input stream: STARLexer scanner = new STARLexer( System.in )
  3. Create a SansParser (or CifParser) object on the lexer: SansParser parser = new SansParser( scanner )
  4. Register myClass with parser: 
            parser.setContentHandler( myClass ); 
        parser.setErrorHandler( myClass );
  5. Call parser.parse().
When parser encounters a token, it will call appropriate ContentHandler or ErrorHandler method in myClass. Those methods are where you put your application's logic.

See Test.java in the source directory for basic usage example.