Scanner (org.macroing.cit.java API)

java.lang.Object
- org.macroing.cit.java.util.Scanner

Direct Known Subclasses:

ByteScanner, TextScanner
```
public abstract class Scanner
extends java.lang.Object
```
An abstract base class for a simple scanner.
It makes no assumptions about the data to scan. That's entirely up to the current implementation at hand.
All Scanners are built around a fixed length DataBuffer and two indices. The indices being the indices at the beginning and end of the next consumption. The index at the beginning of the next consumption is inclusive, and the index at the end of the next consumption is exclusive. A consumption essentially sets the value of the index at the beginning of the next consumption to the value of the index at the end of the next consumption.
In order to consume data, you need something to consume. That's where all methods starting with next(...) comes in. The simplest of them is the next() method of this Scanner class. All the others are specific for a given implementation. All of them returns true on success and false otherwise. This means that if you succeed, you have something to consume, and so, calling any of the consume(...) methods should work.
The skip() method essentially advances the index at the beginning of the next consumption and, if necessary, also the index at the end of the next consumption.
The consumption() method returns a String with the current consumption, without consuming it.
The mark() method returns a key that can be used to access the current state again in the future. To access the current state again, simply provide the key to the rewind(int) method. And, to remove the key without rewinding, you can call the unmark(int) method with the key. A key works only once though. The state represents the two indices only.
The error(...) methods can be used to report errors in the syntax, or anything else for that matter.

Since:

1.0.0

Author:

Jörgen Lundgren

Constructor Summary

Constructors
Modifier Constructor and Description

protected Scanner(DataBuffer dataBuffer)
Constructs a new Scanner instance with a given DataBuffer.

Constructors
Modifier	Constructor and Description
`protected`	`Scanner(DataBuffer dataBuffer)` Constructs a new `Scanner` instance with a given `DataBuffer`.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`consume()` A call to this method will attempt to consume the data between the two indices.
`boolean`	`consume(java.lang.StringBuilder stringBuilder)` A call to this method will attempt to consume the data between the two indices, while appending it to `stringBuilder` If the data is successfully consumed, `true` will be returned, `false` otherwise.
`java.lang.String`	`consumption()` Returns a `String` representation of the data that can currently be consumed.
`abstract void`	`error()` Causes a `ScannerException` to be thrown with an implementation-specific detail message.
`abstract void`	`error(java.lang.String message)` Causes a `ScannerException` to be thrown with the given detail message.
`int`	`getIndexAtBeginningOfConsumption()` Returns the index at the beginning of the next consumption.
`int`	`getIndexAtEndOfConsumption()` Returns the index at the end of the next consumption.
`int`	`mark()` Marks the current state of this `Scanner` and returns a key to that mark, such that you can rewind to it at a later time.
`abstract boolean`	`next()` A simple method for advancing the index at the end of the next consumption.
`boolean`	`rewind(int key)` Rewinds the current state of this `Scanner` to some previously marked state.
`void`	`setIndexAtBeginningOfConsumption(int indexAtBeginningOfConsumption)` Sets the index at the beginning of the next consumption.
`void`	`setIndexAtEndOfConsumption(int indexAtEndOfConsumption)` Sets the index at the end of the next consumption.
`boolean`	`skip()` Skips the current data by advancing the index at the beginning of the next consumption with one.
`boolean`	`testNext()` A simple method for testing that `next()` can be called.
`abstract java.lang.String`	`toString(int absoluteIndex)` Returns a `String` representation of the data at the given absolute index.
`boolean`	`unmark(int key)` Unmarks a previous mark given its key.

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

- Constructor Detail
  - Scanner
```
protected Scanner(DataBuffer dataBuffer)
```
    Constructs a new Scanner instance with a given DataBuffer.
    If dataBuffer is null, a NullPointerException will be thrown.
    
    Parameters:
    
    dataBuffer - the DataBuffer used by this Scanner instance
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, dataBuffer is null
- Method Detail
  - consume
```
public final boolean consume()
```
    A call to this method will attempt to consume the data between the two indices.
    If the data is successfully consumed, true will be returned, false otherwise.
    A consumption essentially sets the value of the index at the beginning of the next consumption to the value of the index at the end of the next consumption.
    
    Returns:
    
    true if, and only if, the data is successfully consumed
  - consume
```
public final boolean consume(java.lang.StringBuilder stringBuilder)
```
    A call to this method will attempt to consume the data between the two indices, while appending it to stringBuilder
    If the data is successfully consumed, true will be returned, false otherwise.
    A consumption essentially sets the value of the index at the beginning of the next consumption to the value of the index at the end of the next consumption.
    If stringBuilder is null, a NullPointerException will be thrown.
    
    Parameters:
    
    stringBuilder - the StringBuilder to append the data to
    
    Returns:
    
    true if, and only if, the data is successfully consumed
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, stringBuilder is null
  - next
```
public abstract boolean next()
```
    A simple method for advancing the index at the end of the next consumption.
    If it succeeds, true is returned, false otherwise.
    The data that can be consumed by a successful call to this method is implementation-specific.
    
    Returns:
    
    true if, and only if, the index at the end of the next consumption is advanced, false otherwise
  - rewind
```
public final boolean rewind(int key)
```
    Rewinds the current state of this Scanner to some previously marked state.
    If no state is associated with key, nothing will happen.
    If this Scanner successfully rewinds to the previous state, true will be returned, false otherwise.
    Note that a key can only be used once. In order to rewind again, you need to call the mark() method again after this method has been called.
    
    Parameters:
    
    key - the key of the state to rewind to
    
    Returns:
    
    true if, and only if, this Scanner successfully rewinded to the state given the key, false otherwise
  - skip
```
public final boolean skip()
```
    Skips the current data by advancing the index at the beginning of the next consumption with one.
    The index at the end of the next consumption may be advanced, but only if it would be less than the new index at the beginning of the next consumption.
    If data has been successfully skipped, true will be returned, false otherwise.
    
    Returns:
    
    true if, and only if, data has been successfully skipped, false otherwise
  - testNext
```
public final boolean testNext()
```
    A simple method for testing that next() can be called.
    If it succeeds, true is returned, false otherwise.
    No data can be consumed after a call to this method, as it will be rewinded.
    
    Returns:
    
    true if, and only if, the test that next() can be called, false otherwise
  - unmark
```
public final boolean unmark(int key)
```
    Unmarks a previous mark given its key.
    If the key does not exist, nothing will happen.
    If the mark is successfully unmarked, true will be returned, false otherwise.
    
    Parameters:
    
    key - the key to the mark
    
    Returns:
    
    true if, and only if, the mark was successfully unmarked
  - getIndexAtBeginningOfConsumption
```
public final int getIndexAtBeginningOfConsumption()
```
    Returns the index at the beginning of the next consumption.
    
    Returns:
    
    the index at the beginning of the next consumption
  - getIndexAtEndOfConsumption
```
public final int getIndexAtEndOfConsumption()
```
    Returns the index at the end of the next consumption.
    
    Returns:
    
    the index at the end of the next consumption
  - mark
```
public final int mark()
```
    Marks the current state of this Scanner and returns a key to that mark, such that you can rewind to it at a later time.
    
    Returns:
    
    the key of the mark
  - consumption
```
public final java.lang.String consumption()
```
    Returns a String representation of the data that can currently be consumed.
    Calling this method will not consume the data.
    
    Returns:
    
    a String representation of the data that can currently be consumed
  - toString
```
public abstract java.lang.String toString(int absoluteIndex)
```
    Returns a String representation of the data at the given absolute index.
    If absoluteIndex is less than 0, or greater than or equal to the capacity of the underlying Buffer, an IllegalArgumentException will be thrown.
    
    Parameters:
    
    absoluteIndex - the absolute index
    
    Returns:
    
    a String representation of the data at the given absolute index
    
    Throws:
    
    java.lang.IllegalArgumentException - thrown if, and only if, absoluteIndex is less than 0, or greater than or equal to the capacity of the underlying Buffer
  - error
```
public abstract void error()
```
    Causes a ScannerException to be thrown with an implementation-specific detail message.
    
    Throws:
    
    ScannerException - thrown if, and only if, this method is called
  - error
```
public abstract void error(java.lang.String message)
```
    Causes a ScannerException to be thrown with the given detail message.
    If message is null, a NullPointerException will be thrown.
    
    Parameters:
    
    message - the detail message of the ScannerException
    
    Throws:
    
    java.lang.NullPointerException - thrown if, and only if, message is null
    
    ScannerException - thrown if, and only if, this method is called and message is not null
  - setIndexAtBeginningOfConsumption
```
public final void setIndexAtBeginningOfConsumption(int indexAtBeginningOfConsumption)
```
    Sets the index at the beginning of the next consumption.
    If indexAtBeginningOfConsumption is less than 0, an IllegalArgumentException will be thrown.
    
    Parameters:
    
    indexAtBeginningOfConsumption - the new index at the beginning of the next consumption
    
    Throws:
    
    java.lang.IllegalArgumentException - thrown if, and only if, indexAtBeginningOfConsumption is less than 0
  - setIndexAtEndOfConsumption
```
public final void setIndexAtEndOfConsumption(int indexAtEndOfConsumption)
```
    Sets the index at the end of the next consumption.
    If indexAtEndOfConsumption is less than getIndexAtBeginningOfConsumption(), an IllegalArgumentException will be thrown.
    
    Parameters:
    
    indexAtEndOfConsumption - the new index at the end of the next consumption
    
    Throws:
    
    java.lang.IllegalArgumentException - thrown if, and only if, indexAtEndOfConsumption is less than getIndexAtBeginningOfConsumption()

Class Scanner

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Scanner

Method Detail

consume

consume

next

rewind

skip

testNext

unmark

getIndexAtBeginningOfConsumption

getIndexAtEndOfConsumption

mark

consumption

toString

error

error

setIndexAtBeginningOfConsumption

setIndexAtEndOfConsumption