/* fget.h -- alternatives to fscanf that die on error. */
/* Last edited on 2004-11-01 22:11:22 by stolfi */

#ifndef fget_H
#define fget_H

/* This module provides alternatives to {fscanf} that will skip
  spaces, then parse one value of a given type, aborting the program
  in case of syntax error or unexpected end-of-file.
  
  Created on Dec/2002 by J. Stolfi, from Modula-3 version ca. 1995,
  inspired on Lex.m3 by L. Cardelli. */

#include <stdio.h>
#include <js.h>

void fget_skip_spaces(FILE *f); 
  /* Skips spaces (SPACE, TAB, NUL) until the first non-space
    character or end-of-file.  Will NOT skip line or page breaks. */

void fget_skip_formatting_chars(FILE *f); 
  /* Skips all blank `formatting' characters --- namely spaces (SPACE,
    TAB, NUL), line breaks (CR, LF), and page breaks (FF, VT) ---
    until the first non-blank character, or end-of-file. */

void fget_match(FILE *f, char *t);
  /* Requires the string {t} to be the next thing on {f}, and
    consumes that string. */

bool fget_test_char(FILE *f, char c);
  /* Checks whether the next character is {c}. If it is, consumes that
    character and returns TRUE. If it is something else (including
    space, line or page break, or end-of-file), returns FALSE and
    leaves the character there. */

/* The following procedures will skip (SPACEs, TABs and NULs; but not
  line or page breaks) before the desired input. */

char fget_char(FILE *f);
  /* Skips spaces, then reads a single character --- which must
    not be a space, line break, or page break. */

char *fget_string(FILE *f);
  /* Skips spaces, then reads zero or more characters, until
    end-of-file or the first formatting character (space, line break,
    or page break), which is not consumed. The result is returned as a
    newly allocated string. */
    
bool fget_bool(FILE *f);
  /* The procedure {fget_bool} will skip spaces, then read a single
    character: 'T','t','1' for TRUE, 'F','f','0' for FALSE. Anything
    else is an error. In particular, if the file contains {TRUE} or
    {FALSE}, only the first letter will be consumed. */
    
int fget_int(FILE *f);
  /* Skips spaces, reads the longest possible non-empty string that
    looks like an integer, and tries to convert it to an {int} value.
    A failure in any of these steps is a fatal error. */

double fget_double(FILE *f);
  /* Skips spaces, reads the longest possible non-empty string that
    looks like a floating-point number (including optional exponent),
    and tries to convert it to a {double} value. A failure in any of
    these steps is a fatal error. */

void fget_eol(FILE *f);
  /* Equivalent to {fget_skip_spaces(f); fget_match(f, "\n")}. */

bool fget_skip_and_test_char(FILE *f, char c);
  /* Equivalent to {fget_skip_spaces(f); fget_test_char(rc, c)}. */

#endif