#ifndef _LINEREADER_H_5b3c5d8f_
#define _LINEREADER_H_5b3c5d8f_

/* This file is in the public domain. */

/*
 * Package for reading lines from text files.
 *
 * LINEREADER is an opaque type, internals private to linereader.c,
 *  representing a stream-of-lines source coming from a file
 *  descriptor.
 *
 * A LINEREADER assumes it owns the file descriptor, while it exists.
 *  lr_done() releases the fd back to the caller, but with nothing
 *  promised about where its seek pointer points, not even if
 *  lr_getline() indicated EOF.
 */
typedef struct linereader LINEREADER;

/*
 * Create a LINEREADER.  The argument is a file descriptor, open for
 *  (at least) reading onto the file.  The return value is a handle to
 *  be passed to the other functions.
 */
extern LINEREADER *lr_setup(int);

/*
 * Close down a LINEREADER.  Frees up all internal data.  Does not
 *  close the file descriptor.
 */
void lr_done(LINEREADER *);

/*
 * Get a line.  Return value is LINE if we got a line, EOF if we
 *  reached EOF, or ERROR if an error of some sort occurred.  The first
 *  time ERROR is returned for a given LINEREADER, errno will be set
 *  appropriately; later calls will return ERROR as well, without
 *  touching errno.
 *
 * To actually get at the line, use lr_ptr() and/or lr_lineno().
 */
typedef enum {
	  LRGL_LINE = 1,
	  LRGL_EOF,
	  LRGL_ERROR,
	  } LRGLSTAT;
extern LRGLSTAT lr_getline(LINEREADER *);

/*
 * If lr_getline() returns LRGL_LINE, call this to get a pointer to the
 *  line.  As indicated by the const on the return value, you should
 *  not write through the returned pointer.  The memory remains valid
 *  up until the next lr_getline() or lr_done() call on the LINEREADER.
 */
extern const char *lr_ptr(LINEREADER *);

/*
 * If lr_getline() returns LRGL_LINE, call this to get the line number
 *  of the line.  The first line is number 1, not 0.
 */
extern int lr_lineno(LINEREADER *);

#endif