Class ReadLineHandler

Namespace

InteractiveReadLine

Assembly

InteractiveReadLine.dll

This class handles getting a single line of input from the underlying IReadLineProvider. It reads keys from the provider, determines what the current line of text being edited should be and where the cursor should be positioned. It pushes out the text to the provider, which also serves as the view.

public class ReadLineHandler : IKeyBehaviorTarget

Inheritance

object

ReadLineHandler

Implements

IKeyBehaviorTarget

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

ReadLineHandler(IReadLineProvider, ReadLineConfig?)

Creates a handler which will read a single line of input through the given provider.

public ReadLineHandler(IReadLineProvider provider, ReadLineConfig? config = null)

Parameters

provider IReadLineProvider

The backend which reads keys and displays the line

config ReadLineConfig

The configuration controlling key behaviors, formatting, lexing, auto-completion and history, or null to use ReadLineConfig.Basic.

Properties

CursorPosition

Gets or sets the integer position of the cursor. Cannot be set before the beginning or after the end of the TextBuffer.

public int CursorPosition { get; set; }

Property Value

int

CutBuffer

Gets the text accumulated by the most recent run of cut operations. The paste behavior inserts this text at the cursor. The value is empty when nothing has been cut.

public string CutBuffer { get; }

Property Value

string

Remarks

The buffer belongs to a single read line operation and does not carry over to the next one. It is populated through CutForward and CutBackward, which accumulate consecutive cuts into one piece of text that can be pasted.

LineState

Gets the current LineState representation of the text and the cursor position

public LineState LineState { get; }

Property Value

LineState

ReceivedKey

Gets the ConsoleKey which was received for the current request

public ConsoleKeyInfo ReceivedKey { get; }

Property Value

ConsoleKeyInfo

TextBuffer

Gets the string buffer which holds the current readline text which is being edited by the user

public StringBuilder TextBuffer { get; }

Property Value

StringBuilder

Methods

AutoCompleteNext()

Invokes the auto-complete's "next" functionality, which substitutes in the next suggestion

public void AutoCompleteNext()

AutoCompletePrevious()

Invokes the auto-complete's "previous" functionality, which substitutes in the previous suggestion

public void AutoCompletePrevious()

Cancel()

Tells the ReadLine handler to abandon the current line and discard the entered text. This matches conventional Ctrl+C behavior: the handler records nothing in history and completes without an error.

public void Cancel()

CutBackward(string)

Records text removed from behind the cursor, placing it at the front of the cut buffer.

public void CutBackward(string text)

Parameters

text string

The text that was removed from the line.

Remarks

A behavior that removes text from behind the cursor, such as cutting to the start of the line or cutting the previous word, should report it here. Cutting three words backward one after another therefore leaves the three words in the buffer in their original order.

CutForward(string)

Records text removed from in front of the cursor, placing it at the end of the cut buffer.

public void CutForward(string text)

Parameters

text string

The text that was removed from the line.

Remarks

Cut text is stored in its original order on the line, so a run of cuts can be pasted back as the original text. A behavior that removes text in front of the cursor, such as cutting to the end of the line, should report it here.

EndOfInput()

Tells the ReadLine handler that the user has signaled the end of input, which is what Ctrl+D on an empty line means to a shell. The line is discarded, and the caller is told that no further input is coming.

public void EndOfInput()

Finish()

Causes the ReadLine handler to finish, returning the contents of the text buffer

public void Finish()

GetTextTokens()

Gets the tokenized text buffer when the handler configuration has a lexer.

public TokenizedLine? GetTextTokens()

Returns

TokenizedLine

The tokenized line, or null when the configuration has no lexer.

HistoryNext()

Invokes the history's "next" functionality, which replaces the entire line with the next element in the history collection. If the last history element has been reached, the previously entered LineState will be reverted.

public void HistoryNext()

HistoryPrevious()

Invokes the history's "previous" functionality, which replaces the entire line with the previous element in the history collection.

public void HistoryPrevious()

InsertText(FormattedText)

Inserts text to the console out in the spot where the current read line input is, then immediately re-displays the line input on the next row. Use this to interrupt the user with a message or information while the ReadLine is still being used

public void InsertText(FormattedText text)

Parameters

text FormattedText

The text to write to the console, a newline char will be added automatically

Read(CancellationToken)

Interactively manages a line of console input and returns a result that describes the text and how the interaction ended.

public ReadLineResult Read(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token that cancels the read. Cancellation raises an OperationCanceledException instead of producing a result, which is what distinguishes it from the user abandoning the line with Ctrl+C.

Returns

ReadLineResult

Exceptions

OperationCanceledException

The token was canceled before input completed.

ReadAsync(CancellationToken)

Interactively manages a line of console input without blocking a thread while waiting for keys, and returns a result that describes the text and how the interaction ended.

public Task<ReadLineResult> ReadAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token that cancels the read. Cancellation raises an OperationCanceledException instead of producing a result, which is what distinguishes it from the user abandoning the line with Ctrl+C.

Returns

Task<ReadLineResult>

A task that produces the completed interaction result.

Remarks

This method performs the same interaction as Read and differs only in how it waits for each key. Each key behavior, auto-completion operation, and history operation runs synchronously on the thread that resumes the wait.

Exceptions

OperationCanceledException

The token was canceled before input completed.

ReadLine(CancellationToken)

Interactively manage the user input of a line of text at the console, returning the contents of the text when finished.

public string? ReadLine(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token that cancels the read.

Returns

string

The finished text; null if the user signaled the end of input; or an empty string if the user abandoned the line. Use Read to distinguish an abandoned line from an entered empty line.

Exceptions

OperationCanceledException

The token was canceled before input completed.

ReadLineAsync(CancellationToken)

Interactively manages a line of console input without blocking a thread while waiting for keys, returning the contents of the text when finished.

public Task<string?> ReadLineAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token that cancels the read.

Returns

Task<string>

The finished text; null if the user signaled the end of input; or an empty string if the user abandoned the line. Use ReadAsync to distinguish an abandoned line from an entered empty line.

Exceptions

OperationCanceledException

The token was canceled before input completed.