deno.land / std@0.167.0 / node / _readline.d.ts
نووسراو ببینە
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.// deno-lint-ignore-file no-explicit-any
// Forked from https://github.com/DefinitelyTyped/DefinitelyTyped/blob/cd61f5b4d3d143108569ec3f88adc0eb34b961c4/types/node/readline.d.ts
import { Abortable, EventEmitter } from "./_events.d.ts";import * as promises from "./readline/promises.ts";import { ReadableStream, WritableStream } from "./_global.d.ts";import { Buffer } from "./buffer.ts";import type { AsyncCompleter, Completer, CompleterResult, ReadLineOptions,} from "./_readline_shared_types.d.ts";
/** * The `readline` module provides an interface for reading data from a `Readable` stream (such as `process.stdin`) one line at a time. * * To use the promise-based APIs: * * ```js * import * as readline from 'node:readline/promises'; * ``` * * To use the callback and sync APIs: * * ```js * import * as readline from 'node:readline'; * ``` * * The following simple example illustrates the basic use of the `readline` module. * * ```js * import * as readline from 'node:readline/promises'; * import { stdin as input, stdout as output } from 'node:process'; * * const rl = readline.createInterface({ input, output }); * * const answer = await rl.question('What do you think of Node.js? '); * * console.log(`Thank you for your valuable feedback: ${answer}`); * * rl.close(); * ``` * * Once this code is invoked, the Node.js application will not terminate until the`readline.Interface` is closed because the interface waits for data to be * received on the `input` stream. * @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/readline.js) */export { promises };export interface Key { sequence?: string | undefined; name?: string | undefined; ctrl?: boolean | undefined; meta?: boolean | undefined; shift?: boolean | undefined;}/** * Instances of the `readline.Interface` class are constructed using the`readline.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. * @since v0.1.104 */export class Interface extends EventEmitter { readonly terminal: boolean; /** * The current input data being processed by node. * * This can be used when collecting input from a TTY stream to retrieve the * current value that has been processed thus far, prior to the `line` event * being emitted. Once the `line` event has been emitted, this property will * be an empty string. * * Be aware that modifying the value during the instance runtime may have * unintended consequences if `rl.cursor` is not also controlled. * * **If not using a TTY stream for input, use the `'line'` event.** * * One possible use case would be as follows: * * ```js * const values = ['lorem ipsum', 'dolor sit amet']; * const rl = readline.createInterface(process.stdin); * const showResults = debounce(() => { * console.log( * '\n', * values.filter((val) => val.startsWith(rl.line)).join(' ') * ); * }, 300); * process.stdin.on('keypress', (c, k) => { * showResults(); * }); * ``` * @since v0.1.98 */ readonly line: string; /** * The cursor position relative to `rl.line`. * * This will track where the current cursor lands in the input string, when * reading input from a TTY stream. The position of cursor determines the * portion of the input string that will be modified as input is processed, * as well as the column where the terminal caret will be rendered. * @since v0.1.98 */ readonly cursor: number; /** * NOTE: According to the documentation: * * > Instances of the `readline.Interface` class are constructed using the * > `readline.createInterface()` method. * * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface */ protected constructor( input: ReadableStream, output?: WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean, ); /** * NOTE: According to the documentation: * * > Instances of the `readline.Interface` class are constructed using the * > `readline.createInterface()` method. * * @see https://nodejs.org/dist/latest-v10.x/docs/api/readline.html#readline_class_interface */ protected constructor(options: ReadLineOptions); /** * The `rl.getPrompt()` method returns the current prompt used by `rl.prompt()`. * @since v15.3.0 * @return the current prompt string */ getPrompt(): string; /** * The `rl.setPrompt()` method sets the prompt that will be written to `output`whenever `rl.prompt()` is called. * @since v0.1.98 */ setPrompt(prompt: string): void; /** * 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. * @since v0.1.98 * @param preserveCursor If `true`, prevents the cursor placement from being reset to `0`. */ prompt(preserveCursor?: boolean): void; /** * 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. * * Example usage: * * ```js * rl.question('What is your favorite food? ', (answer) => { * console.log(`Oh, so your favorite food is ${answer}`); * }); * ``` * * Using an `AbortController` to cancel a question. * * ```js * const ac = new AbortController(); * const signal = ac.signal; * * rl.question('What is your favorite food? ', { signal }, (answer) => { * console.log(`Oh, so your favorite food is ${answer}`); * }); * * signal.addEventListener('abort', () => { * console.log('The food question timed out'); * }, { once: true }); * * setTimeout(() => ac.abort(), 10000); * ``` * * If this method is invoked as it's util.promisify()ed version, it returns a * Promise that fulfills with the answer. If the question is canceled using * an `AbortController` it will reject with an `AbortError`. * * ```js * const util = require('util'); * const question = util.promisify(rl.question).bind(rl); * * async function questionExample() { * try { * const answer = await question('What is you favorite food? '); * console.log(`Oh, so your favorite food is ${answer}`); * } catch (err) { * console.error('Question rejected', err); * } * } * questionExample(); * ``` * @since v0.3.3 * @param query A statement or query to write to `output`, prepended to the prompt. * @param callback A callback function that is invoked with the user's input in response to the `query`. */ question(query: string, callback: (answer: string) => void): void; question( query: string, options: Abortable, callback: (answer: string) => void, ): void; /** * The `rl.pause()` method pauses the `input` stream, allowing it to be resumed * later if necessary. * * Calling `rl.pause()` does not immediately pause other events (including`'line'`) from being emitted by the `readline.Interface` instance. * @since v0.3.4 */ pause(): this; /** * The `rl.resume()` method resumes the `input` stream if it has been paused. * @since v0.3.4 */ resume(): this; /** * 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. * @since v0.1.98 */ close(): void; /** * The `rl.write()` method will write either `data` or a key sequence identified * by `key` to the `output`. The `key` argument is supported only if `output` is * a `TTY` text terminal. See `TTY keybindings` for a list of key * combinations. * * If `key` is specified, `data` is ignored. * * When called, `rl.write()` will resume the `input` stream if it has been * paused. * * If the `readline.Interface` was created with `output` set to `null` or`undefined` the `data` and `key` are not written. * * ```js * rl.write('Delete this!'); * // Simulate Ctrl+U to delete the line written previously * rl.write(null, { ctrl: true, name: 'u' }); * ``` * * The `rl.write()` method will write the data to the `readline` `Interface`'s`input`_as if it were provided by the user_. * @since v0.1.98 */ write(data: string | Buffer, key?: Key): void; write(data: undefined | null | string | Buffer, key: Key): void; /** * Returns the real position of the cursor in relation to the input * prompt + string. Long input (wrapping) strings, as well as multiple * line prompts are included in the calculations. * @since v13.5.0, v12.16.0 */ getCursorPos(): CursorPos; /** * events.EventEmitter * 1. close * 2. line * 3. pause * 4. resume * 5. SIGCONT * 6. SIGINT * 7. SIGTSTP * 8. history */ addListener(event: string, listener: (...args: any[]) => void): this; addListener(event: "close", listener: () => void): this; addListener(event: "line", listener: (input: string) => void): this; addListener(event: "pause", listener: () => void): this; addListener(event: "resume", listener: () => void): this; addListener(event: "SIGCONT", listener: () => void): this; addListener(event: "SIGINT", listener: () => void): this; addListener(event: "SIGTSTP", listener: () => void): this; addListener(event: "history", listener: (history: string[]) => void): this; emit(event: string | symbol, ...args: any[]): boolean; emit(event: "close"): boolean; emit(event: "line", input: string): boolean; emit(event: "pause"): boolean; emit(event: "resume"): boolean; emit(event: "SIGCONT"): boolean; emit(event: "SIGINT"): boolean; emit(event: "SIGTSTP"): boolean; emit(event: "history", history: string[]): boolean; on(event: string, listener: (...args: any[]) => void): this; on(event: "close", listener: () => void): this; on(event: "line", listener: (input: string) => void): this; on(event: "pause", listener: () => void): this; on(event: "resume", listener: () => void): this; on(event: "SIGCONT", listener: () => void): this; on(event: "SIGINT", listener: () => void): this; on(event: "SIGTSTP", listener: () => void): this; on(event: "history", listener: (history: string[]) => void): this; once(event: string, listener: (...args: any[]) => void): this; once(event: "close", listener: () => void): this; once(event: "line", listener: (input: string) => void): this; once(event: "pause", listener: () => void): this; once(event: "resume", listener: () => void): this; once(event: "SIGCONT", listener: () => void): this; once(event: "SIGINT", listener: () => void): this; once(event: "SIGTSTP", listener: () => void): this; once(event: "history", listener: (history: string[]) => void): this; prependListener(event: string, listener: (...args: any[]) => void): this; prependListener(event: "close", listener: () => void): this; prependListener(event: "line", listener: (input: string) => void): this; prependListener(event: "pause", listener: () => void): this; prependListener(event: "resume", listener: () => void): this; prependListener(event: "SIGCONT", listener: () => void): this; prependListener(event: "SIGINT", listener: () => void): this; prependListener(event: "SIGTSTP", listener: () => void): this; prependListener( event: "history", listener: (history: string[]) => void, ): this; prependOnceListener(event: string, listener: (...args: any[]) => void): this; prependOnceListener(event: "close", listener: () => void): this; prependOnceListener(event: "line", listener: (input: string) => void): this; prependOnceListener(event: "pause", listener: () => void): this; prependOnceListener(event: "resume", listener: () => void): this; prependOnceListener(event: "SIGCONT", listener: () => void): this; prependOnceListener(event: "SIGINT", listener: () => void): this; prependOnceListener(event: "SIGTSTP", listener: () => void): this; prependOnceListener( event: "history", listener: (history: string[]) => void, ): this; [Symbol.asyncIterator](): AsyncIterableIterator<string>;}export type ReadLine = Interface; // type forwarded for backwards compatibilityexport { AsyncCompleter, Completer, CompleterResult, ReadLineOptions };/** * The `readline.createInterface()` method creates a new `readline.Interface`instance. * * ```js * const readline = require('readline'); * const rl = readline.createInterface({ * input: process.stdin, * output: process.stdout * }); * ``` * * Once the `readline.Interface` instance is created, the most common case is to * listen for the `'line'` event: * * ```js * rl.on('line', (line) => { * console.log(`Received: ${line}`); * }); * ``` * * If `terminal` is `true` for this instance then the `output` stream will get * the best compatibility if it defines an `output.columns` property and emits * a `'resize'` event on the `output` if or when the columns ever change * (`process.stdout` does this automatically when it is a TTY). * * When creating a `readline.Interface` using `stdin` as input, the program * will not terminate until it receives `EOF` (Ctrl+D on * Linux/macOS, Ctrl+Z followed by Return on * Windows). * If you want your application to exit without waiting for user input, you can `unref()` the standard input stream: * * ```js * process.stdin.unref(); * ``` * @since v0.1.98 */export function createInterface( input: ReadableStream, output?: WritableStream, completer?: Completer | AsyncCompleter, terminal?: boolean,): Interface;export function createInterface(options: ReadLineOptions): Interface;/** * The `readline.emitKeypressEvents()` method causes the given `Readable` stream to begin emitting `'keypress'` events corresponding to received input. * * Optionally, `interface` specifies a `readline.Interface` instance for which * autocompletion is disabled when copy-pasted input is detected. * * If the `stream` is a `TTY`, then it must be in raw mode. * * This is automatically called by any readline instance on its `input` if the`input` is a terminal. Closing the `readline` instance does not stop * the `input` from emitting `'keypress'` events. * * ```js * readline.emitKeypressEvents(process.stdin); * if (process.stdin.isTTY) * process.stdin.setRawMode(true); * ``` * * ## Example: Tiny CLI * * The following example illustrates the use of `readline.Interface` class to * implement a small command-line interface: * * ```js * const readline = require('readline'); * const rl = readline.createInterface({ * input: process.stdin, * output: process.stdout, * prompt: 'OHAI> ' * }); * * rl.prompt(); * * rl.on('line', (line) => { * switch (line.trim()) { * case 'hello': * console.log('world!'); * break; * default: * console.log(`Say what? I might have heard '${line.trim()}'`); * break; * } * rl.prompt(); * }).on('close', () => { * console.log('Have a great day!'); * process.exit(0); * }); * ``` * * ## Example: Read file stream line-by-Line * * A common use case for `readline` is to consume an input file one line at a * time. The easiest way to do so is leveraging the `fs.ReadStream` API as * well as a `for await...of` loop: * * ```js * const fs = require('fs'); * const readline = require('readline'); * * async function processLineByLine() { * const fileStream = fs.createReadStream('input.txt'); * * const rl = readline.createInterface({ * input: fileStream, * crlfDelay: Infinity * }); * // Note: we use the crlfDelay option to recognize all instances of CR LF * // ('\r\n') in input.txt as a single line break. * * for await (const line of rl) { * // Each line in input.txt will be successively available here as `line`. * console.log(`Line from file: ${line}`); * } * } * * processLineByLine(); * ``` * * Alternatively, one could use the `'line'` event: * * ```js * const fs = require('fs'); * const readline = require('readline'); * * const rl = readline.createInterface({ * input: fs.createReadStream('sample.txt'), * crlfDelay: Infinity * }); * * rl.on('line', (line) => { * console.log(`Line from file: ${line}`); * }); * ``` * * Currently, `for await...of` loop can be a bit slower. If `async` / `await`flow and speed are both essential, a mixed approach can be applied: * * ```js * const { once } = require('events'); * const { createReadStream } = require('fs'); * const { createInterface } = require('readline'); * * (async function processLineByLine() { * try { * const rl = createInterface({ * input: createReadStream('big-file.txt'), * crlfDelay: Infinity * }); * * rl.on('line', (line) => { * // Process the line. * }); * * await once(rl, 'close'); * * console.log('File processed.'); * } catch (err) { * console.error(err); * } * })(); * ``` * @since v0.7.7 */export function emitKeypressEvents( stream: ReadableStream, readlineInterface?: Interface,): void;export type Direction = -1 | 0 | 1;export interface CursorPos { rows: number; cols: number;}/** * The `readline.clearLine()` method clears current line of given `TTY` stream * in a specified direction identified by `dir`. * @since v0.7.7 * @param callback Invoked once the operation completes. * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. */export function clearLine( stream: WritableStream, dir: Direction, callback?: () => void,): boolean;/** * The `readline.clearScreenDown()` method clears the given `TTY` stream from * the current position of the cursor down. * @since v0.7.7 * @param callback Invoked once the operation completes. * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. */export function clearScreenDown( stream: WritableStream, callback?: () => void,): boolean;/** * The `readline.cursorTo()` method moves cursor to the specified position in a * given `TTY` `stream`. * @since v0.7.7 * @param callback Invoked once the operation completes. * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. */export function cursorTo( stream: WritableStream, x: number, y?: number, callback?: () => void,): boolean;/** * The `readline.moveCursor()` method moves the cursor _relative_ to its current * position in a given `TTY` `stream`. * * ## Example: Tiny CLI * * The following example illustrates the use of `readline.Interface` class to * implement a small command-line interface: * * ```js * const readline = require('readline'); * const rl = readline.createInterface({ * input: process.stdin, * output: process.stdout, * prompt: 'OHAI> ' * }); * * rl.prompt(); * * rl.on('line', (line) => { * switch (line.trim()) { * case 'hello': * console.log('world!'); * break; * default: * console.log(`Say what? I might have heard '${line.trim()}'`); * break; * } * rl.prompt(); * }).on('close', () => { * console.log('Have a great day!'); * process.exit(0); * }); * ``` * * ## Example: Read file stream line-by-Line * * A common use case for `readline` is to consume an input file one line at a * time. The easiest way to do so is leveraging the `fs.ReadStream` API as * well as a `for await...of` loop: * * ```js * const fs = require('fs'); * const readline = require('readline'); * * async function processLineByLine() { * const fileStream = fs.createReadStream('input.txt'); * * const rl = readline.createInterface({ * input: fileStream, * crlfDelay: Infinity * }); * // Note: we use the crlfDelay option to recognize all instances of CR LF * // ('\r\n') in input.txt as a single line break. * * for await (const line of rl) { * // Each line in input.txt will be successively available here as `line`. * console.log(`Line from file: ${line}`); * } * } * * processLineByLine(); * ``` * * Alternatively, one could use the `'line'` event: * * ```js * const fs = require('fs'); * const readline = require('readline'); * * const rl = readline.createInterface({ * input: fs.createReadStream('sample.txt'), * crlfDelay: Infinity * }); * * rl.on('line', (line) => { * console.log(`Line from file: ${line}`); * }); * ``` * * Currently, `for await...of` loop can be a bit slower. If `async` / `await`flow and speed are both essential, a mixed approach can be applied: * * ```js * const { once } = require('events'); * const { createReadStream } = require('fs'); * const { createInterface } = require('readline'); * * (async function processLineByLine() { * try { * const rl = createInterface({ * input: createReadStream('big-file.txt'), * crlfDelay: Infinity * }); * * rl.on('line', (line) => { * // Process the line. * }); * * await once(rl, 'close'); * * console.log('File processed.'); * } catch (err) { * console.error(err); * } * })(); * ``` * @since v0.7.7 * @param callback Invoked once the operation completes. * @return `false` if `stream` wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`. */export function moveCursor( stream: WritableStream, dx: number, dy: number, callback?: () => void,): boolean;
std
Version Info
a year ago
