.\"                                      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 \- ابزار پرس‌وجوی RDF در Rasqal
.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)"
ابزار
.B roqet
امکان پرس‌وجو از محتوای RDF را با استفاده از کتابخانه پرس‌وجوی RDF به نام
.B Rasqal
فراهم می‌کند و نتایج مقیدسازی‌های متغیر (variable bindings)، گراف RDF یا نتایج بولی (boolean) را در قالب‌های گوناگون چاپ می‌نماید. پرس‌وجو از \fIquery-URI\fR خوانده می‌شود و در صورت وجود، \fIbase-URI\fR اختیاری به عنوان URI پایه پرس‌وجو به کار می‌رود.
.SH "گزینه‌های اصلی (MAIN OPTIONS)"
دستور roqet از نحو استاندارد خط فرمان GNU پیروی می‌کند که در آن در صورت پشتیبانی توسط تابع getopt_long، گزینه‌های طولانی با دو خط تیره (`-') آغاز می‌شوند. در غیر این صورت، تنها گزینه‌های کوتاه در دسترس خواهند بود.
.TP
.B \-e, \-\-exec QUERY
رشته پرس‌وجوی ارائه‌شده در آرگومان
.I QUERY
را اجرا می‌کند، به‌جای آنکه پرس‌وجو از یک URI خوانده شود (حالتی که در آن \fB\-e\fP /
\fB\-\-exec\fP مشخص نشده باشد).
.TP
.B \-i, \-\-input LANGUAGE
زبان پرس‌وجوی ورودی
.I LANGUAGE
را روی یکی از زبان‌های پشتیبانی‌شده تنظیم می‌کند که شامل 'sparql' (زبان پرس‌وجوی SPARQL برای RDF، پیش‌فرض)، 'sparql11' و 'laqrs' است. فهرست کامل زبان‌ها و زیرمجموعه‌های پشتیبانی‌شده در خلاصه راهنما به همراه گزینه
\fB\-h\fP / \fB\-\-help\fP
ارائه شده است.
.TP
.B \-p, \-\-protocol SERVICE-URI
پروتکل SPARQL HTTP در \fISERVICE-URI\fP را برای اجرای پرس‌وجو فراخوانی می‌کند، به‌جای آنکه آن را به صورت محلی در موتور پرس‌وجوی Rasqal اجرا نماید (زمانی که \fB-e\fP داده شده باشد، یا یک رشته پرس‌وجو مشخص شده باشد).
.TP
.B \-r, \-\-results FORMAT
قالب خروجی نتایج پرس‌وجو
.I FORMAT
را تعیین می‌کند.
.IP
برای مقیدسازی متغیرها، مقادیر
.I FORMAT
بسته به موارد پشتیبانی‌شده در Rasqal متفاوت است، اما شامل 'simple' برای یک قالب متنی ساده (پیش‌فرض)، 'xml' برای قالب XML نتایج پرس‌وجوی SPARQL، و 'csv' برای SPARQL CSV، و 'tsv' برای SPARQL TSV، و 'rdfxml' و 'turtle' برای قالب‌های نحوی RDF، و همچنین 'json' برای نسخه JSON نتایج می‌باشد.
.IP
برای نتایج گراف RDF، مقادیر
.I FORMAT
عبارتند از 'ntriples' (قالب N-Triples، پیش‌فرض)، 'rdfxml-abbrev' (قالب RDF/XML مختصر)، 'rdfxml' (قالب RDF/XML)، 'turtle' (قالب Turtle)، 'json' (قالب منبع‌محور RDF/JSON)، 'json-triples' (سه‌تایی‌های RDF/JSON) یا 'rss-1.0' (قالب RSS 1.0 که یک نحو RDF/XML نیز هست).
.IP
فهرست دقیق قالب‌ها بستگی به این دارد که libraptor2(3) با چه گزینه‌هایی کامپایل شده باشد، اما فهرست صحیح آن در پیام راهنمای کاربری با \-h آورده شده است.
.TP
.B \-R, \-\-results-input-format FORMAT
قالب ورودی نتایج پرس‌وجو
.I
FORMAT
را تعیین می‌کند.
.IP
این گزینه برای استفاده به همراه \-t است و مقادیر 'xml' برای قالب XML نتایج پرس‌وجوی SPARQL، و 'csv' برای SPARQL CSV، و 'tsv' برای SPARQL TSV، و همچنین 'turtle' و 'rdfxml' برای قالب‌های نحوی RDF را می‌پذیرد.
.TP
.B \-t, \-\-results\-input FILE
نتایج پرس‌وجو را از
.I FILE
می‌خواند.
.SH "سایر گزینه‌ها (OTHER OPTIONS)"
.TP
.B \-c, \-\-count
تنها سه‌تایی‌ها (triples) را می‌شمارد و هیچ خروجی دیگری تولید نمی‌کند.
.TP
.B \-d, \-\-dump\-query FORMAT
پرس‌وجوی تحلیل‌شده را در قالب
.I FORMAT
داده‌شده چاپ می‌کند؛ یکی از مقادیر 'none' (پیش‌فرض)، 'debug'، 'structure' یا 'sparql'.
.TP
.B \-D, \-\-data URI
نشانی URI منبع داده RDF (غیر از یک گراف نام‌دار) را اضافه می‌کند. اگر هیچ منبع داده‌ای مشخص نشده باشد، خود پرس‌وجو باید مانند عبارات SPARQL FROM \fIuri\fP به داده‌ها اشاره کند.
.TP
.B \-E, \-\-ignore\-errors
پیام‌های خطا را چاپ نمی‌کند و با وضعیت غیر صفر خارج نمی‌شود.
.TP
.B \-f, \-\-feature NAME(=VALUE)
ویژگی پرس‌وجوی
.I NAME
را روی
.I VALUE
تنظیم می‌کند، یا در صورت عدم ذکر مقدار، عدد صحیح 1 را برای آن در نظر می‌گیرد.
ویژگی‌های شناخته‌شده را می‌توان با \fB-f help\fP یا \fB--feature help\fP مشاهده کرد.
.TP
.B \-F, \-\-format NAME
قالب منبع داده \fIname\fP را برای گراف‌های داده بعدی که با \fB\-D\fP / \fB\-\-data\fP یا \fB\-G\fP / \fB\-\-named\fP فراخوانی می‌شوند تعیین می‌کند.
در صورت مشخص نشدن، پیش‌فرض موتور پرس‌وجو حدس زدن قالب است. مقدار \fIname\fP نام یکی از تجزیه‌کننده‌های Raptor است.
.TP
.B \-G, \-\-named URI
نشانی URI منبع داده RDF (گراف نام‌دار) را اضافه می‌کند.
.TP
.B \-h, \-\-help
خلاصه‌ای از گزینه‌ها را نمایش می‌دهد.
.TP
.B \-n, \-\-dryrun
پرس‌وجو را آماده‌سازی می‌کند اما آن را اجرا نمی‌نماید.
.TP
.B \-q, \-\-quiet
از نمایش پیام‌های اطلاعاتی اضافی جلوگیری می‌کند.
.TP
.B \-s, \-\-source URI
نشانی URI منبع داده RDF (گراف نام‌دار)
.I URI
را با افزودن آن به فهرست URIهای منبع داده پرس‌وجو اضافه می‌کند.
.I FORMAT
را به 'simple' (پیش‌فرض) یا 'xml' (یک قالب آزمایشی XML) تغییر می‌دهد.
.TP
.B \-v, \-\-version
نسخه کتابخانه rasqal را چاپ کرده و خارج می‌شود.
.TP
.B \-W, \-\-warnings LEVEL
سطح هشدار
.I LEVEL
را در بازه 0 (عدم نمایش هیچ هشداری) تا 100 (نمایش تمام هشدارها) تنظیم می‌کند. مقدار پیش‌فرض Rasqal در میانه این بازه (50) است.
.SH "مثال‌ها (EXAMPLES)"
.IP
.B roqet sparql-query-file.rq
.LP
اجرای یک پرس‌وجوی SPARQL موجود در فایل محلی sparql-query-file.rq.
داده‌های مورد استفاده در عبارت‌های FROM درون فایل پرس‌وجو توصیف خواهند شد.
.IP
.B roqet -q -i sparql http://example.org/sparql-query.rq
.LP
اجرای یک پرس‌وجوی SPARQL واقع در وب در نشانی URI
http://example.org/sparql-query.rq
بدون پیام‌های اضافی (حالت بی‌صدا، -q).
.IP
.B roqet -q query-file.rq http://example.org/base
.LP
اجرای یک پرس‌وجو (با زبان پیش‌فرض SPARQL) از یک فایل محلی query-file.rq اما با استفاده از URI پایه http://example.org/base جهت تفکیک هرگونه URI نسبی.
.IP
.B roqet -q -i sparql -r xml http://example.org/sparql-query.rq
.LP
اجرای یک پرس‌وجوی SPARQL واقع در وب در نشانی URI http://example.org/sparql-query.rq و قالب‌بندی نتایج در قالب SPARQL Query Results XML بدون پیام‌های اضافی.
.IP
.B roqet -i sparql -e \(aqSELECT * WHERE { ?s ?p ?o }\(aq -D stuff.rdf
.LP
اجرای یک پرس‌وجوی SPARQL مشخص‌شده در خط فرمان بر روی داده‌های موجود در فایل stuff.rdf. نوع فایل حدس زده خواهد شد و احتمالاً از نوع RDF/XML است.
.IP
.B roqet -t result.srx -r html
.LP
خواندن نتایج یک پرس‌وجوی SPARQL در قالب SPARQL Query Results XML (پیش‌فرض) و چاپ آن به صورت HTML.
.IP
.B roqet -t result.ttl -R turtle -r csv
.LP
خواندن نتایج یک پرس‌وجوی SPARQL در قالب RDF/Turtle و چاپ آن به صورت CSV.
.SH "سازگاری با استانداردها (CONFORMING TO)"
\fISPARQL 1.1 Query Language\fR،
Steve Harris و Andy Seaborne (ویراستاران)،
توصیه‌نامه W3C،‏ ۲۱ مارس ۲۰۱۳
.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 (ویراستار ویرایش دوم)، Jeen Broekstra و Dave Beckett (ویراستاران)،
توصیه‌نامه W3C،‏ ۲۱ مارس ۲۰۱۳.
.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),
.BR libraptor (3)
.SH "تغییرات (CHANGES)"
.br
.SH "نویسنده (AUTHOR)"
Dave Beckett - 
.UR http://www.dajobe.org
http://www.dajobe.org
.UE
.br