TunableParser (BandM metatools API doc)

java.lang.Object
- eu.bandm.tools.util2.TunableParser<D>

Direct Known Subclasses:

TunableParserForXml
```
public abstract class TunableParser<D>
extends Object
```
Parser skeleton for explicit lexical decoding and recursive descent ("hand-coded") parsing of idiosyncratic grammars. It is prepared for use as a base class for TunedDTDParser (in fact, it is an extraction from the original code.) Therefore it is prepared for "external entity expansion", which is "file inclusion" in a more general way of talking. This is maintained by IncludingCharBuf, to which all character read, buffer insertion and buffer restore is delegated.
The interface methods fall in different categories:
- boolean lookahead (...) yields whether the current input does match.
- void match (...) consumes specified input. MUST match, otherwise calls "fatalError()"
- boolean matchahead (...) combination of both: consumes specified input iff possible.
Beside these basic interfaces there are some more specialized:
- matchUpTo(..) and skipUpTo(..) consumes as long as the specified prefix is NOT reached (or end of input is reached).
- eof(..) matches iff end of input is reached.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`TunableParser.CharSet` Auxiliary class which realizes a character set by the characteristic predicate.
`static class`	`TunableParser.ExtensionalCharSet` Auxiliary class which realizes a character set by a `BitSet`.

Field Summary

Fields
Modifier and Type	Field and Description
`protected @Opt URL`	`base` Basis for resolving include directives.
`protected IncludingCharBuf<D>`	`in` The current input.
`protected SimpleMessage.Generator<D>`	`messageGenerator`
`protected D`	`topleveldocumentid` Id for generating locations in messages.

Constructor Summary

Constructors
Modifier Constructor and Description

protected TunableParser(Reader in, D id, MessageReceiver<? super SimpleMessage<D>> msg)
Constructor.

Constructors
Modifier	Constructor and Description
`protected`	`TunableParser(Reader in, D id, MessageReceiver<? super SimpleMessage<D>> msg)` Constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`consume()` Advance input by one character position.
`protected void`	`eof()` Assume end of input reached.
`protected void`	`error(String msg)`
`protected void`	`failure(String msg)`
`protected abstract void`	`fatalError(String s)` Signals parsing errors, must be re-defined by derived class.
`MessageReceiver<? super SimpleMessage<D>>`	`getMessageReceiver()`
`protected boolean`	`lookahead_eof()` Report whether end of input reached.
`protected boolean`	`lookahead(char c)` Returns whether the next character to read is equal to the parameter.
`protected boolean`	`lookahead(int k, char c)` Returns whether the next character after (k-1) consumptions would be equal to the parameter.
`protected boolean`	`lookahead(int k, TunableParser.CharSet s)` Returns whether the next character after (k-1) consumptions would be contained in the parameter.
`protected boolean`	`lookahead(String prefix)` Returns whether the current input is prefixed by the string parameter.
`protected boolean`	`lookahead(TunableParser.CharSet s)` Returns whether the next character to read is contained in the parameter.
`protected char`	`match()` Consumes any character and returns it.
`protected void`	`match(char c)` Call to `lookahead(char)`,must succeed, then `consume()`.
`protected void`	`match(String prefix)` Call to `lookahead(String)`,must succeed, then `consume()`.
`protected char`	`match(TunableParser.CharSet s)` Call to `lookahead(CharSet)`,must succeed, then `consume()`.
`protected boolean`	`matchahead(char c)` Like `lookahead(char)`, and then `consume()` if success.
`protected boolean`	`matchahead(String prefix)` Like `lookahead(String)`, and then `consume()` if success.
`protected boolean`	`matchahead(TunableParser.CharSet s)` Like `lookahead(CharSet)`, and then `consume()` if success.
`protected String`	`matchUpto(char end)` Consumes all characters upto (excluding) the given delimiter and returns them.
`protected String`	`matchUpto(String end)` Consumes all characters upto (excluding) the given delimiter and returns them.
`@Opt String`	`readExternal(String systemID)` Read a file relative to the current `base` and return its contents.
`void`	`setBase(@Opt URL base)` set base for resolving include directives.
`void`	`setMessageReceiver(MessageReceiver<? super SimpleMessage<D>> messageReceiver)`
`protected void`	`skipUpto(String end)` Consumes all characters upto (excluding) the given delimiter and discard them.
`protected void`	`warning(String msg)`
`protected String`	`word(TunableParser.CharSet alphabet)` Accept any sequence of characters from the given set, including the empty word, and return it.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - in
```
protected IncludingCharBuf<D> in
```
    The current input.
  - topleveldocumentid
```
protected D topleveldocumentid
```
    Id for generating locations in messages.
  - base
```
@Opt
protected @Opt URL base
```
    Basis for resolving include directives.
  - messageGenerator
```
protected final SimpleMessage.Generator<D> messageGenerator
```
- Constructor Detail
  - TunableParser
```
protected TunableParser(Reader in,
                        D id,
                        MessageReceiver<? super SimpleMessage<D>> msg)
```
    Constructor.
    
    Parameters:
    
    in - source to parse
    
    id - id of toplevel document, for locations in messages
    
    msg - message channel
- Method Detail
  - setBase
```
public void setBase(@Opt
                    @Opt URL base)
```
    set base for resolving include directives.
  - setMessageReceiver
```
public void setMessageReceiver(MessageReceiver<? super SimpleMessage<D>> messageReceiver)
```
  - getMessageReceiver
```
public MessageReceiver<? super SimpleMessage<D>> getMessageReceiver()
```
  - error
```
protected void error(String msg)
```
  - failure
```
protected void failure(String msg)
```
  - warning
```
protected void warning(String msg)
```
  - fatalError
```
protected abstract void fatalError(String s)
```
    Signals parsing errors, must be re-defined by derived class.
  - readExternal
```
@Opt
public @Opt String readExternal(String systemID)
```
    Read a file relative to the current base and return its contents. Is based on URLs to allow include of RELATIVELY given files for files in the file system as well as files given as resource/via class loader.
    
    Parameters:
    
    systemID - a "system identifier", which is an URI according to [xml1.0]
  - lookahead
```
protected final boolean lookahead(char c)
```
    Returns whether the next character to read is equal to the parameter.
  - lookahead
```
protected final boolean lookahead(int k,
                                  char c)
```
    Returns whether the next character after (k-1) consumptions would be equal to the parameter.
  - lookahead
```
protected final boolean lookahead(String prefix)
```
    Returns whether the current input is prefixed by the string parameter.
  - lookahead
```
protected final boolean lookahead(TunableParser.CharSet s)
```
    Returns whether the next character to read is contained in the parameter.
  - lookahead
```
protected final boolean lookahead(int k,
                                  TunableParser.CharSet s)
```
    Returns whether the next character after (k-1) consumptions would be contained in the parameter.
  - matchahead
```
protected final boolean matchahead(char c)
```
    Like lookahead(char), and then consume() if success.
  - matchahead
```
protected final boolean matchahead(String prefix)
```
    Like lookahead(String), and then consume() if success.
  - matchahead
```
protected final boolean matchahead(TunableParser.CharSet s)
```
    Like lookahead(CharSet), and then consume() if success.
  - match
```
protected final void match(char c)
```
    Call to lookahead(char),must succeed, then consume(). Calls fatalError(String) if not.
  - match
```
protected final void match(String prefix)
```
    Call to lookahead(String),must succeed, then consume(). Calls fatalError(String) if not.
  - match
```
protected final char match(TunableParser.CharSet s)
```
    Call to lookahead(CharSet),must succeed, then consume().
    Calls fatalError(String) if not.
  - match
```
protected final char match()
```
    Consumes any character and returns it.
  - matchUpto
```
protected String matchUpto(char end)
```
    Consumes all characters upto (excluding) the given delimiter and returns them.
    Calls fatalError(String) if reading beyond end of input.
  - matchUpto
```
protected String matchUpto(String end)
```
    Consumes all characters upto (excluding) the given delimiter and returns them.
    Calls fatalError(String) if reading beyond end of input.
  - skipUpto
```
protected void skipUpto(String end)
```
    Consumes all characters upto (excluding) the given delimiter and discard them.
    Calls fatalError(String) if reading beyond end of input.
  - consume
```
protected void consume()
```
    Advance input by one character position.
  - eof
```
protected void eof()
```
    Assume end of input reached. Call fatalError(String) if not.
  - lookahead_eof
```
protected boolean lookahead_eof()
```
    Report whether end of input reached.
  - word
```
protected String word(TunableParser.CharSet alphabet)
```
    Accept any sequence of characters from the given set, including the empty word, and return it.

Class TunableParser<D>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

in

topleveldocumentid

base

messageGenerator

Constructor Detail

TunableParser

Method Detail

setBase

setMessageReceiver

getMessageReceiver

error

failure

warning

fatalError

readExternal

lookahead

lookahead

lookahead

lookahead

lookahead

matchahead

matchahead

matchahead

match

match

match

match

matchUpto

matchUpto

skipUpto

consume

eof

lookahead_eof

word