/ 
Terminal-Control-0.07
River stage zero No dependents
/ Terminal::Control

NAME

Terminal::Control - Perl extension for the terminal window control

SYNOPSIS

use Terminal::Control;

# Clear screen using escape sequences.
clear_screen();

# Reset screen using escape sequences.
reset_screen();

# Get terminal 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 chars from terminal size and output the result on the screen.
($rows, $cols) = chars();
# Print chars.
printf ("%s\n%s\n", $rows, $cols);

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

# Get the cursor position using escape sequences.
my ($y, $x) = get_cursor_position();
printf ("%s\n%s\n", $y, $x);

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

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

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

# Enable cursor using escape sequences.
cursor_on();

# Disable cursor using escape sequences.
cursor_off();

# Set timeout in microseconds.
my $timeout = 1000000;
# Get window and screen size using escape sequences.
window_size_chars($timeout);   # $timeout is optional. if not set 1000000 microseconds (1 second) is used.
windows_size_pixels($timeout); # $timeout is optional. if not set 1000000 microseconds (1 second) is used 
screen_size_chars($timeout);   # $timeout is optional. if not set 1000000 microseconds (1 second) is used 
screen_size_pixels($timeout);  # $timeout is optional. if not set 1000000 microseconds (1 second) is used

Motivation for 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. Detailed comparison is outstanding. This one example already shows a significant advantage of the new routine.

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.

Requirement for Full Functionality

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.

ANSI escape sequences versus XTERM control sequences

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

DESCRIPTION

Implemented Methods

The methods below are sorted according to their logical relationship.

The following methods have been implemented so far within the module:

  • 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)

Reading from STDIN is blocking, 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.

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

Method description

The method clear_screen is clearing the terminal. This is similar to the Perl system command call system("clear"). The method reset_screen is reseting the terminal. This is similar to the Perl system command call system("reset").

The method winsize() 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.)

The method get_cursor_position() gets the current cursor position in the terminal window. The method set_cursor_position() sets the cursor position in the terminal window.

echo_on() and echo_off() turnes echo of commands on or off.cursor_on() and cursor_off shows or hides the cursor.

Programmable background

The methods clear_screen() and reset_screen() are using ANSI escape sequences. Doing this no other Perl commands are needed to clear and reset a screen.

The method winsize() is using the C/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.

SEE ALSO

ANSI escape sequences

XTERM control sequences

stty(1) - 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.