.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.36.
.\" Man Page for expect-lite - initial version - created 7/19/2010
.\" Updated Man Page for expect-lite - version 3.7.0	7/31/2010
.\" Updated Man Page for expect-lite - version 4.0.x	9/28/2011
.\" Updated Man Page for expect-lite - version 4.0.2	10/8/2011
.\" Updated Man Page for expect-lite - version 4.3.0	3/25/2012
.\" Updated Man Page for expect-lite - version 4.4.0	12/16/2012
.\" Updated Man Page for expect-lite - version 4.5.0	2/18/2013
.\" Updated Man Page for expect-lite - version 4.6.0	5/25/2013
.\" Updated Man Page for expect-lite - version 4.6.2	11/17/2013
.\" Updated Man Page for expect-lite - version 4.7.0	4/20/2014
.\" Updated Man Page for expect-lite - version 4.7.2	7/22/2014
.\" Updated Man Page for expect-lite - version 4.8.0	1/15/2015
.\" Updated Man Page for expect-lite - version 4.9.0	8/15/2015
.\"
.TH EXPECT-LITE "1" "August 2015" "expect-lite version 4.9.0" "User Commands"
.SH NAME
expect-lite \- a quick and easy command line automation tool
.SH SYNOPSIS
.B expect-lite 
[\fI\-vv\fR] \fI-c <script>\fR [\fI-r <host>\fR]  [\fICONSTANT=value\fR] [\fI*DIRECTIVE\fR] [-h|--help]
.br
or
.br
.B script.elt 
[\fI\-vv\fR]  [\fIr=<host>\fR] [\fICONSTANT=value\fR] [\fI*DIRECTIVE\fR] [-h|--help]
.SH DESCRIPTION
.ds sd \fIexpect-lite\fP
.PP
Written in Expect, it is designed to directly map an interactive terminal session into an
automation script. expect-lite scripts use punctuation character(s) at the beginning of each line
to indicate the action. Basic expect-lite scripts can be created by simply cutting and pasting
text from a terminal window into a script, and adding \fB>\fR \fB<\fR characters. Knowledge of
Expect is not required.

.PP
usage: expect\-lite remote_host=<remote_host_IP> cmd_file=<command_file> [user_dir=<user_dir>] [const1=value1] [*DIRECTIVE]
.PP
or short form: expect\-lite r=<remote_host_IP> c=<command_file> [d=<user_dir>] [const1=value1] [*DIRECTIVE]
.IP
eg. ./expect\-lite r=host\-008  c=pm_alt.elt  d=/local/sw myvar=myvalue *NOCOLOR
.TP
additional login options: user_name=<username> user_password=<password>
.IP
eg. ./expect\-lite r=host\-008 c=pm_alt.elt u=superuser p=mysecret
.PP
additional debug options: \fB\-v\fR|\fB\-vv\fR|\fB\-\-verbose\fR
.TP
\fB\-v\fR
prints warnings, and infos (i.e. conditionals, dynamic var assignments)
.TP
\fB\-vv\fR|\fB\-\-verbose\fR
prints warnings and debug (i.e. expect match info)
.TP
eg. ./expect\-lite \-v r=host\-008 c=pm_alt.elt
.PP
user defined help options: \fB\-h\fR|\fB\-\-help\fR
.IP
displays user defined help text (demarcated by ;;;) and variables defined in script which can be overridden by constants on the command line
.PP

.SH
COMMAND SYNOPSIS
.PP
This  is  just a brief synopsis of \*(sd commands to serve as a reminder to those who already
know \*(sd;  other  documentation  (such  as  the  html  document)  must  be  consulted  for 
more complete descriptions.
.SS
Special Characters
.TP
>
wait for a prompt, then send string to the remote host
.TP
>>
send string to remote host, without waiting for prompt 

.TP
<
string/regex MUST be received from the remote host in the allotted timeout or the script will FAIL! 
.TP
<< 	
literal string MUST be received (similar to '<' without regex evaluation)
.TP
-<
NOT expect, if string/regex IS received from the remote host the script will FAIL! 
.TP
~<
fuzzy expect, expect an approximate number (decimal or hex)
.TP
#
used to indicate comment lines, and have no effect
.TP
;
are also used to indicate comment lines, but are printed to stdout (for logging)
.TP
;<colour> comment
add custom colour comment lines, colour may be blue, ltblue, gray, ltgray, cyan, black, pink, purple, red, green, yellow
.TP
;;
similar to above, but no extra newlines are printed (useful for printing script help)
.TP
;;;
marks beginning and ending of a block of help text. Help Text is user defined help for a script and is printed when -h or --help is on the command line
.TP
@num
changes the expect timeout to num of seconds
.TP
:num
sleeps for num seconds. Mili-seconds also supported e.g. :1.005 is 1005 mili-seconds
.TP
$var=
static variable assignment at script invocation. Variable names limited to letters, numbers, and underscore 
.TP
+$var=
.RI
dynamic variable assignment  
.TP
+$var
increment value of $var by 1 decimal 
.TP
-$var
decrement value of $var by 1 decimal
.TP
=$var
math functions, perform bitwise and arithmetic operations:  << >> & | ^ * / % + - (see math functions)
.TP
=$str
string math functions, if $str is a string, perform string operations: //search/replace/ + - (see string math functions in documentation)
.TP
!
indicates an embedded expect line 
.TP
?
c-style if/then/else in the format ?cond?action::else_action. code block are also supported in the action and else_action statements. e.g. 
.br
.RS 10
?if $i < $n ? [
.br
   >send string
.br
   <expect string
.br
]::[
  >send else string
.br
  <expect else string
.br
]
.RE
.TP
[ 
While Loop, using code blocks e.g.
.br
.RS 10
[ $i < $n
.br
   +$i
.br
]
.RE
.IP
Foreach Loop, using code blocks, each iteration $item is assigned the next item in the list. List \fBmust\fR be space delimited e.g.
.br
.RS 10
$thelist=ab cd ef
.br
[ $item=$thelist
.br
    >echo $item
.br
]
.RE
.TP
%
label - used for jumping to labels 
.TP
~\fIfilename\fP [constant=value] [constant=value with spaces] 
includes a expect-lite script file, useful for creation of common variable files, or 'subprograms/subroutines'. Can pass optional parameters which will override (as constants) the variables in the include file. Constant values passed may have spaces, no quotes are required
.PP
.SS
Directives
.TP
*~\fIfilename\fP
Include a fail script, which expect-lite runs only if the main script fails 
.TP
*/prompt/
Set a user defined prompt (defined in regex)
.TP
*TERM <N>
Immediately terminates script, and returns the value of N, if N is not specified returns 0
.TP
*PASS
Immediately terminates script, and returns 0 (pass) 
.TP
*FAIL
Immediately fails script, and returns 1 (fail), unless *NOFAIL is set, then script will run to completion, and return 1 
.TP
*NOFAIL
Script will run to completion, and returns 1, if failure occurred during execution, or 0, if pass (it is a sticky flag, and can not be unset)
.TP
**SHELL=<shell>
Configuration directive which sets the shell immediately after automatic login to remote host (see setting the shell)
.TP
*INTERACT
A breakpoint which places user in interact mode, and pauses the script and turns control of the keyboard over to the user 
.TP
*NOINTERACT
Once set, will ignore all succeeding breakpoints (*INTERACT). This permits running a  script or scripts in an unattended regression. This can not be unset (it is a sticky flag)
.TP
*FORK <session>
Multiple session support. Directs expect-lite to open a new session and spawns a new shell 
.TP
*SHOW VARS
Debug information, displays all expect-lite variables. Can be used in interact mode.
.TP
*SHOW ENV
Debug information, displays expect-lite environment, including state of directives, infinite loop counter, log file name (if used), and environment variables. Can be used in interact mode.
.TP
*INFINITE_LOOP N
Infinite loop protection value, sets N as new value
.TP
*EOLS LF|*EOLS CRLF
Controls end of line sequence sent to remote host, either line feed, or carriage return + line feed.
.TP
*DVPROMPT|*NODVPROMPT
Enable/disable the Dynamic Variable capture method to require a trailing prompt (default=*DVPROMPT).
.TP
*NOINCLUDE
Once set, will ignore all succeeding include files (lines starting with ~). This was the default behaviour in Library mode (introduced in v4.1). This behaviour is no longer default, and this directive provides a method to previous behavior.

.P
.SS
Logging
.PP
Logging encompasses two operations: 1) writing script output to a file, 2) controlling additional messages, such as info, exp_info and warnings. All logging commands when used on the CLI will override those inside the script
.TP
*LOG|*NOLOG
Enable/disable logging of standard out and messages to a file. The log file name will be <script_name>.log saved in the script directory.(see Environment Variable EL_LOG_EXT below)
.TP
*LOG <file_name>|*LOGAPPEND <file_name>
Enable logging to a user specified path/file_name. When invoked on the CLI, the specified file_name must end in ".log" (or as defined by EL_LOG_EXT) to avoid ambiguity 
.TP
*INFO|*NOINFO
Enable/disable informational messages
.TP
*EXP_INFO|*NOEXP_INFO
Enable/disable "expected" messages (additionally use -V flag to enable) 
.TP
*WARN|*NOWARN
Enable/disable warning messages
.TP
*DEBUG|*NODEBUG
Enable/disable debug messages
.TP
*NOCOLOR
Disables color on stdout
.TP
*TIMESTAMP <ISO|YMD|DMY|MDY>
Prints Date and Timestamp with milisecond accuracy, for each command sent, ISO is default. Timestamps will be written to log file when *LOG is used.
.TP
*NOTIMESTAMP
Disables timestamp printing


.P

.SS 
Environment Variables 
.PP
It is no longer necessary to hand edit the expect-lite script itself. All parameters such as connect_method, login name and password are controlled via shell environment variables. This permits individual customization in a multi user environment. It is recommended to save these values in \fI.expect-literc\fR and source it from .bashrc or .cshrc. If set, the following environment variables will be used:
.TP
EL_CONNECT_METHOD
The method expect-lite uses to connect to remote host. Valid options are: none|telnet|ssh|ssh_key Default is none
.TP
EL_CONNECT_USER
User name to use for login on remote host (telnet|ssh)
.TP
EL_CONNECT_PASS
Password to use for login on remote host (telnet|ssh)
.TP
EL_INFINITE_LOOP=N
Infinite loop protection value, sets N to user's default value
.TP
EL_DELAY_WAIT_FOR_HOST
Delay (in ms) to wait for host in Not Expect, and Dynamic Var Capture. 100 ms is a good value for a local LAN, 200 ms if running across high speed internet
.TP
EL_REMOTE_HOST
Name or IP of remote host
.TP
EL_CMD_FILE
Name of expect-lite script to run
.TP
EL_USER_DIR
Change to this directory upon login before executing script
.TP
EL_SHELL
Start this shell (default bash) when using EL_CONNECT_METHOD=none
.TP
EL_DYN_VAR_PROMPT
Set the Dynamic Variable capture method to require a prompt (default=1). Disable by setting to 0.
.TP
EL_LOG_EXT
Set the log file name extension string (default=".log") which is appended to the script name when using *LOG without file name argument or used to detect a log file name on the command line.
.TP
EL_*
Any other shell environment variables starting with EL_ will become constants
.PP



.SS
Debugger (IDE)
.PP
The debugger performs three primary functions: 1) connecting the user to the remote host or device under test, 2) monitoring special commands prefaced with the escape key for stepping, and other functions, and 3) the debugger will allow expect-lite script lines to be executed by either typing directly or pasting them into the IDE.
.PP
The debugger is invoked at a breakpoint by placing the *INTERACT command in the script, or using by instant-interact at anytime during the script execution by pressing ctrl+backslash ^\\
.TP
<esc>s
Step, execute next step in script
.TP
<esc>k
sKip next step in script
.TP
<esc>c
Continue execution of the script
.TP
<esc>v
show Vars, display expect-lite variables and values
.TP
<esc>e
show Environment, display expect-lite environment
.TP
<esc>0to9
display next N lines of script
.TP
<esc>-1to-9
display last N lines of script
.TP
ctrl+d
Quit & Exit expect-lite
.TP
<esc>h
display Help
.TP
[pasted line(s)]
execute any pasted line(s) from a script into the IDE
.TP
[type any expect-lite line]
execute any typed expect-lite script line 



.SH AUTHOR
Written by Craig Miller
.SH "REPORTING BUGS"
Report bugs to <cvmiller at gmail dot com>.
.SH COPYRIGHT
Copyright \(co 2008-2015 Craig Miller
.br
Copyright \(co 2005-2007 FreeScale Semiconductor and Craig Miller
.br
License BSD-Style: 
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "SEE ALSO"
The full documentation for 
.B
expect-lite
is maintained as an HTML manual. Please see http://expect-lite.sf.net/ for complete documentation.