command line interface - description of Pager.pm

JT::CLI::Pager - The module provides methods to page string arrays or files. The user can navigate between the pages and search for regular expressions.

  use JT::CLI::Pager;

  # page a file
  my $fpager = JT::CLI::Pager->new('/some/file/name');
  $fpager->page_size(48); # 24 per default
  $fpager->line_size(60); # 75 per default
  $fpager->run();

  # page another file
  $fpager->file_name('/some/other/file/name');
  $fpager->run();

  # page an array
  my $apager = JT::CLI::Pager->new();
  my @lines = ('first', 'second', 'third', ...);
  $apager->run(\@lines);

This documentation describes version 0.2 of JT::CLI::Pager.

The module provides an object oriented interface to display a list of data page per page. The user can page up and down through the list, got to the end or to the beginning or to a defined page. A pattern search up- and downwards is also possible. The data source can be an array or a file. Input read from a file is formatted to a defined line size.

There are no terminal specific properties in use, the pager should do his work on every terminal, even if you are connected via Telnet or SSH. No control keys are used, only an ordinary keyboard with alphanumeric keys is requested.

new([fileName])
Creates a new Pager instance. If a file name is given this file is displayed when calling the run([arrayRef]) method until another file name is set or an array reference is used when running the pager.

During initialization the page size is set to 24 lines per page and the line size is set to 75 characters per line.

file_name([fileName])
Sets a new file name to display. Returns the file name or undef if the file name is not set or the file does not exist or is not readable.

page_size([pageSize])
Sets the page size (lines per page). The value must be an integer greater than zero. The actual page size is returned.

line_size([lineSize])
Sets the line size (characters per line). The value must be an integer greater than or equal to 40. The actual line size is returned. The line size ist ignored if the run([arrayRef]) method is called with an array. In this case the caller is responsible for the line size.

label([aLabel])
Sets the label that is displayed on top of each page. Returns the label or undef if the label is not set. If no label is set the file name or (if displaying an array) "--UNDEF--" is printed on top of page.

run([arrayRef])
Displays the pages of the file or the array. If neither array nor file are set or if the file could not be read the module dies.

On top of each page the label is displayed as described above. At the bottom a control line is displayed with information about the actual page number and the keys to move forward and backwards and to start a search.

The lines are formatted using the line_size property if a file is displayed. The page_size property defines the number of lines diplayed at once.

The following keys are accepted to control the Pager:

+
Move one page forward

-
Move one page backwards

0
Move to the first page

$
Move to the last page

page number
Move to the requested page

/pattern
Search forward for the pattern, subsequent / inputs search for the same pattern down to the end.

?pattern
Search backwards for the pattern, subsequent / inputs search for the same pattern up to the beginning.

q
Exits the run method.

No known bugs. If you find a bug, please contact me and send me a detailed bug report.