Parameters follow the usual convention that uppercase is used for scalars and integers, while lowercase is used for normal and associative array. It is always safe for user code to read these parameters. Some parameters may also be set; these are noted explicitly. Others are included in this group as they are set by the function system for the user’s benefit, i.e. setting them is typically not useful but is benign.
It is often also useful to make settable parameters local to a function.
For example, ‘local TCP_SILENT=1
’ specifies that data read during the
function call will not be printed to standard output, regardless of the
setting outside the function. Likewise, ‘local TCP_SESS=
sess’
sets a session for the duration of a function, and ‘local
TCP_PROMPT=
’ specifies that no prompt is used for input during the
function.
tcp_expect_lines
Array. The set of lines read during the last call to tcp_expect
,
including the last ($TCP_LINE
).
tcp_filter
Array. May be set directly. A set of extended globbing patterns which,
if matched in tcp_output
, will cause the line not to be printed to
standard output. The patterns should be defined as described for the
arguments to tcp_expect
. Output of line to log files is not affected.
TCP_HANDLER_ACTIVE
Scalar. Set to 1 within tcp_fd_handler
to indicate to functions
called recursively that they have been called during an editor session.
Otherwise unset.
TCP_LINE
The last line read by tcp_read
, and hence also tcp_expect
.
TCP_LINE_FD
The file descriptor from which $TCP_LINE
was read.
${tcp_by_fd[$TCP_LINE_FD]}
will give the corresponding session name.
tcp_lines
Array. The set of lines read during the last call to tcp_read
,
including the last ($TCP_LINE
).
TCP_LOG
May be set directly, although it is also controlled by tcp_log
.
The name of a file to which output from all sessions will be sent.
The output is proceeded by the usual $TCP_PROMPT
. If it is not an
absolute path name, it will follow the user’s current directory.
TCP_LOG_SESS
May be set directly, although it is also controlled by tcp_log
.
The prefix for a set of files to which output from each session separately
will be sent; the full filename is ${TCP_LOG_SESS}.
sess.
Output to each file is raw; no prompt is added. If it is not an absolute
path name, it will follow the user’s current directory.
tcp_no_spam_list
Array. May be set directly. See tcp_spam
for how this is used.
TCP_OUTPUT
May be set directly. If a non-empty string, any data sent to a session by
tcp_send
will be logged. This parameter gives the prompt to be used
in a file specified by $TCP_LOG
but not in a file generated from
$TCP_LOG_SESS
. The prompt string has the same format as
TCP_PROMPT
and the same rules for its use apply.
TCP_PROMPT
May be set directly. Used as the prefix for data read by tcp_read
which is printed to standard output or to the log file given by
$TCP_LOG
, if any. Any ‘%s
’, ‘%f
’ or ‘%%
’ occurring in the
string will be replaced by the name of the session, the session’s
underlying file descriptor, or a single ‘%
’, respectively. The
expression ‘%c
’ expands to 1 if the session being read is the current
session, else 0; this is most useful in ternary expressions such as
‘%(c.-.+)
’ which outputs ‘+
’ if the session is
the current one, else ‘-
’.
If the prompt starts with %P
, this is stripped and the complete
result of the previous stage is passed through standard prompt %
-style
formatting before being output.
TCP_READ_DEBUG
May be set directly. If this has non-zero length, tcp_read
will give
some limited diagnostics about data being read.
TCP_SECONDS_START
This value is created and initialised to zero by tcp_open.
The functions tcp_read
and tcp_expect
use the shell’s
SECONDS
parameter for their own timing purposes. If that parameter
is not of floating point type on entry to one of the functions, it will
create a local parameter SECONDS
which is floating point and set the
parameter TCP_SECONDS_START
to the previous value of $SECONDS
.
If the parameter is already floating point, it is used without a local
copy being created and TCP_SECONDS_START
is not set. As the global
value is zero, the shell elapsed time is guaranteed to be the sum of
$SECONDS
and $TCP_SECONDS_START
.
This can be avoided by setting SECONDS
globally to a floating point
value using ‘typeset -F SECONDS
’; then the TCP functions will never
make a local copy and never set TCP_SECONDS_START
to a non-zero value.
TCP_SESS
May be set directly. The current session; must refer to one of the
sessions established by tcp_open
.
TCP_SILENT
May be set directly, although it is also controlled by tcp_log
.
If of non-zero length, data read by tcp_read
will not be written to
standard output, though may still be written to a log file.
tcp_spam_list
Array. May be set directly. See the description of the function
tcp_spam
for how this is used.
TCP_TALK_ESCAPE
May be set directly. See the description of the function tcp_talk
for
how this is used.
TCP_TIMEOUT
May be set directly. Currently this is only used by the function
tcp_command
, see above.
The following parameters are not set by the function system, but have a special effect if set by the user.
tcp_on_read
This should be an associative array; if it is not, the behaviour is
undefined. Each key is the name of a shell function or other command,
and the corresponding value is a shell pattern (using EXTENDED_GLOB
).
Every line read from a TCP session directly or indirectly using
tcp_read
(which includes lines read by tcp_expect
) is compared
against the pattern. If the line matches, the command given in the key is
called with two arguments: the name of the session from which the line was
read, and the line itself.
If any function called to handle a line returns a non-zero status, the
line is not output. Thus a tcp_on_read
handler containing only
the instruction ‘return 1
’ can be used to suppress output of
particular lines (see, however, tcp_filter
above). However, the line
is still stored in TCP_LINE
and tcp_lines
; this occurs after all
tcp_on_read
processing.
These parameters are controlled by the function system; they may be read directly, but should not usually be set by user code.
tcp_aliases
Associative array. The keys are the names of sessions established with
tcp_open
; each value is a space-separated list of aliases which refer
to that session.
tcp_by_fd
Associative array. The keys are session file descriptors; each value is the name of that session.
tcp_by_name
Associative array. The keys are the names of sessions; each value is the file descriptor associated with that session.