Struct Live 

pub struct Live<W: Write> { /* private fields */ }

An in-place updating display over a renderable. Mirrors rich.live.Live. Output is written to a generic sink W, so it can target stdout or, in tests, a byte buffer.

A display started while another runs on its console or a clone of it is nested, as upstream’s: it draws nothing itself, and the first display draws its renderable below its own. A refresh of a nested display draws the first display’s frame to the nested display’s sink, so displays that nest should write to one terminal.

Implementations

impl<W: Write> Live<W>

pub fn new(renderable: Box<dyn Renderable>, console: Console, writer: W) -> Self

Create a live display for renderable, rendering with console and writing control/output bytes to writer.

pub fn get_renderable( self, get: impl Fn() -> Box<dyn Renderable> + 'static, ) -> Self

Take the renderable from get at every refresh instead (upstream’s get_renderable), as a Progress builds its task table afresh for each frame. What a print draws below itself is the renderable of the last refresh, as upstream.

pub fn options(self, options: &LiveOptions) -> Self

Apply every option but LiveOptions::refresh_on_start.

pub fn transient(self, transient: bool) -> Self

Clear the display when it stops (upstream transient): the final frame is drawn, then erased and the cursor put back where it started.

pub fn screen(self, screen: bool) -> Self

Show the display on the alternate screen (upstream screen), filling it as upstream’s Screen does. Like upstream, a screen display is always transient, and it needs a terminal.

pub fn redirect_stdout(self, redirect: bool) -> Self

Print what is written to stdout through the display while it runs on a terminal (upstream redirect_stdout, default true). When off, the proxy writes straight to its file.

pub fn redirect_stderr(self, redirect: bool) -> Self

The same for stderr (upstream redirect_stderr).

pub fn vertical_overflow(self, vertical_overflow: VerticalOverflow) -> Self

What to do with a frame taller than the screen (upstream vertical_overflow, default VerticalOverflow::Ellipsis). The final frame drawn by stop is always shown in full.

pub fn is_started(&self) -> bool

Whether the display has been started and not yet stopped. Port of Live.is_started.

pub fn console(&self) -> &Console

The console the display renders with. Port of Live.console.

pub fn start(&mut self)

Begin the live display: hide the cursor and draw the first frame. Upstream’s start(refresh=True), as with Live(renderable): does.

pub fn start_with(&mut self, refresh: bool)

Begin the live display, drawing the first frame only when refresh is set. Port of Live.start(refresh); a display started without a refresh is first drawn by the next refresh, update or stop.

pub fn update(&mut self, renderable: Box<dyn Renderable>)

Swap in a new renderable and redraw in place. Upstream’s update(renderable, refresh=True).

pub fn update_with(&mut self, renderable: Box<dyn Renderable>, refresh: bool)

Swap in a new renderable, redrawing only when refresh is set. Port of Live.update(renderable, refresh): the display takes it at the next refresh, so a print before then still draws the old one below it.

pub fn refresh(&mut self)

Redraw the current renderable in place. Port of Live.refresh: on an interactive terminal the cursor goes back over the last frame (or home, on the alternate screen) and the frame is drawn; elsewhere only the final frame of a stopped, non-transient display is written. The first display on the console’s stack draws every display’s renderable (upstream’s Live.renderable), and a nested display redraws it.

pub fn print(&mut self, renderable: &dyn Renderable)

Print renderable above the display, as console.print does while upstream’s Live is running (its render hook): the display is erased, the output printed, and the display drawn again below it.

pub fn print_str(&mut self, content: &str)

print a string as console markup, as upstream’s console.print("...").

pub fn log( &mut self, objects: &[LogObject<'_>], options: &LogOptions<'_>, ) -> Result<()>

Log objects above the display, as console.log does while upstream’s Live is running (through its render hook). Port of the log upstream’s Progress binds to its console: the time, the message and the caller found with #[track_caller] (DIVERGENCES §47).

pub fn log_at( &mut self, objects: &[LogObject<'_>], options: &LogOptions<'_>, file: &str, line: u32, ) -> Result<()>

log with the caller’s file and line given (Console::log_at).

pub fn stop(&mut self)

Commit the final frame (with a trailing newline) and show the cursor. Port of Live.stop; the alternate screen is switched off rather than drawn again.

pub fn stdout(&mut self) -> FileProxy<&mut Self, Stdout>

A writer standing in for stdout while the display runs (upstream’s sys.stdout replaced by a FileProxy): whole lines print above the display; when not redirecting, writes go to the process’s stdout.

pub fn stderr(&mut self) -> FileProxy<&mut Self, Stderr>

stdout for stderr (upstream’s sys.stderr proxy).

pub fn file_proxy<F: Write>( &mut self, stream: ProxyStream, file: F, ) -> FileProxy<&mut Self, F>

A proxy for stream over any file, which receives the writes when the display is not redirecting.

pub fn writer(&self) -> &W

The output sink (for inspecting captured bytes in tests).

pub fn into_writer(self) -> W

Consume the display, returning its output sink.

impl<W: Write + Send + 'static> Live<W>

pub fn spawn( renderable: Box<dyn Renderable + Send>, console: Console, writer: W, refresh_per_second: f64, ) -> AutoLive<W>

Start an auto-refreshing live display on a background thread: it draws the first frame, then redraws every 1/refresh_per_second seconds (and immediately on each AutoLive::update). Mirrors upstream’s auto_refresh/refresh_per_second. The renderable, console, and writer are moved into the thread, so all three must be Send.

pub fn spawn_with( renderable: Box<dyn Renderable + Send>, console: Console, writer: W, refresh_per_second: f64, transient: bool, ) -> AutoLive<W>

spawn, clearing the display when it stops when transient is set (upstream Live(transient=True)).

pub fn spawn_options( renderable: Box<dyn Renderable + Send>, console: Console, writer: W, refresh_per_second: f64, options: LiveOptions, ) -> AutoLive<W>

spawn with every option of upstream’s Live(...).

pub fn spawn_get_renderable( get: impl Fn() -> Box<dyn Renderable> + Send + 'static, console: Console, writer: W, refresh_per_second: f64, options: LiveOptions, ) -> AutoLive<W>

spawn_options over upstream’s get_renderable: get is called on the refresh thread for a fresh renderable at every refresh (Live::get_renderable).

Trait Implementations

impl<W: Write> ProxyTarget for &mut Live<W>

fn proxy_write(&mut self, stream: ProxyStream, bytes: &[u8]) -> bool

Upstream’s FileProxy.write: buffer bytes and print every completed line through the display.

fn proxy_flush(&mut self, stream: ProxyStream) -> bool

Upstream’s FileProxy.flush: print a buffered partial line.