txt

Documentation

Overview

Package txt is a generic utility for parsing and processing a text that is structured in individual lines.

Index

• Variables
• func Is(matchingCharacter ...rune) func(rune) bool
• func IsSpaceOrTab(r rune) bool
• func SubRune(text []rune, start int, length int) []rune
• type Block
  • func ParseBlock(text string, precedingLineCount int) (Block, int)
• type Error
  • func NewError(b Block, line int, start int, length int, code string, title string, ...) Error
• type Indentator
  • func NewIndentator(allowedIndentationStyles []string, l Line) *Indentator
  • func (i *Indentator) NewIndentedParseable(l Line, atLevel int) *Parseable
  • func (i *Indentator) Style() string
• type Line
  • func NewLineFromString(rawLineText string) Line
  • func (l *Line) Indentation() string
  • func (l *Line) IsBlank() bool
  • func (l *Line) Original() string
• type Parseable
  • func NewParseable(l Line, startPointerPosition int) *Parseable
  • func (p *Parseable) Advance(increment int)
  • func (p *Parseable) Length() int
  • func (p *Parseable) Peek() rune
  • func (p *Parseable) PeekUntil(isMatch func(rune) bool) (Parseable, bool)
  • func (p *Parseable) Remainder() Parseable
  • func (p *Parseable) RemainingLength() int
  • func (p *Parseable) SkipWhile(isMatch func(rune) bool)
  • func (p *Parseable) ToString() string

Variables

var Indentations = []string{"    ", "   ", "  ", "\t"}

var LineEndings = []string{"\r\n", "\n"}

Functions

func Is

func Is(matchingCharacter ...rune) func(rune) bool

func IsSpaceOrTab

func IsSpaceOrTab(r rune) bool

IsSpaceOrTab checks whether a rune is a space or a tab character.

func SubRune

func SubRune(text []rune, start int, length int) []rune

SubRune returns a subset of a rune list. It might be shorter than the requested length, if the text doesn’t contain enough characters. It returns empty, if the start position is bigger than the length.

Types

type Block

type Block interface {
	// Lines returns all lines.
	Lines() []Line

	// SignificantLines returns the lines that are not blank. The two integers
	// are the number of insignificant lines at the beginning and the end.
	SignificantLines() (significant []Line, headCount int, tailCount int)

	// OverallLineIndex returns the overall line index, taking into
	// account the context of all preceding blocks.
	OverallLineIndex(int) int

	// SetPrecedingLineCount adjusts the overall line count.
	SetPrecedingLineCount(int)
}

Block is multiple consecutive lines with text, with no blank lines in between, but possibly one or more blank lines before or after. It’s basically like a paragraph of text, with surrounding whitespace. The Block is guaranteed to contain exactly a single sequence of significant lines, i.e. lines that contain text.

func ParseBlock

func ParseBlock(text string, precedingLineCount int) (Block, int)

ParseBlock parses a block from the beginning of a text. It returns the parsed block, along with the number of bytes consumed from the string. If the text doesn’t contain significant lines, it returns nil.

type Error

type Error interface {
	// Error is an alias for Message.
	Error() string

	// LineNumber returns the logical line number, as shown in an editor.
	LineNumber() int

	// LineText is the original text of the line.
	LineText() string

	// Position is the cursor position in the line, excluding the indentation.
	Position() int

	// Column is the cursor position in the line, including the indentation.
	Column() int

	// Length returns the number of erroneous characters.
	Length() int

	// Code returns a unique identifier of the error kind.
	Code() string

	// Title returns a short error description.
	Title() string

	// Details returns additional information, such as hints or further explanations.
	Details() string

	// Message is a combination of Title and Details.
	Message() string

	// Origin returns the origin of the error, such as the file name.
	Origin() string
	SetOrigin(string) Error
}

Error contains infos about a parsing error in a Line.

func NewError

func NewError(b Block, line int, start int, length int, code string, title string, details string) Error

type Indentator

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

Indentator is a utility to check to process indented text. It is initialised with the first indented line, and determines the indentation style of that line. For all subsequent lines, it can then create Parseable’s that are already pre- processed.

func NewIndentator

func NewIndentator(allowedIndentationStyles []string, l Line) *Indentator

NewIndentator creates an indentator object, if the given line is indented according to the allowed styles.

func (*Indentator) NewIndentedParseable

func (i *Indentator) NewIndentedParseable(l Line, atLevel int) *Parseable

NewIndentedParseable returns a Parseable with already skipped indentation. It returns `nil` if the encountered indentation level is smaller than `atLevel`. It only consumes the desired indentation and disregards any additional indentation.

func (*Indentator) Style

func (i *Indentator) Style() string

type Line

type Line struct {
	// Text contains the copy of the line.
	Text string

	// LineEnding is the encountered line ending sequence `\n` or `\r\n`.
	// Note that for the last line in a file, there might be no line ending.
	LineEnding string
}

Line is a data structure that represent one line of the source file.

func NewLineFromString

func NewLineFromString(rawLineText string) Line

NewLineFromString turns data into a Line object.

func (*Line) Indentation

func (l *Line) Indentation() string

Indentation returns the indentation sequence of a line that is indented at least once. Note: it cannot determine the level of indentation. If the line is not indented, it returns empty string.

func (*Line) IsBlank

func (l *Line) IsBlank() bool

IsBlank checks whether a line is all spaces or tabs.

func (*Line) Original

func (l *Line) Original() string

Original returns the (byte-wise) identical line of text as it appeared in the file.

type Parseable

type Parseable struct {
	Chars           []rune
	PointerPosition int
}

Parseable is utility data structure for parsing a piece of text.

func NewParseable

func NewParseable(l Line, startPointerPosition int) *Parseable

NewParseable creates a parseable from the given line.

func (*Parseable) Advance

func (p *Parseable) Advance(increment int)

Advance moves forward the cursor position.

func (*Parseable) Length

func (p *Parseable) Length() int

Length returns the total length of the line.

func (*Parseable) Peek

func (p *Parseable) Peek() rune

Peek returns the next character, or `utf8.RuneError` if there is none anymore.

func (*Parseable) PeekUntil

func (p *Parseable) PeekUntil(isMatch func(rune) bool) (Parseable, bool)

PeekUntil moves the cursor forward until the condition is satisfied, or until the end of the line is reached. It returns a Parseable containing the consumed part of the line, as well as a bool to indicate whether the condition was met (`true`) or the end of the line was encountered (`false`).

func (*Parseable) Remainder

func (p *Parseable) Remainder() Parseable

Remainder returns the rest of the text.

func (*Parseable) RemainingLength

func (p *Parseable) RemainingLength() int

RemainingLength returns the number of chars until the end of the line.

func (*Parseable) SkipWhile

func (p *Parseable) SkipWhile(isMatch func(rune) bool)

SkipWhile consumes all upcoming characters that match the predicate.

func (*Parseable) ToString

func (p *Parseable) ToString() string

ToString returns the line text as string.