NAME

Term::Scroller - Display text in a scrolling viewport in your terminal

SYNOPSIS

    use Term::Scroller;
    
    # Default options
    my $scroll = Term::Scroller->new();
    print $scroll "blah blah blah\n" for (1..100);
    # You should always call the end() method when you're done
    $scroll->end();

    # Some more options (limited window size, with a border)
    $scroll = scroller(width => 40, height => 5, window => '-#-#-#-#');
    print $scroll "beee daah booo\n" for (1..100);
    $scroll->end();

    # See the rest of the documentation for more options!

DESCRIPTION

Term::Scroller provides you with a way to view a large stream of text inside a small, scrolling viewport on your terminal. The size and borders of the viewport/window can be customized along with a number of other control options.

For a command-line program that uses this to display the output of commands see scroller.

Methods

new

Returns a new scroller instance. The scroller is a filehandle (actually an instance of IO::Pty) where anything written to it is displayed in the scrolling window. The scroller will sanitize any cursor-related ANSI escape sequences so text that expects them to work might look garbled, but at least it should be very difficult to escape or break the window. color-related ANSI sequences are left untouched though so colored text will still work inside the window.

Don't forget to call the 'end' method when you're done with it!

The arguments to scroller are interpreted as a hash and can contain the following options:

Size & Styling Options

• height

  Integer representing the maximum height (in lines) of the viewport. The window will grow as more lines of input come in and start scrolling once it reaches this height. (Default: 10)

• width

  Integer representing the maximum width (in columns) of the viewport. Input lines will truncated at this width, not including ANSI escape sequences. (Default: the width of the connected terminal, or 80 if the width couldn't be determined for some reason).

• tabwidth

  Integer representing the width of tabs (in characters) when viewed in the viewport. For consistent printing, tabs are replaced with this number of spaces. (Default: 4)

• style

  A string representing an ANSI color escape sequence used to style the text displayed inside the window. If this is set, it will override any color escape sequences in the input text. This can be a raw escape sequence (e.g "\033[2m" for faded text) or a constant from the Term::ANSIColor module. (Default: undef).

• window

  A string specifying the characters to use when drawing a border around the window. See the WINDOW DRAWING section for how to create a border specification. The documentation for scroller also has some examples you can copy from. (Default: undef, so no borders, if only we could live in such a world)

Control Options

• out

  Filehandle to write/draw the window to. Naturally, this should be connected to a terminal. (Default: the currently selected filehandle, so STDOUT unless you selected something else first).

• hide

  If true, the window will be erased once its done (i.e. once you close the input filehandle). Otherwise, the window remains with the last lines of text still visible. (Default: False).

• passthrough

  If this is an open filehandle, input text will also be passed through to this filehandle completely unaltered. Useful if you want a record of all the text that went through the window.

pid

Every scroller instance uses a forked child process that reads the psuedoterminal and draws the window to the terminal. This method returns the pid of an instance's associated fork.

end

This is the preferred way to stop using a scroller. Simply closing the filehandle will immediately destroy the allocated pty which means any text that the window hasn't drawn yet will be lost. This method will safely wait for the child process to catch up before closing by sending an explicit EOF to the pty, waiting on the child process and then finally closing the filehandle. Returns the exit status of the instance's child process.

WINDOW DRAWING

A window specification is a string up to 8 characters long indicating which character to use for a part of the window, in clockwise order. That is, the characters specify the top side, top-right corner, right side, bottom-right corner, bottom side, bottom-left corner, left side and top-left corner respectively. If any character is a whitespace or is missing (due to the string not being long enough), then that part of the window will not be drawn.

SEE ALSO

scroller

AUTHOR

Cameron Tauxe camerontauxe@gmail.com

LICENSE AND COPYRIGHT

This software is copyright (c) 2020 by Cameron Tauxe.

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