NAME¶
Term::VT102 - a class to emulate a DEC VT102 terminal
SYNOPSIS¶
use Term::VT102;
my $vt = Term::VT102->new ('cols' => 80, 'rows' => 24);
while (<>) { $vt->process ($_); }
DESCRIPTION¶
The VT102 class provides emulation of most of the functions of a DEC VT102
terminal. Once initialised, data passed to a VT102 object is processed and the
in-memory "screen" modified accordingly. This "screen" can
be interrogated by the external program in a variety of ways.
This allows your program to interface with full-screen console programs by
running them in a subprocess and passing their output to a VT102 class. You
can then see what the application has written on the screen by querying the
class appropriately.
OPTIONS¶
Setting
cols or
rows in the
new() hash
allows you to change the size of the terminal being emulated. If you do not
specify a size, the default is 80 columns by 24 rows.
After initialisation, you can read and set the following terminal options using
the
option_read() and
option_set() methods:
LINEWRAP line wrapping; 1=on, 0=off. Default is OFF.
LFTOCRLF treat LF (\n) as CRLF (\r\n); 1=on, 0=off. Default OFF.
IGNOREXOFF ignore XON/XOFF characters; 1=on (ignore). Default ON.
METHODS¶
The following methods are provided:
- attr_pack
($fg,$bg
,$bo,
$fa,$st,$ul,$bl,$rv)
- Returns the packed version of the given attribute settings,
which are given in the same order as returned by attr_unpack. The
packed version will be a binary string not longer than 2 bytes.
- attr_unpack ($data)
- Returns a list of the contents of the given packed
attribute settings, of the form (
$fg,$bg
,$bo,
$fa,$st
,$ul,
$bl,$rv ).
$fg and $bg are the ANSI
foreground and background text colours, and $bo,
$fa, $st,
$ul, $bl, and
$rv are flags (1 = on, 0 = off) for bold, faint,
standout, underline, blink and reverse respectively.
- callback_call ($name,
$par1, $par2)
- Calls the callback $name (eg
'ROWCHANGE') with parameters $par1 and
$par2, as if the VT102 module had called it. Does
nothing if that callback has not been set with callback_set
().
- callback_set ($callback,
$ref, $private)
- Sets the callback callback to function reference
ref with private data $private.
See the section on CALLBACKS below.
- new (%config)
- Returns a new VT102 object with options specified in
%config (see the OPTIONS section for
details).
- option_read ($option)
- Returns the current value of terminal option
$option (see OPTIONS for details), or
undef if that option does not exist. Note that you cannot read the
terminal size with this call; use size() for
that.
- option_set ($option,
$value )
- Sets the current value of terminal option
$option to $value, returning
the old value or undef if no such terminal option exists or you
have specified an undefined $value. Note that you
cannot resize the terminal with this call; use
resize() for that.
- process ($string)
- Processes the string $string (which
can be zero-length), updating the VT102 object accordingly and calling any
necessary callbacks on the way.
- resize ($cols,
$rows )
- Resizes the VT102 terminal to cols columns by
rows rows, eg $vt->resize (80, 24).
The virtual screen is cleared first.
- reset ()
- Resets the object to its "power-on" state.
- row_attr ($row,
[$startcol , $endcol])
- Returns the attributes for row $row
(or undef if out of range) as a string of packed attributes, each
character cell's attributes being 2 bytes long. To unpack the attributes
for a given cell, use substr(), eg
$attr =substr($row,4,2) would set
$attr to the attributes for cell 3 (steps of 2: 0 ..
2 .. 4, so 4 means the 3rd character). You would then use the
attr_unpack() method to unpack that character
cell's attributes.
If $startcol and $endcol are
defined, only returns the part of the row between columns
$startcol and $endcol inclusive
instead of the whole row.
- row_text ($row,
[$startcol , $endcol])
- Returns the textual contents of row
$row (or undef if out of range), with totally
unused characters being represented as NULL (\0). If
$startcol and $endcol are
defined, only returns the part of the row between columns
$startcol and $endcol inclusive
instead of the whole row.
- row_plaintext ($row,
[$startcol, $endcol])
- Returns the textual contents of row
$row (or undef if out of range), with unused
characters being represented as spaces. If $startcol
and $endcol are defined, only returns the part of the
row between columns $startcol and
$endcol inclusive instead of the whole row.
- row_sgrtext ($row,
[$startcol , $endcol])
- Returns the textual contents of row
$row (or undef if out of range), with unused
characters being represented as spaces, and ANSI/ECMA-48 escape sequences
(CSI SGR) used to set the colours and attributes as appropriate. If
$startcol and $endcol are
defined, only returns the part of the row between columns
$startcol and $endcol inclusive
instead of the whole row.
Use row_sgrtext to get a row if you want to output it to a real
terminal and preserve all colours, bold, etc.
- sgr_change ($source,
$dest )
- Returns a string containing ANSI/ECMA-48 escape sequences
to change colours and attributes from $source to
$dest, which are both packed attributes (see
attr_pack). This is used internally by row_sgrtext.
- cols ()
- Return the number of columns in the VT102 object.
- rows ()
- Return the number of rows in the VT102 object.
- size ()
- Return a pair of values (columns,rows)
denoting the size of the terminal in the VT102 object.
- x ()
- Return the current cursor X co-ordinate (1 being leftmost).
Note: It is possible for the current X co-ordinate to be 1 more than
the number of columns. This happens when the end of a row is reached such
that the next character would wrap on to the next row.
- y ()
- Return the current cursor Y co-ordinate (1 being
topmost).
- cursor ()
- Return the current cursor state (1 being on, 0 being
off).
- xtitle ()
- Return the current xterm window title.
- xicon ()
- Return the current xterm window icon name.
- status ()
- Return a list of values (
$x,$y,$attr,$ti,$ic),
where $x and $y are the cursor
co-ordinates (1,1 = top left), $attr is a packed
version of the current attributes (see attr_unpack),
$ti is the xterm window title, and
$ic is the xterm window icon name.
- version ()
- Return the version of the VT102 module being used.
CALLBACKS¶
Callbacks are the processing loop's way of letting your main program know that
something has happened. They are called while in a
process() loop.
To specify a callback, use the
callback_set interface, giving a reference
to the function to call. Your function should take five scalar arguments: the
VT102 object being processed, the name of the callback, and two arguments
whose value depends on the callback, as shown below. The final argument is the
private data scalar you passed when you called
callback_set.
The name of the callback is passed to the callback function so that you can have
one function to handle all callbacks if you wish.
Available callback names are:
BELL BEL (beep, \007) character received
CLEAR screen about to be cleared
OUTPUT data (arg1) to be sent back to data source
ROWCHANGE screen row (row number is argument 1) content has changed
SCROLL_DOWN about to scroll down (arg1=top row, arg2=num to scroll)
SCROLL_UP about to scroll up (ditto)
UNKNOWN unknown/unsupported code (arg1=name, arg2=code/sequence)
STRING string received (arg1=source, eg PM, APC, arg2=string)
XICONNAME xterm icon name to be changed to arg1
XWINTITLE xterm title name to be changed to arg1
LINEFEED line feed about to be processed (arg1=row)
GOTO cursor about to be moved (args=new pos)
Note that the wording of the above is significant in terms of exactly
when the callback is called. For instance,
CLEAR is called just
before the screen is cleared, whereas
ROWCHANGE is called
after
the given row has been changed.
A good callback handler for
OUTPUT is to simply
syswrite() argument 1 to your data source - eg if
you're reading from a telnet session, write that argument straight to it. It
is used for cursor position request responses and suchlike.
Note that
SCROLL_DOWN is called when scrolling down, so text is about to
move UP the screen;
arg1 will be the row number of the bottom of the
scrolling region, and
arg2 will be the number of rows to be scrolled.
Likewise,
SCROLL_UP is called when text is about to move down;
arg1 will be the row number of the top of the scrolling region.
The
STRING callback is called for escape sequences that contain a string
that would otherwise be ignored, such as DSC, PM, and APC. The first argument
is the escape sequence that contained the string, such as DSC, and the second
argument is the string itself. This callback doesn't get called for OSC
strings.
The
LINEFEED callback can be thought of as "line completed",
it's called when LF, NEL or IND are about to be processed or just before a
line wraps, so it generally indicates that an application has finished
updating a particular line on the screen. Handy for scrollback buffer
processing.
The
GOTO callback is only called just before the cursor is explicitly
moved, by one of CUU, CUD, VPR, CUF, HPR, CUB, CNL, CPL, CHA, HPA, CUP, HVP.
The parameters give the destination column and row, without taking scrolling
and boundaries into account.
Finally, note that
ROWCHANGE is only triggered when text is being
entered; screen scrolling or screen clearance does not trigger it, that would
trigger a
SCROLL_DOWN or
SCROLL_UP or
CLEAR. Line or
character insertion or deletion will cause one or more
ROWCHANGE
callbacks, however.
SUPPORTED CODES¶
The following sequences are supported:
007 (BEL) beep
010 (BS) backspace
011 (HT) horizontal tab to next tab stop
012 (LF) line feed
013 (VT) line feed
014 (FF) line feed
015 (CR) carriage return
021 (XON) resume transmission (only if option IGNOREXOFF is cleared)
023 (XOFF) stop transmission (only if option IGNOREXOFF is cleared)
030 (CAN) interrupt escape sequence
032 (SUB) interrupt escape sequence
033 (ESC) start escape sequence
177 (DEL) ignored
233 (CSI) same as ESC [
ESC 7 (DECSC) save state
ESC 8 (DECRC) restore most recently saved state
ESC H (HTS) set tab stop at current column
ESC g visual beep - treated as BEL
ESC # 8 (DECALN) DEC screen alignment test - fill screen with E's
CSI @ (ICH) insert blank characters
CSI A (CUU) move cursor up
CSI B (CUD) move cursor down
CSI C (CUF) move cursor right
CSI D (CUB) move cursor left
CSI E (CNL) move cursor down and to column 1
CSI F (CPL) move cursor up and to column 1
CSI G (CHA) move cursor to column in current row
CSI H (CUP) move cursor to row, column
CSI J (ED) erase display
CSI K (EL) erase line
CSI L (IL) insert blank lines
CSI M (DL) delete lines
CSI P (DCH) delete characters on current line
CSI X (ECH) erase characters on current line
CSI a (HPR) move cursor right
CSI c (DA) return ESC [ ? 6 c (VT102)
CSI d (VPA) move to row (current column)
CSI e (VPR) move cursor down
CSI f (HVP) move cursor to row, column
CSI m (SGR) set graphic rendition
CSI n (DSR) device status report
CSI r (DECSTBM) set scrolling region to (top, bottom) rows
CSI s (CUPSV) save cursor position
CSI u (CUPRS) restore cursor position
CSI ` (HPA) move cursor to column in current row
CSI g (TBC) clear tab stop (CSI 3 g = clear all stops)
LIMITATIONS¶
Unknown escape sequences and control characters are ignored. All escape
sequences pertaining to character sets are ignored.
The following known control characters / sequences are ignored:
005 (ENQ) trigger answerback message
016 (SO) activate G1 charset, carriage return
017 (SI) activate G0 charset
The following known escape sequences are ignored:
ESC %@ (CSDFL) select default charset (ISO646/8859-1)
ESC %G (CSUTF8) select UTF-8
ESC %8 (CSUTF8) select UTF-8 (obsolete)
ESC (8 (G0DFL) G0 charset = default mapping (ISO8859-1)
ESC (0 (G0GFX) G0 charset = VT100 graphics mapping
ESC (U (G0ROM) G0 charset = null mapping (straight to ROM)
ESC (K (G0USR) G0 charset = user defined mapping
ESC (B (G0TXT) G0 charset = ASCII mapping
ESC )8 (G1DFL) G1 charset = default mapping (ISO8859-1)
ESC )0 (G1GFX) G1 charset = VT100 graphics mapping
ESC )U (G1ROM) G1 charset = null mapping (straight to ROM)
ESC )K (G1USR) G1 charset = user defined mapping
ESC )B (G1TXT) G1 charset = ASCII mapping
ESC *8 (G2DFL) G2 charset = default mapping (ISO8859-1)
ESC *0 (G2GFX) G2 charset = VT100 graphics mapping
ESC *U (G2ROM) G2 charset = null mapping (straight to ROM)
ESC *K (G2USR) G2 charset = user defined mapping
ESC +8 (G3DFL) G3 charset = default mapping (ISO8859-1)
ESC +0 (G3GFX) G3 charset = VT100 graphics mapping
ESC +U (G3ROM) G3 charset = null mapping (straight to ROM)
ESC +K (G3USR) G3 charset = user defined mapping
ESC > (DECPNM) set numeric keypad mode
ESC = (DECPAM) set application keypad mode
ESC N (SS2) select G2 charset for next char only
ESC O (SS3) select G3 charset for next char only
ESC P (DCS) device control string (ended by ST)
ESC X (SOS) start of string
ESC ^ (PM) privacy message (ended by ST)
ESC _ (APC) application program command (ended by ST)
ESC \ (ST) string terminator
ESC n (LS2) invoke G2 charset
ESC o (LS3) invoke G3 charset
ESC | (LS3R) invoke G3 charset as GR
ESC } (LS2R) invoke G2 charset as GR
ESC ~ (LS1R) invoke G1 charset as GR
The following known CSI (ESC [) sequences are ignored:
CSI q (DECLL) set keyboard LEDs
The following known CSI (ESC [) sequences are only partially supported:
CSI h (SM) set mode (only support CSI ? 25 h, cursor on/off)
CSI l (RM) reset mode (as above)
EXAMPLES¶
For some examples, including how to interface Term::VT102 with Net::Telnet or a
command such as SSH, please see the
examples/ directory in the
distribution.
AUTHORS¶
Copyright (C) 2003 Andrew Wood "<andrew dot wood at ivarch dot
com>". Distributed under the terms of the Artistic License 2.0.
Credit is also due to:
Charles Harker <CHarker at interland.com>
- reported and helped to diagnose a bug in the handling of TABs
Steve van der Burg <steve.vanderburg at lhsc.on.ca>
- supplied basis for an example script using Net::Telnet
Chris R. Donnelly <cdonnelly at digitalmotorworks.com>
- added support for DECTCEM, partial support for SM/RM
Paul L. Stoddard
- reported a possible bug in cursor movement handling
Joerg Walter
- provided a patch for Unicode handling
THINGS TO WATCH OUT FOR¶
Make sure that your code understands NULL (\000) - you will get this in strings
where nothing has been printed on the screen. For instance, the sequence
"12\e[C34" ("12", "CUF (move right)",
"34") you might think would yield the string "12 34", but
in fact it can also yield "12\00034" - that is, "12"
followed by a zero byte followed by "34". This is because the
screen's contents defaults to zeroes, not spaces.
To avoid that, use
row_plaintext, which will convert NULLs to spaces,
instead of
row_text.
Different types of terminal disagree on certain corner cases. For example,
gnome-terminal and
screen handle TAB stops and TABbing past the
end of the screen in slightly different ways. Term::VT102 is closer to
screen in the way it handles this sort of thing.
SEE ALSO¶
console_codes(4),
IO::Pty(3)