Node.ReadLine
- Package
- purescript-node-readline
- Repository
- purescript-node/purescript-node-readline
This module provides a binding to the Node readline API.
#Interface Source
data InterfaceA handle to a console interface.
A handle can be created with the createInterface function.
Interface extends EventEmiter
From Node docs v18:
Instances of the
readline.Interfaceclass are constructed using thereadline.createInterface()method. Every instance is associated with a single input Readable stream and a single output Writable stream. The output stream is used to print prompts for user input that arrives on, and is read from, the input stream.
#createInterface Source
createInterface :: forall r. Readable r -> Options InterfaceOptions -> Effect InterfaceBuilds an interface with the specified options.
The Readable arg to this function
will be used as the input option below:
input<stream.Readable> The Readable stream to listen to. This option is required.output<stream.Writable> The Writable stream to write readline data to.completer<Function> An optional function used for Tab autocompletion.terminal<boolean> true if the input and output streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Default: checking isTTY on the output stream upon instantiation.history<string[]> Initial list of history lines. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: [].historySize<number> Maximum number of history lines retained. To disable the history set this value to 0. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: 30.removeHistoryDuplicates<boolean> If true, when a new input line added to the history list duplicates an older one, this removes the older line from the list. Default: false.prompt<string> The prompt string to use. Default: '> '.crlfDelay<number> If the delay between \r and \n exceeds crlfDelay milliseconds, both \r and \n will be treated as separate end-of-line input. crlfDelay will be coerced to a number no less than 100. It can be set to Infinity, in which case \r followed by \n will always be considered a single newline (which may be reasonable for reading files with \r\n line delimiter). Default: 100.escapeCodeTimeout<number> The duration readline will wait for a character (when reading an ambiguous key sequence in milliseconds one that can both form a complete key sequence using the input read so far and can take additional input to complete a longer key sequence). Default: 500.tabSize<integer> The number of spaces a tab is equal to (minimum 1). Default: 8.signal<AbortSignal> Allows closing the interface using an AbortSignal. Aborting the signal will internally call close on the interface.
#createConsoleInterface Source
createConsoleInterface :: Completer -> Effect InterfaceCreate an interface with the specified completion function.
#InterfaceOptions Source
data InterfaceOptionsOptions passed to readline's createInterface
input<stream.Readable> The Readable stream to listen to. This option is required.output<stream.Writable> The Writable stream to write readline data to.completer<Function> An optional function used for Tab autocompletion.terminal<boolean> true if the input and output streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Default: checking isTTY on the output stream upon instantiation.history<string[]> Initial list of history lines. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: [].historySize<number> Maximum number of history lines retained. To disable the history set this value to 0. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: 30.removeHistoryDuplicates<boolean> If true, when a new input line added to the history list duplicates an older one, this removes the older line from the list. Default: false.prompt<string> The prompt string to use. Default: '> '.crlfDelay<number> If the delay between \r and \n exceeds crlfDelay milliseconds, both \r and \n will be treated as separate end-of-line input. crlfDelay will be coerced to a number no less than 100. It can be set to Infinity, in which case \r followed by \n will always be considered a single newline (which may be reasonable for reading files with \r\n line delimiter). Default: 100.escapeCodeTimeout<number> The duration readline will wait for a character (when reading an ambiguous key sequence in milliseconds one that can both form a complete key sequence using the input read so far and can take additional input to complete a longer key sequence). Default: 500.tabSize<integer> The number of spaces a tab is equal to (minimum 1). Default: 8.signal<AbortSignal> Allows closing the interface using an AbortSignal. Aborting the signal will internally call close on the interface.
#noCompletion Source
noCompletion :: CompleterA completion function which offers no completions.
#promptStr Source
promptStr :: Option InterfaceOptions StringOption for prompt; name is changed to prevent naming clash with prompt function
#closeH Source
closeH :: EventHandle0 InterfaceThe 'close' event is emitted when one of the following occur:
- The
rl.close()method is called and the readline.Interface instance has relinquished control over the input and output streams; - The input stream receives its 'end' event;
- The input stream receives
Ctrl+Dto signal end-of-transmission (EOT); - The input stream receives
Ctrl+Cto signalSIGINTand there is noSIGINTevent listener registered on the readline.Interface instance.
The listener function is called without passing any arguments.
The readline.Interface instance is finished once the close event is emitted.
#lineH Source
lineH :: EventHandle1 Interface StringThe 'line' event is emitted whenever the input stream receives an end-of-line input (\n, \r, or \r\n).
This usually occurs when the user presses Enter or Return.
The 'line' event is also emitted if new data has been read from a stream and that stream ends without a final end-of-line marker.
The listener function is called with a string containing the single line of received input.
#historyH Source
historyH :: EventHandle1 Interface (Array String)The 'history' event is emitted whenever the history array has changed.
The listener function is called with an array containing the history array. It will reflect all changes, added lines and removed lines due to historySize and removeHistoryDuplicates.
The primary purpose is to allow a listener to persist the history. It is also possible for the listener to change the history object. This could be useful to prevent certain lines to be added to the history, like a password.
#pauseH Source
pauseH :: EventHandle0 InterfaceThe 'pause' event is emitted when one of the following occur:
- The input stream is paused.
- The input stream is not paused and receives the 'SIGCONT' event. (See events 'SIGTSTP' and 'SIGCONT'.)
The listener function is called without passing any arguments.
#resumeH Source
resumeH :: EventHandle0 InterfaceThe 'resume' event is emitted whenever the input stream is resumed.
The listener function is called without passing any arguments.
#sigContH Source
sigContH :: EventHandle0 InterfaceThe 'SIGCONT' event is emitted when a Node.js process previously moved into the background using Ctrl+Z (i.e. SIGTSTP) is then brought back to the foreground using fg(1p).
If the input stream was paused before the SIGTSTP request, this event will not be emitted.
The listener function is invoked without passing any arguments.
The 'SIGCONT' event is not supported on Windows.
#sigIntH Source
sigIntH :: EventHandle0 InterfaceThe 'SIGINT' event is emitted whenever the input stream receives a Ctrl+C input, known typically as SIGINT. If there are no 'SIGINT' event listeners registered when the input stream receives a SIGINT, the 'pause' event will be emitted.
The listener function is invoked without passing any arguments.
#sigStpH Source
sigStpH :: EventHandle0 InterfaceThe 'SIGTSTP' event is emitted when the input stream receives a Ctrl+Z input, typically known as SIGTSTP. If there are no 'SIGTSTP' event listeners registered when the input stream receives a SIGTSTP, the Node.js process will be sent to the background.
When the program is resumed using fg(1p), the 'pause' and 'SIGCONT' events will be emitted. These can be used to resume the input stream.
The 'pause' and 'SIGCONT' events will not be emitted if the input was paused before the process was sent to the background.
The listener function is invoked without passing any arguments.
The 'SIGTSTP' event is not supported on Windows.
#close Source
close :: Interface -> Effect UnitClose the specified Interface.
The rl.close() method closes the readline.Interface instance and relinquishes control over the input and output streams. When called, the 'close' event will be emitted.
Calling rl.close() does not immediately stop other events (including 'line') from being emitted by the readline.Interface instance.
#prompt' Source
prompt' :: Boolean -> Interface -> Effect UnitpreserveCursor<boolean> If true, prevents the cursor placement from being reset to 0.
The rl.prompt() method writes the readline.Interface instances configured prompt to a new line in output in order to provide a user with a new location at which to provide input.
When called, rl.prompt() will resume the input stream if it has been paused.
If the readline.Interface was created with output set to null or undefined the prompt is not written.
#question Source
question :: String -> (String -> Effect Unit) -> Interface -> Effect UnitWrites a query to the output, waits for user input to be provided on input, then invokes the callback function
Args:
query<string> A statement or query to write to output, prepended to the prompt.options<Object>signal<AbortSignal> Optionally allows the question() to be canceled using an AbortController.
callback<Function> A callback function that is invoked with the user's input in response to the query.
The rl.question() method displays the query by writing it to the output, waits for user input to be provided on input, then invokes the callback function passing the provided input as the first argument.
When called, rl.question() will resume the input stream if it has been paused.
If the readline.Interface was created with output set to null or undefined the query is not written.
The callback function passed to rl.question() does not follow the typical pattern of accepting an Error object or null as the first argument. The callback is called with the provided answer as the only argument.
#question' Source
question' :: String -> { signal :: AbortSignal } -> (String -> Effect Unit) -> Interface -> Effect UnitWrites a query to the output, waits for user input to be provided on input, then invokes the callback function
Args:
query<string> A statement or query to write to output, prepended to the prompt.options<Object>signal<AbortSignal> Optionally allows the question() to be canceled using an AbortController.
callback<Function> A callback function that is invoked with the user's input in response to the query.
The rl.question() method displays the query by writing it to the output, waits for user input to be provided on input, then invokes the callback function passing the provided input as the first argument.
When called, rl.question() will resume the input stream if it has been paused.
If the readline.Interface was created with output set to null or undefined the query is not written.
The callback function passed to rl.question() does not follow the typical pattern of accepting an Error object or null as the first argument. The callback is called with the provided answer as the only argument.