#ifndef _GETLINE_H_5bca6261_
#define _GETLINE_H_5bca6261_

/*
 * Abstraction encapsulating the "read input and accumulate lines"
 *  operation.
 */

#include <stdio.h>

/*
 * Encapsulation of state.  This is opaque to callers of this package.
 */
typedef struct linegetter LINEGETTER;

/*
 * Set up to accumulate lines.  Input comes from the argument FILE *.
 *  (If you want input to come from somewhere else, wrap a FILE *
 *  around it.)
 */
extern LINEGETTER *lg_init(FILE *);

/*
 * Read input and accumulate a line.  The line is returned,
 *  NUL-terminated with the newline stripped off.  The pointed-to
 *  memory is owned by the LINEGETTER and remains valid until either
 *  (a) lg_getline is called again on the same LINEGETTER or (b)
 *  lg_done is called on it.
 *
 * If EOF is reached mid-line (ie, the last line doesn't end with a
 *  newline), a newline is, effectively, silently supplied.
 *
 * If a line ends with a CRLF instead of a newline, the CRLF is
 *  effectively converted to a newline - that is, it operates as a line
 *  ending.  CRs occurring other than immediately before LFs get no
 *  special treatment.  NULs get no special treatment, but, since the
 *  line is returned NUL-terminated rather than a pointer-and-length,
 *  they will effectively truncate the line where they occur.
 */
extern char *lg_getline(LINEGETTER *);

/*
 * Shut down the LINEGETTER.  This frees all associated storage.  It
 *  does not do anything to the underlying FILE *.
 */
extern void lg_done(LINEGETTER *);

#endif