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.

5 files changed, 217 insertions, 3 deletions

diff --git a/doc/conf.py.in b/doc/conf.py.in
index 70efec61..2ae43555 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -29,7 +29,9 @@ _opaque = [
     "FILE",
     "SerdAllocatorImpl",
     "SerdCaretImpl",
+    "SerdCursorImpl",
     "SerdEnvImpl",
+    "SerdModelImpl",
     "SerdNodeImpl",
     "SerdNodesImpl",
     "SerdReaderImpl",
diff --git a/doc/man/meson.build b/doc/man/meson.build
index 575d3d71..b9ce66a7 100644
--- a/doc/man/meson.build
+++ b/doc/man/meson.build
@@ -23,6 +23,7 @@ if not get_option('tools').disabled()
 
     install_man(files('serd-filter.1'))
     install_man(files('serd-pipe.1'))
+    install_man(files('serd-sort.1'))
   endif
 
   # Build/install HTML man pages if mandoc is present
@@ -47,6 +48,7 @@ if not get_option('tools').disabled()
     page_names = [
       'serd-filter',
       'serd-pipe',
+      'serd-sort',
     ]
 
     html_mandir = docdir / versioned_name / 'man'
diff --git a/doc/man/serd-filter.1 b/doc/man/serd-filter.1
index 634d5f3b..ff076b97 100644
--- a/doc/man/serd-filter.1
+++ b/doc/man/serd-filter.1
@@ -132,6 +132,8 @@ To print every statement about http://example.org/subject:
 .It
 .Xr serd-pipe 1
 .It
+.Xr serd-sort 1
+.It
 .Lk http://drobilla.net/software/serd/
 .El
 .Sh STANDARDS
diff --git a/doc/man/serd-pipe.1 b/doc/man/serd-pipe.1
index 2d6534ae..a2ce86eb 100644
--- a/doc/man/serd-pipe.1
+++ b/doc/man/serd-pipe.1
@@ -8,13 +8,14 @@
 .Nd read and write RDF data
 .Sh SYNOPSIS
 .Nm serd-pipe
-.Op Fl CVhq
+.Op Fl CVh
 .Op Fl B Ar base
 .Op Fl I Ar syntax
 .Op Fl O Ar syntax
 .Op Fl R Ar root
 .Op Fl b Ar bytes
 .Op Fl k Ar bytes
+.Op Fl l Ar level
 .Op Fl o Ar filename
 .Op Fl s Ar string
 .Op Ar input ...
@@ -224,12 +225,31 @@ Parsing is performed using a pre-allocated stack for performance and security re
 By default, the stack is 1 MiB, which should be sufficient for most data.
 This can be increased to support unusually structured data and huge literals,
 or decreased to reduce overall memory requirements and reduce startup time.
+.It Fl l Ar level
+Maximum log level, or (equivalently) minimum log priority.
+Only messages with at least the priority of this level will be displayed.
+The
+.Ar level
+is as in
+.Xr syslog 2 ,
+either a number from
+.Cm 0
+to
+.Cm 7,
+or
+.Cm emerg ,
+.Cm alert ,
+.Cm crit ,
+.Cm err ,
+.Cm warn ,
+.Cm note ,
+.Cm info ,
+or
+.Cm debug .
 .It Fl o Ar filename
 Write output to the given
 .Ar filename
 instead of stdout.
-.It Fl q
-Suppress all output except data.
 .It Fl s Ar string
 Parse
 .Ar string
@@ -281,6 +301,8 @@ exits with a status of 0, or non-zero if an error occurred.
 .It
 .Xr serd-filter 1
 .It
+.Xr serd-sort 1
+.It
 .Lk http://drobilla.net/software/serd/
 .It
 .Lk http://gitlab.com/drobilla/serd/
diff --git a/doc/man/serd-sort.1 b/doc/man/serd-sort.1
new file mode 100644
index 00000000..1484d67e
--- /dev/null
+++ b/doc/man/serd-sort.1
@@ -0,0 +1,186 @@
+.\" # Copyright 2021-2022 David Robillard <d@drobilla.net>
+.\" # SPDX-License-Identifier: ISC
+.Dd July 15, 2022
+.Dt SERD-SORT 1
+.Os Serd
+.Sh NAME
+.Nm serd-sort
+.Nd reorder RDF statements
+.Sh SYNOPSIS
+.Nm serd-sort
+.Op Fl htV
+.Op Fl B Ar base
+.Op Fl I Ar syntax
+.Op Fl O Ar syntax
+.Op Fl b Ar bytes
+.Op Fl c Ar collation
+.Op Fl k Ar bytes
+.Op Fl o Ar filename
+.Op Ar input ...
+.Sh DESCRIPTION
+.Nm
+reorders statements in RDF data by loading everything into memory then rewriting it.
+By default,
+a
+.Dq pretty
+ordering is used which is ideal for pretty-printing Turtle or TriG.
+The
+.Fl c
+option can be used to request a specific ordering,
+which is mainly useful when emitting a line-based syntax like NTriples or NQuads in a pipeline.
+.Pp
+Input and output arguments work the same way as with
+.Xr serd-pipe 1 .
+.Pp
+The options are as follows:
+.Pp
+.Bl -tag -compact -width 3n
+.It Fl B Ar base
+Base URI, path, or
+.Cm rebase
+to use the output path.
+See
+.Xr serd-pipe 1
+for details.
+.Pp
+.It Fl I Ar syntax
+Input syntax or option:
+.Cm NQuads ,
+.Cm NTriples ,
+.Cm TriG ,
+.Cm Turtle ,
+.Cm lax ,
+.Cm variables ,
+.Cm relative ,
+or
+.Cm labels .
+See
+.Xr serd-pipe 1
+for details.
+.Pp
+.It Fl O Ar syntax
+Output syntax or option:
+.Cm empty ,
+.Cm NQuads ,
+.Cm NTriples ,
+.Cm TriG ,
+.Cm Turtle ,
+.Cm ascii ,
+.Cm expanded ,
+.Cm verbatim ,
+.Cm terse ,
+or
+.Cm lax .
+See
+.Xr serd-pipe 1
+for details.
+.Pp
+.It Fl V
+Display version information and exit.
+.Pp
+.It Fl b Ar bytes
+I/O block size.
+See
+.Xr serd-pipe 1
+for details.
+.Pp
+.It Fl c Ar collation
+A specific collation (statement ordering) to use.
+This can be any ordering of the characters
+.Dq SPO ,
+which stand for the subject, predicate, and object of statements.
+Optionally,
+.Dq G
+can be added as the first character,
+which will sort graph-first.
+Concretely, the valid values are:
+.Cm SPO ,
+.Cm SOP ,
+.Cm OPS ,
+.Cm OSP ,
+.Cm PSO ,
+.Cm POS ,
+.Cm GSPO ,
+.Cm GSOP ,
+.Cm GOPS ,
+.Cm GOSP ,
+.Cm GPSO ,
+and
+.Cm GPOS .
+.Pp
+.It Fl h
+Print the command line options.
+.Pp
+.It Fl k Ar bytes
+Parser stack size.
+See
+.Xr serd-pipe 1
+for details.
+.Pp
+.It Fl o Ar filename
+Write output to the given
+.Ar filename
+instead of stdout.
+.Pp
+.It Fl t
+Do not write type as
+.Dq a
+before other properties.
+Instead, rdf:type will be written in order like any other property.
+.El
+.Sh EXIT STATUS
+.Nm
+exits with a status of 0, or non-zero if an error occured.
+.Sh EXAMPLES
+To pretty-print a file:
+.Pp
+.Dl $ serd-sort -o pretty.ttl input.ttl
+.Pp
+To print statements ordered by predicate, subject, then object:
+.Pp
+.Dl $ serd-sort -c PSO input.ttl
+.Sh SEE ALSO
+.Bl -item -compact
+.It
+.Xr serd-pipe 1
+.It
+.Xr serd-filter 1
+.It
+.Lk http://drobilla.net/software/serd/
+.El
+.Sh STANDARDS
+.Bl -item -compact
+.It
+.Rs
+.%A W3C
+.%T RDF 1.1 NQuads
+.%D February 2014
+.Re
+.Lk https://www.w3.org/TR/n-quads/
+.It
+.Rs
+.%A W3C
+.%D February 2014
+.%T RDF 1.1 NTriples
+.Re
+.Lk https://www.w3.org/TR/n-triples/
+.It
+.Rs
+.%A W3C
+.%T RDF 1.1 TriG
+.%D February 2014
+.Re
+.Lk https://www.w3.org/TR/trig/
+.It
+.Rs
+.%A W3C
+.%D February 2014
+.%T RDF 1.1 Turtle
+.Re
+.Lk https://www.w3.org/TR/turtle/
+.El
+.Sh AUTHORS
+.Nm
+is a part of serd, by
+.An David Robillard
+.Mt d@drobilla.net .