--------------------
Introduction
--------------------

This is the README file for Expect, a program that performs programmed
dialogue with other interactive programs.  It is briefly described by
its man page, expect(1).  This directory contains the source and
documentation for Expect.

This is Expect 5 for Tcl 7.0 thru 7.3.  Tk 3.3 thru 3.6 are also
supported.  If you have Expect 4 scripts, read the CHANGES.4to5 file.

--------------------
Getting Started
--------------------

The easiest way to get started with Expect is to read the 1991
Computing Systems paper (see "Readings" below).  That paper is the
best introduction but is also a bit dated - some of the low-level
details (e.g., syntax) have changed a bit.  You may find it worthwhile
to read the other papers too, but it is not necessary.

For all the details, read the man page.  If you are just starting out,
just read about the commands:

	spawn		(starts a process)
	send		(sends to a process)
	expect		(waits for output from a process)
	interact	(lets you interact with a process)

To write sophisticated applications, you will want to read the rest of
the man page.

To print out the Expect man page, invoke your local troff using the
-man macros, such as either of:

		ptroff -man expect.man
		ditroff -man expect.man

If Expect is installed, you should be able to read the man pages using
the "usual" man commands, such as "man expect".  If it is not
installed, view the man page on your screen by saying something like:

		nroff -man expect.man | more

Expect uses Tcl as the underlying language for expressing things such
as procedures, loops, file I/O, and arithmetic expressions.  For many
simple scripts, it's not necessary to learn about Tcl.  Just by
reading the papers, you will learn enough Tcl to get by.  But if you
would like to learn more about Tcl or use it in your own applications,
read the Tcl README file which provides pointers to the extensive Tcl
documentation.

----------------------
Examples
----------------------

This distribution contains many example scripts.  These are described
in the INSTALL file.  A few of the more sophisticated ones have man
pages of their own.  The example scripts can be found in the "example"
subdirectory.

Other interesting scripts are available separately in the
pub/expect/scripts directory (retrieved as above).  You are welcome to
send me scripts to add to this directory.

--------------------
Readings on Expect
--------------------

The implementation, philosophy, and design are discussed in "expect:
Curing Those Uncontrollable Fits of Interaction", Proceedings of the
Summer 1990 USENIX Conference, Anaheim, CA, June 11-15, 1990.

Examples and discussion, specifically aimed at system administrators,
are in "Using expect to Automate System Administration Tasks",
Proceedings of the 1990 USENIX Large Systems Administration Conference
(LISA) IV, Colorado Springs, CO, October 17-19, 1990.

A comprehensive paper of example scripts is "expect: Scripts for
Controlling Interactive Programs", Computing Systems, Vol. 4, No. 2,
University of California Press Journals, 1991.

Regression and conformance testing is discussed in "Regression Testing
and Conformance Testing Interactive Programs", Proceedings of the
Summer 1992 USENIX Conference, San Antonio, TX, June 8-12, 1992.

An explanation of some of the more interesting source code to an early
version of Expect is in Chapter 36 ("Expect") of "Obfuscated C and
Other Mysteries", John Wiley & Sons, 1993.

A paper on connecting multiple interactive programs together using
Expect is "Kibitz - Connecting Multiple Interactive Programs
Together", Software - Practice & Experience, Vol. 23, No. 5, May 1993.

The debugger is discussed in "A Debugger for Tcl Applications",
Proceedings of the 1993 Tcl/Tk Workshop, Berkeley, CA, June 10-11,
1993.

Using Expect with Tk is described in the paper "X Wrappers for
Non-Graphic Interactive Programs", Proceedings of Xhibition '94, San
Jose, CA, June 20-24, 1994.

--------------------
How to Get the Latest Version of Expect or the Readings
--------------------

Expect may be ftp'd as pub/expect/expect.tar.Z from ftp.cme.nist.gov.
Request email delivery by mailing to "library@cme.nist.gov".  The
contents of the message should be (no subject line) "send
pub/expect/expect.tar.Z".  (Development versions of Expect may
occasionally be made available as alpha.tar.Z in the same directory.)

Once you have retrieved the system, please read the INSTALL file.  The
papers mentioned above can be retrieved separately as:

  pub/expect/seminal.ps.Z (USENIX '90 - Intro and Implementation)
  pub/expect/sysadm.ps.Z (LISA '90 - System Administration)
  pub/expect/scripts.ps.Z (Computing Systems '91 - Overview of Scripts)
  pub/expect/regress.ps.Z (USENIX '92 - Testing)
  pub/expect/kibitz.ps.Z (SP&E '93 - Automating Multiple Interactive
					Programs Simulateously)
  pub/expect/tcl-debug.ps.Z (Tcl/Tk '93 - Tcl/Tk Debugger)
  pub/expect/expectk.ps.Z (Xhibition '94 paper - Using Expect with Tk)

The Obfuscated C book is not on-line but is available in bookstores or
directly from the publisher (Wiley).  I expect a book specifically on
Expect to be available in the second half of '94.

Overhead transparencies I've used at conferences are also available in
the same way.  The transparencies are pretty sketchy but if you are
familiar with Expect and just want to give a short talk on it to your
colleagues, you may find the transparencies useful.  Each one is
approximately a 15 minute talk.  These are:

  pub/expect/seminal-talk.ps.Z (USENIX '90 - Intro and Implementation)
  pub/expect/sysadm-talk.ps.Z (LISA '90 - System Administration)
  pub/expect/regress-talk.ps.Z (USENIX '92 - Testing)
  pub/expect/tcl-debug-talk.ps.Z (Tcl/Tk '93 - Tcl/Tk Debugger)

All of the documents are compressed PostScript files and should be
uncompressed and sent to a PostScript printer.  The documents are
intended for printing at 8.5"x11" and may fail on some ISO A4
printers.  According to Hans Mayer <Hans.Mayer@gmd.de>, you can make
it A4-able by searching for "FMVERSION" and changing the next line
from:

	1 1 0 0 612 792 0 1 13 FMDOCUMENT
to:
	1 1 0 0 594 841 0 1 13 FMDOCUMENT


--------------------
Using Expect with and without Tcl and/or Tk.
--------------------

The usual way of using Expect is as a stand-alone program.  This
requires Tcl.  Since you may already have Tcl, it is available
separately.  Tcl may be retrieved as pub/expect/tcl7.0.tar.Z in the
same way as described above for Expect.  When new releases of Tcl
appear, I will try to check them out for Expect as soon as possible.
If you would like to get the newest Tcl release without waiting, ftp
it from ftp.cs.berkeley.edu (directory: ucb/tcl).  You may request
email copies of Tcl by writing to ouster@sprite.berkeley.edu.

Expect may also be built using the Tk library, a Tcl interface to the
X window system.  Tk is available in the same way as Tcl.

It is possible to embed the Expect/Tcl core and optionally Tk in your
own C programs.  This is described in libexptcl(3) and libexptk(3).

Expect can also be used from a C or C++ program without Tcl.  This is
described in libexpect(3).  While I consider this library to be easy
to use, the standalone Expect program is much, much easier to use than
working with the C compiler and its usual edit, compile, debug cycle.
Unlike typical programming, most of the debugging isn't getting the C
compiler to accept your programs - rather, it is getting the dialogue
correct.  Also, translating scripts from Expect to C is usually not
necessary.  For example, the speed of interactive dialogues is
virtually never an issue.  So please try 'expect' first.  I suspect it
is a more appropriate solution for most people than the library.

--------------------
Systems Supported
--------------------

I do not know of any systems which Expect will not run on.  Systems
which do not support select or poll can use Expect, but without the
ability to run multiple processes simultaneously.  I am willing to
work with you to complete a port.

--------------------
Installing Expect
--------------------

Read the INSTALL file.

--------------------
History
--------------------

Expect was conceived of in September, 1987.  The bulk of version 2 was
designed and written between January and April, 1990.  Minor evolution
occurred after that until Tcl 6.0 was released.  At that time
(October, 1991) approximately half of Expect was rewritten for version
3.  See the HISTORY file for more information.  The HISTORY file may
be retrieved separately as pub/expect/HISTORY.

Around January 1993, an alpha version of Expect 4 was introduced.
This included Tk support as well as a large number of enhancements.  A
few changes were made to the user interface itself, which is why the
major version number was changed.  A production version of version 4
was released in August 1993.

In October 1993, an alpha version of Expect 5 was released to match
Tcl 7.0.  A large number of enhancements were made, including some
changes to the user interface itself, which is why the major version
number was changed (again).  This documentation and software
distribution is the production version 5 of Expect - initially
released in March '94.

Some of the papers listed above correspond to earlier versions
although they are still good ways to learn about Expect.  There are
important differences between version 3, 4, and 5.  See the CHANGES.*
files if you want to read about them.  Expect 4 has ceased further
development and will no longer be supported.  However, if for some
reason you want the old code, it is available from pub/expect/old as
described below.

--------------------
Support
--------------------

Although I can't promise anything in the way of support, I'd be
interested to hear about your experiences using it (either good or
bad).  I'm also interested in hearing bug reports and suggestions for
improvement even though I can't promise to implement them immediately.

If you send me a bug report, fix, or question, include the version of
Expect (as reported by expect -d), version of Tcl, and name and
version of the OS that you are using.

Awards, love letters, and bug reports may be sent to:

Don Libes
National Institute of Standards and Technology
Bldg 220, Rm A-127
Gaithersburg, MD  20899
(301) 975-3535
libes@nist.gov




I hereby place this software in the public domain.  NIST and I would
appreciate credit if this program or parts of it are used.

Design and implementation of this program was funded primarily by myself.
Other contributors include the NIST Automated Manufacturing Research
Facility (funded by the Navy Manufacturing Technology Program), the NIST
Scientific and Technical Research Services, the ARPA Persistent Object
Bases project and the Computer-aided Acquisition and the Logistic Support
(CALS) program of the Office of the Secretary of Defense.

--------------------
Cygnus Support
--------------------

Cygnus Support provides commercial support for Expect (as well as Tcl
and Tk).  If your company has a financial investment in Expect or you
wish to be assured of continuing support for Expect, you can buy a
support contract this way.  Cygnus may be reached at:

Cygnus Support
1937 Landings Drive
Mountain View, CA  94043
+1 (415) 903-1400
info@cygnus.com

Neither I nor NIST has any commercial relationship with Cygnus.
Cygnus is in the process of signing an agreement with NIST that
describes its non-exclusive position to support Expect.  Other
companies are welcome to apply for such an agreement or other kinds of
agreements such as permission-to-use.  Strictly speaking, such
agreements are not necessary, however they make us look good to our
funding source, the U.S. Congress.
