#ifndef WH_LESS_H_e0c9c1c2_
#define WH_LESS_H_e0c9c1c2_

/*
 * Stuff for running less(1) to display text.
 *
 * The paradigm is that we create a less(1) process with less_start().
 *  We then write text to it by calling less_send().  To end the text
 *  and wait for the less process to exit, call less_done().  To abort
 *  the whole operation at any point, call less_abort().
 *
 * Once we call less_start(), we cannot do anything but call
 *  less_send() zero or more times, then finally less_done(), after
 *  which we are back to normal operation...except that, at any point
 *  after less_start(), we can instead call less_abort() to abort the
 *  whole thing.
 */

/*
 * Opaque handle type.
 */
typedef struct less LESS;

/*
 * Start a less(1) instance.  This returns a LESS * handle which must
 *  be passed to the rest of the routines.
 *
 * As outlined above, this relinquishes control of the UI.  No further
 *  user interaction can take place beyond sending text to the less
 *  instance until less_abort() or less_done() is called.
 *
 * If this encounters an unexpected error, it will pline() an error
 *  message and return nil.  In this case, no net effect on the UI
 *  occurs.
 */
extern LESS *less_start(void);

/*
 * Send text to the less instance.
 *
 * Arglist is
 *	LESS *less
 *	const char *text
 *	int textlen
 *	unsigned int flags
 *
 * If textlen is -1, strlen(text) is used instead.  flags can be zero
 *  or more of
 *
 *	LESS_BLOCKING
 *		If specified, blocks until the whole string is sent or
 *		an error occurs.  If not specified, may return with the
 *		string partially unwritten.
 *
 * Return value is the number of bytes successfully written, or -1 if
 *  an error occurred.
 *
 * If LESS_BLOCKING was specified, the return value is always either -1
 *  or the full length.  If it's -1, some of the text may have been
 *  written before the error; there is no way to tell how much.
 *
 * When LESS_BLOCKING is not specified, any return value >=0 is
 *  non-erroneous.
 */
extern int less_send(LESS *, const char *, int, unsigned int);
#define LESS_BLOCKING 0x00000001

/*
 * Send EOF to the less isntance, then wait until the user quits out of
 *  it.  Once this returns, the LESS * is invalid and must not be used
 *  further.
 *
 * In certain unlikely error cases this can pline() an error message.
 *  It still terminates the less process and returns control to the UI.
 */
extern void less_done(LESS *);

/*
 * Abort the whole operation.  This closes the LESS instance, killing
 *  the process ungracefully.  This has the same consequences for the
 *  LESS * that less_done() does.
 */
extern void less_abort(LESS *);

#endif