lib/sfl-istream.h

   1 /* A string or file based input stream, that keeps track of a line number.
   2    Copyright (C) 2024 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as
   6    published by the Free Software Foundation, either version 3 of the
   7    License, or (at your option) any later version.
   8
   9    This file is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 /* Written by Bruno Haible <bruno@clisp.org>, 2024.  */
  18
  19 #ifndef _SFL_ISTREAM_H
  20 #define _SFL_ISTREAM_H
  21
  22 #include "sf-istream.h"
  23
  24 /* An input stream type that can read from a file or from a string
  25    and that keeps track of a line number.  */
  26 typedef struct sfl_istream sfl_istream_t;
  27 struct sfl_istream
  28 {
  29   sf_istream_t istream;
  30   size_t line_number;
  31 };
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /* Initializes STREAM to read from FP.
  38    FP must be a FILE stream open for reading.  */
  39 extern void sfl_istream_init_from_file (sfl_istream_t *stream, FILE *fp);
  40 /* Initializes STREAM to read from a NUL-terminated string INPUT.
  41    The contents of INPUT must stay available and unchanged as long as STREAM
  42    is in use.  */
  43 extern void sfl_istream_init_from_string (sfl_istream_t *stream,
  44                                           const char *input);
  45 /* Initializes STREAM to read from a string INPUT.
  46    The contents of INPUT must stay available and unchanged as long as STREAM
  47    is in use.  Operations on STREAM will not modify the contents of INPUT.  */
  48 extern void sfl_istream_init_from_string_desc (sfl_istream_t *stream,
  49                                                string_desc_t input);
  50
  51 /* Sets the current line number of STREAM.  */
  52 extern void sfl_set_line_number (sfl_istream_t *stream, size_t line_number);
  53
  54 /* Returns the current line number of STREAM.  */
  55 extern size_t sfl_get_line_number (sfl_istream_t *stream);
  56
  57 /* Reads a single 'char' from STREAM, and returns it as an 'unsigned char'.
  58    Returns EOF when the end of stream was already reached.  */
  59 extern int sfl_getc (sfl_istream_t *stream);
  60
  61 /* Tests whether STREAM has encountered an error.
  62    You may want to call this function after sf_getc (stream) has
  63    returned EOF; in other situations it is guaranteed to return 0.  */
  64 extern int sfl_ferror (sfl_istream_t *stream);
  65
  66 /* Assuming that C was the last value returned by sf_getc (stream),
  67    this call pushes back C onto the stream.
  68    Only 1 character of pushback is guaranteed.  */
  69 extern void sfl_ungetc (sfl_istream_t *stream, int c);
  70
  71 /* Frees all memory held by STREAM.
  72    This call has no effect on the arguments provided to sfl_istream_init_*.  */
  73 extern void sfl_free (sfl_istream_t *stream);
  74
  75 #ifdef __cplusplus
  76 }
  77 #endif
  78
  79 #endif /* _SFL_ISTREAM_H */