ansiscreen(3)

NAME

Term::ANSIScreen - Terminal control using ANSI escape
sequences.

SYNOPSIS

# qw/:color/ is exported by default,  i.e.  color()  &
colored()
use  Term::ANSIScreen  qw/:color :cursor :screen :keyboard/;
print setmode(1), setkey('a','b');
print "40x25 mode now, with 'a' mapped to 'b'.";
<STDIN>; resetkey; setmode 3; cls;
locate 1, 1; print "@ This is (1,1)", savepos;
print locate(24,60), "@ This is (24,60)"; loadpos;
print down(2), clline, "@ This is (3,15)0;
color 'black on white'; clline;
print "This line is black on white.0;
print color 'reset'; print "This text is normal.0;
print  colored  ("This  text  is  bold  blue.0,  'bold
blue');
print "This text is normal.0;
print  colored  ['bold  blue'],  "This  text  is  bold
blue.0;
print "This text is normal.0;
use Term::ANSIScreen qw/:constants/; # constants mode
print BLUE ON GREEN . "Blue on green.0;
$Term::ANSIScreen::AUTORESET = 1;
print BOLD GREEN .  ON_BLUE  "Bold  green  on  blue.",
CLEAR;
print "0his text is normal.0;

DESCRIPTION

Term::ANSIScreen is a superset of Term::ANSIColor. In
addition to color-sequence generating subroutines exported
by ":color" and ":constants", this module also features
":cursor" for cursor positioning, ":screen" for screen
control, as well as ":keyboard" for key mapping.

NOTES
� All subroutines in Term::ANSIScreen will print its return value
if called under a void context.
� The cursor position, current color, screen mode and keyboard
map pings affected by Term::ANSIScreen will last after the pro
gram terminates. You might want to reset them before the end of
your program.

The ":color" function set (exported by default)

Term::ANSIScreen recognizes (case-insensitively) following color
attributes: clear, reset, bold, underline, underscore, blink, reverse, concealed, black, red, green, yellow, blue, magenta,
on_black, on_red, on_green, on_yellow, on_blue, on_magenta,
on_cyan, and on_white.
The color alone sets the foreground color, and on_color sets the
background color. You may also use on_color without the under
score, e.g. "black on white".
color LIST Takes any number of strings as arguments and considers
them to be space-separated lists of attributes. It then forms
and returns the escape sequence to set those attributes.
colored EXPR, LIST Takes a scalar as the first argument and any
number of attribute strings as the second argument, then returns
the scalar wrapped in escape codes so that the attributes will be
set as requested before the string and reset to normal after the
string.
Alternately, you can pass a reference to an array as the first
argument, and then the contents of that array will be taken as
attributes and color codes and the remainder of the arguments as
text to colorize.
Normally, this function just puts attribute codes at the begin
ning and end of the string, but if you set $Term::ANSIS
creen::EACHLINE to some string, that string will be considered
the line delimiter and the attribute will be set at the beginning
of each line of the passed string and reset at the end of each
line. This is often desirable if the output is being sent to a
program like a pager, which can be confused by attributes that
span lines.
Normally you'll want to set $Term::ANSIColor::EACHLINE to "0 to
use this feature.

The ":constants" function set

If you import ":constants" you can use the constants CLEAR, RESET, BOLD, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CONCEALED,
BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, ON_BLACK, ON_RED,
ON_GREEN, ON_YELLOW, ON_BLUE, ON_MAGENTA, ON_CYAN, and ON_WHITE
directly. These are the same as color('attribute') and can be
used if you prefer typing:
print BOLD BLUE ON_WHITE "Text0, RESET;
print BOLD BLUE ON WHITE "Text0, RESET; # _ is optional
to print colored ("Text0, 'bold blue on_white');
When using the constants, if you don't want to have to remember
to add the ", RESET" at the end of each print line, you can set
$Term::ANSIColor::AUTORESET to a true value. Then, the display
mode will automatically be reset if there is no comma after the
constant. In other words, with that variable set:
print BOLD BLUE "Text0;
will reset the display mode afterwards, whereas:
print BOLD, BLUE, "Text0;
will not.

The ":cursor" function set

locate [EXPR, EXPR] Sets the cursor position. The first argument
is its row number, and the second one its column number. If
omitted, the cursor will be located at (1,1).
up [EXPR] =item down [EXPR] =item left [EXPR] =item right
[EXPR] Moves the cursor toward any direction for EXPR characters.
If omitted, EXPR is 1.
savepos =item loadpos Saves/restores the current cursor position.

The ":screen" function set

cls Clears the screen with the current background color, and set
cur sor to (1,1).
clline Clears the current row with the current background color,
and set cursor to the 1st column.
setmode EXPR Sets the screen mode to EXPR. Under DOS, ANSI.SYS
recognizes fol lowing values:
0: 40 x 25 x 2 (text) 1: 40 x 25 x 16 (text)
2: 80 x 25 x 2 (text) 3: 80 x 25 x 16 (text)
4: 320 x 200 x 4 5: 320 x 200 x 2
6: 640 x 200 x 2 7: Enables line wrapping
13: 320 x 200 x 4 14: 640 x 200 x 16 15: 640 x 350 x 2 16: 640 x 350 x 16 17: 640 x 480 x 2 18: 640 x 480 x 16 19: 320 x 200 x 256
wrapon =item wrapoff Enables/disables the line-wraping mode.

The ":keyboard" function set

setkey EXPR, EXPR Takes a scalar representing a single keystroke
as the first argu ment (either a character or an escape sequence
in the form of "num1;num2"), and maps it to a string defined by
the second argu ment. Afterwards, when the user presses the
mapped key, the string will get outputed instead.
resetkey [LIST] Resets each keys in the argument list to its
original mapping. If called without an argument, resets all previously mapped keys.

DIAGNOSTICS

Invalid attribute name %s: You passed an invalid attribute name to either color() or colored().
Identifier %s used only once: possible typo: You probably mistyped a constant color name such as:

print FOOBAR "This text is color FOOBAR0;; It's probably better to always use commas after con
stant names in order to force the next error.
No comma allowed after filehandle: You probably mistyped a constant color name such as:

print FOOBAR, "This text is color FOOBAR0;; Generating this fatal compile error is one of the main
advantages of using the constants interface, since
you'll immediately know if you mistype a color name.
Bareword %s not allowed while "strict subs" in use: You probably mistyped a constant color name such as:

$Foobar = FOOBAR . "This line should be blue0;; or:

@Foobar = FOOBAR, "This line should be blue0;; This will only show up under use strict (another good
reason to run under use strict).

AUTHORS

Original idea (using constants) by Zenin (zenin@best.com),
reimplemented using subs by Russ Allbery (rra@stan
ford.edu), and then combined with the original idea by
Russ with input from Zenin to Term::ANSIColor. Screen mode
and keyboard mapping codes were added by Autrijus Tang,
along with revised code and documentation.

COPYRIGHT

Copyright 2001 by Autrijus Tang <autrijus@autrijus.org>. Based on works of Zenin (zenin@best.com),: Russ Allbery (rra@stanford.edu).

docs.sk

comprehensive documentation repository

Most Viewed