NAME

Terminal::Control - Perl extension with methods for the control of the terminal window

SYNOPSIS

use Terminal::Control;

clear_screen();
reset_screen();

($rows, $cols, $xpix, $ypix) = winsize();
($rows, $cols) = chars();
($xpix, $ypix) = pixels();

($row, $col) = get_cursor_position();
set_cursor_position($row, $col);

echo_on();
echo_off();

cursor_on();
cursor_off();   

window_size_chars([$timeout]);  
windows_size_pixels([$timeout]);
screen_size_chars([$timeout]); 
screen_size_pixels([$timeout]);

Variables in square brackets in the method call are optional. They are in the related method predefined.

DESCRIPTION

Module description

The module contains a collection of methods to control a terminal window. The basic methods are used to delete and reset a terminal window and to query the current window size.

Implemented methods

The following methods have been implemented so far within the module. The methods below are sorted according to their logical relationship.

• clear_screen()

• reset_screen()

• get_cursor_position()

• set_cursor_position($rows, $cols)

• winsize()

• chars()

• pixels()

• echo_on()

• echo_off()

• cursor_on()

• cursor_off()

• screen_size_chars($timeout)

• screen_size_pixels($timeout)

• window_size_chars($timeout)

• windows_size_pixels($timeout)

• ctlseqs_request($parameter, $timeout)

METHODS

clear_screen()

Clear the terminal window. The method is using Perls syswrite for printing ANSI escape sequences to STDOUT. The standard terminal window is STDOUT for the output of Perl. This command has the same effect like calling the Perl command system("clear").

reset_screen()

Reset the terminal window. The method is using Perls syswrite for printing ANSI escape sequences to STDOUT. The standard terminal window is STDOUT for the output of Perl. This command has the same effect like calling the Perl command system("reset").

echo_on

Turn the echo on. The method uses for the moment the Shell command stty for turning the echo of (user) input on.

echo_off

Turn the echo off. The method uses for the moment the Shell command stty for turning the echo of (user) input off.

Turn the echo off.

cursor_on

Turn the cursor on. The cursor is enabled by using ANSI escape sequences in the method.

cursor_off

Turn the cursor off. The cursor is disabled by using ANSI escape sequences in the method.

get_cursor_position()

Get the cursor position. The method gets the current cursor position in the terminal window.

set_cursor_position($row, $col)

Set the cursor position. The method gets the current cursor position in the terminal window.

window_size_chars([$timeout]);

windows_size_pixels([$timeout]);

screen_size_chars([$timeout]);

screen_size_pixels([$timeout]);

winsize()

Get the window size. The method gets the dimensions in x-direction and y-direction of the terminal. The methods chars and pixels extract chars (rows and cols) and pixels (xpix and ypix) from the winsize data. The method is using the C-header for the system call ioctl and the call or command TIOCGWINSZ. The call returns the winsize in rows and cols and xpix and ypix.

Variables in square brackets in the method call are optional. They are in the related method predefined.

EXAMPLES

# Clear the terminal window using ANSI escape sequences.
clear_screen();

# Reset the terminal window using ANSI escape sequences.
reset_screen();

# Get the window size calling ioctl and output the result on the screen.
my ($rows, $cols, $xpix, $ypix) = winsize();
printf ("%s\n%s\n%s\n%s\n", $rows, $cols, $xpix, $ypix);

# Get the chars from the window size and output the result on the screen.
($rows, $cols) = chars();
printf ("%s\n%s\n", $rows, $cols);

# Get the pixels from the window size and output the result on the screen.
($xpix, $ypix) = pixels();
printf ("%s\n%s\n", $xpix, $ypix);

# Get the cursor position in chars (not in pixels) using ANSI escape sequences.
my ($row, $col) = get_cursor_position();
printf ("%s\n%s\n", $row, $col);

# Set the cursor position in chars (not in pixels) using ANSI escape sequences.
my $row = 20; 
my $col = 80; 
# $row and $col are required and must be set by the user.
set_cursor_position($row, $col);

# Enable echoing of commands using stty. 
echo_on();

# Disable echoing of commands using stty. 
echo_off();

# Enable visibility of the cursor using ANSI escape sequences.
cursor_on();

# Disable visibility of the cursor using ANSI escape sequences.
cursor_off();

# Set the timeout for reading from STDIN in microseconds.
my $timeout = 1000000;
# Get the window and the screen size using XTERM control sequences.
# $timeout is optional. If not set 1000000 microseconds (1 second) are used.
window_size_chars($timeout);  
windows_size_pixels($timeout);
screen_size_chars($timeout); 
screen_size_pixels($timeout);

VARIABLES EXPLANATION

The x-direction is corresponding to window width and the y-direction is corresponding to window height.

$row     => Row (y-position) of terminal window as char position
$col     => Column (x-position) of terminal window as char position
$rows    => Rows (height) of terminal window as chars
$cols    => Columns (width) of terminal window as chars
$ypix    => Rows (y-direction or height) of terminal window as pixels
$xpix    => Coulumns (x-direction or width) of terminal window as pixels
$timeout => Timeout for reading from STDIN in microseconds

The predefined value of $timeout is 1000000 microseconds (1 second). The value of the parameter $timeout has to be given in microseconds.

NOTES

Development

The idea for the necessity of the module arises from the fact that especially the call of the Perl command system system("reset") of the Shell command reset is noticeably slow.

By using so-called ANSI escape sequences instead of calling a Shell command a significant acceleration can be achieved. The logical consequence is the programming of a Perl command that replaces the call of the Perl command system to reset the terminal window.

A single method is the best way to realise this for the terminal reset and several other commands. There is no need to implement a class with a bunch of methods to achive this.

Prove of concept

Exemplary comparison of time of execution:

system("reset")  =>  1.026892 Seconds = 1026,892 Milliseconds = 1026892 Microseconds

reset_screen()   =>  0.000076 Seconds =    0,076 Milliseconds = 76 Microseconds

Using reset on the command line and the Perl command system("reset") have nearly the same result in time of execution. Detailed comparison is outstanding. This one example already shows a significant advantage of the new routine.

Non-blocking behaviour

Reading from STDIN is blocking w.r.t. to the request of escape sequences, if no data are available. To overcome the problem of waiting endless for user input a timeout is programmed. Unfortunately, the programming implementation also slows down the processing when data is available in STDIN. If the standard value is not applicable, reduce the timeout step by step. If the timeout is to short the method is not able to catch the input from STDIN. A error code -1 is returned.

SYSTEM COMPATIBILITY

Three things must be fulfilled in order to use the full functionality of the module.

On operating systems that support ANSI escape sequences, individual methods will work out of the box. Some methods use the Shell command stty. The Shell command stty must be available accordingly. One method is using the system call ioctl, which is optional with respect to the functionality of the module. The restriction under Perl is explained further below.

The above requirements are fulfilled in principle by all Unix or Unix-like systems.

FUNCTIONALITY REQUIREMENT

The Perl header sys/ioctl.ph is required for the ioctl call of the function TIOCGWINSZ to get the window size. The equivalent C/C++ header is sys/ioctl.h. The Perl command h2ph converts .h C/C++ header files to .ph Perl header files.

In contrast to modules in general, the module installation process cannot be told to create a sys/ioctl.ph. This is necessary manually via the h2ph command.

To prevent tests within CPAN from failing due to a missing sys/ioctl.ph, a fallback solution based on the Shell command stty is implemented.

PORTABILITY

The module should work on Linux as well as Unix or Unix-like operating systems in general.

CONTROL SEQUENCES

ANSI escape sequences are widely known. Less well known are the so-called XTERM control sequences.

ANSI escape sequences

Escape sequences used by the module:

CSI n ; m H  =>  CUP      =>  Cursor Position       =>  Moves the cursor to row n, column m 
CSI 6n       =>  DSR      =>  Device Status Report  =>  Reports the cursor position (CPR)
                                                        by transmitting ESC[n;mR,
                                                        where n is the row and m is the column
CSI ? 25 h   =>  DECTCEM  =>  Shows the cursor
CSI ? 25 l   =>  DECTCEM  =>  Hides the cursor 

XTERM control sequences

Escape sequences used by the module:

CSI 1 4 t  =>  report window size in pixels
CSI 1 5 t  =>  report screen size in pixels
CSI 1 8 t  =>  report window size in chars
CSI 1 9 t  =>  report screen size in chars

METHOD ALIASES

clear_screen and reset_screen can also be used with this aliases:

reset_terminal  <=  reset_screen
clear_terminal  <=  clear_screen
reset           <=  reset_screen
clear           <=  clear_screen

KNOWN BUGS

It happens that in rare cases the CPAN test of the module gives several errors during compilation. The first error issued is actually an error. This error then obviously causes subsequent errors that are not actually errors. It is still unclear how the first real error can be permanently eliminated.

ABSTRACT

The module is intended for Linux as well as Unix or Unix-like operating systems in general. These operating systems meet the requirements for using the module and its methods. The module contains, among others, two methods for clearing and resetting the terminal window. This is a standard task when scripts has to be executed in the terminal window. The related Shell commands are slow in comparison to the implemented methods in this module. This is achieved by using ANSI escape sequences. In addition XTERM control sequences can be used to query screen and window size. The terminal or window size is in general available via the system call ioctl.

SEE ALSO

ANSI escape sequences

XTERM control sequences

stty(1) - Linux manual page

termios(3) — Linux manual page

ioctl_tty(2) — Linux manual page

AUTHOR

Dr. Peter Netz, <ztenretep@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2022 by Dr. Peter Netz

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

cpanm Terminal::Control

perl -MCPAN -e shell
install Terminal::Control