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