[ Main Table Of Contents | Table Of Contents | Keyword Index ]

linenoise(n) 1 doc "Tcl Line Editor"

Name

linenoise - Linenoise - Package Reference

Table Of Contents

Synopsis

  • package require Tcl 8.5
  • package require linenoise ?1?

Description

Welcome to Linenoise, a binding to Antirez's linenoise minimal line editor library, as modified and extended by Steve Bennet of Workware.au

This document is the reference manpage for the linenoise package, a binding to Antirez's minimal line editor library (of the same name) and as extended by Steve Bennet. Its intended audience are developers wishing to write Tcl applications and packages using linenoise.

API

This section describe the available commands.

All of them are found under the linenoise ensemble command.

linenoise cmdloop ?options...?

This command implements the core of a REPL (read-eval-print loop). While the defaults of the various options are geared towards the REPL of a Tcl shell, other types of REPL can implemented just fine by overriding them with the proper callbacks. By default the loop can be aborted only by entering Control-C on the keyboard, or equivalent.

The recognized options are

-complete cmdprefix

The value of this option is a command prefix taking the current contents of the line buffer as its single argument and returning a list of possible completions. The default is the empty command, disabling command completion.

-continued cmdprefix

The value of this option is a command prefix taking the user-entered line as its single argument and returning a boolean value telling the REPL if the line is incomplete and needs more input, i.e. a "continuation line". The default value recognizes incomplete Tcl command lines.

-dispatch cmdprefix

The value of this option is a command prefix taking the user-entered line(s), i.e. command as its single argument and executing it. The result of the command is the result of the command prefix, and delivered to option -report for printing. Errors thrown by the execution are caught and printed through -report as well. The default value simply runs the command in the context calling the REPL.

-exit cmdprefix

The value of this option is a command prefix taking no arguments and returning a boolean value indicating if the command loop should be stopped (true), or not. The default value never stops the loop.

-history boolean

The value of this option specifies if the command should put the entered strings into the history (true), or not. The default value is false, leaving the history untouched.

-prompt1 cmdprefix

The value of this option is a command prefix without arguments. Its result is treated as the main (primary) prompt used by the REPL. This callback is run for each iteration of the main loop, allowing for changes to the prompt in response to a changing system state. The default value returns "% ".

-prompt2 cmdprefix

The value of this option is a command prefix without arguments. Its result is treated as the secondary prompt used by the REPL, when entering continuation lines. This callback is run for each iteration of the secondary loop, allowing for changes to the prompt in response to a changing system state. The default value returns "> ".

-report cmdprefix

The value of this option is a command prefix taking two arguments, the type of a command result (ok, or fail), and the result itself, and "printing" this data in some way. The default value prints ok result to stdout and fail results to stderr.

linenoise columns

This command returns the current width of the console window the package is talking to. This enables the user to adapt its output (for example help texts) to the console.

linenoise hidden ?enable?

This command returns the current state of the system's hidden flag, which is true if hidden input is activated, and false otherwise. If the argument is specified it has to be a boolean value which becomes the new value of the flag. This new value is then returned.

linenoise history add string

This command adds the string to the history. The result of the command is a boolean flag, true if the addition suceeded, and false otherwise. The string will not be added if it is identical to the last entry of the history, preventing entry of adjacent duplicates.

The history reaching its maximal size does not prevent the addition of the string. It simply bumps of the oldest entry to make room for the new.

linenoise history clear

This command clears (empties) the history.

linenoise history list

This command returns a list containing the history. The first element of the result is the oldest entry in the history, and the last element the newest.

linenoise history load path

This command loads the contents of the file at path into the history. Note, this is not a replacement, but an appending, like with linenoise history add.

linenoise history maxsize ?n?

This command returns the current maximal size of the system's history, as a positive integer number greater than zero. If the argument is specified it has to be a positive integer number greater than zero, which becomes the new maximal size of the history. This new value is then returned.

If the new maximal size is less than the current size of the history the oldest entries are discarded to bring the history down to the new size.

linenoise history save path

This command takes the history and stores it into the file at the specified path. The previous contents of the file are written over and lost.

linenoise history size

This command returns the number of entries in the history, as positive integer number (including zero).

linenoise prompt ?options...?

This command implements a one-shot prompt (instead of a REPL), returning the string entered by the user after completing the interaction.

The recognized options are similar to what is recognized by cmdloop, albeit reduced and simplified:

-complete cmdprefix

The value of this option is a command prefix taking the current contents of the line buffer as its single argument and returning a list of possible completions. The default is the empty command, disabling command completion.

-hidden boolean

The value of this option specifies if the command should hide user input (true), or not. The default value is false, for visible line entry. A use case for this option is the entry of passwords and the like.

-history boolean

The value of this option specifies if the command should put the entered string into the history (true), or not. The default value is false, leaving the history untouched.

-prompt string

The value of this option is the string to use as the prompt. The default value is "% ".

Authors

Andreas Kupries (Tcl Binding), Steve Bennett (extended linenoise C library), Salvatore Sanfilippo (Antirez, original linenoise C library).

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report them at the Issues tracker. Ideas for enhancements you may have for either package, application, and/or the documentation are also very welcome and should be reported at the Issues tracker as well.

Keywords

console, edit line, line editor, line reading, linenoise, raw mode, read line, terminal, tty

Category

Binding