Document behaviour when matching against multiple regular expressions.

[miniexpect.git] / miniexpect.pod

diff --git a/miniexpect.pod b/miniexpect.pod
index f17cda9..b4f0edc 100644 (file)
--- a/miniexpect.pod
+++ b/miniexpect.pod
@@ -18,21 +18,23 @@ miniexpect - A very simple expect library for C.
  }
  mexp_close (h);
 
- cc prog.c -o prog -lminiexpect
+ cc prog.c -o prog -lminiexpect -lpcre
 
 =head1 DESCRIPTION
 
-miniexpect is a very simple expect-like library for C.
+Miniexpect is a very simple expect-like library for C.  Expect is a
+way to control an external program that wants to be run interactively.
 
-It has a saner interface than libexpect, and doesn't depend on Tcl.
-It is also thread safe, const-correct and uses modern C standards.
+Miniexpect has a saner interface than libexpect, and doesn't depend on
+Tcl.  It is also thread safe, const-correct and uses modern C
+standards.
 
-It is standalone, except that it requires the PCRE (Perl Compatible
-Regular Expressions) library from http://www.pcre.org/.  The PCRE
-dependency is fundamental because we want to offer the most powerful
-regular expression syntax to match on, but more importantly because
-PCRE has a convenient way to detect partial matches which made this
-library very simple to implement.
+Miniexpect is a standalone library, except for a single dependency: it
+requires the PCRE (Perl Compatible Regular Expressions) library from
+L<http://www.pcre.org/>.  The PCRE dependency is fundamental because
+we want to offer the most powerful regular expression syntax to match
+on, but more importantly because PCRE has a convenient way to detect
+partial matches which made this library very simple to implement.
 
 This manual page documents the API.  Examples of how to use the API
 can be found in the source directory.
@@ -112,6 +114,19 @@ the process, but it will contain at least the part matched by the
 regular expression (and maybe some more).  C<buffer> is the read
 buffer and C<len> is the number of bytes of data in the buffer.
 
+   ssize_t next_match;
+
+If C<mexp_expect> returns a match, then C<next_match> points to the
+first byte in the buffer I<after> the fully matched expression.  (It
+may be C<-1> which means it is invalid).  The next time that
+C<mexp_expect> is called, it will start by consuming the data
+C<buffer[next_match...len-1]>.  Callers may also need to read from
+that point in the buffer before calling L<read(2)> on the file
+descriptor.  Callers may also set this, for example setting it to
+C<-1> in order to ignore the remainder of the buffer.  In most cases
+callers can ignore this field, and C<mexp_expect> will just do the
+right thing when called repeatedly.
+
    size_t read_size;
 
 Callers may set this to the natural size (in bytes) for reads from the
@@ -242,6 +257,29 @@ for EOF or timeout.
 C<regexps[].re>, C<regexps[].extra>, C<regexps[].options>, C<ovector>
 and C<ovecsize> are passed through to the L<pcre_exec(3)> function.
 
+=item *
+
+If multiple regular expressions are passed, then they are checked in
+turn and the I<first> regular expression that matches is returned
+I<even if the match happens later in the input than another regular
+expression>.
+
+For example if the input is C<"hello world"> and you pass the two
+regular expressions:
+
+ regexps[0].re = world
+ regexps[1].re = hello
+
+then the first regular expression (C<"world">) may match and the
+C<"hello"> part of the input may be ignored.
+
+In some cases this can even lead to unpredictable matching.  In the
+case above, if we only happened to read C<"hello wor">, then the
+second regular expression (C<"hello">) I<would> match.
+
+If this is a concern, combine your regular expressions into a single
+one, eg. C<(hello)|(world)>.
+
 =back
 
 =head2 mexp_expect example
@@ -261,7 +299,7 @@ compiler, you can just use a local variable instead.
  char *errptr;
  int offset;
  pcre *password_re, *prompt_re;
- int ovecsize = 12;
+ const int ovecsize = 12;
  int ovector[ovecsize];
  
  password_re = pcre_compile ("assword", 0, &errptr, &offset, NULL);
@@ -302,8 +340,25 @@ B<int mexp_printf (mexp_h *h, const char *fs, ...);>
 
 This returns the number of bytes, if the whole message was written OK.
 If there was an error, -1 is returned and the error is available in
-C<errno>.  Note that this function will not do a partial write.  If it
-cannot write all the data, then it will return an error.
+C<errno>.
+
+Notes:
+
+=over 4
+
+=item *
+
+C<mexp_printf> will not do a partial write.  If it cannot write all
+the data, then it will return an error.
+
+=item *
+
+This function does not write a newline automatically.  If you want to
+send a command followed by a newline you have to do something like:
+
+ mexp_printf (h, "exit\n");
+
+=back
 
 =head1 SOURCE