Add model and serd-sort utility

With all the new functionality, the complexity of the serd-pipe command-line
interface is starting to push the limits of available flags. So, instead of
grafting on further options to control a model, this commit adds a new tool,
serd-sort, which acts somewhat like a stripped-down serd-pipe that stores
statements in a model in memory.

This keeps the complexity (including the user-facing complexity) of any one
tool down, since other more focused tools can be used for streaming tasks in a
pipeline.

In other words, abandon Swissarmyknifeism, take a page from the Unix
philosophy, and try to expose the model functionality to the command-line in a
dedicated focused tool.  The model implementation is tested by using this tool
to run a subset of the usual test suites, and a special suite to test statement
sorting.

1 files changed, 83 insertions, 0 deletions

diff --git a/include/serd/cursor.h b/include/serd/cursor.h
new file mode 100644
index 00000000..eba88ca7
--- /dev/null
+++ b/include/serd/cursor.h
@@ -0,0 +1,83 @@
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef SERD_CURSOR_H
+#define SERD_CURSOR_H
+
+#include "serd/attributes.h"
+#include "serd/memory.h"
+#include "serd/statement.h"
+#include "serd/status.h"
+#include "zix/attributes.h"
+
+#include <stdbool.h>
+
+SERD_BEGIN_DECLS
+
+/**
+   @defgroup serd_cursor Cursor
+   @ingroup serd_storage
+   @{
+*/
+
+/**
+   A cursor that iterates over statements in a model.
+
+   A cursor is a smart iterator that visits all statements that match a
+   pattern.
+*/
+typedef struct SerdCursorImpl SerdCursor;
+
+/// Return a new copy of `cursor`
+SERD_API SerdCursor* ZIX_ALLOCATED
+serd_cursor_copy(SerdAllocator* ZIX_NULLABLE    allocator,
+                 const SerdCursor* ZIX_NULLABLE cursor);
+
+/// Return the statement pointed to by `cursor`
+SERD_API const SerdStatement* ZIX_NULLABLE
+serd_cursor_get(const SerdCursor* ZIX_NULLABLE cursor);
+
+/**
+   Increment cursor to point to the next statement.
+
+   Null is treated like an end cursor.
+
+   @return Failure if `cursor` was already at the end.
+*/
+SERD_API SerdStatus
+serd_cursor_advance(SerdCursor* ZIX_NULLABLE cursor);
+
+/**
+   Return true if the cursor has reached its end.
+
+   Null is treated like an end cursor.
+*/
+SERD_PURE_API bool
+serd_cursor_is_end(const SerdCursor* ZIX_NULLABLE cursor);
+
+/**
+   Return true iff `lhs` equals `rhs`.
+
+   Two cursors are equivalent if they point to the same statement in the same
+   index in the same model, or are both the end of the same model.  Note that
+   two cursors can point to the same statement but not be equivalent, since
+   they may have reached the statement via different indices.
+
+   Null is treated like an end cursor.
+*/
+SERD_PURE_API bool
+serd_cursor_equals(const SerdCursor* ZIX_NULLABLE lhs,
+                   const SerdCursor* ZIX_NULLABLE rhs);
+
+/// Free `cursor`
+SERD_API void
+serd_cursor_free(SerdAllocator* ZIX_NULLABLE allocator,
+                 SerdCursor* ZIX_NULLABLE    cursor);
+
+/**
+   @}
+*/
+
+SERD_END_DECLS
+
+#endif // SERD_CURSOR_H