Document use of mexp_get_pcre_error when calling pcre_get_substring.

virt-p2v uses this, and it surprised me as well.

diff --git a/miniexpect.pod b/miniexpect.pod
index baca020..e27a4cc 100644 (file)
--- a/miniexpect.pod
+++ b/miniexpect.pod
@@ -110,7 +110,7 @@ B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
 
 B<void mexp_set_timeout (mexp_h *h, int secs);>
 
-Get and set the timeout used by C<mexp_expect> (see below).  The
+Get and set the timeout used by C<mexp_expect> [see below].  The
 resolution is milliseconds (1/1000th of a second).  Set this before
 calling C<mexp_expect>.  Passing -1 to either of the C<set_> methods
 means no timeout.  The default setting is 60000 milliseconds (60
@@ -125,10 +125,32 @@ The default is 1024.  Most callers will not need to change this.
 
 B<int mexp_get_pcre_error (mexp *h);>
 
+When C<mexp_expect> [see below] calls the PCRE function
+L<pcre_exec(3)>, it stashes the return value in the C<pcre_error>
+field in the handle, and that field is returned by this method.
+
+There are two uses for this:
+
+=over 4
+
+=item 1.
+
 If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
 error code returned by L<pcre_exec(3)> is available by calling this
 method.  For a list of PCRE error codes, see L<pcreapi(3)>.
 
+=item 2.
+
+A more unusual use is if you ever need to get the captured substrings
+from your regular expression (calling L<pcre_get_substring(3)>).  The
+third parameter of that function (C<stringcount>) is the value
+returned by L<pcre_exec(3)>, and so you can call it like this:
+
+ pcre_get_substring (h->buffer, ovector,
+                     mexp_get_pcre_error (h), 1, &matched);
+
+=back
+
 The following fields in the handle do not have methods, but can be
 accessed directly instead: