.\" Copyright 2011-2024 David Robillard <d@drobilla.net>
.\" SPDX-License-Identifier: ISC
.Dd April 30, 2023
.Dt SERDI 1
.Os Serd 0.32.1
.Sh NAME
.Nm serdi
.Nd read and write RDF syntax
.Sh SYNOPSIS
.Nm serdi
.Op Fl abefhlqv
.Op Fl c Ar prefix
.Op Fl i Ar syntax
.Op Fl o Ar syntax
.Op Fl p Ar prefix
.Op Fl r Ar root
.Op Fl s Ar string
.Ar input
.Op Ar base_uri
.Sh DESCRIPTION
.Nm
is a fast command-line utility for streaming and processing RDF data.
It reads an RDF document and writes the data to stdout,
possibly transformed and/or in a different syntax.
By default,
the input syntax is guessed from the file extension,
and output is written in NTriples or NQuads.
.Pp
.Nm
can be used to check for syntax errors,
convert from one syntax to another,
pretty-print documents,
or transform URIs and blank node IDs.
.Pp
The options are as follows:
.Bl -tag -width 3n
.It Fl a
Write ASCII output.
If this is enabled, all non-ASCII characters will be escaped, even if the output syntax allows them to be written in UTF-8.
.It Fl b
Bulk output writing.
If this is enabled, output will be written a page at a time, rather than a byte at a time.
.It Fl c Ar prefix
Chop
.Ar prefix
from matching blank node IDs.
This is typically used to revert the effects of
.Fl p .
For example, with
.Ar prefix
.Dq doc01 ,
the blank node
.Li _:doc01b42
will be emitted as
.Li _:b42 .
.It Fl e
Eat input one character at a time, rather than a page at a time which is the default.
This is useful when reading from a pipe since output will be generated immediately as input arrives, rather than waiting until an entire page of input has arrived.
With this option serdi uses one page less memory, but will likely be significantly slower.
.It Fl f
Fast and loose URI mode:
preserve full URIs (without qualifying or making relative),
and pass prefixed names through as-is.
.It Fl h
Print the command line options.
.It Fl i Ar syntax
Read input as
.Ar syntax .
Case is ignored, valid values are:
.Dq NQuads ,
.Dq NTriples ,
.Dq TriG ,
.Dq Turtle .
.It Fl l
Lax (non-strict) parsing.
If this is enabled, recoverable syntax errors will print a warning, but parsing will proceed starting at the next statement if possible.
Note that data may be lost when using this option.
.It Fl o Ar syntax
Write output as
.Ar syntax .
Case is ignored, valid values are:
.Dq NQuads ,
.Dq NTriples ,
.Dq TriG ,
.Dq Turtle .
.It Fl p Ar prefix
Add
.Ar prefix
to blank node IDs.
This can be used to avoid clashes between blank node IDs in input documents.
The effects can be reversed in a later run with
.Fl c .
For example, with
.Ar prefix
.Dq doc01 ,
the blank node
.Li _:b42
will be emitted as
.Li _:doc01b42 .
.It Fl q
Suppress all output except data.
.It Fl r Ar root
Keep relative URIs within a
.Ar root
URI.
This will avoid creating any relative URI references with leading path segments like
.Pa ../
that enter a parent of
.Ar root .
.Pp
For example,
if
.Pa /home/you/file.ttl
is written to the file
.Pa /home/me/output.ttl
using the destination's base URI,
then it could be written as
.Li <../you/file.ttl> .
Setting
.Fl r Li file:///home/me/
would prevent references from
.Dq escaping
like this,
so the above would instead be written as
.Li <file:///home/you/file.ttl> ,
since it can't be expressed relative to the root URI.
.Pp
This is useful for keeping relative references within some directory.
.It Fl s Ar string
Parse
.Ar string
input instead of a file (terminates options).
.It Fl v
Display version information and exit.
.El
.Sh EXIT STATUS
.Nm
exits with a status of 0, or non-zero if an error occurred.
.Sh EXAMPLES
.Bl -tag -width 3n
.It Pretty-print a document:
.Nm Fl o
.Ar turtle
.Pa file.ttl
>
.Pa out.ttl
.It Print any errors:
.Nm Pa file.ttl
>
.Pa /dev/null
.El
.Sh SEE ALSO
.Bl -item -compact
.It
.Lk http://drobilla.net/software/serd/
.It
.Lk http://gitlab.com/drobilla/serd/
.El
.Sh STANDARDS
.Bl -item
.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 .