Struct Output

pub struct Output { /* private fields */ }

This struct contains all the methods that the OutputOnly and InputOutput structs have in common. Any method of this struct may be called on either of the other structs.

Implementations

impl Output

pub fn println<T>(&self, line: T)

where T: Into<Line>,

Prints a (possibly styled) line of regular output to the screen.

Note: As usual with Output methods, you can pass a Line, a plain String/&str, or a Cow<str> here. See also the liso! macro.

pub fn wrapln<T>(&self, line: T)

where T: Into<Line>,

Prints a (possibly styled) line of regular output to the screen, wrapping it to the width of the terminal. Only available with the “wrap” feature, which is enabled by default.

Note: As usual with Output methods, you can pass a Line, a plain String/&str, or a Cow<str> here. See also the liso! macro.

pub fn echoln<T>(&self, line: T)

where T: Into<Line>,

Prints a (possibly styled) line of regular output to the screen, but only if we are being run interactively. Use this if you want to to echo commands entered by the user, so that echoed commands will not gum up the output when we are outputting to a pipe.

Note: As usual with Output methods, you can pass a Line, a plain String/&str, or a Cow<str> here. See also the liso! macro.

pub fn status<T>(&self, line: Option<T>)

where T: Into<Line>,

Sets the status line to the given (possibly styled) text. This will be displayed above the prompt, but below printed output. (Does nothing in pipe mode.)

Note: status(Some("")) and status(None) will have different results! The former will display a blank status line, while the latter will display no status line.

Note: As usual with Output methods, you can pass a Line, a plain String/&str, or a Cow<str> here. See also the liso! macro.

pub fn remove_status(&self)

Removes the status line. This is equivalent to status(None) but without needing a turbofish.

pub fn notice<T>(&self, line: T, max_duration: Duration)

where T: Into<Line>,

Displays a (possibly styled) notice that temporarily replaces the prompt. The notice will disappear when the allotted time elapses, when the user presses any key, or when another notice is displayed, whichever happens first. (Does nothing in pipe mode.)

You should only use this in direct response to user input; in fact, the only legitimate use may be to complain about an unknown control character. (See Response for an example of this use.)

Note: As usual with Output methods, you can pass a Line, a plain String/&str, or a Cow<str> here. See also the liso! macro.

pub fn prompt<T>(&self, line: T, input_allowed: bool, clear_input: bool)

where T: Into<Line>,

Sets the prompt to the given (possibly styled) text. The prompt is displayed in front of the user’s input, unless we are running in pipe mode.

The default prompt is blank, with input allowed.

• input_allowed: True if the user should be allowed to write input.
• clear_input: True if any existing partial input should be cleared when the new prompt is displayed. (If input_allowed is false, this should probably be true.)

Note: If the prompt is styled, whatever style is active at the end of the prompt will be used when displaying the user’s input. This is the only circumstance in which Liso will not automatically reset style information for you at the end of a Line.

Note: When running in pipe mode, input is always allowed, there is no way to clear buffered input, and prompts are never displayed. In short, this function does nothing at all in pipe mode.

Note: As usual with Output methods, you can pass a Line, a plain String/&str, or a Cow<str> here. See also the liso! macro.

pub fn bell(&self)

Get the user’s attention with an audible or visible bell.

pub fn suspend_and_run<F: 'static + FnMut() + Send>(&self, f: F)

Use this when you need to perform some work that outputs directly to stdout/stderr and can’t run it through Liso. Prompt, status, and input in progress will be erased from the screen, and the terminal will be put back into normal mode. When the function returns, Liso will set up the terminal, display the prompt, and continue as normal.

Bear in mind that this will run in a separate thread, possibly after a short delay. If you need to return a value, wait for completion, or otherwise communicate with the main program, you should use the usual inter-thread communication primitives, such as channels or atomics.

Note that you cannot use this to create a subprocess that will read from stdin! Even though output is suspended, Liso will still be reading from stdin in another thread, and thus, will be competing with the subprocess for user input. (On sane UNIXes, this will result in your program being suspended by your shell, and then misbehaving when it resumes.) If you want to create a subprocess that can use stdin and stdout, you’ll have to write your own pipe handling based around Liso. If you want to create a subprocess that can interactively use the terminal—you have to drop the InputOutput instance, and all of the existing Output instances will go dead as a result. Just don’t do it!

pub fn clone_output(&self) -> OutputOnly

Make a new OutputOnly that can also output to the terminal. The clone and the original can be stored in separate places, even in different threads or tasks. All output will go to the same terminal, without any conflict between other threads doing output simultaneously or with user input.

For OutputOnly, this is the same as clone. For InputOutput, you must call this method instead, as this makes it clear that you are not trying to clone the Input half of that InputOutput.

pub fn send_custom<T: Any + Send>(&self, value: T)

Send the given value to the input thread, wrapped in a Response::Custom.

pub fn send_custom_box(&self, value: Box<dyn Any + Send>)

Send the given already-boxed value to the input thread, wrapped in a Response::Custom.

pub fn set_completor(&self, completor: Option<Box<dyn Completor>>)

Provide a new Completor for doing tab completion.