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, 57 insertions, 0 deletions

diff --git a/include/serd/describe.h b/include/serd/describe.h
new file mode 100644
index 00000000..c571aeae
--- /dev/null
+++ b/include/serd/describe.h
@@ -0,0 +1,57 @@
+// Copyright 2011-2023 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef SERD_DESCRIBE_H
+#define SERD_DESCRIBE_H
+
+#include "serd/attributes.h"
+#include "serd/cursor.h"
+#include "serd/memory.h"
+#include "serd/sink.h"
+#include "serd/status.h"
+#include "zix/attributes.h"
+
+#include <stdint.h>
+
+SERD_BEGIN_DECLS
+
+/**
+   @defgroup serd_range Range
+   @ingroup serd_storage
+   @{
+*/
+
+/// Flags that control the style of a model description
+typedef enum {
+  SERD_NO_TYPE_FIRST = 1U << 0U, ///< Disable writing rdf:type ("a") first
+} SerdDescribeFlag;
+
+/// Bitwise OR of SerdDescribeFlag values
+typedef uint32_t SerdDescribeFlags;
+
+/**
+   Describe a range of statements by writing to a sink.
+
+   This will consume the given cursor, and emit at least every statement it
+   visits.  More statements from the model may be written in order to describe
+   anonymous blank nodes that are associated with a subject in the range.
+
+   The default is to write statements in an order suited for pretty-printing
+   with Turtle or TriG with as many anonymous nodes as possible.  If
+   `SERD_NO_INLINE_OBJECTS` is given, a simple sorted stream is written
+   instead, which is faster since no searching is required, but can result in
+   ugly output for Turtle or Trig.
+*/
+SERD_API SerdStatus
+serd_describe_range(SerdAllocator* ZIX_NULLABLE    allocator,
+                    const SerdCursor* ZIX_NULLABLE range,
+                    const SerdSink* ZIX_NONNULL    sink,
+                    SerdDescribeFlags              flags);
+
+/**
+   @}
+*/
+
+SERD_END_DECLS
+
+#endif // SERD_DESCRIBE_H