Documentation
¶
Overview ¶
Package textpos provides types and functions for working with line-based positions of text in a textual document.
WARNING: This package's API is in flux. It is based on the "go/token" package.
Index ¶
- type Column
- type File
- func (f *File) AddLine(offset int)
- func (f *File) Base() int
- func (f *File) Line(p Pos) Line
- func (f *File) LineCount() int
- func (f *File) LineStart(line Line) Pos
- func (f *File) MergeLine(line int)
- func (f *File) Name() string
- func (f *File) Offset(p Pos) int
- func (f *File) Pos(offset int) Pos
- func (f *File) PosForLineColumn(lc LineColumn) Pos
- func (f *File) Position(p Pos) (pos Position)
- func (f *File) SetLines(lines []int) bool
- func (f *File) SetLinesForContent(content []byte)
- func (f *File) Size() int
- type FileSet
- type Line
- type LineColumn
- type Pos
- type Position
- type Range
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Column ¶
type Column struct {
// contains filtered or unexported fields
}
Column is a number indicating a horrizontal offset within a line of text.
Column may be used to designate byte or character offsets. Byte offsets are advantageous because they are simple well-defined but match cursor positions in most text editors. Characters are not a universally well-defined and require more complex lookup but generally correspond to cursor positions in text editors.
func ColumnFromOffset ¶
ColumnFromOffset returns a Column object from an offset value (where 0 indicates the first line).
func ColumnFromOrdinal ¶
ColumnFromOrdinal returns a Column object from an ordinal value (where 1 indicates the first line).
type File ¶
type File struct {
// contains filtered or unexported fields
}
A File is a handle for a file belonging to a FileSet. A File has a name, size, and line offset table.
func (*File) AddLine ¶
AddLine adds the line offset for a new line. The line offset must be larger than the offset for the previous line and smaller than the file size; otherwise the line offset is ignored.
func (*File) Line ¶
Line returns the line number for the given file position p; p must be a Pos value in that file or NoPos.
func (*File) LineStart ¶
LineStart returns the Pos value of the start of the specified line. It ignores any alternative positions set using AddLineColumnInfo. LineStart panics if the 1-based line number is invalid.
func (*File) MergeLine ¶
MergeLine merges a line with the following line. It is akin to replacing the newline character at the end of the line with a space (to not change the remaining offsets). To obtain the line number, consult e.g. Position.Line. MergeLine will panic if given an invalid line number.
func (*File) Offset ¶
Offset returns the offset for the given file position p; p must be a valid Pos value in that file. f.Offset(f.Pos(offset)) == offset.
func (*File) Pos ¶
Pos returns the Pos value for the given file offset; the offset must be <= f.Size(). f.Pos(f.Offset(p)) == p.
func (*File) PosForLineColumn ¶
func (f *File) PosForLineColumn(lc LineColumn) Pos
PosForLineColumn returns the position of the given (line, column) pair in the file or NoPos if the (line, column) pair is out of bounds.
func (*File) Position ¶
Position returns the Position value for the given file position p. Calling f.Position(p) is equivalent to calling f.PositionFor(p, true).
func (*File) SetLines ¶
SetLines sets the line offsets for a file and reports whether it succeeded. The line offsets are the offsets of the first character of each line; for instance for the content "ab\nc\n" the line offsets are {0, 3}. An empty file has an empty line offset table. Each line offset must be larger than the offset for the previous line and smaller than the file size; otherwise SetLines fails and returns false. Callers must not mutate the provided slice after SetLines returns.
func (*File) SetLinesForContent ¶
SetLinesForContent sets the line offsets for the given file content. It ignores position-altering //line comments.
type FileSet ¶
type FileSet struct {
// contains filtered or unexported fields
}
A FileSet represents a set of source files. Methods of file sets are synchronized; multiple goroutines may invoke them concurrently.
The byte offsets for each file in a file set are mapped into distinct (integer) intervals, one interval [base, base+size] per file. Base represents the first byte in the file, and size is the corresponding file size. A Pos value is a value in such an interval. By determining the interval a Pos value belongs to, the file, its file base, and thus the byte offset (position) the Pos value is representing can be computed.
When adding a new file, a file base must be provided. That can be any integer value that is past the end of any interval of any file already in the file set. For convenience, FileSet.Base provides such a value, which is simply the end of the Pos interval of the most recently added file, plus one. Unless there is a need to extend an interval later, using the FileSet.Base should be used as argument for FileSet.AddFile.
func (*FileSet) AddFile ¶
AddFile adds a new file with a given filename, base offset, and file size to the file set s and returns the file. Multiple files may have the same name. The base offset must not be smaller than the FileSet's Base(), and size must not be negative. As a special case, if a negative base is provided, the current value of the FileSet's Base() is used instead.
Adding the file will set the file set's Base() value to base + size + 1 as the minimum base value for the next file. The following relationship exists between a Pos value p for a given file offset offs:
int(p) = base + offs
with offs in the range [0, size] and thus p in the range [base, base+size]. For convenience, File.Pos may be used to create file-specific position values from a file offset.
func (*FileSet) Base ¶
Base returns the minimum base offset that must be provided to AddFile when adding the next file.
func (*FileSet) File ¶
File returns the file that contains the position p. If no such file is found (for instance for p == NoPos), the result is nil.
type Line ¶
type Line struct {
// contains filtered or unexported fields
}
Line is the line number of some text in a file.
func LineFromOffset ¶
LineFromOffset returns a Line object from an offset value.
func LineFromOrdinal ¶
LineFromOrdinal returns a Line object from a positive value.
type LineColumn ¶
type LineColumn struct {
// contains filtered or unexported fields
}
LineColumn is a two dimensional textual position (line, column).
func MakeLineColumn ¶
func MakeLineColumn(line Line, col Column) LineColumn
MakeLineColumn returns a new LineColumn tuple.
func (LineColumn) Column ¶
func (p LineColumn) Column() Column
Column returns the column for the tuple.
func (LineColumn) String ¶
func (p LineColumn) String() string
String returns a string representation of a LineColumn pair.
If column and line are valid, returns "lineOrdinal:columnOrdinal."
type Pos ¶
type Pos int
Pos is a compact encoding of a source position within a file set. It can be converted into a Position for a more convenient, but much larger, representation.
The Pos value for a given file is a number in the range [base, base+size], where base and size are specified when a file is added to the file set. The difference between a Pos value and the corresponding file base corresponds to the byte offset of that position (represented by the Pos value) from the beginning of the file. Thus, the file base offset is the Pos value representing the first byte in the file.
To create the Pos value for a specific source offset (measured in bytes), first add the respective file to the current file set using FileSet.AddFile and then call File.Pos(offset) for that file. Given a Pos value p for a specific file set fset, the corresponding Position value is obtained by calling fset.Position(p).
Pos values can be compared directly with the usual comparison operators: If two Pos values p and q are in the same file, comparing p and q is equivalent to comparing the respective source file offsets. If p and q are in different files, p < q is true if the file implied by p was added to the respective file set before the file implied by q.
const NoPos Pos = 0
NoPos is the zero value for Pos; there is no file and line information associated with it, and NoPos.IsValid() is false. NoPos is always smaller than any other Pos value. The corresponding Position value for NoPos is the zero value for Position.
type Position ¶
type Position struct {
// contains filtered or unexported fields
}
Position describes an arbitrary source position including the file, line, and column location. A Position is valid if the line number is > 0.
func (Position) String ¶
String returns a string in one of several forms:
file:line:column valid position with file name file:line valid position with file name but no column (column == 0) line:column valid position without file name line valid position without file name and no column (column == 0) file invalid position with file name - invalid position without file name
type Range ¶
type Range struct {
// contains filtered or unexported fields
}
Range is a range within a single file.
The range specifies all of the characters in the interval [r.Start(), r.End()).
Source Files