diff options
Diffstat (limited to 'include/serd/serd.h')
| -rw-r--r-- | include/serd/serd.h | 81 |
1 files changed, 72 insertions, 9 deletions
diff --git a/include/serd/serd.h b/include/serd/serd.h index c7dc4a17..b5c7c4f0 100644 --- a/include/serd/serd.h +++ b/include/serd/serd.h @@ -84,6 +84,9 @@ extern "C" { /// Global library state typedef struct SerdWorldImpl SerdWorld; +/// The origin of a statement in a document +typedef struct SerdCursorImpl SerdCursor; + /// Lexical environment for relative URIs or CURIEs (base URI and namespaces) typedef struct SerdEnvImpl SerdEnv; @@ -246,12 +249,10 @@ typedef struct { /// An error description typedef struct { - SerdStatus status; ///< Error code - const char* SERD_NULLABLE filename; ///< File with error - unsigned line; ///< Line in file with error or 0 - unsigned col; ///< Column in file with error - const char* SERD_NONNULL fmt; ///< Printf-style format string - va_list* SERD_NONNULL args; ///< Arguments for fmt + SerdStatus status; ///< Error code + const SerdCursor* SERD_NULLABLE cursor; ///< Origin of error + const char* SERD_NONNULL fmt; ///< Printf-style format string + va_list* SERD_NONNULL args; ///< Arguments for fmt } SerdError; /** @@ -1110,14 +1111,15 @@ serd_reader_start_stream(SerdReader* SERD_NONNULL reader, SerdReadFunc SERD_NONNULL read_func, SerdStreamErrorFunc SERD_NONNULL error_func, void* SERD_NONNULL stream, - const char* SERD_NULLABLE name, + const SerdNode* SERD_NULLABLE name, size_t page_size); /// Prepare to read from a string SERD_API SerdStatus -serd_reader_start_string(SerdReader* SERD_NONNULL reader, - const char* SERD_NONNULL utf8); +serd_reader_start_string(SerdReader* SERD_NONNULL reader, + const char* SERD_NONNULL utf8, + const SerdNode* SERD_NULLABLE name); /** Read a single "chunk" of data during an incremental read @@ -1264,6 +1266,67 @@ serd_writer_finish(SerdWriter* SERD_NONNULL writer); /** @} + @defgroup serd_cursor Cursor + @{ +*/ + +/** + Create a new cursor + + Note that, to minimise model overhead, the cursor does not own the name + node, so `name` must have a longer lifetime than the cursor for it to be + valid. That is, serd_cursor_name() will return exactly the pointer + `name`, not a copy. For cursors from models, this is the lifetime of the + model. For user-created cursors, the simplest way to handle this is to use + `SerdNodes`. + + @param name The name of the document or stream (usually a file URI) + @param line The line number in the document (1-based) + @param col The column number in the document (1-based) + @return A new cursor that must be freed with serd_cursor_free() +*/ +SERD_API +SerdCursor* SERD_ALLOCATED +serd_cursor_new(const SerdNode* SERD_NONNULL name, unsigned line, unsigned col); + +/// Return a copy of `cursor` +SERD_API +SerdCursor* SERD_ALLOCATED +serd_cursor_copy(const SerdCursor* SERD_NULLABLE cursor); + +/// Free `cursor` +SERD_API +void +serd_cursor_free(SerdCursor* SERD_NULLABLE cursor); + +/// Return true iff `lhs` is equal to `rhs` +SERD_PURE_API +bool +serd_cursor_equals(const SerdCursor* SERD_NULLABLE lhs, + const SerdCursor* SERD_NULLABLE rhs); + +/** + Return the document name. + + This is typically a file URI, but may be a descriptive string node for + statements that originate from streams. +*/ +SERD_PURE_API +const SerdNode* SERD_NONNULL +serd_cursor_name(const SerdCursor* SERD_NONNULL cursor); + +/// Return the one-relative line number in the document +SERD_PURE_API +unsigned +serd_cursor_line(const SerdCursor* SERD_NONNULL cursor); + +/// Return the zero-relative column number in the line +SERD_PURE_API +unsigned +serd_cursor_column(const SerdCursor* SERD_NONNULL cursor); + +/** + @} @} */ |