README

   1 NOTE: ALPHA AND BETA RELEASES OF TCL/TK ARE NOT SUPPORTED!
   2
   3 --------------------
   4 Introduction
   5 --------------------
   6
   7 This is the README file for Expect, a program that performs programmed
   8 dialogue with other interactive programs.  It is briefly described by
   9 its man page, expect(1).  This directory contains the source and man
  10 page for Expect.
  11
  12 This README file covers Expect 5.38 and up.  These versions of Expect
  13 work with Tcl 8.2 and up and Tk 8.2 and up.  Significant changes and
  14 other news can be found in the NEWS file.
  15
  16 The Expect home page is: http://expect.nist.gov
  17 The Expect FAQ is:       http://expect.nist.gov/FAQ.html
  18
  19 --------------------
  20 Getting Started - The Preferable Way
  21 --------------------
  22
  23 A book on Expect is available from O'Reilly with the title "Exploring
  24 Expect: A Tcl-Based Toolkit for Automating Interactive Applications",
  25 ISBN 1-56592-090-2.
  26
  27 The book is filled with detailed examples and explanations, and is a
  28 comprehensive tutorial to Expect.  The book also includes a tutorial
  29 on Tcl written specifically for Expect users (so you don't have to
  30 read the Expect papers or the man pages).  Exploring Expect is 602
  31 pages.
  32
  33 --------------------
  34 Getting Started - The Hacker Way
  35 --------------------
  36
  37 While the book is the best way to learn about Expect, it is not
  38 absolutely necessary.  There are man pages after all and there are
  39 numerous articles and papers on Expect.  All of my own papers are in
  40 the public domain and can be received free.  If you are a hacker on a
  41 tight budget, this may appeal to you.  Nonetheless, I think you will
  42 find the book pays for itself very quickly.  It is much more readable
  43 than the man pages, it includes well-written and explained examples,
  44 and it describes everything in the papers as a coherent whole.  The
  45 concepts in the papers actually only make up a small fraction of the
  46 book.
  47
  48 The 1990 USENIX paper (see "Readings" below) is probably the best one
  49 for understanding Expect conceptually.  The 1991 Computing Systems and
  50 the LISA IV papers provide a nice mix of examples.  The only downside
  51 is, the examples in these papers don't actually work anymore - some
  52 aspects (e.g., syntax) of both Expect and Tcl have changed.  The
  53 papers still make interesting reading - just don't study the examples
  54 too closely!  Fortunately, most of the examples from the papers also
  55 accompany this distribution - and all of these are up to date.
  56
  57 For all the details, read the man page.  It is long but you can get
  58 started just by skimming the sections on the following commands:
  59
  60         spawn           (starts a process)
  61         send            (sends to a process)
  62         expect          (waits for output from a process)
  63         interact        (lets you interact with a process)
  64
  65 To print out the Expect man page, invoke your local troff using the
  66 -man macros, such as either of:
  67
  68                 ptroff -man expect.man
  69                 ditroff -man expect.man
  70
  71 If Expect is installed, you can read the man pages using the "usual"
  72 man commands, such as "man expect".  If not installed, view the man
  73 page on your screen by saying something like:
  74
  75                 nroff -man expect.man | more
  76
  77 Expect uses Tcl as the underlying language for expressing things such
  78 as procedures, loops, file I/O, and arithmetic expressions.  For many
  79 simple scripts, it is not necessary to learn about Tcl.  Just by
  80 studying the examples, you will learn enough Tcl to get by.  But if
  81 you would like to learn more about Tcl or use it in your own
  82 applications, read the Tcl README file which provides pointers to the
  83 extensive Tcl documentation.  Or read Exploring Expect.  Chapter 2 of
  84 Exploring Expect is a Tcl tutorial specifically designed for Expect
  85 users.
  86
  87 An interactive debugger is bundled with Expect.  The debugger has its
  88 own documentation that comes separately.  It is listed in the Readings
  89 below.  Again, it is slightly out of date.  An up-to-date description
  90 of the debugger appears in Chapter 18 of Exploring Expect.  This
  91 chapter also contains additional advice and tips for debugging.
  92
  93 You may get the feeling that the Expect documentation is somewhat
  94 scattered and disorganized.  This was true prior to publication of
  95 Exploring Expect.  The book contains everything you need to know, all
  96 up-to-date, and with examples of every concept.  (The book contains no
  97 references to any of the Expect papers because none are necessary.)
  98
  99 ----------------------
 100 Examples
 101 ----------------------
 102
 103 This distribution contains many example scripts.  (All of the
 104 substantive examples in the book are included.)  They can be found in
 105 the example directory of this distribution.  The README file in that
 106 directory briefly describes all of the example scripts.  Many of the
 107 more sophisticated examples have man pages of their own.
 108
 109 Other interesting scripts are available separately in the directory
 110 http://expect.nist.gov/scripts/ (ftpable as
 111 ftp://ftp.nist.gov/mel/div826/subject/expect/scripts).  (See below for
 112 how to retrieve these.)  You are welcome to send me scripts to add to
 113 this directory.  A number of Expect scripts are also available in the
 114 Tcl archive, available at ftp://ftp.neosoft.com/pub/tcl.
 115
 116 --------------------
 117 Readings on Expect
 118 --------------------
 119
 120 The implementation, philosophy, and design are discussed in "expect:
 121 Curing Those Uncontrollable Fits of Interaction", Proceedings of the
 122 Summer 1990 USENIX Conference, Anaheim, CA, June 11-15, 1990.
 123
 124 Examples and discussion, specifically aimed at system administrators,
 125 are in "Using expect to Automate System Administration Tasks",
 126 Proceedings of the 1990 USENIX Large Systems Administration Conference
 127 (LISA) IV, Colorado Springs, CO, October 17-19, 1990.
 128
 129 A comprehensive paper of example scripts is "expect: Scripts for
 130 Controlling Interactive Programs", Computing Systems, Vol. 4, No. 2,
 131 University of California Press Journals, 1991.
 132
 133 Regression and conformance testing is discussed in "Regression Testing
 134 and Conformance Testing Interactive Programs", Proceedings of the
 135 Summer 1992 USENIX Conference, San Antonio, TX, June 8-12, 1992.
 136
 137 An explanation of some of the more interesting source code to an early
 138 version of Expect is in Chapter 36 ("Expect") of "Obfuscated C and
 139 Other Mysteries", John Wiley & Sons, ISBN 0-471-57805-3, January 1993.
 140
 141 A paper on connecting multiple interactive programs together using
 142 Expect is "Kibitz - Connecting Multiple Interactive Programs
 143 Together", Software - Practice & Experience, Vol. 23, No. 5, May 1993.
 144
 145 The debugger is discussed in "A Debugger for Tcl Applications",
 146 Proceedings of the 1993 Tcl/Tk Workshop, Berkeley, CA, June 10-11,
 147 1993.
 148
 149 Using Expect with Tk is described in the paper "X Wrappers for
 150 Non-Graphic Interactive Programs", Proceedings of Xhibition '94, San
 151 Jose, CA, June 20-24, 1994.
 152
 153 Simple techniques to allow secure handling of passwords in background
 154 processes are covered in "Handling Passwords with Security and
 155 Reliability in Background Processes", Proceedings of the 1994 USENIX
 156 LISA VIII Conference, San Diego, CA, September 19-23, 1994.
 157
 158 More publications can be found in the Expect home page (see elsewhere).
 159
 160 --------------------
 161 How to Get the Latest Version of Expect or the Readings
 162 --------------------
 163
 164 Expect may be ftp'd as mel/div826/subject/expect/expect.tar.gz from
 165 expect.nist.gov.  (Yes, the URL is much shorter:
 166 http://expect.nist.gov/expect.tar.Z) Request email delivery by mailing
 167 to "library@cme.nist.gov".  The contents of the message should be (no
 168 subject line) "send pub/expect/expect.tar.Z".
 169
 170 Once you have retrieved the system, read the INSTALL file.  The papers
 171 mentioned above can be retrieved separately (from the same directories
 172 listed above) as:
 173
 174  doc/seminal.ps.Z         (USENIX '90 - Intro and Implementation)
 175  doc/sysadm.ps.Z            (LISA '90 - System Administration)
 176  doc/scripts.ps.Z  (Comp. Systems '91 - Overview of Scripts)
 177  doc/regress.ps.Z         (USENIX '92 - Testing)
 178  doc/kibitz.ps.Z            (SP&E '93 - Automating Multiple
 179                                         Interactive Programs Simultaneously)
 180  doc/tcl-debug.ps.Z       (Tcl/Tk '93 - Tcl/Tk Debugger)
 181  doc/expectk.ps.Z      (Xhibition '94 - Using Expect with Tk)
 182  doc/bgpasswd.ps.Z          (LISA '94 - Passwds in Background Procs)
 183  doc/chargraph.ps.Z         (SP&E '96 - Testing and Automation
 184                                         of Character Graphic Applications)
 185
 186 The book "Exploring Expect" is described in more detail earlier in
 187 this file.
 188
 189 The book "Obfuscated C and Other Mysteries" is not on-line but is
 190 available in bookstores or directly from the publisher (Wiley).
 191
 192 Overhead transparencies I've used at conferences are also available in
 193 the same way as the papers themselves.  The transparencies are sketchy
 194 and not meant for personal education - however if you are familiar
 195 with Expect and just want to give a short talk on it to your
 196 colleagues, you may find the transparencies useful.  They vary in
 197 length from 15 to 20 minutes in length.  These are:
 198
 199   doc/seminal-talk.ps.Z    (USENIX '90 - Intro and Implementation)
 200   doc/sysadm-talk.ps.Z       (LISA '90 - System Administration)
 201   doc/regress-talk.ps.Z    (USENIX '92 - Testing)
 202   doc/tcl-debug-talk.ps.Z  (Tcl/Tk '93 - Tcl/Tk Debugger)
 203   doc/expectk-talk.ps.Z (Xhibition '94 - Expect + Tk = Expectk)
 204   doc/bgpasswd-talk.ps.Z     (LISA '94 - Passwords in the Background)
 205
 206 All of the documents are compressed PostScript files and should be
 207 uncompressed and sent to a PostScript printer.  The documents are
 208 intended for printing at 8.5"x11" and may fail on some ISO A4
 209 printers.  According to Hans Mayer <Hans.Mayer@gmd.de>, you can make
 210 them A4-able by searching for "FMVERSION" and changing the next line
 211 from:
 212
 213         1 1 0 0 612 792 0 1 13 FMDOCUMENT
 214 to:
 215         1 1 0 0 594 841 0 1 13 FMDOCUMENT
 216
 217
 218 --------------------
 219 Using Expect with and without Tcl and/or Tk.
 220 --------------------
 221
 222 The usual way of using Expect is as a standalone program with Tcl as
 223 the control language.  Since you may already have Tcl, it is available
 224 separately.  Tcl may be retrieved as tcl.tar.Z in the same way as
 225 described above for Expect.  When new releases of Tcl appear, I will
 226 try to check them out for Expect as soon as possible.  If you would
 227 like to get the newest Tcl release without waiting, ftp it from
 228 ftp.scriptics.com (directory pub/tcl).
 229
 230 Expect may also be built using the Tk library, a Tcl interface to the
 231 X Window System.  Tk is available in the same way as Tcl.
 232
 233 It is possible to embed the Expect/Tcl core and optionally Tk in your
 234 own C programs.  This is described in libexpect(3).
 235
 236 Expect can also be used from a C or C++ program without Tcl.  This is
 237 described in libexpect(3).  While I consider this library to be easy
 238 to use, the standalone Expect program is much, much easier to use than
 239 working with the C compiler and its usual edit, compile, debug cycle.
 240 Unlike typical programming, most of the debugging isn't getting the C
 241 compiler to accept your programs - rather, it is getting the dialogue
 242 correct.  Also, translating scripts from Expect to C is usually not
 243 necessary.  For example, the speed of interactive dialogues is
 244 virtually never an issue.  So please try 'expect' first.  It is a more
 245 appropriate tool than the library for most people.
 246
 247 --------------------
 248 Systems Supported
 249 --------------------
 250
 251 I do not know of any UNIX systems on which Expect will not run.
 252 Systems which do not support select or poll can use Expect, but
 253 without the ability to run multiple processes simultaneously.  I am
 254 willing to work with you to complete a port.
 255
 256 Before sending me changes, please download or verify that you have the
 257 latest version of Expect (see above).  Then send me a "diff -c" along
 258 with a suitable English explanation.  If your diff involves something
 259 specific to a machine, give me diffs for configure.in as well or give
 260 me a hint about when the diffs should be done so I can write the
 261 configure support myself.  Also please include the version of the OS
 262 and whether it is beta, current, recent, or totally out-of-date and
 263 unsupported.
 264
 265 --------------------
 266 Installing Expect
 267 --------------------
 268
 269 Expect comes with a configure script that provides for an automated
 270 installation.  I believe you will find that Expect is very easy to
 271 install.  (Tcl and Tk, too.)
 272
 273 For more information, read the INSTALL file.
 274
 275 --------------------
 276 Support from Don Libes or NIST
 277 --------------------
 278
 279 Although I can't promise anything in the way of support, I'd be
 280 interested to hear about your experiences using it (good or bad).  I'm
 281 also interested in hearing bug reports and suggestions for improvement
 282 even though I can't promise to implement them.
 283
 284 If you send me a bug, fix, or question, include the version of Expect
 285 (as reported by expect -d), version of Tcl, and name and version of
 286 the OS that you are using.  Before sending mail, it may be helpful to
 287 verify that your problem still exists in the latest version.  You can
 288 check on the current release and whether it addresses your problems by
 289 retrieving the latest HISTORY file (see "History" above).
 290
 291
 292 Awards, love letters, and bug reports may be sent to:
 293
 294 Don Libes
 295 National Institute of Standards and Technology
 296 Bldg 220, Rm A-127
 297 Gaithersburg, MD  20899
 298 (301) 975-3535
 299 libes@nist.gov
 300
 301 I hereby place this software in the public domain.  NIST and I would
 302 appreciate credit if this program or parts of it are used.
 303
 304 Design and implementation of this program was funded primarily by
 305 myself.  Funding contributors include the NIST Automated Manufacturing
 306 Research Facility (funded by the Navy Manufacturing Technology
 307 Program), the NIST Scientific and Technical Research Services, the
 308 ARPA Persistent Object Bases project and the Computer-aided
 309 Acquisition and the Logistic Support (CALS) program of the Office of
 310 the Secretary of Defense.
 311
 312 Especially signicant contributions were made by John Ousterhout, Henry
 313 Spencer, and Rob Savoye.  See the HISTORY file for others.
 314
 315 --------------------
 316 Commercial Support, Classes
 317 --------------------
 318
 319 Several companies provide commercial support for Expect.  If your
 320 company has a financial investment in Expect or you wish to be assured
 321 of continuing support for Expect, you can buy a support contract this
 322 way.  These companies currently include:
 323
 324 ActiveState
 325 #200 - 580 Granville St
 326 Vancouver, BC
 327 V6C 1W6 Canada
 328 +1 (604) 484-6800
 329 http://www.activestate.com/Company/contact.plex
 330
 331 Cygnus Support
 332 1937 Landings Drive
 333 Mountain View, CA  94043
 334 +1 (415) 903-1400
 335 info@cygnus.com
 336 http://www.cygnus.com
 337
 338 Computerized Processes Unlimited (CPU)
 339 4200 S. I-10 Service Rd., Suite 205
 340 Metairie, LA  70006
 341 +1 (504) 889-2784
 342 info@cpu.com
 343 http://www.cpu.com
 344 http://www.cpu.com/cpu/expect.htm (Expect class page)
 345
 346 CPU provides Expect support and also Expect classes.  Contact them for
 347 more information.
 348
 349 Neither NIST nor I have any financial relationship with these
 350 companies.  Please contact me to be added to this list.