File Coverage

blib/lib/Term/Output/List.pm

Criterion	Covered	Total	%
statement	22	27	81.4
branch	2	6	33.3
condition			n/a
subroutine	5	5	100.0
pod	1	2	50.0
total	30	40	75.0

package Term::Output::List;
use 5.020;
use experimental 'signatures';

use Module::Load 'load';

our $VERSION = '0.06';

=head1 NAME

Term::Output::List - output an updateable list of ongoing jobs

=head1 SYNOPSIS

    my $printer = Term::Output::List->new(
        hook_warnings => 1,
	ellipsis => "\N{HORIZONTAL ELLIPSIS}",
    );
    my @ongoing_tasks = ('file1: frobnicating', 'file2: bamboozling', 'file3: frobnicating');
    $printer->output_list(@ongoing_tasks);

    $printer->output_permanent("Frobnicated gizmos"); # appears above the list

=cut

sub detect_terminal_type($os = $^O) {
	if( $os eq 'MSWin32' ) {
		require Win32::Console;
		if( Win32::Console->Mode & 0x0004 ) { #ENABLE_VIRTUAL_TERMINAL_PROCESSING
			return 'ansi';
		} else {
			return 'win32'
		}
	} else {
		return 'ansi';
	}
}

sub new($class,%args) {
	my $ttype = detect_terminal_type();

	my $impl = 'Term::Output::List::ANSI';
	if( $ttype eq 'win32' ) {
	    $impl = 'Term::Output::List::Win32';
	}
	load $impl;
	return $impl->new( %args )
}

=head1 METHODS

=head2 C<< Term::Output::List->new() >>

=over 4

=item C<< fh >>

Filehandle used for output. Default is C<< STDOUT >>.

=item C<< interactive >>

Whether the script is run interactively and should output intermittent
updateable information

=item C<< hook_warnings >>

Install a hook for sending warnings to C<< ->output_permanent >>. This
prevents ugly tearing/overwriting when your code outputs warnings.

=back

=head2 C<< ->scroll_up >>

Helper method to place the cursor at the top of the updateable list.

=head2 C<< ->output_permanent >>

  $o->output_permanent("Frobnicated 3 items for job 2");
  $o->output_list("Frobnicating 9 items for job 1",
                  "Frobnicating 2 items for job 3",
  );
  $o->output_permanent("Frobnicated 3 items for job 2");

Outputs items that should go on the permanent record. It is expected to
output the (remaining) list of ongoing jobs after that.

=head2 C<< ->output_list @items >>

  $o->output_list("Frobnicating 9 items for job 1",
                  "Frobnicating 2 items for job 3",
  );

Outputs items that can be updated later, as long as no intervening output
(like from C, C or C) has happened. If you want to output
lines that should not be overwritten later, see C<output_permanent>>

=head2 C<< ->fresh_output >>

  $o->fresh_output();

Helper subroutine to make all items from the last output list remain as is.

For compatibility between output to a terminal and output without a terminal,
you should use C<< ->output_permanent >> for things that should be permanent
instead.

=cut

1;