From: cjm1@gte.com (Christopher J. Matheus)
Newsgroups: comp.lang.tcl
Subject: alpha testers wanted: expecTerm
Keywords: expect alpha expecTerm
Date: 19 Aug 92 21:20:13 GMT

We are looking for alpha testers for expecTerm, a screen-based
extension to Don Libes expect program (both based on tcl).

We've been using expecTerm within GTE Laboratories for several months
and believe it to be fairly stable under SUNOS 4.1 and AIX 3.2.
However we would like to get comments back from some external alpha
testers before releasing it to the world.

Below is the man page for expecTerm.  If you are seriously interested
in testing expecTerm please send email to matheus@gte.com and we will
email you a uuencoded, compressed tar file of the alpha release.

Mark Weissman
GTE Laboratories Incorporated
weissman@gte.com
 
Chris Matheus
GTE Laboratories Incorporated
matheus@gte.com

-------------------------------------------------------------------------------

EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



NAME
     expecTerm -- expect with terminal emulation

SYNOPSIS
     expecTerm [ expect_options ]

INTRODUCTION
     expecTerm adds terminal emulation to Don Libes' expect  pro-
     gram.   The standard expect commands are all supported, mak-
     ing expecTerm compatible with existing expect scripts.

     expecTerm introduces five new commands:

          emulate: adds terminal emulation to an existing  spawned
          process

          screen_info: returns  information  about  an  emulator's
          screen and cursor

          set_master: controls which emulator the user is viewing

          status_line: displays a message  on  expecTerm's  status
          line

          term_switch: provides access to terminal  switches  such
          as echo and logging.

     expecTerm adds several new options to the expect command  to
     support  screen-based pattern matching.  These are described
     in the COMMANDS section below.

     The spawn command has  been  given  one  additional  option,
     -pipe,  which  causes  the processes to be established using
     pipes rather than pseudo ttys.  This feature is useful  when
     applications  require  more spawned processes than available
     pseudo ttys, and the spawned processes do not  require  full
     pseudo tty support.

     The timeout command  has  also  been  changed  to  accept  a
     decimal argument for time, e.g. set timeout 0.5. The follow-
     ing simple script illustrates the use of terminal  emulation
     in expecTerm:

          spawn csh
          emulate -term vt100
          send who\n
          expect -cols 0:3 jcr2 {puts stdout "jcr2 is logged in"}

     This script spawns a csh process and connects it to a  vt100
     emulation.  It then sends the the process the command to run
     the who program which will display a list of current  system
     users.  The  expect line then scans for the string "jrc2" to



Sun Release 4.1     Last change: 18 June 1992                   1






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



     appear in the first 4 columns in any  of  the  rows  on  the
     screen.

     Pattern matching on  emulated  screens  occurs  at  distinct
     break  points,  rather than after every new character (as in
     normal expect). Distinct break points  normally  occur  when
     the  input  buffer  is  full,  or the input stream is empty.
     This behavior can be modified with the  term_switch  command
     to  make  breaks  also occur whenever the cursor moves back-
     wards or up on the screen.


USAGE
     For general usage information see the expect manpage.    The
     rest  of  this  document assumes the reader is familiar with
     expect and its suite of commands.



COMMANDS
     emulate [ -i spawn_id ] [[ -term ] term_type ]

          When a terminal type is specified on the command  line,
          emulate  creates  a terminal emulator and associates it
          with the current spawn_id (or  the  spawn_id  specified
          with  -i).  With  no term_type argument emulate returns
          the name of the terminal being emulated.  Any  terminal
          can  be  emulated provided the system has the necessary
          terminfo or termcap data (but see  the  Caveat  section
          about  non-invertible  screen commands). emulate always
          returns the name of the terminal type being emulated.

          emulate can also be used to change the terminal type of
          a  spawned  process  by simply invoking it again with a
          new term_type.


     expect [[ -opts ] patlist1 body1 ] ... [ -opts ] patlistn  [
     bodyn ]

          In  addition  to  its  standard  behavior,  expect  has
          several   new  options  that  modify  its  handling  of
          screen-based patterns. As with other expect  arguments,
          these  options  modify  the  processing of the patterns
          they immediately precede.

          -serial, -scr, -attr

          These options specify whether scanning is  to  be  done
          over  the  raw serial input ( -serial ) the screen con-
          tents ( -scr ), or the screen  attributes  (  -attr  ).
          The  default is serial scanning ( -serial ) which tells



Sun Release 4.1     Last change: 18 June 1992                   2






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



          expect to  ignore  terminal  emulation  completely  and
          operate  directly on the current input stream, i.e. the
          normal expect behavior.

          If -scr (or -screen ) appears before a  pattern,  scan-
          ning  will  be  done on the emulated screen's contents.
          -scr is not  necessary  if  any  of  the  other  screen
          options described below appear before the pattern.

          -attr (or -attributes ) causes pattern matching  to  be
          done  over  the  attributes  of  the  characters on the
          screen, rather than the  characters  themselves.   Each
          character is associated with a single code representing
          information about the character's  display  attributes.
          The codes are listed below in order of descending domi-
          nance:

            'N' = NORMAL
            'B' = BOLD
            'S' = STANDOUT
            'U' = UNDERLINE
            'A' = ALTCHARSET
            'R' = REVERSE
            'D' = DIM
            'b' = BLINK
            'I' = INVISIBLE
            'P' = PROTECT

          If a character has two or  more  attributes,  only  the
          most dominant attribute is available for scanning.  For
          example, if a character is both  BOLD  and  REVERSE  it
          will have an attribute code of B.

          Here are some simple examples:

               expect BB
               expect -scr BB
               expect -attr BB

          The first command waits for two subsequent B's  on  the
          serial  input (the optional -serial flag has been omit-
          ted).  The second waits for two adjacent  B's  anywhere
          on  the  screen.  Note  that the first command will not
          always match when the second command  matches,  e.g  if
          the  two  B's  are  not  displayed  one right after the
          other.  The last command scans for  two  adjacent  bold
          characters anywhere on the screen.

          -rows, -cols


          -rows and -cols define the screen region to be  scanned



Sun Release 4.1     Last change: 18 June 1992                   3






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



          during pattern matching.  Each option requires an argu-
          ment of the form n:n, where each n is a  number  (posi-
          tive  or  negative)  or  a  '$'.   When  used, a '$' is
          translated into either the number of rows or the number
          of  columns  on  the  emulated  screen  (depending upon
          whether -rows or -cols is used).

          The first number in the n:n form defines the  beginning
          of  the  scan  region and is always required.  The last
          number specifies the end of  the  scan  region  and  is
          optional  --  if  unspecified  it defaults to the first
          number.  When the last number is  not  given,  the  ':'
          should  not  be  specified.   The last number should be
          equal to or greater than the  first  number,  otherwise
          the defined screen region will be empty.

          The coordinate system is zero-based with 0,0 represent-
          ing the upper left corner of the screen, i.e., "-rows 0
          -cols 0" specifies the first  character  in  the  first
          row.   Negative  numbers  may be used to define regions
          counting backward from the last  row  or  last  column.
          For  example,  -rows  -1  indicates the last row; -rows
          -2:-1 indicates the last two rows.


          -rows and -cols are optional.  If neither is given, the
          scanning  region  defaults to all rows and all columns.
          If only one is given, the other dimension  defaults  to
          all  rows  or  all  columns.    Whenever possible it is
          advisable to  specify  the  smallest  necessary  screen
          region (rather than using the full-screen defaults), as
          this will improve performance.

          When the screen region consists of  multiple  rows  the
          ends  of  the  rows are explicitly indicated by newline
          characters (\n).  Patterns can span  multiple  rows  by
          matching \n.

          Examples:

               expect -rows 0:9 -cols 5 "a"
               expect -cols 5:$ "ab"
               expect -rows -5:-1 "ab"
               expect -rows 0:1 -cols 0:4 "aaaaa\nbbbbb"

          The first command scans a region covering the first ten
          rows  made  up of the sixth character in each row.  The
          second command scans  a  region  spanning  columns  six
          through  the  end of the line over all rows.  The third
          command scans a region spanning all columns in the last
          five  rows.   The last command looks for "aaaaa" in the
          first five columns of the first row and "bbbbb" in  the



Sun Release 4.1     Last change: 18 June 1992                   4






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



          first five columns of the second row.

          -rrows, -rcols


          -rrows and -rcols are just like -rows and -cols  except
          they  specify  screen  regions  relative to the current
          cursor location.  Like -rows and -cols, each  takes  an
          argument  of the form n:n.  If the second number is not
          given it defaults to the first.

          The relative coordinate system is zero-based  from  the
          cursor  location.   For  example,  "-rrows  0 -rcols 0"
          specifies the character location of the cursor.   Nega-
          tive  numbers define regions counting backward from the
          cursor (e.g. -rrows -1 indicates the row above the  row
          the cursor is on).


          -rrows and -rcols can  be  intermixed  with  -rows  and
          -cols. If a dimension is unspecified it defaults to its
          absolute behavior (either

          -rows or -cols ).  Examples:

               expect -rrows -1:1 -rcols 0:5
               expect -rrows 0

          The first command scans the three rows centered on  the
          cursor, matching characters from the cursor's column to
          five columns past the cursor. The second command  scans
          all columns on the cursor's row.

          -quiet n

          This option indicates that  n  seconds  of  quiet  time
          (i.e. no activity on the input stream) must pass before
          the pattern can  match.  n  may  be  a  floating  point
          number.  The quiet timer starts when the expect command
          is executed.  Consequently, at  least  n  seconds  will
          pass  before  a  match  is  possible, even if the input
          stream was quiet for some time before the command. This
          option  is  useful  for  ensuring that all changes have
          been made to the screen before matching a  pattern  and
          executing its command body.

          -quiet_total n

          This option is similar to -quiet except the quiet timer
          looks  back  in  time  prior  to  the invocation of the
          expect  command.   As  a  result,  a  pattern  with   a
          -quiet_total  n  specification can match in less than n



Sun Release 4.1     Last change: 18 June 1992                   5






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



          seconds (e.g. immediately) if the input stream had been
          quiet before the call to expect.

          -quiet_after_noise n

          This option tells  expect  to  wait  for  some  initial
          activity  on  the input stream followed by n seconds of
          quiet.  n may be a floating point number. This  feature
          is useful when waiting for some response from a process
          that may require time to finish writing to the screen.

          -nobreaks

          This option says that pattern matching  should  NOT  be
          performed  when the cursor moves backwards or up on the
          screen.   It  is  only  useful  when  the   term_switch
          all_breaks is on.


     screen_info [ -i spawn_id ] [ options ]

          screen_info  provides  information  about  the  current
          state of a process's emulated screen. If no options are
          specified, screen_info returns a  copy  of  the  entire
          contents  of  the  emulated screen, encoded as a string
          with newline characters (\n) separating rows.

          screen_info understands  the  "screen  region"  options
          described  above,  e.g.  -rows,  -cols, -rrows, -rcols,
          -attr. In addition, it accepts  the  following  options
          for obtaining terminal-specific information:

          -cursor_row returns the row the cursor is on.

          -cursor_col returns the column the cursor is on.

          -nocase like the   -nocase option in expect, this modi-
          fies  a  screen  region  query  such  that the returned
          string is all lower case.

          -numrows returns the number of  rows  on  the  emulated
          terminal.

          -numcols returns the number of columns on the  emulated
          terminal.

          If more than one option is specified, the result  is  a
          list  of  the  individual  return  values, given in the
          order in which they were specified on the command line.






Sun Release 4.1     Last change: 18 June 1992                   6






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



     set_master [ -i spawn_id | -next | -previous ] [ -refresh ]

          While multiple emulations  may  be  running  simultane-
          ously,  only  one at a time can be viewed on the user's
          screen.  set_master switches the  view  to  a  specific
          emulator. With no arguments set_master sets the view to
          the emulator  associated  with  the  current  spawn_id.
          -next and -previous switch the view to the next or pre-
          vious emulator, where the  ordering  is  based  on  the
          spawn_id.  -refresh refreshes the display of the emula-
          tor.


     status_line [ -i spawn_id ] [ -none |  -default  |  -message
     string ] [ -refresh ]"

          status_line allows the user to display a message on the
          status line of the emulated terminal.  This line is not
          part of the emulated screen -- it is not seen by any of
          the scanning commands.  It is purely for the benefit of
          the user monitoring  the  screen.   With  no  arguments
          status_line  returns  the the state of the status line,
          either -default, -none, or -message string.

          -none sets the status  line  to  nothing,  i.e.  blank.
          -default  sets  the  status line to its default message
          which contains information about the state of the  ter-
          minal in the following format:
               Flags: cetrl Session:0/0 Master:3/3 x:00 y:00 vt100
          The flags are upper (on) or lower  (off)  case  letters
          indicating  the  state  of  the  crnl  (c),  echo  (e),
          tabspace (t), rawlog (r), and log (l) switches.

          The  -message  option  tells  status_line  to  put  the
          corresponding string into the status line. The -refresh
          argument causes the status line to be  updated  on  the
          screen.  For example:

               status_line -refresh -message "type: [screen_info -term]"

          produces a status line of the following form:

               type: vt100


     term_switch [ -i spawn_id ] [ switch_option ] [ -refresh ] [
     -log [ args ]] [ -rawlog [ args ]]

          term_switch allows the user to query and  set  switches
          controlling  the behavior of an emulated terminal.  The
          state of these switches are sometimes important for the
          proper  handling  of  certain  programs (for example vi



Sun Release 4.1     Last change: 18 June 1992                   7






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



          requires that the emulator's crnl switch be "on").  The
          options that control these switches are:

          -echo controls whether typed characters are echoed when
          the  user  is  interacting  with  the  emulated screen.
          Default is 0 (off).

          -crnl controls whether end of the line is indicated  by
          carriage-return/newline  (on)  or  just carriage-return
          (off). Default is 0 (off).

          -tabspace controls whether tabs are handled  as  spaces
          (on) or tabs (off). Default is 0 (off).

          -all_breaks controls whether pattern matching occurs at
          all distinct breaks (on) or only if the input buffer is
          full or empty (off).   With  -all_breaks  on,  distinct
          breaks occur when 1) the cursor moves backwards, 2) the
          input buffer is full, or 3) the input buffer is  empty.
          Default is 0 (off).

          The above four switches are controlled with one of  the
          following  optional arguments: -on turns the switch on,
          -off turns the switch off, -toggle toggles  the  switch
          state, -get queries the switch's state.  If no argument
          is given for a switch it defaults  to  -get.  Whichever
          argument  is  used,  the command always returns the new
          value of the switch, either 1 for "on" or 0 for "off".

          -refresh This option refreshes the display of the  emu-
          lated  screen.   It's  most  useful in combination with
          other switches when the effect of  the  changed  switch
          needs to be displayed right away.

          -log, -rawlog These options control the logging of  the
          screen  information  to  a  file.  Logging  is  off  by
          default. When turned on using -log,  information  about
          the  appearance of the screen is sent to the file when-
          ever
           the screen scrolls or is updated.  With  -rawlog,  the
          raw input (including control characters) is sent to the
          file whenever new input arrives.

          The -log options take the same  optional  arguments  as
          the  other switches.  It also understands the following
          additional arguments:

          -append appends the logging information to an  existing
          file rather than overwriting it.

          -file specifies the name of the file  to  log  to.   If
          this   option  is  omitted  the  filename  defaults  to



Sun Release 4.1     Last change: 18 June 1992                   8






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



          ExpectLog.Spawn_id or ExpectLog.rawSpawn_id,  depending
          upon whether -log or -rawlog is used.

          Multiple switches can be set or queried within a single
          term_switch  command,  in  which  case a list of switch
          values is returned. For example,

               term_switch -echo -crnl -off

          returns a list of two values, the  state  of  the  echo
          switch and the state of the crnl switch.

          The default values for these switches  are  defined  by
          global  variables  described  in  the VARIABLES section
          below.  In all cases 0 = off and 1 = on.


VARIABLES
     expect_out(n,row), expect_out(n,col)

     These are two new elements  of  the  expect_out  associative
     variable  that  contains  information  on  the most recently
     matched patterns.  These elements return the row  or  column
     number  of  the  first  character  in the matched pattern. n
     refers to the number of the pattern of interest, which typi-
     cally will be 0 unless regular expressions are used (see the
     expect manpage for more information pattern numbers).


     term_type This variable specifies the terminal type  to  use
     if  none  is  specified  in an emulate command.  The initial
     value of term_type is vt100.


     term_echo This variable defines the  default  for  the  echo
     switch.  Its initial value is 0 (off).


     term_crnl This variable defines the  default  for  the  crnl
     switch.  Its initial value is 0 (off).


     term_tabspace This variable  defines  the  default  for  the
     tabspace switch.  Its initial value is 0 (off).


     term_breaks  This  variable  defines  the  default  for  the
     all_breaks  switch.   Its  initial value is 0 (off), meaning
     pattern matching occurs when the (1) input buffer  is  full,
     (2)  the  input buffer is empty, but NOT (3) when the cursor
     moves up or backwards.




Sun Release 4.1     Last change: 18 June 1992                   9






EXPECTERM(1)             USER COMMANDS               EXPECTERM(1)



CAVEATS
     Some terminals have escape sequences that are not invertible
     from  the  terminfo  or  termcap data.  To make the terminal
     handle these cases properly, a set of translations  need  to
     be   defined   in   the  file  ExpectCap  (usually  kept  in
     /usr/local/lib/expect).  This file has a similar  format  to
     the  terminfo database (see the manpage for terminfo for how
     to construct this file).   The  entries  in  ExpectCap  will
     override  those  from terminfo.  Single terminal entries may
     be specified in  a  file  named  ExpectCap.<terminal>  (e.g.
     ExpectCap.vt100) which will override ExpectCap for a partic-
     ular terminal.

     If stray escape characters appear on the screen  or  if  the
     screen appears different from what it does outside of expec-
     Term, additional ExpectCap entries  are  probably  required.
     Many  screen problems are caused when the terminfo specifies
     the same escape sequence for different actions and the  emu-
     lator, forced to choose, picks the wrong one.

     ExpectCap may contain any  valid  terminfo  capability.   In
     addition,  a  NOOP capability is defined which does nothing.
     This may be used to quiet unrecognized sequences that  don't
     do anything useful.

     The ExpectCap file provided with expecTerm contains  entries
     for vt100 and xterm.


SEE ALSO
     Tcl(3), expect(3), terminfo(3), termcap(3), curses(3)


AUTHORS OF EXPECTERM
     Mark D. Weissman, GTE Laboratories Incorporated
     Christopher J. Matheus, GTE Laboratories Incorporated


AUTHOR OF EXPECT
     Don Libes, National Institute of Standards and Technology


ACKNOWLEDGMENTS
     Design and implementation of expect was paid for by the U.S.
     government  and  is  therefore in the public domain. However
     the author and NIST would like credit if  this  program  and
     documentation or portions of them are used.

     Design and implementation of expecTerm was paid for  by  GTE
     Laboratories  Incorporated which owns the copyright. The use
     of this program, however, is  extended  freely  and  without
     warranty  to  the  public  as  specified  in  the  copyright
     statement.



COPYRIGHT NOTICE:
-------------------------------------------------------------------------------
DO NOT REDISTRIBUTE THE CODE IN THIS ALPHA RELEASE
WITHOUT PERMISSION FROM GTE LABORATORIES INCORPORATED.

expecTerm version: alpha release
Copyright 1992 by GTE Laboratories Incorporated.

Portions of this work are in the public domain.  Permission to use,
copy, modify, and distribute this software and its documentation for
any purpose and without fee is hereby granted, provided that the above
copyright notice appear in all copies and that both the copyright
notice and warranty disclaimer appear in supporting documentation, and
that the names of GTE Laboratories or any of their entities not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.

GTE disclaims all warranties with regard to this software, including
all implied warranties of merchantability and fitness for a particular
purpose, even if GTE Laboratories Incorporated knows about the
purpose.  In no event shall GTE be liable for any special, indirect or
consequential damages or any damages whatsoever resulting from loss of
use, data or profits, whether in an action of contract, negligence or
other tortuous action, arising out of or in connection with the use or
performance of this software.

This code is based on and may include parts of Don Libes' expect code:
  expect written by: Don Libes, NIST, 2/6/90
  Design and implementation of expect was paid for by U.S. tax
  dollars.  Therefore it is public domain.  However, the author and NIST
  would appreciate credit if this program or parts of it are used.