||1 week ago|
|README.md||1 week ago|
|main.slo||1 week ago|
|module.json||1 week ago|
line-edit module is a native slope line reading library that can be used where you might, in another language, use bindings to
line-edit is a pure slope affair that utilizes terminal escape sequences to control the line and an internal buffer to track state.
What it does
At a basic level, it allows a user to input text... and to navigate that text as they are inputting it: moving the cursor around, clearing the line, etc.
line-edit allows the programmer to supply a prompt and a seed value to the line. The prompt is not editable by the user. The seed value is an initial value that the buffer is set to and can be edited by the user.
(line-edit::line "$ " "") would give the user the prompt
$ with no seed value and will return a string containing the text that they entered.
line-edit provides a few basic control key chords to enable navigating the line without arrow keys if need be, but nowhere near as robust as
If the entry is longer than the available terminal width minus the prompt length then an offset value is kept in the buffer to allow for horizontal scolling of the input line.
What it does not do
- Fancy stuff like moving the cursor to the next/previous word
- Support multiline input
- Wrap long lines (horizontal scrolling is used instead)
- Support actual tab characters as input (tab will instead convert to a number of spaces equal to the
tabwidthsetting - see below)
How to use it
There are basically two procedures and a few variables available to a user of the module.
Reading a key
This is exposed to the user, but is mostly present as a part of reading a line. However, it may be useful for any number of situations and should thus be documented here.
(load-mod line-edit) (define my-key-press (line-edit::get-key))
Key Responses / Variables
The returned value will be a
number. That number will generally correspond to the ascii value of the key being pressed, or the rune (codepoint) of a UTF-8 character. Some values have variables set for convenience; these are listed as follows:
You can use these like so:
(load-mod line-edit) (if (equal? (line-edit::home-key) (line-edit::get-key)) (display "Home key was pressed") (display "A key was pressed... but it wasn't the home key"))
Reading a line
This is the main procedure of the module. The procedure signature is:
(line-edit::get-line [prompt: string] [seed: string]) => string
seed are required, but both/either can be an empty string.
Usage takes the form of:
(load-mod line-edit) (define name (line-edit::get-line "Name: " ""))
line-edit includes a modest set of key bindings:
||Move cursor to the beginning of the line|
||Move cursor to the end of the line|
||Move the cursor one character to the left|
||Move the cursor one character to the right|
||Delete the character under the cursor|
||Delete the character before the cursor|
||Delete from the cursor to the end of the line|
||Empty the line (delete all content in the buffer)|
||Enter paste mode (the next read can accept pasted data)|
||Delete from the beginning of the line to the cursor|
||Paste the contents of the paste buffer|
||Submit the line|
|Most printable chars||Add the character to the buffer at the cursor location|
As noted above,
tab is not registered for input as it donks up the horizontal scrolling provided by
The Paste Buffer
The paste buffer survives accross multiple calls to module procedures, including
get-line. As such, it can be used as a paste buffer for the whole slope interpreter session, not just a single procedure call. Anything that is deleted with Ctrl+K, Ctrl+U, or Ctrl+L gets put into the paste buffer. The paste buffer only has one level which gets overwritten any time one of the above key chords gets pressed (even if no deletion occurs, such as
^U at the beginning of the line, which will leave an empty paste buffer).
Pasting text into line-edit
Unicode parsing is funky here. To enable good usage of utf-8 text, in line with the rest of slope as a programming system, a single utf-8 character (including the ascii set) can be pasted and will appear as intended. Due to a mixture of complicated specs and design decisions for this module the key chord
^P should be entered before attempting to paste more than a single character. Doing so will allow a paste and read pasted data up to the first newline. Unicode is properly supported within this paste. There is a maximum paste size of ~2kb.
The TAB key
Tab spacing is variable by user by system. In order to not wade into that mess
line-edit will accept the tab key being pressed but will enter spaces up to the next tabstop, as defined by the
To get/set the tab width:
(load-mod line-edit) (display (line-edit::tabwidth)) ; 4 (line-edit::tabwidth 8) ; sets the tabwidth to 8 (display (line-edit::tabwidth)) ; 8
This behavior will accurately replicate what tabs do, but via spaces.
If in a call to
line-edit::get-line you provide default text that has a literal tab character in it, it will be display, but movement and cursor alignment will be off and will be a very odd user experience. It is advised that you convert any default text to use tab stops that work with the
tabwidth setting the
line-edit module is using at the time of the procedure call.