.\"                                      Hey, EMACS: -*- nroff -*-
.\"
.\" roqet.1 - Rasqal RDF query utility
.\"
.\" Copyright (C) 2004-2014 David Beckett - http://www.dajobe.org/
.\" Copyright (C) 2004-2005 University of Bristol - http://www.bristol.ac.uk/
.\"
.TH roqet 1 "2013-12-11"
.\" Please adjust this date whenever revising the manpage.
.SH NAME
roqet \- Rasqal RDF query utility
.SH SYNOPSIS
.B roqet
.RB [ OPTIONS ]
.IR "<query-URI>"
.IR "[base-URI]"
.br
.B roqet
.RB [ OPTIONS ] -e
.IR "query-string"
.IR "[base-URI]"
.br
.B roqet
.RB [ OPTIONS ] -p
.IR "sparql-protocol-service-URI" 
.IR "query-URI"
.IR "[base-URI]"
.br
.B roqet
.RB [ OPTIONS ] -p
.IR "sparql-protocol-service-URI"
.RB [ -e
.IR "query-string"
.RB ]
.IR "[base-URI]"
.br
.B roqet
.RB [ OPTIONS ] -t
.IR "query results file" 
.IR "[base-URI]"
.SH DESCRIPTION
The
.B roqet
utility allows querying of RDF content using the
.B Rasqal
RDF query library, printing the results for variable bindings, RDF
graph or boolean results in a variety of formats.  The query is read
from \fIquery-URI\fR and the optional \fIbase-URI\fR is used as the
base URI of the query if present.
.SH MAIN OPTIONS
roqet uses the usual GNU command line syntax, with long
options starting with two dashes (`-') if supported by the
getopt_long function.  Otherwise only the short options are available.
.TP
.B \-e, \-\-exec QUERY
Execute the query string in the argument
.I QUERY
instead of reading the query from a URI (when \fB\-e\fP /
\fB\-\-exec\fP is not given).
.TP
.B \-i, \-\-input LANGUAGE
Set the input query
.I LANGUAGE
to one of the supported languages which includes 'sparql'
(SPARQL Query Language for RDF, default), 'sparql11' and 'laqrs'.
The full list of supported languages and subsets is given in the help
summary with the
\fB\-h\fP / \fB\-\-help\fP option.
.TP
.B \-p, \-\-protocol SERVICE-URI
Call the SPARQL HTTP protocol \fISERVICE-URI\fP to execute the query
instead of executing it inside the Rasqal query engine locally (
when \fB-e\fP is given, or a query string given)
.TP
.B \-r, \-\-results FORMAT
Set the query results output
.I FORMAT
.IP
For variable bindings, the values of
.I FORMAT
vary upon what Rasqal supports but include 'simple' for a simple text
format (default), 'xml' for the SPARQL Query Results XML
format, 'csv' for SPARQL CSV, 'tsv' for SPARQL TSV, 'rdfxml'
and 'turtle' for RDF syntax formats,
and 'json' for a JSON version of the results.
.IP
For RDF graph results, the values of
.I FORMAT
are 'ntriples' (N-Triples, default), 'rdfxml-abbrev'
(RDF/XML Abbreviated), 'rdfxml' (RDF/XML), 'turtle' (Turtle), 'json'
(RDF/JSON resource centric), 'json-triples' (RDF/JSON triples)
or 'rss-1.0' (RSS 1.0, also an RDF/XML syntax).
.IP
The exact list of formats depends on what libraptor2(3) was built with
but is given correct in the usage message with \-h.
.TP
.B \-R, \-\-results-input-format FORMAT
Set the query results input
.I
FORMAT
.IP
This is for use with \-t and takes values of 'xml' for the SPARQL
Query Results XML format,, 'csv' for SPARQL CSV,, 'tsv' for SPARQL
TSV, 'turtle' and 'rdfxml' for RDF syntax formats.
.TP
.B \-t, \-\-results\-input FILE
Read query results from
.I FILE
.SH OTHER OPTIONS
.TP
.B \-c, \-\-count
Only count the triples and produce no other output.
.TP
.B \-d, \-\-dump\-query FORMAT
Print the parsed query out in a given
.I FORMAT
one of 'none' (default), 'debug', 'structure' or 'sparql'
.TP
.B \-D, \-\-data URI
Add RDF data source URI (not a named graph).  If no data sources
are given, the query itself must point to the data such as via
SPARQL FROM \fIuri\fP statements.
.TP
.B \-E, \-\-ignore\-errors
Do not print error messages and do not exit with a non-0 status.
.TP
.B \-f, \-\-feature NAME(=VALUE)
Set query feature
.I NAME
to the
.I VALUE
or integer 1 if omitted.
The known features can be shown with \fB-f help\fP or \fB--feature help\fP.
.TP
.B \-F, \-\-format NAME
Set the data source format \fIname\fP for subsequent data graphs called
with \fB\-D\fP / \fB\-\-data\fP or \fB\-G\fP / \fB\-\-named\fP.
The default if this is not specified is for the query engine to
guess.  The \fIname\fP is a Raptor parser name.
.TP
.B \-G, \-\-named URI
Add RDF data source URI (named graph)
.TP
.B \-h, \-\-help
Show a summary of the options.
.TP
.B \-n, \-\-dryrun
Prepare the query but do not execute it.
.TP
.B \-q, \-\-quiet
No extra information messages.
.TP
.B \-s, \-\-source URI
Add RDF data source URI (named graph)
.I URI
by adding it to the list of query data source URIs.
.I FORMAT
to 'simple' (default) or 'xml' (an experimental XML format)
.TP
.B \-v, \-\-version
Print the rasqal library version and exit.
.TP
.B \-W, \-\-warnings LEVEL
Set the warning 
.I LEVEL
in the range 0 (do not warn about anything) to 100 (show every
warning). The Rasqal default is in the middle (50).
.SH EXAMPLES
.IP
.B roqet sparql-query-file.rq
.LP
Run a SPARQL query contained in the local file sparql-query-file.rq.
The data used would be described in FROM statements in the query file.
.IP
.B roqet -q -i sparql http://example.org/sparql-query.rq
.LP
Run a SPARQL query that is in the web at URI
http://example.org/sparql-query.rq
without an extra messages (quiet, -q).
.IP
.B roqet -q query-file.rq http://example.org/base/
.LP
Run an query (default languge SPARQL) from a local file query-file.rq
but using base URI http://example.org/base/ to resolve any relative
URIs.
.IP
.B roqet -q -i sparql -r xml http://example.org/sparql-query.rq
.LP
Run a SPARQL query that is in the web at URI http://example.org/sparql-query.rq
and format the results in the SPARQL Query Results XML format with no extra
messages.
.IP
.B roqet -i sparql -e 'SELECT * WHERE { ?s ?p ?o }' -D stuff.rdf
.LP
Run a SPARQL query given on the command line against data in
the file stuff.rdf.  The type of the file will be guessed and likely
is of format RDF/XML.
.IP
.B roqet -t result.srx -r html
.LP
Read a SPARQL query results in SPARQL Query Results XML format (default)
and print it in HTML.
.IP
.B roqet -t result.ttl -R turtle -r csv
.LP
Read a SPARQL query results in RDF/Turtle format and print it in CSV.
.SH "CONFORMING TO"
\fISPARQL 1.1 Query Language\fR,
Steve Harris and Andy Seaborne (eds),
W3C Recommendation, 21 March 2013
.UR http://www.w3.org/TR/2013/REC-sparql11-query-20130321/
http://www.w3.org/TR/2013/REC-sparql11-query-20130321/
.UE
.LP
\fISPARQL Query Results XML Format (Second Edition)\fR, 
Sandro Hawke (Second Edition ed), Jeen Broekstra and Dave Beckett (eds),
W3C Recommendation, 21 March 2013.
.UR http://www.w3.org/TR/2013/REC-rdf-sparql-XMLres-20130321/
http://www.w3.org/TR/2013/REC-rdf-sparql-XMLres-20130321/
.UE
.SH SEE ALSO
.BR librasqal(3), libraptor(3)
.SH CHANGES
.br
.SH AUTHOR
Dave Beckett - 
.UR http://www.dajobe.org/
http://www.dajobe.org/
.UE
.br