Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::Pager(3)	      User Contributed Perl Documentation	  IO::Pager(3)

NAME
       IO::Pager - Select a pager (possibly perl-based)	& pipe it text if a
       TTY

SYNOPSIS
	 # Select an appropriate pager and set the PAGER environment variable
	 use IO::Pager;

	 # TIMTOWTDI Object-oriented
	 {
	   # open()			      #	Use all	the defaults.
	   my $object =	new IO::Pager;

	   # open FILEHANDLE		      #	Unbuffered is default subclass
	   my $object =	new IO::Pager *STDOUT;

	   # open FILEHANDLE,EXPR	      #	Specify	subclass
	   my $object =	new IO::Pager *STDOUT,	'Unbuffered';

	   # Direct subclass instantiation    #	FH is optional
	   use IO::Pager::Unbuffered;
	   my $object =	new IO::Pager::Unbuffered  *STDOUT;

	   $object->print("OO shiny...\n") while 1;
	   print "Some other text sent to STODUT, perhaps from a foreign routine."

	   # $object passes out	of scope and filehandle	is automagically closed
	 }

	 # TIMTOWTDI Procedural
	 {
	   # open FILEHANDLE			# Unbuffered is	default	subclass
	   my $token = IO::Pager::open *STDOUT;

	   # open FILEHANDLE,EXPR		# Specify subclass
	   my $token = IO::Pager::open *STDOUT,	 'Unbuffered';

	   # open FILEHANDLE,MODE,EXPR		# En lieu of a separate	binmode()
	   my $token = IO::Pager::open *STDOUT,	'|-:utf8', 'Unbuffered';

	   print <<"  HEREDOC" ;
	   ...
	   A bunch of text later
	   HEREDOC

	   # $token passes out of scope	and filehandle is automagically	closed
	 }

	 {
	   # You can also use scalar filehandles...
	   my $token = IO::Pager::open(my $FH) or warn($!); XXX
	   print $FH "No globs or barewords for	us thanks!\n" while 1;
	 }

DESCRIPTION
       IO::Pager can be	used to	locate an available pager and set the PAGER
       environment variable (see "NOTES"). It is also a	factory	for creating
       I/O objects such	as IO::Pager::Buffered and IO::Pager::Unbuffered.

       IO::Pager subclasses are	designed to programmatically decide whether or
       not to pipe a filehandle's output to a program specified	in PAGER.
       Subclasses may implement	only the IO handle methods desired and inherit
       the remainder of	those outlined below from IO::Pager. For anything
       else, YMMV. See the appropriate subclass	for implementation specific
       details.

METHODS
   new(	FILEHANDLE, [MODE], [SUBCLASS] )
       Almost identical	to open, except	that you will get an IO::Handle	back
       if there's no TTY to allow for IO::Pager-agnostic programming.

   open( FILEHANDLE, [MODE], [SUBCLASS]	)
       Instantiate a new IO::Pager, which will paginate	output sent to
       FILEHANDLE if interacting with a	TTY.

       Save the	return value to	check for errors, use as an object, or for
       implict close of	OO handles when	the variable passes out	of scope.

       FILEHANDLE
	   You may provide a glob or scalar.

	   Defaults to currently select()-ed FILEHANDLE.

       SUBCLASS
	   Specifies which variety of IO::Pager	to create.  This accepts fully
	   qualified packages IO::Pager::Buffered, or simply the third portion
	   of the package name Buffered	for brevity.

	   Defaults to IO::Pager::Unbuffered.

	   Returns false and sets $! on	failure, same as perl's	"open".

   PID
       Call this method	on the token returned by "open"	to get the process
       identifier for the child	process	i.e; pager; if you need	to perform
       some long term process management e.g; perl's "waitpid"

       You can also access the PID by numifying	the instantiation token	like
       so:

	 my $child = $token+0;

   close( FILEHANDLE )
       Explicitly close	the filehandle,	this stops any redirection of output
       on FILEHANDLE that may have been	warranted.

       This does not default to	the current filehandle.

       Alternatively, you may rely upon	the implicit close of lexical handles
       as they pass out	of scope e.g;

	 {
	    IO::Pager::open local *RIBBIT;
	    print RIBBIT "No toad sexing allowed";
	    ...
	 }
	 #The filehandle is closed to additional output

	 {
	    my $token =	new IO::Pager::Buffered;
	    $token->print("I like trains");
	    ...
	 }
	 #The string "I	like trains" is	flushed	to the pager, and the handle closed

   binmode( FILEHANDLE,	[LAYER]	)
       Used to set the I/O layer a.k.a.	discipline of a	filehandle, such as
       ':utf8' for UTF-8 encoding.

       :LOG([__FILE])

       IO::Pager implements a pseudo-IO-layer for capturing output and sending
       it to a file, similar to	tee(1).	Although it is limited to one file,
       this feature is pure-perl and adds no dependencies.

       You may indicate	what file to store in parentheses, otherwise the
       default is "$$.log". You	may also use an	implicit (no indicator)	or
       explicit	(_) indicator to overwrite an existing file, or	an explicit
       (__) for	appending to a log file. For example:

	   binmode(*STDOUT, ':LOG(clobber.log)');
	   ...
	   $STDOUT->binmode(':LOG(>>noclobber.log)');

       For full	tee-style support, use PerlIO::Util like so:

	   binmode(*STDOUT, ":tee(TH)");
	   #OR
	   $STDOUT->binmode(':tee(TH)');

   eof(	FILEHANDLE )
       Used in the eval-until-eof idiom	below, IO::Pager will handle broken
       pipes from deceased children for	you in one of two ways.	If
       $ENV{IP_EOF} is false then program flow will pass out of	the loop on
       SIGPIPE,	this is	the default. If	the variable is	true, then the program
       continues running with output for the previously	paged filehandle
       directed	to the STDOUT stream; more accurately, the filehandle is
       reopened	to file	descriptor 1.

	 use IO::Pager::Page; #or whichever you	prefer;
	 ...
	 eval{
	   say "Producing prodigious portions of product";
	   ...
	 } until( eof(*STDOUT) );
	 print "Cleaning up after our child before terminating."

       If using	eof() with less, especially when IP_EOF	is set,	you may	want
       to use the --no-init option by setting $ENV{IP_EOF}='X' to prevent the
       paged output from being erased when the pager exits.

   fileno( FILEHANDLE )
       Return the filehandle number of the write-only pipe to the pager.

   print( FILEHANDLE LIST )
       print() to the filehandle.

   printf( FILEHANDLE FORMAT, LIST )
       printf()	to the filehandle.

   syswrite( FILEHANDLE, SCALAR, [LENGTH], [OFFSET] )
       syswrite() to the filehandle.

ENVIRONMENT
       IP_EOF
	   Controls IO:Pager behavior when "eof" is used.

       PAGER
	   The location	of the default pager.

       PATH
	   If the location in PAGER is not absolute, PATH may be searched.

	   See "NOTES" for more	information.

FILES
       IO::Pager may fall back to these	binaries in order if PAGER is not
       executable.

       /etc/alternatives/pager
       /usr/local/bin/less
       /usr/bin/less
       IO::Pager::Perl as "tp" via IO::Pager::less
       /usr/bin/more

       See "NOTES" for more information.

NOTES
       The algorithm for determining which pager to use	is as follows:

       1. Defer	to PAGER
	   If the PAGER	environment variable is	set, use the pager it
	   identifies, unless this pager is not	available.

       2. Usual	suspects
	   Try the standard, hardcoded paths in	"FILES".

       3. File::Which
	   If File::Which is available,	use the	first pager possible amongst
	   "less", "most", "w3m", "lv",	"pg" and more.

       4. Term::Pager via IO::Pager::Perl
	   You may also	set $ENV{PAGER}	to Term::Pager to select this
	   extensible, pure perl pager for display.

       5. more
	   Set PAGER to	"more",	and cross our fingers.

       Steps 1,	3 and 5	rely upon the PATH environment variable.

CAVEATS
       You probably want to do something with SIGPIPE eg;

	 eval {
	   local $SIG{PIPE} = sub { die	};
	   local $STDOUT = IO::Pager::open(*STDOUT);

	   while (1) {
	     # Do something
	   }
	 }

	 # Do something	else

SEE ALSO
       IO::Pager::Buffered, IO::Pager::Unbuffered, I::Pager::Perl,
       IO::Pager::Page,	IO::Page, Meta::Tool::Less

AUTHOR
       Jerrad Pierce <jpierce@cpan.org>

       Florent Angly <florent.angly@gmail.com>

       This module was inspired	by Monte Mitzelfelt's IO::Page 0.02

COPYRIGHT AND LICENSE
       Copyright (C) 2003-2020 Jerrad Pierce

       o   Thou	shalt not claim	ownership of unmodified	materials.

       o   Thou	shalt not claim	whole ownership	of modified materials.

       o   Thou	shalt grant the	indemnity of the provider of materials.

       o   Thou	shalt use and dispense freely without other restrictions.

       Or, if you prefer:

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.0 or,	at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.0			  2020-06-13			  IO::Pager(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | ENVIRONMENT | FILES | NOTES | CAVEATS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Pager&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help