diff --git a/doc/chat.doc b/doc/chat.doc index 793e373..20c4ff9 100644 --- a/doc/chat.doc +++ b/doc/chat.doc @@ -1,16 +1,29 @@ -(chat ...) +------------------------------------------------------------------------------- +(CHAT ...) -> values syntax -dynvars: $task $chat-cont $chat-abort-re $chat-timeout +Chat introduces a programmed conversation with a given task. Within +the body expressions, the LOOK-FOR and SEND functions are intended to +either wait for an output of the task, or to send a message to the +task respectively. Furthermore, there are some side-effecting +functions that set some options for this chat. (look-for* re [on-timeout]) -(look-for re [on-timeout ...]) +(look-for re [ ...]) + +LOOK-FOR waits until a portion of the task's output matches the given +regular expression. The optional second argument of LOOK-FOR*, or the +body expressions in the LOOK-FOR macro, are executed if the output of +the task does not match within the time specified by the CHAT-TIMEOUT +option (see below). (send fmt arg ...) (send/cr fmt arg ...) -logging output funs? +SEND simply writes a formatted string to the input-port of the task +(see FORMAT). SEND/CR adds a carriage-return character to the end of +the string. -side-effecting option setting +Side-effecting option setting functions: (chat-abort ) if this regular expression is matched, the chat call is aborted. (chat-timeout ) @@ -18,17 +31,17 @@ side-effecting option setting (chat-monitor ) monitor has to be a function taking two arguments (event val), where event is a symbol, and val a possible value for this - event: + event. The events and the possible type of value are: - looking-for(re) - found(match) - new-input(text) - sending(text) - - abort(text) + - abort(match) - eof - timeout chat can return the following values: - 'eof - 'timeout if no timeout-handler was specified in a look-for clause - - in case of an abortion the submatch of the abort-regexp + - in case of an abortion the match of the abort-regexp - #f if the whole body evaluated normally