Expand description
Liso (LEE-soh) is an acronym for Line Input with Simultaneous Output. It is
a library for a particular kind of text-based Rust application; one where
the user is expected to give command input at a prompt, but output can
occur at any time. It provides simple line editing, and prevents input from
clashing with output. It can be used asynchronously (with tokio) or
synchronously (without).
Usage
Create an InputOutput object with
InputOutput::new(). Liso will automatically configure itself based on how
your program is being used.
Your InputOutput instance can be used to send output or receive input.
Call clone_output to create an OutputOnly
instance, which can only be used to send output. You can call
clone_output as many times as you like, as well as cloning the
OutputOnlys directly. An unlimited number of threads or tasks can send
output through Liso, but only one thread/task can receive user input:
whichever one currently holds the InputOutput instance.
Liso can work with Strings and &strs directly. If you want to add style
or color, create a Line, either manually or using
the convenient liso! macro. Send output to the
user by calling println() or
wrapln(), whichever you prefer. Any
styling and color information is reset after the line is output, so you
don’t have to worry about dangling attributes.
Liso supports a prompt line, which is presented ahead of the user input.
Use prompt() to set it. Styling and
color information is not reset between the prompt and the current input
text, so you can style/color the input text by having the desired
styles/colors active at the end of the prompt line.
Liso supports an optional status line, which “hangs out” above the input
text. Use status() to set it. Printed
text appears above the status line, the prompt and any in-progress input
appears below it. Use this to present contextual or frequently-changing
information.
Liso supports “notices”, temporary messages that appear in place of the
prompt and input for a limited time. Use
notice() to display one. The notice
will disappear when the allotted time elapses, when the user presses any
key, or when another notice is displayed, whichever happens first. 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.)
Pipe mode
If either stdin or stdout is not a tty, or the TERM environment
variable is set to either dumb or pipe, Liso enters “pipe mode”. In
this mode, status lines, notices, and prompts are not outputted, style
information is discarded, and every line of input is passed directly to
your program without any processing of control characters or escape
sequences. This means that a program using Liso will behave nicely when
used in a pipeline, or with a relatively unsophisticated terminal.
TERM=dumb is respected out of backwards compatibility with old UNIXes and
real terminals that identify this way. TERM=pipe is present as an
alternative for those who would rather not perpetuate an ableist slur, but
is not compatible with other UNIX utilities and conventions. On UNIX. you
can activate “pipe mode” without running afoul of any of this by piping the
output of the Liso-enabled program to cat, as in my_liso_program | cat.
Macros
Structs
Output::clone_output), but
only one thread at a time may have ownership of the overlying InputOutput
type and therefore the ability to receive input.liso! macro is extremely convenient for
building these. You can also pass a String, &str, or Cow<str> to
most Liso functions that accept a Line.Line, along with the byte index it begins at,
and the Style and Colors it would be displayed with. This is
yielded by LineCharIterator, which is
returned by Line::chars().Line,
one at a time, along with their Style and Color information.
This is returned by Line::chars().OutputOnly and
InputOutput structs have in common. Any method
of this struct may be called on either of the other structs.Enums
InputOutput methods: