Introduce methods to access some fields in the handle.

[miniexpect.git] / miniexpect.pod

diff --git a/miniexpect.pod b/miniexpect.pod
index 827a268..baca020 100644 (file)
--- a/miniexpect.pod
+++ b/miniexpect.pod
@@ -85,28 +85,56 @@ in a NULL-terminated array.
 
 =head1 HANDLES
 
-After spawning a subprocess, you get back a handle.  There are various
-fields in this handle which you can read or write:
+After spawning a subprocess, you get back a handle which is a pointer
+to a struct:
 
- struct mexp_h {
-   int fd;
-   pid_t pid;
+ struct mexp_h;
+ typedef struct mexp_h mexp_h;
+
+Various methods can be used on the handle:
+
+B<int mexp_get_fd (mexp_h *h);>
+
+Return the file descriptor of the pty of the subprocess.  You can read
+and write to this if you want, although convenience functions are also
+provided (see below).
+
+B<pid_t mexp_get_pid (mexp_h *h);>
+
+Return the process ID of the subprocess.  You can send it signals if
+you want.
 
-C<fd> is the pty of the subprocess.  You can read and write to this if
-you want, although convenience functions are also provided (see
-below).  C<pid> is the process ID of the subprocess.  You can send it
-signals if you want.
+B<int mexp_get_timeout_ms (mexp_h *h);>
 
-   int timeout;
+B<void mexp_set_timeout_ms (mexp_h *h, int millisecs);>
 
-C<timeout> is the timeout in milliseconds (1/1000th of a second) used
-by C<mexp_expect> (see below).  You can set this before calling
-C<mexp_expect> if you want.  Setting it to -1 means no timeout.  The
-default setting is 60000 (60 seconds).
+B<void mexp_set_timeout (mexp_h *h, int secs);>
 
-   char *buffer;
-   size_t len;
-   size_t alloc;
+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
+seconds).
+
+B<size_t mexp_get_read_size (mexp *h);>
+
+B<void mexp_set_read_size (mexp *h, size_t read_size);>
+
+Get or set the natural size (in bytes) for reads from the subprocess.
+The default is 1024.  Most callers will not need to change this.
+
+B<int mexp_get_pcre_error (mexp *h);>
+
+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)>.
+
+The following fields in the handle do not have methods, but can be
+accessed directly instead:
+
+ char *buffer;
+ size_t len;
+ size_t alloc;
 
 If C<mexp_expect> returns a match then these variables contain the
 read buffer.  Note this buffer does not contain the full input from
@@ -114,7 +142,7 @@ 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;
+ 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
@@ -127,29 +155,13 @@ 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
-subprocess.  The default is 1024.  Most callers will not need to
-change this.
-
-   int pcre_error;
-
-If C<mexp_expect> returns C<MEXP_PCRE_ERROR>, then the actual PCRE
-error code returned by L<pcre_exec(3)> is available here.  For a list
-of PCRE error codes, see L<pcreapi(3)>.
-
-   void *user1;
-   void *user2;
-   void *user3;
+ void *user1;
+ void *user2;
+ void *user3;
 
 Opaque pointers for use by the caller.  The library will not touch
 these.
 
- };
- 
- typedef struct mexp_h mexp_h;
-
 =head1 CLOSING THE HANDLE
 
 To close the handle and clean up the subprocess, call: