Qore Linenoise Module

The linenoise module provides readline-like functionality to Qore, allowing qore programs to manage comfortable user input in the command line.

This module is released under a choice of two licenses:

• LGPL 2.1
• MIT (see COPYING.MIT in the source distribution for more information)

The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the Qore library was initialized).

The underlying functionality is provided by Linenoise library, Steve Bennett's fork https://github.com/msteveb/linenoise of the original version https://github.com/antirez/linenoise

Basic Usage

The core of functionality is the Qore::Linenoise::line() function. It waits for user input providing basic and advanced edit functionality.

%new-style
%require-types
%strict-args

%requires linenoise

while (True) {
    *string line = Linenoise::line("prompt> ");
    if (!exists line) {
        printf("^C signal caught. Exiting.\n");
        break;
    }

    # process the line value...
}

History Handling

Linenoise module keeps history in its internal structure. To add a history item use Qore::Linenoise::history_add()

Full history content can be obained with Qore::Linenoise::history

To handle history size use Qore::Linenoise::history_set_max_len and Qore::Linenoise::history_get_max_len

History is not persistent accross processes (the memory is cleared when the process terminates). To store and load history content use Qore::Linenoise::history_save() and Qore::Linenoise::history_load()

Line Completion

Users start line completion by pressing the TAB key when in Qore::Linenoise::line().

An callback has to be used to provide line completion values. The callback is registered with Qore::Linenoise::set_callback().

Note

The callback code must accept a string as an input argument and return a list.

If the input argument isn't a string, a RUNTIME-OVERLOAD-ERROR exception will be thrown.

If the return value isn't a list, the return will be ignored.

Non string members of returned list will be converted to string (string representation of the list member will be used).

Example

# h<TAB> is expanded to string: history
list sub my_callback(string value) {
    list ret = ();
    if (value == 'h')
        push ret, 'history';

    return ret;
}

Linenoise::set_callback(\my_callback());

Keyboard Shortcuts

Shortcut	Alternative	Description
Enter	Return	submit the user input
Tab		starts a code completion if the callback is defined, Line Completion
Up	Ctrl+P	history move, one step up
Down	Ctrl+N	history move, one step down
PgUp		move to start of history
PgDown		move to the end of history = current text
Left	Ctrl+B	move by one char left
Right	Ctrl+F	move by one char right
Home	Ctrl+A	go to the start of the line
End	Ctrl+E	go to the end of the line
Ctrl+C		keyboard interrupt, NOTHING is returned from Qore::Linenoise::line() call
Backspace	Ctrl+H	delete one char before
Ctrl+D		like a Ctrl+C when there is no user content in edit buffer, otherwise like a DELETE
Ctrl+W		delete word at left, save deleted chars
Ctrl+R		display the reverse-i-search prompt and process chars. See an additional controls for Search Keyboard Shortcuts
Ctrl+T		if cursor is at end, transpose the previous two chars
Ctrl+V		handle ^V sequence. Add ^V than waits for any other input or cancel ^V if it's in ^V mode already
Ctrl+U		delete to beginning of line, save deleted chars
Ctrl+K		delete from current to end of line, save deleted chars
Ctrl+Y		insert saved chars at current position
Ctrl+L		clear screen

Search Keyboard Shortcuts

These shortcuts are valid in reverse-i-search (Ctrl+R) mode

Shortcut	Alternative	Description
Delete	Ctrl+H	delete, return to normal operation mode if the line is empty
Up	Ctrl+P	Search for the previous (earlier) match
Down	Ctrl+N	Search for the next (later) match
Ctrl+G	Ctrl+C	terminates the search with no effect
Ctrl+J		terminates the search leaving the buffer in place