expect-lite

Automation for the rest of us now in Library form

Celebrating 10 years of creating quick solutions

Using expect-lite as a TCL Library

expect-lite can now can run in two modes: standalone, and library-mode. In library-mode expect-lite be used within a TCL (Tool Command Language) program.

What this means is that expect-lite can be called programmatically from TCL, allowing the integration of the ease of expect-lite scripting with a more complex TCL-based regression system. An example TCL program, test_el_lib.tcl, using library-mode is included in the tarball.

In keeping with the principle of 'keeping it simple', the goal is allow expect-lite scripts to be used unchanged, or with minimal changes, in a native TCL environment. Important differences from standalone mode are described below.

The expect-lite library seeks to leverage the ease of expect-lite scripting with easy integration into a more complex TCL environment.

Applications Programmers Interface (API)

As part of playing well with other TCL software, a majority of expect-lite has been encapsulated in a TCL namespace, expectlite (TCL does not permit dash in a namespace name). This prevents procedure- (or functions) and variable-name collisions with other TCL code.

The API includes the following functions, listed in typical order of use:

expectlite::_el_init_library
expectlite::_el_import_session_ids
expectlite::_el_import_const
expectlite::_el_buffer
expectlite::_el_exec_script

Details & examples of the API

Included in the expect-lite tarball is the file test_el_lib.tcl. The example program, is a hybrid script, part TCL, and part expect-lite. The API functions are listed below in more detail, and are listed without the namespace name: expectlite for brevity.

_el_init_library

Used to initialize the expect-lite library, loads the expect library, and optionally can take a list of expect-lite constants (read-only variables) as name value pairs in the form of var=value, and expect-lite directives.

Example:

_el_init_library "*EXP_INFO IP=10.5.5.5 *DEBUG"

_el_import_session_ids

The TCL program may have previously created expect sessions which would be used in the expect-lite script. Session names are imported into the expect-lite *FORK sessions, and the expect-lite script will have access to use the session names defined by the program.

Since TCL can not pass arrays, the array of sessions is passed as a list (via [array get session]).

Example:

# create spawn sessions and set prompt to identify the session
spawn bash
send "export PS1='0\$ '\n"
set session(default) $spawn_id

spawn bash
send "export PS1='1\$ '\n"
set session(dut1) $spawn_id

_el_import_session_ids [array get session]

_el_import_const

As mentioned earlier, it is possible to pass expect-lite constants and directives via _el_init_library call. However that can only be called once. It may be more desirable to create a loop where TCL variables are imported into expect-lite. The _el_import_const function that does this can be called many times.

Example:

_el_import_const "DUT=mydut *NOFAIL"

_el_import_const "DUT2=thatdut "

_el_buffer

This function is used to read a file into expect-lite's private command buffer space. In the included example test_el_lib.tcl, the TCL file itself is read into _el_buffer. Since any line that does not begin with expect-lite's punctuation characters is ignored, all the TCL in the test program will be ignored.

This function returns a pointer to the private buffer space. This must be passed to _el_exec_script for execution.

Example:

# read this file as expect-lite script, and return pointer to buffer
set cmd_file $argv0
set cmd_list_ptr [_el_buffer $cmd_file]

_el_exec_script

Having prepared the library with the necessary information, this function is the core of expect-lite. It interprets the expect-lite punctuation commands (such as '>', '<'), as well as dereference expect-lite variables. This function returns the following result codes:

zero (0) if the expect-lite script passes
one (1) if the expect-lite script fails
two (2) if the result is unknown (usually abnormal end of the script).

Example:

# call el script exec
set RESULT [ _el_script_exec "" $cmd_list_ptr ]

# Print result of test
switch $RESULT {
	0 	{ puts "\nTest Passed" }
	1	{ puts "\nTest Failed" }
	2	{ puts "\nTest Abend" }
}

Changes in behaviour when running expect-lite as a library

The thinking is that when running expect-lite as a Library (aka library mode), one would not be debugging the expect-lite script itself, but rather one's focused on the integration of the program into the TCL environment. Therefore the following functionality is changed compared to how expect-lite runs in standalone mode.

*INTERACT is be ignored in library mode
*TCL is a method which is ignored during normal expect-lite operation, but in library mode, it enables the calling of native TCL functions from within the embedded expect-lite script. Notes:

*TCL is still line oriented, and should only be used for one line TCL commands, or calls to TCL functions
*TCL has no protection, bad TCL syntax will crash the TCL program
expect-lite timeouts (@number) will not occur on a *TCL line

~include_file is no longer ignored in Library mode (as of v4.6.2). Use *NOINCLUDE to retain v4.1.0 behaviour

19 November 2013
http://expect-lite.sourceforge.net/

this document for version 4.6.2 and above