/ 
Log-Progress-0.13
River stage zero No dependents
/ Log::Progress::RenderTTY

NAME

Log::Progress::RenderTTY - Render progress state on a terminal

SYNOPSIS

use Log::Progress::Parser;
use Log::Progress::RenderTTY;
my $p= Log::Progress::Parser->new( ... );
my $r= Log::Progress::RenderTTY->new( parser => $p );
while (sleep .5) {
  $r->render;  # calls $p->parse and renders result
}

DESCRIPTION

This module takes the state data parsed by Log::Progress::Parser and renders it to a terminal as a progress bar, or multiple progress bars if sub-steps are found.

Your terminal must be supported by Term::Cap, and you must have a stty command on your system for the progress bar to display correctly.

ATTRIBUTES

parser

Reference to a Log::Progress::Parser, whose state should be rendered.

tty_metrics

Stores the dimensions and baud rate of the current terminal. It fetched this information by shelling out to stty -a, which should work on most unix flavors.

termcap

Reference to a Term::Cap object that is used for generating TTY escape sequences.

listen_resize

The way to listen to screen resizes on Linux is to trap SIGWINCH and re-load the terminal dimensions. The problem is that you can only have one $SIG{WINCH}, so things get messy when multiple objects try to watch for changes.

If you want this instance of RenderTTY to set a signal handler for SIGWINCH, set this attribute to a true value during the constrctor. It is read-only after the object is created.

Otherwise, you can set up the signal handler yourself, using whatever framework you happen to be using:

use AnyEvent;
my $sig= AE::signal WINCH => sub { $renderer->clear_tty_metrics; };

out

File handle on which the progress bar will be rendered.

METHODS

format

$text= $renderer->format( \%state, \%dimensions );

Format progress state (from Log::Progress::Parser) as plain multi-line text. The dimensions are used to size the text to the viewport, and also store additional derived measurements.

Returns a plain-text string. The lines of text are then re-parsed by the "render" method to apply the necessary terminal cursor escapes.

render

$renderer->render

Call ->parser->parse, format the parser's state as text, then print terminal escape sequences to display the text with minimal overwriting.

This method goes to some additional effort to make sure the scrollback buffer stays readable in the case where your sub-steps exceed the rows of the terminal window.

Note that this method can trigger various terminal-related exceptions since it might be the first thing that lazy-initializes the "tty_metrics" or "termcap" attributes.

AUTHOR

Michael Conrad <mike@nrdvana.net>

VERSION

version 0.13

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.