From e85861faf230da4384e99dbbe6c5794d63ce9f4e Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Fri, 29 Apr 2022 10:41:48 -0700 Subject: [PATCH 1/3] Update README. --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 3db705ab..a016b577 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# SPARQL for RDF.rb +# SPARQL Query and Update library for Ruby -This is a [Ruby][] implementation of [SPARQL][] for [RDF.rb][]. +An implementation of [SPARQL][] for [RDF.rb][]. [![Gem Version](https://badge.fury.io/rb/sparql.png)](https://badge.fury.io/rb/sparql) [![Build Status](https://github.com/ruby-rdf/sparql/workflows/CI/badge.svg?branch=develop)](https://github.com/ruby-rdf/sparql/actions?query=workflow%3ACI) @@ -17,11 +17,13 @@ This is a [Ruby][] implementation of [SPARQL][] for [RDF.rb][]. or HTML. * SPARQL CONSTRUCT or DESCRIBE serialized based on Format, Extension of Mime Type using available RDF Writers (see [Linked Data][]) -* SPARQL Client for accessing remote SPARQL endpoints. -* SPARQL Update +* SPARQL Client for accessing remote SPARQL endpoints (via [sparql-client](https://github.com/ruby-rdf/sparql-client)). +* [SPARQL 1.1 Protocol][] (via {SPARQL::Server}). +* [SPARQL 1.1 Update][] * [Rack][] and [Sinatra][] middleware to perform [HTTP content negotiation][conneg] for result formats * Compatible with any [Rack][] or [Sinatra][] application and any Rack-based framework. * Helper method for describing [SPARQL Service Description][SSD] + * Helper method for setting up datasets as part of the [SPARQL 1.1 Protocol][]. * Implementation Report: {file:etc/earl.html EARL} * Compatible with Ruby >= 2.6. * Supports Unicode query strings both on all versions of Ruby. @@ -29,11 +31,12 @@ This is a [Ruby][] implementation of [SPARQL][] for [RDF.rb][]. ## Description -The {SPARQL} gem implements [SPARQL 1.1 Query][], and [SPARQL 1.1 Update][], and provides [Rack][] and [Sinatra][] middleware to provide results using [HTTP Content Negotiation][conneg]. +The {SPARQL} gem implements [SPARQL 1.1 Query][], and [SPARQL 1.1 Update][], and provides [Rack][] and [Sinatra][] middleware to provide results using [HTTP Content Negotiation][conneg] and to support [SPARQL 1.1 Protocol][]. * {SPARQL::Grammar} implements a [SPARQL 1.1 Query][] and [SPARQL 1.1 Update][] parser generating [SPARQL S-Expressions (SSE)][SSE]. * {SPARQL::Algebra} executes SSE against Any `RDF::Graph` or `RDF::Repository`, including compliant [RDF.rb][] repository adaptors such as [RDF::DO][] and [RDF::Mongo][]. * {Rack::SPARQL} and {Sinatra::SPARQL} provide middleware components to format results using an appropriate format based on [HTTP content negotiation][conneg]. +* {SPARQL::Server} implements the [SPARQL 1.1 Protocol][] using {Sinatra::SPARQL}. ### [SPARQL 1.1 Query][] Extensions and Limitations The {SPARQL} gem uses the [SPARQL 1.1 Query][] {file:etc/sparql11.html EBNF grammar}, which provides much more capability than [SPARQL 1.0][], but has a few limitations: @@ -62,11 +65,8 @@ The gem also includes the following [SPARQL 1.1 Update][] operations: Not supported: * [Federated Query][SPARQL 1.1 Federated Query], -* [Entailment Regimes][SPARQL 1.1 Entailment Regimes], -* [Protocol][SPARQL 1.1 Protocol], and -* [Graph Store HTTP Protocol][SPARQL 1.1 Graph Store HTTP Protocol] - -either in this, or related gems. +* [Entailment Regimes][SPARQL 1.1 Entailment Regimes], and +* [Graph Store HTTP Protocol][SPARQL 1.1 Graph Store HTTP Protocol] but the closely related [Linked Data Platform][] implemented in [rdf-ldp](https://github.com/ruby-rdf/rdf-ldp) supports these use cases. ### Updates for RDF 1.1 Starting with version 1.1.2, the SPARQL gem uses the 1.1 version of the [RDF.rb][], which adheres to [RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/) rather than [RDF 1.0](https://www.w3.org/TR/rdf-concepts/). The main difference is that there is now no difference between a _Simple Literal_ (a literal with no datatype or language) and a Literal with datatype _xsd:string_; this causes some minor differences in the way in which queries are understood, and when expecting different results. @@ -436,7 +436,7 @@ This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange develo ## License This is free and unencumbered public domain software. For more information, -see or the accompanying {file:UNLICENSE} file. +see or the accompanying {file:UNLICENSE}. A copy of the [SPARQL EBNF][] and derived parser files are included in the repository, which are not covered under the UNLICENSE. These files are covered via the [W3C Document License](https://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231). @@ -482,4 +482,4 @@ A copy of the [SPARQL 1.0 tests][] and [SPARQL 1.1 tests][] are also included in [SPARQL 1.1 Entailment Regimes]: https://www.w3.org/TR/sparql11-entailment/ [SPARQL 1.1 Protocol]: https://www.w3.org/TR/sparql11-protocol/ [SPARQL 1.1 Graph Store HTTP Protocol]: https://www.w3.org/TR/sparql11-http-rdf-update/ - +[Linked Data Platform]: https://www.w3.org/TR/ldp/ From 3bd11bbe1dc51e6abe8922d5a05656b6101f2042 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Thu, 5 May 2022 14:53:51 -0700 Subject: [PATCH 2/3] Document pre-binding variables to queries. --- README.md | 18 ++++++++++++++++++ lib/sparql/algebra/query.rb | 4 +++- spec/readme_spec.rb | 2 +- 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a016b577..43130862 100755 --- a/README.md +++ b/README.md @@ -103,6 +103,10 @@ Then, use the function in a query: See {SPARQL::Algebra::Expression.register_extension} for details. +### Variable Pre-binding + +A call to execute a parsed query can include pre-bound variables, which cause queries to be executed with matching variables bound as defined. Variable pre-binding can be done using a Hash structure, or a Query Solution. See [Query with Binding example](#query-with-binding) and {SPARQL::Algebra::Query#execute}. + ### SPARQLStar (SPARQL-star) The gem supports [SPARQL-star][] where patterns may include sub-patterns recursively, for a kind of Reification. @@ -287,6 +291,20 @@ a full set of RDF formats. query = SPARQL::Algebra.parse(%{(bgp (triple ?s ?p ?o))}) sparql = query.to_sparql #=> "SELECT * WHERE { ?s ?p ?o }" +### Query with Binding + + bindings = {page: RDF::URI("https://greggkellogg.net/")} + queryable = RDF::Repository.load("etc/doap.ttl") + query = SPARQL.parse(%( + PREFIX foaf: + SELECT ?person + WHERE { + ?person foaf:homepage ?page . + } + )) + solutions = query.execute(queryable, bindings: bindings) + solutions.to_sxp #=> (((person ))) + ### Command line processing sparql execute --dataset etc/doap.ttl etc/from_default.rq diff --git a/lib/sparql/algebra/query.rb b/lib/sparql/algebra/query.rb index 2ff4d5e9..3e3db8ab 100644 --- a/lib/sparql/algebra/query.rb +++ b/lib/sparql/algebra/query.rb @@ -38,7 +38,9 @@ def variables # the graph or repository to query # @param [Hash{Symbol => Object}] options # any additional keyword options - # @option options [Boolean] debug + # @option options [RDF::Query::Solution] :bindings + # a query solution containing zero or more variable bindings + # @option options [Boolean] :debug # Query execution debugging # @option options [RDF::Term, RDF::Query::Variable] :graph_name # @yield [solution] diff --git a/spec/readme_spec.rb b/spec/readme_spec.rb index 882f6f00..1e2836cb 100644 --- a/spec/readme_spec.rb +++ b/spec/readme_spec.rb @@ -16,7 +16,7 @@ def self.read_examples case title when "Command line processing" code.split("\n").reject {|c| c =~ /^\s*(?:#.*)?$/}.each do |command| - examples << {title: command, sh: command} + examples << {title: "#{title}: #{command.strip}", sh: command} end else examples << {title: title, eval_true: code} From ec0b429b10bb1da9693263d870f4937f46565aa4 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Thu, 5 May 2022 14:55:56 -0700 Subject: [PATCH 3/3] Version 3.2.3. --- VERSION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION b/VERSION index be94e6f5..b347b11e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -3.2.2 +3.2.3