diff options
Diffstat (limited to 'doc/man/serd-pipe.1')
| -rw-r--r-- | doc/man/serd-pipe.1 | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/doc/man/serd-pipe.1 b/doc/man/serd-pipe.1 new file mode 100644 index 00000000..32482c73 --- /dev/null +++ b/doc/man/serd-pipe.1 @@ -0,0 +1,210 @@ +.\" Copyright 2011-2023 David Robillard <d@drobilla.net> +.\" SPDX-License-Identifier: ISC +.Dd May 04, 2023 +.Dt SERD-PIPE 1 +.Os Serd 1.1.1 +.Sh NAME +.Nm serd-pipe +.Nd read and write RDF data +.Sh SYNOPSIS +.Nm serd-pipe +.Op Fl abefhlqtv +.Op Fl c Ar prefix +.Op Fl i Ar syntax +.Op Fl k Ar bytes +.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 one less page of memory is used, but likely with a performance penalty. +.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 , +and +.Dq Turtle . +.It Fl k Ar bytes +Parser stack size. +Parsing is performed using a pre-allocated stack for performance and security reasons. +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 +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 empty , +.Dq NQuads , +.Dq NTriples , +.Dq TriG , +and +.Dq Turtle . +The +.Cm empty +syntax suppresses the output, +so that only warnings and errors will be printed. +.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 t +Write terser output without newlines. +.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 only errors and discard the output: +.Nm Fl O +.Ar empty +.Pa input.ttl +.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 . |