From 50d7d74097ab6cd1675b80f64ecd7ccfde6e856b Mon Sep 17 00:00:00 2001 From: Sasha Koshka Date: Fri, 31 Mar 2023 19:40:25 -0400 Subject: [PATCH] Added documentaion comments for textmanip --- textmanip/textmanip.go | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/textmanip/textmanip.go b/textmanip/textmanip.go index b89ec03..2fdb462 100644 --- a/textmanip/textmanip.go +++ b/textmanip/textmanip.go @@ -2,12 +2,18 @@ package textmanip import "unicode" +// Dot represents a cursor or text selection. It has a start and end position, +// referring to where the user began and ended the selection respectively. type Dot struct { Start, End int } +// EmptyDot returns a zero-width dot at the specified position. func EmptyDot (position int) Dot { return Dot { position, position } } +// Canon places the lesser value at the start, and the greater value at the end. +// Note that a canonized dot does not in all cases correspond directly to the +// original. func (dot Dot) Canon () Dot { if dot.Start > dot.End { return Dot { dot.End, dot.Start } @@ -16,10 +22,12 @@ func (dot Dot) Canon () Dot { } } +// Empty returns whether or not the func (dot Dot) Empty () bool { return dot.Start == dot.End } +// Add shifts the dot to the right by the specified amount. func (dot Dot) Add (delta int) Dot { return Dot { dot.Start + delta, @@ -27,6 +35,7 @@ func (dot Dot) Add (delta int) Dot { } } +// Add shifts the dot to the left by the specified amount. func (dot Dot) Sub (delta int) Dot { return Dot { dot.Start - delta, @@ -34,6 +43,7 @@ func (dot Dot) Sub (delta int) Dot { } } +// Constrain constrains the dot's start and end from zero to length (inclusive). func (dot Dot) Constrain (length int) Dot { if dot.Start < 0 { dot.Start = 0 } if dot.Start > length { dot.Start = length} @@ -42,16 +52,20 @@ func (dot Dot) Constrain (length int) Dot { return dot } +// Width returns how many runes the dot spans. func (dot Dot) Width () int { dot = dot.Canon() return dot.End - dot.Start } +// Slice returns the subset of text that the dot covers. func (dot Dot) Slice (text []rune) []rune { dot = dot.Canon().Constrain(len(text)) return text[dot.Start:dot.End] } +// WordToLeft returns how far away to the left the next word boundary is from a +// given position. func WordToLeft (text []rune, position int) (length int) { if position < 1 { return } if position > len(text) { position = len(text) } @@ -68,6 +82,8 @@ func WordToLeft (text []rune, position int) (length int) { return } +// WordToRight returns how far away to the right the next word boundary is from +// a given position. func WordToRight (text []rune, position int) (length int) { if position < 0 { return } if position > len(text) { position = len(text) } @@ -84,6 +100,7 @@ func WordToRight (text []rune, position int) (length int) { return } +// WordAround returns a dot that surrounds the word at the specified position. func WordAround (text []rune, position int) (around Dot) { return Dot { WordToLeft(text, position), @@ -91,6 +108,9 @@ func WordAround (text []rune, position int) (around Dot) { } } +// Backspace deletes the rune to the left of the dot. If word is true, it +// deletes up until the next word boundary on the left. If the dot is non-empty, +// it deletes the text inside of the dot. func Backspace (text []rune, dot Dot, word bool) (result []rune, moved Dot) { dot = dot.Constrain(len(text)) if dot.Empty() { @@ -109,6 +129,9 @@ func Backspace (text []rune, dot Dot, word bool) (result []rune, moved Dot) { } } +// Delete deletes the rune to the right of the dot. If word is true, it deletes +// up until the next word boundary on the right. If the dot is non-empty, it +// deletes the text inside of the dot. func Delete (text []rune, dot Dot, word bool) (result []rune, moved Dot) { dot = dot.Constrain(len(text)) if dot.Empty() { @@ -131,6 +154,7 @@ func Delete (text []rune, dot Dot, word bool) (result []rune, moved Dot) { } } +// Lift removes the section of text inside of the dot, and returns a copy of it. func Lift (text []rune, dot Dot) (result []rune, moved Dot, lifted []rune) { dot = dot.Constrain(len(text)) if dot.Empty() { @@ -147,6 +171,8 @@ func Lift (text []rune, dot Dot) (result []rune, moved Dot, lifted []rune) { return } +// Type inserts one of more runes into the text at the dot position. If the dot +// is non-empty, it replaces the text inside of the dot with the new runes. func Type (text []rune, dot Dot, characters ...rune) (result []rune, moved Dot) { dot = dot.Constrain(len(text)) if dot.Empty() { @@ -167,6 +193,8 @@ func Type (text []rune, dot Dot, characters ...rune) (result []rune, moved Dot) } } +// MoveLeft moves the dot left one rune. If word is true, it moves the dot to +// the next word boundary on the left. func MoveLeft (text []rune, dot Dot, word bool) (moved Dot) { dot = dot.Canon().Constrain(len(text)) distance := 0 @@ -180,6 +208,8 @@ func MoveLeft (text []rune, dot Dot, word bool) (moved Dot) { return } +// MoveRight moves the dot right one rune. If word is true, it moves the dot to +// the next word boundary on the right. func MoveRight (text []rune, dot Dot, word bool) (moved Dot) { dot = dot.Canon().Constrain(len(text)) distance := 0 @@ -193,6 +223,8 @@ func MoveRight (text []rune, dot Dot, word bool) (moved Dot) { return } +// SelectLeft moves the end of the dot left one rune. If word is true, it moves +// the end of the dot to the next word boundary on the left. func SelectLeft (text []rune, dot Dot, word bool) (moved Dot) { dot = dot.Constrain(len(text)) distance := 1 @@ -203,6 +235,8 @@ func SelectLeft (text []rune, dot Dot, word bool) (moved Dot) { return dot } +// SelectRight moves the end of the dot right one rune. If word is true, it +// moves the end of the dot to the next word boundary on the right. func SelectRight (text []rune, dot Dot, word bool) (moved Dot) { dot = dot.Constrain(len(text)) distance := 1