nibbler

README

nibbler

Nibble chunks from Reader streams and slice in a common way

Overview

This is a golang module that provides an interface for treating a Reader and a byte slice in a similar way when reading one byte at-a-time, or a sequence of bytes based on a character set, where each character is in the UTF-8 range of codepoint, 1..255, inclusive. It is possible to peek ahead in the byte stream, or return a character previously read to the stream. When using a Reader as the stream source, the package will automatically trigger a Read() whenever necessary.

Documentation

Index

• type ByteNibbler
• type ByteReaderNibbler
  • func NewByteReaderNibbler(streamReader io.Reader) *ByteReaderNibbler
  • func (nibbler *ByteReaderNibbler) AddNamedCharacterSetsMap(setsMap *NamedCharacterSetsMap)
  • func (nibbler *ByteReaderNibbler) PeekAtNextByte() (byte, error)
  • func (nibbler *ByteReaderNibbler) ReadByte() (byte, error)
  • func (nibbler *ByteReaderNibbler) ReadNextBytesMatchingSet(setName string) ([]byte, error)
  • func (nibbler *ByteReaderNibbler) ReadNextBytesNotMatchingSet(setName string) ([]byte, error)
  • func (nibbler *ByteReaderNibbler) UnreadByte() error
• type ByteSliceNibbler
  • func NewByteSliceNibbler(buffer []byte) *ByteSliceNibbler
  • func (nibbler *ByteSliceNibbler) AddNamedCharacterSetsMap(setsMap *NamedCharacterSetsMap)
  • func (nibbler *ByteSliceNibbler) PeekAtNextByte() (byte, error)
  • func (nibbler *ByteSliceNibbler) ReadByte() (byte, error)
  • func (nibbler *ByteSliceNibbler) ReadNextBytesMatchingSet(setName string) ([]byte, error)
  • func (nibbler *ByteSliceNibbler) ReadNextBytesNotMatchingSet(setName string) ([]byte, error)
  • func (nibbler *ByteSliceNibbler) UnreadByte() error
• type NamedCharacterSetsMap
  • func NewNamedCharacterSetsMap() *NamedCharacterSetsMap
  • func (setsMap *NamedCharacterSetsMap) AddNamedCharacterSetFromByteArray(nameOfSet string, byteArray []byte) *NamedCharacterSetsMap
  • func (setsMap *NamedCharacterSetsMap) AddNamedCharacterSetFromString(nameOfSet string, stringOfASCIICharacters string) *NamedCharacterSetsMap

Types

type ByteNibbler

type ByteNibbler interface {
	ReadByte() (byte, error)
	UnreadByte() error
	PeekAtNextByte() (byte, error)
	AddNamedCharacterSetsMap(*NamedCharacterSetsMap)
	ReadNextBytesMatchingSet(setName string) ([]byte, error)
	ReadNextBytesNotMatchingSet(setName string) ([]byte, error)
}

ByteNibbler is an interface for dealing with a byte buffer or byte stream one byte-at-a-time or in chunks based on character sets. One can read a byte from the stream, return a read byte to the stream, look at the next byte from the stream without removing it, or extract bytes in a set. ReadByte and PeekAtNextByte should return io.EOF when the end of the stream has been reached.

type ByteReaderNibbler

type ByteReaderNibbler struct {
	// contains filtered or unexported fields
}

ByteReaderNibbler is a ByteNibbler that uses an io.Reader as its dynamic backing stream. There is no guarantee that the internal buffer representing the pseudo queue grows to the size of all bytes read, so if UnreadByte() is called repeatedly in succession, it may eventually return an error and may not allow a return of every byte previously read. If a reading action or look-ahead action triggers a Read() of the associated Reader, and that call returns no error, no EOF and zero bytes, an error is raised. This means that a non-blocking Reader shouldn't be provided.

func NewByteReaderNibbler

func NewByteReaderNibbler(streamReader io.Reader) *ByteReaderNibbler

NewByteReaderNibbler returns a ByteReaderNibbler.

func (*ByteReaderNibbler) AddNamedCharacterSetsMap

func (nibbler *ByteReaderNibbler) AddNamedCharacterSetsMap(setsMap *NamedCharacterSetsMap)

AddNamedCharacterSetsMap receives a NamedCharacterSetsMap, to be used by ReadBytesFromSet().

func (*ByteReaderNibbler) PeekAtNextByte

func (nibbler *ByteReaderNibbler) PeekAtNextByte() (byte, error)

PeekAtNextByte looks at the next byte in the stream and returns it without advancing the byte return pointer. Thus, a subsequent call to ReadNext() will return the same byte. Return io.EOF if currently at the end of the stream.

func (*ByteReaderNibbler) ReadByte

func (nibbler *ByteReaderNibbler) ReadByte() (byte, error)

ReadByte reads the next byte from the stream. Return io.EOF if the end of the stream has been reached.

func (*ByteReaderNibbler) ReadNextBytesMatchingSet

func (nibbler *ByteReaderNibbler) ReadNextBytesMatchingSet(setName string) ([]byte, error)

ReadNextBytesMatchingSet reads bytes in the stream as long as they match the characters in the setName (which, in turn, must be supplied to the NamedCharacterSetsMap provided in UseNamedCharacterSetsMap). Return an error if no named character sets map has been provided, if the setName provided is not in that map, or if the stream read produces an error. Note that this error may be io.EOF. Whether or not an error is returned, the assembled slice of bytes read from the stream is also returned. After this method returns, the nibbler's next byte is the one after the last character in the returned set.

func (*ByteReaderNibbler) ReadNextBytesNotMatchingSet

func (nibbler *ByteReaderNibbler) ReadNextBytesNotMatchingSet(setName string) ([]byte, error)

ReadNextBytesNotMatchingSet is the inverse of ReadNextBytesMatchingSet. It reads the underlying byte slice from the first byte in the unread stream, returning the contiguous bytes that do not match the bytes in named set.

func (*ByteReaderNibbler) UnreadByte

func (nibbler *ByteReaderNibbler) UnreadByte() error

UnreadByte returns the last read byte back to the buffered stream. A subsequent ReadByte() will return this same byte. An error is returned if the stream is empty or if the last read byte is the first byte in the stream.

type ByteSliceNibbler

type ByteSliceNibbler struct {
	// contains filtered or unexported fields
}

ByteSliceNibbler is a ByteNibbler using a static byte buffer. A ReadByte or PeekAtNextbyte at the end of the slice will return io.EOF.

func NewByteSliceNibbler

func NewByteSliceNibbler(buffer []byte) *ByteSliceNibbler

NewByteSliceNibbler returns a new ByteSliceNibbler using the backing buffer. Elements of the buffer backing array are not changed by any operation of the ByteSliceNibbler.

func (*ByteSliceNibbler) AddNamedCharacterSetsMap

func (nibbler *ByteSliceNibbler) AddNamedCharacterSetsMap(setsMap *NamedCharacterSetsMap)

AddNamedCharacterSetsMap receives a NamedCharacterSetsMap, to be used by ReadBytesFromSet().

func (*ByteSliceNibbler) PeekAtNextByte

func (nibbler *ByteSliceNibbler) PeekAtNextByte() (byte, error)

PeekAtNextByte returns the next unread byte in the slice or io.EOF if the pseudo-stack is empty.

func (*ByteSliceNibbler) ReadByte

func (nibbler *ByteSliceNibbler) ReadByte() (byte, error)

ReadByte attempts to read the next byte in the backing array. If all bytes have been read, then io.EOF is returned.

func (*ByteSliceNibbler) ReadNextBytesMatchingSet

func (nibbler *ByteSliceNibbler) ReadNextBytesMatchingSet(setName string) ([]byte, error)

ReadNextBytesMatchingSet reads bytes in the stream as long as they match the characters in the setName (which, in turn, must be supplied to the NamedCharacterSetsMap provided in UseNamedCharacterSetsMap). Return an error if no named character sets map has been provided, if the setName provided is not in that map, or if the stream read produces an error. Note that this error may be io.EOF. Whether or not an error is returned, the assembled slice of bytes read from the stream is also returned. After this method returns, the nibbler's next byte is the one after the last character in the returned set.

func (*ByteSliceNibbler) ReadNextBytesNotMatchingSet

func (nibbler *ByteSliceNibbler) ReadNextBytesNotMatchingSet(setName string) ([]byte, error)

ReadNextBytesNotMatchingSet is the inverse of ReadNextBytesMatchingSet. It reads the underlying byte slice from the first byte in the unread stream, returning the contiguous bytes that do not match the bytes in named set.

func (*ByteSliceNibbler) UnreadByte

func (nibbler *ByteSliceNibbler) UnreadByte() error

UnreadByte puts the last read byte back on the nibbler pseudo-stack. An error is returned if the the backing slice is empty or bytes have been unshifted back to the start of the slice.

type NamedCharacterSetsMap

type NamedCharacterSetsMap struct {
	// contains filtered or unexported fields
}

NamedCharacterSetsMap stores sets of ASCII characters, associated with a name. These can be provided to ByteNibblers when reading a string of characters from the input stream to determine which characters are allowed as part of the read.

func NewNamedCharacterSetsMap

func NewNamedCharacterSetsMap() *NamedCharacterSetsMap

NewNamedCharacterSetsMap creates a new empty map.

func (*NamedCharacterSetsMap) AddNamedCharacterSetFromByteArray

func (setsMap *NamedCharacterSetsMap) AddNamedCharacterSetFromByteArray(nameOfSet string, byteArray []byte) *NamedCharacterSetsMap

AddNamedCharacterSetFromByteArray adds the bytes in byteArray as a character set with the provided name.

func (*NamedCharacterSetsMap) AddNamedCharacterSetFromString

func (setsMap *NamedCharacterSetsMap) AddNamedCharacterSetFromString(nameOfSet string, stringOfASCIICharacters string) *NamedCharacterSetsMap

AddNamedCharacterSetFromString treats stringOfAsciiCharacters as a series of ASCII characters. Any rune with a value greater than 255 is ignored. The set is added to the SetsMap with the provided name.