Data.Text.Zipper

TextZipper is designed to be help manipulate the contents of a text input field. It keeps track of the logical lines of text (i.e., lines separated by user-entered newlines) and the current cursor position. Several functions are defined in this module to navigate and edit the TextZipper from the cursor position.

TextZippers can be converted into DisplayLines, which describe how the contents of the zipper will be displayed when wrapped to fit within a container of a certain width. It also provides some convenience facilities for converting interactions with the rendered DisplayLines back into manipulations of the underlying TextZipper.

Documentation

data TextZipper

A zipper of the logical text input contents (the "document"). The lines before the line containing the cursor are stored in reverse order. The cursor is logically between the "before" and "after" text. A "logical" line of input is a line of input up until a user-entered newline character (as compared to a "display" line, which is wrapped to fit within a given viewport width).

Constructors

TextZipper

Fields

• _textZipper_linesBefore :: [Text]
• _textZipper_before :: Text
• _textZipper_after :: Text
• _textZipper_linesAfter :: [Text]

Instances

Eq TextZipper

Defined in Data.Text.Zipper

Methods

(==) :: TextZipper -> TextZipper -> Bool

(/=) :: TextZipper -> TextZipper -> Bool

Show TextZipper

Defined in Data.Text.Zipper

Methods

showsPrec :: Int -> TextZipper -> ShowS

show :: TextZipper -> String

showList :: [TextZipper] -> ShowS

IsString TextZipper

Defined in Data.Text.Zipper

Methods

fromString :: String -> TextZipper

mapZipper :: (Char -> Char) -> TextZipper -> TextZipper

Map a replacement function over the characters in a TextZipper

left :: TextZipper -> TextZipper

Move the cursor left one character, if possible

leftN :: Int -> TextZipper -> TextZipper

Move the cursor left by the given number of characters, or, if the document isn't long enough, to the beginning of the document

right :: TextZipper -> TextZipper

Move the cursor right one character, if possible

rightN :: Int -> TextZipper -> TextZipper

Move the character right by the given number of characters, or, if the document isn't long enough, to the end of the document

up :: TextZipper -> TextZipper

Move the cursor up one logical line, if possible

down :: TextZipper -> TextZipper

Move the cursor down one logical line, if possible

pageUp :: Int -> TextZipper -> TextZipper

Move the cursor up by the given number of lines

pageDown :: Int -> TextZipper -> TextZipper

Move the cursor down by the given number of lines

home :: TextZipper -> TextZipper

Move the cursor to the beginning of the current logical line

end :: TextZipper -> TextZipper

Move the cursor to the end of the current logical line

top :: TextZipper -> TextZipper

Move the cursor to the top of the document

insertChar :: Char -> TextZipper -> TextZipper

Insert a character at the current cursor position

insert :: Text -> TextZipper -> TextZipper

Insert text at the current cursor position

deleteLeft :: TextZipper -> TextZipper

Delete the character to the left of the cursor

deleteRight :: TextZipper -> TextZipper

Delete the character under/to the right of the cursor

deleteLeftWord :: TextZipper -> TextZipper

Delete a word to the left of the cursor. Deletes all whitespace until it finds a non-whitespace character, and then deletes contiguous non-whitespace characters.

tab :: Int -> TextZipper -> TextZipper

Insert up to n spaces to get to the next logical column that is a multiple of n

value :: TextZipper -> Text

The plain text contents of the zipper

empty :: TextZipper

The empty zipper

fromText :: Text -> TextZipper

Constructs a zipper with the given contents. The cursor is placed after the contents.

data Span tag

A span of text tagged with some metadata that makes up part of a display line.

Constructors

Span tag Text

Instances

Eq tag => Eq (Span tag)

Defined in Data.Text.Zipper

Methods

(==) :: Span tag -> Span tag -> Bool

(/=) :: Span tag -> Span tag -> Bool

Show tag => Show (Span tag)

Defined in Data.Text.Zipper

Methods

showsPrec :: Int -> Span tag -> ShowS

show :: Span tag -> String

showList :: [Span tag] -> ShowS

data TextAlignment

Text alignment type

Constructors

TextAlignment_Left

TextAlignment_Right

TextAlignment_Center

Instances

Eq TextAlignment

Defined in Data.Text.Zipper

Methods

(==) :: TextAlignment -> TextAlignment -> Bool

(/=) :: TextAlignment -> TextAlignment -> Bool

Show TextAlignment

Defined in Data.Text.Zipper

Methods

showsPrec :: Int -> TextAlignment -> ShowS

show :: TextAlignment -> String

showList :: [TextAlignment] -> ShowS

type OffsetMapWithAlignment = Map Int (Int, Int)

A map from the index (row) of display line to (fst,snd) fst: leading empty spaces from left (may be negative) to adjust for alignment snd: the text offset from the beginning of the document to the first character of the display line

data WrappedLine

Helper type representing a single visual line that may be part of a wrapped logical line

Constructors

WrappedLine

Fields

• _wrappedLines_text :: Text
• _wrappedLines_hiddenWhitespace :: Bool

  True if this line ends with a deleted whitespace character

• _wrappedLines_offset :: Int

  offset from beginning of line

Instances

Eq WrappedLine

Defined in Data.Text.Zipper

Methods

(==) :: WrappedLine -> WrappedLine -> Bool

(/=) :: WrappedLine -> WrappedLine -> Bool

Show WrappedLine

Defined in Data.Text.Zipper

Methods

showsPrec :: Int -> WrappedLine -> ShowS

show :: WrappedLine -> String

showList :: [WrappedLine] -> ShowS

data DisplayLines tag

Information about the document as it is displayed (i.e., post-wrapping)

Constructors

DisplayLines

Fields

• _displayLines_spans :: [[Span tag]]

  NOTE this will contain a dummy space character if the cursor is at the end

• _displayLines_offsetMap :: OffsetMapWithAlignment

  NOTE this will not include offsets for the y position of dummy ' ' character if it is on its own line

• _displayLines_cursorPos :: (Int, Int)

  cursor position relative to upper left hand corner

Instances

Eq tag => Eq (DisplayLines tag)

Defined in Data.Text.Zipper

Methods

(==) :: DisplayLines tag -> DisplayLines tag -> Bool

(/=) :: DisplayLines tag -> DisplayLines tag -> Bool

Show tag => Show (DisplayLines tag)

Defined in Data.Text.Zipper

Methods

showsPrec :: Int -> DisplayLines tag -> ShowS

show :: DisplayLines tag -> String

showList :: [DisplayLines tag] -> ShowS

splitAtWidth :: Int -> Text -> (Text, Text)

Split a Text at the given column index. For example

splitAtWidth 3 "ᄀabc" == ("ᄀa", "bc")

because the first character has a width of two (see charWidth for more on that).

characterIndexFromWidth :: Int -> Text -> Int

Convert a physical width index to a character index. For example, the physical index 3 of the string "ᄀabc" corresponds to the character index 2, because the first character has a width of 2.

takeWidth :: Int -> Text -> Text

Takes the given number of columns of characters. For example

takeWidth 3 "ᄀabc" == "ᄀa"

because the first character has a width of 2 (see charWidth for more on that). This function will not take a character if its width exceeds the width it seeks to take.

dropWidth :: Int -> Text -> Text

Drops the given number of columns of characters. For example

dropWidth 2 "ᄀabc" == "abc"

because the first character has a width of 2 (see charWidth for more on that). This function will not drop a character if its width exceeds the width it seeks to drop.

charWidth :: Char -> Int

Get the display width of a Char. "Full width" and "wide" characters take two columns and everything else takes a single column. See https://www.unicode.org/reports/tr11/ for more information This is implemented using wcwidth from Vty such that it matches what will be displayed on the terminal. Note that this method can change depending on how vty is configed. Please see vty documentation for details.

spansWidth :: [Span tag] -> Int

Get the width of the text in a set of Spans, taking into account unicode character widths

spansLength :: [Span tag] -> Int

Get the length (number of characters) of the text in a set of Spans

textWidth :: Text -> Int

Compute the width of some Text, taking into account fullwidth unicode forms.

widthI :: Stream Char -> Int

Compute the width of a stream of characters, taking into account fullwidth unicode forms.

charIndexAt :: Int -> Stream Char -> Int

Compute the logical index position of a stream of characters from a visual position taking into account fullwidth unicode forms.

wordsWithWhitespace :: Text -> [Text]

Same as T.words except whitespace characters are included at end (i.e. ["line1 ", ...]) Chars representing white space.

splitWordsAtDisplayWidth :: Int -> [Text] -> [(Text, Bool)]

Split words into logical lines, True in the tuple indicates line ends with a whitespace character that got deleted

alignmentOffset :: TextAlignment -> Int -> Text -> Int

Calculate the offset that will result in rendered text being aligned left, right, or center

wrapWithOffsetAndAlignment

Arguments

:: TextAlignment

-> Int

Maximum width

-> Int

Offset for first line

-> Text

Text to be wrapped

-> [WrappedLine]

Wraps a logical line of text to fit within the given width. The first wrapped line is offset by the number of columns provided. Subsequent wrapped lines are not.

eolSpacesToLogicalLines :: [[WrappedLine]] -> [[(Text, Int)]]

converts deleted eol spaces into logical lines

offsetMapWithAlignmentInternal :: [[WrappedLine]] -> OffsetMapWithAlignment

offsetMapWithAlignment

Arguments

:: [[(Text, Int)]]

The outer list represents logical lines, inner list represents wrapped lines

-> OffsetMapWithAlignment

displayLinesWithAlignment

Arguments

:: TextAlignment

-> Int

Width, used for wrapping

-> tag

Metadata for normal characters

-> tag

Metadata for the cursor

-> TextZipper

The text input contents and cursor state

-> DisplayLines tag

Given a width and a TextZipper, produce a list of display lines (i.e., lines of wrapped text) with special attributes applied to certain segments (e.g., the cursor). Additionally, produce the current y-coordinate of the cursor and a mapping from display line number to text offset

goToDisplayLinePosition :: Int -> Int -> DisplayLines tag -> TextZipper -> TextZipper

Move the cursor of the given TextZipper to the logical position indicated by the given display line coordinates, using the provided DisplayLinesWithAlignment information. If the x coordinate is beyond the end of a line, the cursor is moved to the end of the line.

displayLines

Arguments

:: Int

Width, used for wrapping

-> tag

Metadata for normal characters

-> tag

Metadata for the cursor

-> TextZipper

The text input contents and cursor state

-> DisplayLines tag

Given a width and a TextZipper, produce a list of display lines (i.e., lines of wrapped text) with special attributes applied to certain segments (e.g., the cursor). Additionally, produce the current y-coordinate of the cursor and a mapping from display line number to text offset

wrapWithOffset

Arguments

:: Int

Maximum width

-> Int

Offset for first line

-> Text

Text to be wrapped

-> [Text]

Wraps a logical line of text to fit within the given width. The first wrapped line is offset by the number of columns provided. Subsequent wrapped lines are not.