README
¶
Byte-level I/O, position, and backtracking support
⚠ Caution: The position implementation in pos.go is provisional. Please review the godoc explanation here before adopting this implementation independently in your own projects.
Documentation
¶
Overview ¶
Package reader provides byte-level I/O and position tracking for compilers and interpreters, including backtracking support.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Pos ¶
type Pos struct {
// contains filtered or unexported fields
}
Condensed Pos value.
Pos is a read-only value type. Queries on the baseline form respects line number directives, because this is the form most commonly useful for diagnostics.
This is not as condensed as the Go tokenizer version, but the Go version cannot support multiple interactive streams in its current form.
⚠ Caution ¶
This implementation is provisional, and probably should not be adopted by other parties. The Pos type is exported for efficiency reasons, and a better implementation is coming. The reason I did not adopt a design more similar to the Go tokenizer position manager is that I wanted to be able to support input and position tracking for multiple interactive streams. I have since realized that expanding the Go-style single integer Pos values to int64 would allow this, with the caveat that we would need to set an upper bound (say 2GB) on total input length for any given unit of compilation.
That implementation would be both more compact nad more efficient than this one, and I will probably migrate. The resulting Pos value will be source compatible but not binary compatible.
func (Pos) Column ¶
Return the column number (starting at 1) of this position.
If adjusted is true, the value returned takes line directives (pragmas) into account.
func (Pos) Line ¶
Return the line number (starting at 1) of this position.
If adjusted is true, the value returned takes line directives (pragmas) into account.
type RawPos ¶
type RawPos struct {
Pos
}
Pos variant that ignores line directives (pragmas).
func (RawPos) Column ¶
Return the column number (starting at 1) associated with this position, ignoring any line directives (pragmas).
type Reader ¶
type Reader interface {
// Close this input, discarding any consumed bytes but preserving any line
// and column information that has been constructed.
//
// This function does not close the underlying file descriptor if the input
// source is a stream.
Close() error
// Return the reader's current input position
Position() position.Position
// Return the reader's current input offset
Offset() Offset
// Re-set the reader's current offset
SetOffset(o Offset) error
// Return true iff we are at end of input
IsAtEOI() bool
// Return the byte at the specified offset within this input unit.
//
// If the input unit is a stream, and the requested position exceeds the
// number of bytes read so far, this operation will block for input.
ByteAt(o Offset) (byte, error)
// Return the byte slice covering the range [begin, end)
Content(begin, end Offset) ([]byte, error)
// Get the byte at the current offset without advancing the position.
//
// If the input unit is a stream, and the current position exceeds the
// number of bytes read so far, this operation will block for input.
Peek() (byte, error)
// Return the byte at the current offset and advance the offset.
//
// If the input unit is a stream, and the current position exceeds the
// number of bytes read so far, this operation will block for input.
Next() (byte, error)
// Return a user readable string representation of offset o.
//
// Adjusts for line directives iff adjusted is true.
//
// Defined for any position p < r+1, where r is the greatest position that
// has been successfully accessed by ByteAt().
PositionString(o Offset, adjusted bool) string
// Return the file name associated with this position.
//
// Adjusts for line directives iff adjusted is true.
//
// Defined for any position p < r+1, where r is the greatest position that
// has been successfully accessed by ByteAt().
Filename(o Offset, adjusted bool) string
// Return the line number associated with offset o (starts at 1).
//
// Adjusts for line directives iff adjusted is true.
//
// Defined for any position p < r+1, where r is the greatest position that
// has been successfully accessed by ByteAt().
Line(o Offset, adjusted bool) int
// Return the column number associated with offset o (starts at 1).
//
// Adjusts for line directives iff adjusted is true.
//
// Defined for any position p < r+1, where r is the greatest position that
// has been successfully accessed by ByteAt().
Column(o Offset, adjusted bool) int
// Return the name, line and column number associated with offset o.
//
// Adjusts for line directives iff adjusted is true.
//
// Line and column numbers start at 1. Especially when adjusting, this is
// significanty more efficient than extracting the elements individually.
//
// Defined for any position p < r+1, where r is the greatest position that
// has been successfully accessed by ByteAt().
NameLineAndColumn(o Offset, adjusted bool) (string, int, int)
}
A Reader represents an input unit of compilation.
Source Files