guile18/doc/ref/expect.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Expect
   9 @section Expect
  10
  11 The macros in this section are made available with:
  12
  13 @smalllisp
  14 (use-modules (ice-9 expect))
  15 @end smalllisp
  16
  17 @code{expect} is a macro for selecting actions based on the output from
  18 a port.  The name comes from a tool of similar functionality by Don Libes.
  19 Actions can be taken when a particular string is matched, when a timeout
  20 occurs, or when end-of-file is seen on the port.  The @code{expect} macro
  21 is described below; @code{expect-strings} is a front-end to @code{expect}
  22 based on regexec (see the regular expression documentation).
  23
  24 @defmac expect-strings clause @dots{}
  25 By default, @code{expect-strings} will read from the current input port.
  26 The first term in each clause consists of an expression evaluating to
  27 a string pattern (regular expression).  As characters
  28 are read one-by-one from the port, they are accumulated in a buffer string
  29 which is matched against each of the patterns.  When a
  30 pattern matches, the remaining expression(s) in
  31 the clause are evaluated and the value of the last is returned.  For example:
  32
  33 @smalllisp
  34 (with-input-from-file "/etc/passwd"
  35   (lambda ()
  36     (expect-strings
  37       ("^nobody" (display "Got a nobody user.\n")
  38                  (display "That's no problem.\n"))
  39       ("^daemon" (display "Got a daemon user.\n")))))
  40 @end smalllisp
  41
  42 The regular expression is compiled with the @code{REG_NEWLINE} flag, so
  43 that the ^ and $ anchors will match at any newline, not just at the start
  44 and end of the string.
  45
  46 There are two other ways to write a clause:
  47
  48 The expression(s) to evaluate
  49 can be omitted, in which case the result of the regular expression match
  50 (converted to strings, as obtained from regexec with match-pick set to "")
  51 will be returned if the pattern matches.
  52
  53 The symbol @code{=>} can be used to indicate that the expression is a
  54 procedure which will accept the result of a successful regular expression
  55 match.  E.g.,
  56
  57 @smalllisp
  58 ("^daemon" => write)
  59 ("^d(aemon)" => (lambda args (for-each write args)))
  60 ("^da(em)on" => (lambda (all sub)
  61                   (write all) (newline)
  62                   (write sub) (newline)))
  63 @end smalllisp
  64
  65 The order of the substrings corresponds to the order in which the
  66 opening brackets occur.
  67
  68 A number of variables can be used to control the behaviour
  69 of @code{expect} (and @code{expect-strings}).
  70 Most have default top-level bindings to the value @code{#f},
  71 which produces the default behaviour.
  72 They can be redefined at the
  73 top level or locally bound in a form enclosing the expect expression.
  74
  75 @table @code
  76 @item expect-port
  77 A port to read characters from, instead of the current input port.
  78 @item expect-timeout
  79 @code{expect} will terminate after this number of
  80 seconds, returning @code{#f} or the value returned by expect-timeout-proc.
  81 @item expect-timeout-proc
  82 A procedure called if timeout occurs.  The procedure takes a single argument:
  83 the accumulated string.
  84 @item expect-eof-proc
  85 A procedure called if end-of-file is detected on the input port.  The
  86 procedure takes a single argument: the accumulated string.
  87 @item expect-char-proc
  88 A procedure to be called every time a character is read from the
  89 port.  The procedure takes a single argument: the character which was read.
  90 @item expect-strings-compile-flags
  91 Flags to be used when compiling a regular expression, which are passed
  92 to @code{make-regexp} @xref{Regexp Functions}.  The default value
  93 is @code{regexp/newline}.
  94 @item expect-strings-exec-flags
  95 Flags to be used when executing a regular expression, which are
  96 passed to regexp-exec @xref{Regexp Functions}.
  97 The default value is @code{regexp/noteol}, which prevents @code{$}
  98 from matching the end of the string while it is still accumulating,
  99 but still allows it to match after a line break or at the end of file.
 100 @end table
 101
 102 Here's an example using all of the variables:
 103
 104 @smalllisp
 105 (let ((expect-port (open-input-file "/etc/passwd"))
 106       (expect-timeout 1)
 107       (expect-timeout-proc
 108         (lambda (s) (display "Times up!\n")))
 109       (expect-eof-proc
 110         (lambda (s) (display "Reached the end of the file!\n")))
 111       (expect-char-proc display)
 112       (expect-strings-compile-flags (logior regexp/newline regexp/icase))
 113       (expect-strings-exec-flags 0))
 114    (expect-strings
 115      ("^nobody"  (display "Got a nobody user\n"))))
 116 @end smalllisp
 117 @end defmac
 118
 119 @defmac expect clause @dots{}
 120 @code{expect} is used in the same way as @code{expect-strings},
 121 but tests are specified not as patterns, but as procedures.  The
 122 procedures are called in turn after each character is read from the
 123 port, with two arguments: the value of the accumulated string and
 124 a flag to indicate whether end-of-file has been reached.  The flag
 125 will usually be @code{#f}, but if end-of-file is reached, the procedures
 126 are called an additional time with the final accumulated string and
 127 @code{#t}.
 128
 129 The test is successful if the procedure returns a non-false value.
 130
 131 If the @code{=>} syntax is used, then if the test succeeds it must return
 132 a list containing the arguments to be provided to the corresponding
 133 expression.
 134
 135 In the following example, a string will only be matched at the beginning
 136 of the file:
 137
 138 @smalllisp
 139 (let ((expect-port (open-input-file "/etc/passwd")))
 140   (expect
 141      ((lambda (s eof?) (string=? s "fnord!"))
 142         (display "Got a nobody user!\n"))))
 143 @end smalllisp
 144
 145 The control variables described for @code{expect-strings} also
 146 influence the behaviour of @code{expect}, with the exception of
 147 variables whose names begin with @code{expect-strings-}.
 148 @end defmac