ca.gorman.util.scan
Interface Scanner

All Known Implementing Classes:

AbstractScanner

public interface Scanner

Control interface for a character scanning, matching, and translation engine.

The Scanner applies a list of scan rules that matches character sequences in a scan buffer and sends each character sequence to a corresponding action method. The action method can send the characters to the default output, discard the characters, or do something else with them.

When no characters can be matched from the rule list, characters are removed from the scan buffer and send to the default output until more characters can be matched, or until the scan buffer is empty. An effective way to replace a few subsequences of characters is to use scan rules to identify those subsequences and send the replacements to the default output and let the scanner send all all other characters directly to the default output.

If the application designer knows that long sequences of characters will be discarded to default output, scanning efficiency can often be improved by using ScanRules to identify the sequences and send them directly to the default output. When short sequences are to be discarded to the default output, it may be better to let the Scanner do the work.

Method Summary

void	scan(CharSequence charSequence, Appendable appendable, RuleList ruleList) Set the scanner to initial condition, scan a CharSequence with fixed content, and output to an Appendable.
void	scan(CharSequence charSequence, Appendable appendable, RuleList ruleList, InputControl inputControl) Set the scanner to initial condition, scan a CharSequence with modifiable content, and output to an Appendable.
void	scan(Reader reader, Appendable appendable, RuleList ruleList) Set the scanner to initial condition, scan from a Reader, and output to an Appendable.
AsynchronousScanState	startScan(InputScanBuffer inputScanBuffer, Appendable appendable, RuleList ruleList) Start a new asynchonous scanner and return a view of its current state.

Method Detail

scan

void scan(CharSequence charSequence,
          Appendable appendable,
          RuleList ruleList)
          throws IOException

Set the scanner to initial condition, scan a CharSequence with fixed content, and output to an Appendable.

The Appendable will be flushed if it is a Flushable, but will not be closed if it is also a Closeable

Parameters:

charSequence - a character sequence containing the characters to be scanned as input

appendable - a default destination for output from the Scanner

ruleList - the scanning rules

Throws:

IllegalStateException - if Scanner is already running.

IOException - if an output error occurs

NullPointerException - if any parameter is null

scan

void scan(CharSequence charSequence,
          Appendable appendable,
          RuleList ruleList,
          InputControl inputControl)
          throws IOException

Set the scanner to initial condition, scan a CharSequence with modifiable content, and output to an Appendable.

The Appendable will be flushed if it is a Flushable, but will not be closed if it is also a Closeable

Parameters:

charSequence - a character sequence containing the characters to be scanned as input

appendable - a default destination for output from the Scanner

ruleList - the scanning rules

inputControl - a control object that the Scanner can use to make additional characters available in the charSequence

Throws:

IllegalStateException - if Scanner is already running.

IOException - if an output error occurs

NullPointerException - if any parameter is null

scan

void scan(Reader reader,
          Appendable appendable,
          RuleList ruleList)
          throws IOException

Set the scanner to initial condition, scan from a Reader, and output to an Appendable.

The Appendable will be flushed if it is a Flushable, but will not be closed if it is also a Closeable

Parameters:

reader - a source of characters to be scanned as input

appendable - a default destination for output from the Scanner

ruleList - the scanning rules

Throws:

IllegalStateException - if Scanner is already running.

IOException - if an input or output error occurs

NullPointerException - if any parameter is null

startScan

AsynchronousScanState startScan(InputScanBuffer inputScanBuffer,
                                Appendable appendable,
                                RuleList ruleList)
                                throws IOException,
                                       InterruptedException

Start a new asynchonous scanner and return a view of its current state.

The Appendable will be flushed if it is a Flushable, and be closed if it is also a Closeable

Parameters:

inputScanBuffer - a scannable source of character sequences

appendable - a default destination for output from the Scanner

ruleList - the scanning rules

Returns:

the Thread in which the scanner is running

Throws:

InterruptedException - if the thread is interrupted before this method returns

IOException - if an input or output error occurs

NullPointerException - if any parameter is null