Simplify input stream API

4 files changed, 136 insertions, 24 deletions

diff --git a/include/serd/input_stream.h b/include/serd/input_stream.h
new file mode 100644
index 00000000..cc63e694
--- /dev/null
+++ b/include/serd/input_stream.h
@@ -0,0 +1,90 @@
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef SERD_INPUT_STREAM_H
+#define SERD_INPUT_STREAM_H
+
+#include "serd/attributes.h"
+#include "serd/status.h"
+#include "serd/stream.h"
+#include "zix/attributes.h"
+
+SERD_BEGIN_DECLS
+
+/**
+   @defgroup serd_input_stream Input Streams
+   @ingroup serd_reading_writing
+
+   An input stream is used for reading input as a raw stream of bytes.  It is
+   compatible with standard C `FILE` streams, but allows different functions to
+   be provided for things like reading from a buffer or a socket.
+
+   @{
+*/
+
+/// An input stream that produces bytes
+typedef struct {
+  void* ZIX_NULLABLE         stream; ///< Opaque parameter for functions
+  SerdReadFunc ZIX_NONNULL   read;   ///< Read bytes from input
+  SerdErrorFunc ZIX_NULLABLE error;  ///< Stream error accessor
+  SerdCloseFunc ZIX_NULLABLE close;  ///< Close input
+} SerdInputStream;
+
+/**
+   Open a stream that reads from a provided function.
+
+   @param read_func Function to read input.
+   @param error_func Function used to detect errors.
+   @param close_func Function to close the stream after reading is done.
+   @param stream Opaque stream parameter for functions.
+
+   @return An opened input stream, or all zeros on error.
+*/
+SERD_CONST_API SerdInputStream
+serd_open_input_stream(SerdReadFunc ZIX_NONNULL   read_func,
+                       SerdErrorFunc ZIX_NONNULL  error_func,
+                       SerdCloseFunc ZIX_NULLABLE close_func,
+                       void* ZIX_NULLABLE         stream);
+
+/**
+   Open a stream that reads from a string.
+
+   The string pointer that position points to must remain valid until the
+   stream is closed.  This pointer serves as the internal stream state and will
+   be mutated as the stream is used.
+
+   @param position Pointer to a valid string pointer for use as stream state.
+   @return An opened input stream, or all zeros on error.
+*/
+SERD_CONST_API SerdInputStream
+serd_open_input_string(const char* ZIX_NONNULL* ZIX_NONNULL position);
+
+/**
+   Open a stream that reads from a file.
+
+   An arbitrary `FILE*` can be used with serd_open_input_stream() as well, this
+   convenience function opens the file properly for reading with serd, and sets
+   flags for optimized I/O if possible.
+
+   @param path Path of file to open and read from.
+*/
+SERD_API SerdInputStream
+serd_open_input_file(const char* ZIX_NONNULL path);
+
+/**
+   Close an input stream.
+
+   This will call the close function, and reset the stream internally so that
+   no further reads can be made.  For convenience, this is safe to call on
+   NULL, and safe to call several times on the same input.
+*/
+SERD_API SerdStatus
+serd_close_input(SerdInputStream* ZIX_NULLABLE input);
+
+/**
+   @}
+*/
+
+SERD_END_DECLS
+
+#endif // SERD_INPUT_STREAM_H
diff --git a/include/serd/reader.h b/include/serd/reader.h
index c79d6a44..4c669342 100644
--- a/include/serd/reader.h
+++ b/include/serd/reader.h
@@ -5,15 +5,14 @@
 #define SERD_READER_H
 
 #include "serd/attributes.h"
+#include "serd/input_stream.h"
 #include "serd/node.h"
 #include "serd/sink.h"
 #include "serd/status.h"
-#include "serd/stream.h"
 #include "serd/syntax.h"
 #include "serd/world.h"
 #include "zix/attributes.h"
 
-#include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
@@ -56,31 +55,23 @@ SERD_API void
 serd_reader_add_blank_prefix(SerdReader* ZIX_NONNULL  reader,
                              const char* ZIX_NULLABLE prefix);
 
-/// Prepare to read from the file at a local file `uri`
-SERD_API SerdStatus
-serd_reader_start_file(SerdReader* ZIX_NONNULL reader,
-                       const char* ZIX_NONNULL uri,
-                       bool                    bulk);
-
 /**
-   Prepare to read from a stream.
+   Prepare to read some input.
 
-   The `read_func` is guaranteed to only be called for `page_size` elements
-   with size 1 (i.e. `page_size` bytes).
+   This sets up the reader to read from the given input, but will not read any
+   bytes from it.  This should be followed by serd_reader_read_chunk() or
+   serd_reader_read_document() to actually read the input.
+
+   @param reader The reader.
+   @param input An opened input stream to read from.
+   @param input_name The name of the input stream for error messages.
+   @param block_size The number of bytes to read from the stream at once.
 */
 SERD_API SerdStatus
-serd_reader_start_stream(SerdReader* ZIX_NONNULL         reader,
-                         SerdReadFunc ZIX_NONNULL        read_func,
-                         SerdStreamErrorFunc ZIX_NONNULL error_func,
-                         void* ZIX_NONNULL               stream,
-                         const SerdNode* ZIX_NULLABLE    name,
-                         size_t                          page_size);
-
-/// Prepare to read from a string
-SERD_API SerdStatus
-serd_reader_start_string(SerdReader* ZIX_NONNULL      reader,
-                         const char* ZIX_NONNULL      utf8,
-                         const SerdNode* ZIX_NULLABLE name);
+serd_reader_start(SerdReader* ZIX_NONNULL      reader,
+                  SerdInputStream* ZIX_NONNULL input,
+                  const SerdNode* ZIX_NULLABLE input_name,
+                  size_t                       block_size);
 
 /**
    Read a single "chunk" of data during an incremental read.
diff --git a/include/serd/serd.h b/include/serd/serd.h
index 5b13f676..58c8e7ec 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -78,6 +78,7 @@
    @{
 */
 
+#include "serd/input_stream.h"
 #include "serd/reader.h"
 #include "serd/stream.h"
 #include "serd/writer.h"
diff --git a/include/serd/stream.h b/include/serd/stream.h
index 4b3582f5..f59e2c9d 100644
--- a/include/serd/stream.h
+++ b/include/serd/stream.h
@@ -33,10 +33,19 @@ SERD_BEGIN_DECLS
 typedef int (*SerdStreamErrorFunc)(void* ZIX_NONNULL stream);
 
 /**
+   Function to close an I/O stream.
+
+   Identical semantics to `fclose`.
+
+   @return Non-zero if `stream` has encountered an error.
+*/
+typedef int (*SerdStreamCloseFunc)(void* ZIX_NONNULL stream);
+
+/**
    Function for reading input bytes from a stream.
 
    This has identical semantics to `fread`, but may set `errno` for more
-   informative error reporting than supported by #SerdStreamErrorFunc.
+   informative error reporting than supported by #SerdErrorFunc.
 
    @param buf Output buffer.
    @param size Size of a single element of data in bytes (always 1).
@@ -67,6 +76,27 @@ typedef size_t (*SerdWriteFunc)(const void* ZIX_NONNULL buf,
                                 void* ZIX_NONNULL       stream);
 
 /**
+   Function for detecting I/O stream errors.
+
+   This has identical semantics to `ferror`.
+
+   @return Non-zero if `stream` has encountered an error.
+*/
+typedef int (*SerdErrorFunc)(void* ZIX_NONNULL stream);
+
+/**
+   Function for closing an I/O stream.
+
+   This has identical semantics to `fclose`.  Note that when writing, this may
+   flush the stream which can cause errors, including errors caused by previous
+   writes that appeared successful at the time.  Therefore it is necessary to
+   check the return value of this function to properly detect write errors.
+
+   @return Non-zero if `stream` has encountered an error.
+*/
+typedef int (*SerdCloseFunc)(void* ZIX_NONNULL stream);
+
+/**
    @}
 */