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


version 0.12


  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


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.



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


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.


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


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; };


File handle on which the progress bar will be rendered.



  $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.



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.


Michael Conrad <>


This software is copyright (c) 2020 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.