summaryrefslogtreecommitdiff
path: root/doc/ref/expect.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/expect.texi')
-rw-r--r--doc/ref/expect.texi142
1 files changed, 0 insertions, 142 deletions
diff --git a/doc/ref/expect.texi b/doc/ref/expect.texi
deleted file mode 100644
index 7e169e428..000000000
--- a/doc/ref/expect.texi
+++ /dev/null
@@ -1,142 +0,0 @@
-@page
-@node Expect
-@chapter Expect
-
-The macros in this section are made available with:
-
-@smalllisp
-(use-modules (ice-9 expect))
-@end smalllisp
-
-@code{expect} is a macro for selecting actions based on the output from
-a port. The name comes from a tool of similar functionality by Don Libes.
-Actions can be taken when a particular string is matched, when a timeout
-occurs, or when end-of-file is seen on the port. The @code{expect} macro
-is described below; @code{expect-strings} is a front-end to @code{expect}
-based on regexec (see the regular expression documentation).
-
-@defmac expect-strings clause @dots{}
-By default, @code{expect-strings} will read from the current input port.
-The first term in each clause consists of an expression evaluating to
-a string pattern (regular expression). As characters
-are read one-by-one from the port, they are accumulated in a buffer string
-which is matched against each of the patterns. When a
-pattern matches, the remaining expression(s) in
-the clause are evaluated and the value of the last is returned. For example:
-
-@smalllisp
-(with-input-from-file "/etc/passwd"
- (lambda ()
- (expect-strings
- ("^nobody" (display "Got a nobody user.\n")
- (display "That's no problem.\n"))
- ("^daemon" (display "Got a daemon user.\n")))))
-@end smalllisp
-
-The regular expression is compiled with the @code{REG_NEWLINE} flag, so
-that the ^ and $ anchors will match at any newline, not just at the start
-and end of the string.
-
-There are two other ways to write a clause:
-
-The expression(s) to evaluate
-can be omitted, in which case the result of the regular expression match
-(converted to strings, as obtained from regexec with match-pick set to "")
-will be returned if the pattern matches.
-
-The symbol @code{=>} can be used to indicate that the expression is a
-procedure which will accept the result of a successful regular expression
-match. E.g.,
-
-@smalllisp
-("^daemon" => write)
-("^d\\(aemon\\)" => (lambda args (for-each write args)))
-("^da\\(em\\)on" => (lambda (all sub)
- (write all) (newline)
- (write sub) (newline)))
-@end smalllisp
-
-The order of the substrings corresponds to the order in which the
-opening brackets occur.
-
-A number of variables can be used to control the behaviour
-of @code{expect} (and @code{expect-strings}).
-Most have default top-level bindings to the value @code{#f},
-which produces the default behaviour.
-They can be redefined at the
-top level or locally bound in a form enclosing the expect expression.
-
-@table @code
-@item expect-port
-A port to read characters from, instead of the current input port.
-@item expect-timeout
-@code{expect} will terminate after this number of
-seconds, returning @code{#f} or the value returned by expect-timeout-proc.
-@item expect-timeout-proc
-A procedure called if timeout occurs. The procedure takes a single argument:
-the accumulated string.
-@item expect-eof-proc
-A procedure called if end-of-file is detected on the input port. The
-procedure takes a single argument: the accumulated string.
-@item expect-char-proc
-A procedure to be called every time a character is read from the
-port. The procedure takes a single argument: the character which was read.
-@item expect-strings-compile-flags
-Flags to be used when compiling a regular expression, which are passed
-to @code{make-regexp} @xref{Regexp Functions}. The default value
-is @code{regexp/newline}.
-@item expect-strings-exec-flags
-Flags to be used when executing a regular expression, which are
-passed to regexp-exec @xref{Regexp Functions}.
-The default value is @code{regexp/noteol}, which prevents @code{$}
-from matching the end of the string while it is still accumulating,
-but still allows it to match after a line break or at the end of file.
-@end table
-
-Here's an example using all of the variables:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd"))
- (expect-timeout 1)
- (expect-timeout-proc
- (lambda (s) (display "Times up!\n")))
- (expect-eof-proc
- (lambda (s) (display "Reached the end of the file!\n")))
- (expect-char-proc display)
- (expect-strings-compile-flags (logior regexp/newline regexp/icase))
- (expect-strings-exec-flags 0))
- (expect-strings
- ("^nobody" (display "Got a nobody user\n"))))
-@end smalllisp
-@end defmac
-
-@defmac expect clause @dots{}
-@code{expect} is used in the same way as @code{expect-strings},
-but tests are specified not as patterns, but as procedures. The
-procedures are called in turn after each character is read from the
-port, with two arguments: the value of the accumulated string and
-a flag to indicate whether end-of-file has been reached. The flag
-will usually be @code{#f}, but if end-of-file is reached, the procedures
-are called an additional time with the final accumulated string and
-@code{#t}.
-
-The test is successful if the procedure returns a non-false value.
-
-If the @code{=>} syntax is used, then if the test succeeds it must return
-a list containing the arguments to be provided to the corresponding
-expression.
-
-In the following example, a string will only be matched at the beginning
-of the file:
-
-@smalllisp
-(let ((expect-port (open-input-file "/etc/passwd")))
- (expect
- ((lambda (s eof?) (string=? s "fnord!"))
- (display "Got a nobody user!\n"))))
-@end smalllisp
-
-The control variables described for @code{expect-strings} also
-influence the behaviour of @code{expect}, with the exception of
-variables whose names begin with @code{expect-strings-}.
-@end defmac