terminal.lua

• Index

Contents

• Methods

Classes

• EditLine
• Sequence
• cli.Prompt
• cli.Select

Modules

• terminal
• terminal.clear
• terminal.cursor
• terminal.cursor.position
• terminal.cursor.position.stack
• terminal.cursor.shape
• terminal.cursor.shape.stack
• terminal.cursor.visible
• terminal.cursor.visible.stack
• terminal.draw
• terminal.draw.line
• terminal.input
• terminal.input.keymap
• terminal.output
• terminal.progress
• terminal.scroll
• terminal.scroll.stack
• terminal.text
• terminal.text.color
• terminal.text.stack
• terminal.text.width
• terminal.utils

Topics

• 1. Introduction
• 2. Terminal handling
• CHANGELOG
• CONTRIBUTING
• MIT License

Examples

• async.lua
• colors.lua
• cow.lua
• headers.lua
• keymap.lua
• progress.lua
• prompt-copas.lua
• prompt.lua
• sequence.lua
• testscreen.lua

Class EditLine

UTF8 based EditLine class.

This class handles a UTF8 string with editing operations, cursor tracking, and width tracking.

Usage:

local EditLine = require("terminal.editline")
local line = EditLine("héllo界")

print(line)                                      -- Output: héllo界
print("Characters:", line:len_char())            -- Output: Characters: 6
print("Columns:", line:len_col())                -- Output: Columns: 7 (since '界' is width 2)

-- Move the cursor
line:left(2)
print("Cursor char position:", line:pos_char())  -- Output: 4
print("Cursor column position:", line:pos_col()) -- Output: 4

-- Editing
line:insert("!")
print(line)                                      -- Output: héll!o界

Methods

editline:backspace ([n=1])	Deletes the character left of the current cursor position.
editline:backspace_to_start ()	Deletes all characters to the left of the current cursor position.
editline:backspace_word ([n=1])	Backspace until the start of the current word.
editline:clear ()	Clears the input.
editline:delete ([n=1])	Deletes the character at the current cursor position.
editline:delete_to_end ()	Deletes all characters to the right of the current cursor position.
editline:delete_word ([n=1])	Delete until the end of the current word.
editline:format ([opts])	Format the contents for display, over multiple lines if necessary.
editline:goto_end ()	Moves the cursor to the end of the string.
editline:goto_home ()	Moves the cursor to the start of the string.
editline:goto_index (pos)	Moves the cursor to the position given by the index.
editline:init ([opts={}])	Create a new EditLine instance.
editline:insert (s)	Inserts a string at the current cursor position.
editline:insert_cp (cp)	Inserts a unicode codepoint at the current cursor position.
editline:left ([n=1])	Moves the cursor to the left.
editline:left_word ([n=1])	Moves the cursor to the start of the current word.
editline:len_char ()	Returns the current length (chars).
editline:len_col ()	Returns the current length (columns).
editline:pos_char ()	Returns the current cursor position (chars).
editline:pos_col ()	Returns the current cursor position (columns).
editline:replace (s)	Replaces the current input with a new string.
editline:right ([n=1])	Moves the cursor to the right.
editline:right_word ([n=1])	Moves the cursor to the start of the next word.
editline:sub_char ([i=1[, j=-1]])	Returns a new Editline object being a substring.

Methods

editline:backspace ([n=1])

Deletes the character left of the current cursor position. If/once the cursor is at the start of the string, it does nothing.

Parameters:

• n number the number of characters to delete (default 1)

Returns:

self (for chaining)

editline:backspace_to_start ()

Deletes all characters to the left of the current cursor position.

Returns:

self (for chaining)

editline:backspace_word ([n=1])

Backspace until the start of the current word. If at the start, backspace to the start of the previous word. Words are defined by non-delimiter characters.

Parameters:

• n number the number of words to move left (default 1)

Returns:

self (for chaining)

editline:clear ()

Clears the input.

Returns:

self (for chaining)

editline:delete ([n=1])

Deletes the character at the current cursor position. If/once the cursor is at the end of the string, it does nothing.

Parameters:

• n number the number of characters to delete (default 1)

Returns:

self (for chaining)

editline:delete_to_end ()

Deletes all characters to the right of the current cursor position.

Returns:

self (for chaining)

editline:delete_word ([n=1])

Delete until the end of the current word. Words are defined by non-delimiter characters.

Parameters:

• n number the number of words to move left (default 1)

Returns:

self (for chaining)

editline:format ([opts])

Format the contents for display, over multiple lines if necessary. The return table contains an array of Editline objects. Each entry will have its cursor position set at the end, except for the entry that actually has the cursor which will have the cursor position at the same character as the input position. If padding is used, the cursor will be placed before any padding.

Parameters:

• opts Options for formatting.
  • width number The maximum width (in columns) of each line. (default 80)
  • first_width number The width of the first line (in case of prompts/labels). (default width)
  • wordwrap boolean Whether to wrap words that exceed the width. (default true)
  • pad boolean Whether to pad the lines to the full width. (default true)
  • pad_last boolean Whether to pad the last line. (default pad)
  • no_new_cursor_line boolean If true, no empty new line will be added if the last line exactly fits the width. (default false)

Returns:

1. table A table containing the individual Editline objects.
2. number the cursor position row
3. number the cursor position column

editline:goto_end ()

Moves the cursor to the end of the string.

Returns:

self (for chaining)

editline:goto_home ()

Moves the cursor to the start of the string.

Returns:

self (for chaining)

editline:goto_index (pos)

Moves the cursor to the position given by the index. Cursor position indexes range from 1 to len + 1, where len is the length of the string in characters. Negative indexes are counted from the end backwards, so -1 is the same as goto_end. If the index is out of bounds, it will move the cursor to the closest valid position.

Parameters:

• pos number the position (in characters) to move the cursor to (0-based index)

Returns:

self (for chaining)

editline:init ([opts={}])

Create a new EditLine instance.

Parameters:

• opts Options for the edit line, or a string value to initialize.
  • value string Initial value for the edit line. (default "")
  • word_delimiters string Word delimiters for word operations. (optional)
  • position number Initial cursor position (1-based index). (optional)

Returns:

EditLine A new EditLine instance.

editline:insert (s)

Inserts a string at the current cursor position.

Parameters:

• s string the string to insert

Returns:

self (for chaining)

editline:insert_cp (cp)

Inserts a unicode codepoint at the current cursor position.

Parameters:

• cp number the codepoint to insert

Returns:

self (for chaining)

editline:left ([n=1])

Moves the cursor to the left. This function moves the cursor left by n characters. It will not move the cursor past the start of the string (no error will be raised).

Parameters:

• n number the number of characters to move left (default 1)

Returns:

self (for chaining)

editline:left_word ([n=1])

Moves the cursor to the start of the current word. If already at start, moves to the start of the previous word. This function moves the cursor left until it reaches the start of the previous word. Words are defined by non-delimiter characters.

Parameters:

• n number the number of words to move left (default 1)

Returns:

self (for chaining)

editline:len_char ()

Returns the current length (chars).

Returns:

number the current length in UTF8 characters

editline:len_col ()

Returns the current length (columns).

Returns:

number the current length in display columns

editline:pos_char ()

Returns the current cursor position (chars).

Returns:

number the current cursor position in UTF8 characters.

editline:pos_col ()

Returns the current cursor position (columns).

Returns:

number the current cursor position in display columns

editline:replace (s)

Replaces the current input with a new string. This function clears the current input and inserts the new string at the end. The cursor will be at the end of the new string.

Parameters:

• s string the new string to insert

Returns:

self (for chaining)

editline:right ([n=1])

Moves the cursor to the right. This function moves the cursor right by n characters. It will not move the cursor past the end of the string (no error will be raised).

Parameters:

• n number the number of characters to move right (default 1)

Returns:

self (for chaining)

editline:right_word ([n=1])

Moves the cursor to the start of the next word. This function moves the cursor right until it reaches the start of the next word. Words are defined by non-delimiter characters.

Parameters:

• n number the number of words to move left (default 1)

Returns:

self (for chaining)

editline:sub_char ([i=1[, j=-1]])

Returns a new Editline object being a substring. This operates based on characters. Negative indexes are counted from the end, so -1 is the last character.

Parameters:

• i number Start index. (default 1)
• j number End index. (default -1)

Returns:

EditLine A new EditLine instance containing the substring.