Provided by: libterm-vt102-perl_0.91-3_all bug

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)