sparql 0.0.1 → 0.0.2

data/AUTHORS

@@ -0,0 +1,3 @@
+* Gregg Kellogg <gregg@kellogg-assoc.com>
+* Arto Bendiken <arto.bendiken@gmail.com>
+* Pius Uzamere <pius@alum.mit.edu>

data/README.markdown

@@ -1,88 +1,138 @@
-sparql Release 0.0.1 (July 17th 2008) 
-===================================
+# SPARQL for RDF.rb
 
-**Git**:  [http://github.com/pius/sparql](http://github.com/pius/sparql)   
-**Author**:    Pius Uzamere, [The Uyiosa Corporation](http://www.uyiosa.com)
+This is a [Ruby][] implementation of the [SPARQL][] algebra for [RDF.rb][].
 
-**Copyright**: Pius Uzamere © 2008
-**License**:  The Lesser GNU Public License
+## Features
 
+* 100% free and unencumbered [public domain](http://unlicense.org/) software.
+* [SPARQL 1.0][] query parsing and execution
+* SPARQL results as [XML][SPARQL XML] or [JSON][SPARQL JSON].
+* SPARQL CONSTRUCT or DESCRIBE serialized based on Format, Extension of Mime Type
+  using available RDF Writers (see [Linked Data](http://rubygems.org/gems/linkeddata))
+* SPARQL Client for accessing remote SPARQL endpoints.
+* Helper method for describing [SPARQL Service Description][]
+* Compatible with Ruby Ruby 1.9.x.
+* Compatible with older Ruby versions with the help of the [Backports][] gem.
+* Supports Unicode query strings both on Ruby 1.8.x and 1.9.x.
 
-SYNOPSIS
---------
+## Examples
 
-sparql is a library for Ruby that formally implements the [SPARQL grammar](http://www.w3.org/TR/rdf-sparql-query/#grammar) as a parsing expression grammar (PEG).  The grammar is implemented in a fantastic syntax language called [Treetop](http://treetop.rubyforge.org).
+    require 'rubygems'
+    require 'sparql'
 
+### Executing a SPARQL query against a repository
 
-FEATURE LIST
-------------
-                                                                              
-1. **As of right now (00:10 EST, July 17, 2008) can parse basic SPARQL statements, check the test cases for precisely what it can support**: When finished, this library will be able to parse arbitrary SPARQL queries and can serve as a maintainable reference implementation in Ruby.
+    queryable = RDF::Repository.load("etc/doap.ttl")
+    sse = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
+    sse.execute(queryable)
 
-2.  **Starting point for providing SPARQL endpoints for arbitrary datastores**: When completed, this library will provide hooks that allow a Ruby developer to easily define a translation from SPARQL to another query language or API of their choosing.  Ideally, this will be done using a simple YAML configuration file.
+### Rendering solutions as JSON, XML or HTML
+    queryable = RDF::Repository.load("etc/doap.ttl")
+    solutions = SPARQL.execute("SELECT * WHERE { ?s ?p ?o }", queryable)
+    solutions.to_json #to_xml #to_html
 
-3. **Fully Composable**: Because parsing expression grammars are closed under composition, you can compose this grammar with other Treetop grammars with relative ease.
+### Parsing a SPARQL query string to SSE
 
+    sse = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
+    sse.to_sxp
 
-USAGE
------
+### Command line processing
 
-Though this library only parses a small subset of SPARQL and I've not added all of the API methods yet, it **is** ready to start playing with.
+    sparql --default-graph etc/doap.ttl etc/from_default.rq
+    sparql -e "SELECT * FROM <etc/doap.ttl> WHERE { ?s ?p ?o }"
 
-1. **Install the Gem**
+    # Generate SPARQL Algebra Expression (SSE) format
+    sparql --to-sse etc/input.rq
+    sparql --to-sse -e "SELECT * WHERE { ?s ?p ?o }"
 
-Make sure you've upgraded to RubyGems 1.2.  Then, if you've never installed a gem from GitHub before then do this:
+    # Run query using SSE input
+    sparql --default-graph etc/doap.ttl --sse etc/input.sse
+    sparql --sse -e "(dataset (<etc/doap.ttl>) (bgp (triple ?s ?p ?o))))"
 
-  > gem sources -a http://gems.github.com (you only have to do this once)
+## Documentation
 
-Then:
+Full documentation available on [Rubydoc.info][SPARQL doc]
 
-  > sudo gem install pius-sparql
+### Principle Classes
 
-2. **Make Sure You've Got the Dependencies installed**
+* {SPARQL}
+  * {SPARQL::Algebra}
+    * {SPARQL::Algebra::Expression}
+    * {SPARQL::Algebra::Query}
+    * {SPARQL::Algebra::Operator}
+  * {SPARQL::Grammar}
+    * {SPARQL::Grammar::Parser}
+    * {SPARQL::Grammar::Lexer}
 
-sparql depends on Treetop (http://github.com/nathansobo/treetop).
+## Dependencies
 
-  > sudo gem install treetop
+* [Ruby](http://ruby-lang.org/) (>= 1.9) or (>= 1.8.1 with [Backports][])
+* [RDF.rb](http://rubygems.org/gems/rdf) (>= 0.3.4)
+* [SPARQL::Client](https://rubygems.org/gems/sparql-client) (>= 0.0.11)
+* [SXP](https://rubygems.org/gems/sxp) (>= 0.0.15)
+* [Builder](https://rubygems.org/gems/builder) (>= 3.0.0)
+* [JSON](https://rubygems.org/gems/json) (>= 1.5.1)
 
-3. **Require the gem in your code, play with it**
+## Installation
 
-As of this minute, the code won't be that useful to you, as it can only parse a small subset of SPARQL and the translation hooks have not been added yet.  That being said, stay tuned.  I think development on this is going to move fairly quickly because Treetop is such a joy to write the PEG in.
+The recommended installation method is via [RubyGems](http://rubygems.org/).
+To install the latest official release of the `SPARQL` gem, do:
 
-Anyway, you can get started by doing the following in IRB.
+    % [sudo] gem install sparql
 
-  > irb(main):001:0> require 'rubygems'
+## Download
 
-  > => true
+To get a local working copy of the development repository, do:
 
-  > irb(main):002:0> gem 'pius-sparql'
+    % git clone git://github.com/gkellogg/sparql.git
 
-  > => true
+## Mailing List
 
-  > irb(main):003:0> require 'sparql'
+* <http://lists.w3.org/Archives/Public/public-rdf-ruby/>
 
-  > => true
+## Authors
 
-  > irb(main):004:0> parser = SparqlParser.new
+* [Gregg Kellogg](http://github.com/gkellogg) - <http://kellogg-assoc.com/>
+* [Arto Bendiken](http://github.com/bendiken) - <http://ar.to/>
+* [Pius Uzamere](http://github.com/pius) - <http://pius.me/>
 
-  > => #SparqlParser:0x1270bcc @consume_all_input=true
+## Contributing
 
-  > irb(main):005:0> syntaxtree = parser.parse('SELECT ?foo ?bar WHERE { ?x foaf:knows ?y . ?z foaf:name ?y . }')
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+* Do document every method you add using [YARD][] annotations. Read the
+  [tutorial][YARD-GS] or just look at the existing code for examples.
+* Don't touch the `.gemspec`, `VERSION` or `AUTHORS` files. If you need to
+  change them, do so on your private branch only.
+* Do feel free to add yourself to the `CREDITS` file and the corresponding
+  list in the the `README`. Alphabetical order applies.
+* Do note that in order for us to merge any non-trivial changes (as a rule
+  of thumb, additions larger than about 15 lines of code), we need an
+  explicit [public domain dedication][PDD] on record from you.
 
+## License
 
-4. **Read the documentation**
+This is free and unencumbered public domain software. For more information,
+see <http://unlicense.org/> or the accompanying {file:UNLICENSE} file.
 
-Actually, read the tests -- they will show you the forms that are supported.  Take a look at lib/sparql/sparql.treetop and get a sense of the grammar.  In addition, check out the [formal specification of the SPARQL grammar](http://www.w3.org/TR/rdf-sparql-query/#grammar) so you can see how the Treetop grammar relates to it.
-
-5. **Contribute!**
-
-Fork my repository (http://github.com/pius/sparql), make some changes, and send along a pull request!
-
-The best way to contribute is to add a test case for a specific SPARQL query that does not parse and then tweak the grammar such that your new test case plus all the others pass.
-                                                                              
-
-COPYRIGHT
----------                                                                 
-
-sparql was created in 2008 by Pius Uzamere (pius -AT- alum -DOT- mit -DOT- edu) and is    
-licensed under the LGPL.
+[Ruby]:             http://ruby-lang.org/
+[RDF]:              http://www.w3.org/RDF/
+[YARD]:             http://yardoc.org/
+[YARD-GS]:          http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:              http://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html
+[SPARQL]:           http://en.wikipedia.org/wiki/SPARQL
+[SPARQL 1.0]:       http://www.w3.org/TR/rdf-sparql-query/
+[SPARQL 1.1]:       http://www.w3.org/TR/sparql11-query/
+[SSE]:              http://openjena.org/wiki/SSE
+[SXP]:              http://sxp.rubyforge.org/
+[grammar]:          http://www.w3.org/TR/rdf-sparql-query/#grammar
+[RDF.rb]:           http://rdf.rubyforge.org/
+[YARD]:             http://yardoc.org/
+[YARD-GS]:          http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:              http://unlicense.org/#unlicensing-contributions
+[Backports]:        http://rubygems.org/gems/backports
+[SPARQL doc]:       http://rubydoc.info/github/gkellogg/sparql/frames
+[SPARQL XML]:       http://www.w3.org/TR/rdf-sparql-XMLres/
+[SPARQL JSON]:      http://www.w3.org/TR/rdf-sparql-json-res/
+[SPARQL Protocol]:  http://www.w3.org/TR/rdf-sparql-protocol/
+[SPARQL Service]:   http://www.w3.org/TR/sparql11-service-description/

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/bin/sparql

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "..", 'lib')))
+require 'sparql'
+require 'linkeddata'
+require 'getoptlong'
+
+def run(input, options = {})
+  if options[:debug]
+    puts "input graph:\n#{options[:graph].dump(:n3)}\n" if options[:graph]
+    puts "query:\n#{input}\n"
+  end
+
+  if options[:verbose]
+    puts ("\nSPARQL:\n" + input) 
+  end
+
+  query = if options[:sse]
+    SPARQL::Algebra.parse(input, {:debug => options[:debug]})
+  else
+    SPARQL::Grammar.parse(input, options)
+  end
+
+  if options[:to_sse]
+    puts ("\nSSE:\n" + query.to_sxp)
+  else
+    res = query.execute(options[:graph])
+    puts res.inspect if options[:verbose]
+    puts case res
+    when RDF::Graph then res.dump(:ttl, :base_uri => query.base_uri, :prefixes => query.prefixes)
+    else                 res.map {|s| s.bindings.map {|k,v| "#{k}: #{v}"}}.join("\n")
+    end
+  end
+end
+
+opts = GetoptLong.new(
+  ["--debug", GetoptLong::NO_ARGUMENT],
+  ["--dump", GetoptLong::NO_ARGUMENT],
+  ["--verbose", GetoptLong::NO_ARGUMENT],
+  ["--sse", GetoptLong::NO_ARGUMENT],
+  ["--to-sse", GetoptLong::NO_ARGUMENT],
+  ["--execute", "-e", GetoptLong::REQUIRED_ARGUMENT],
+  ["--default-graph", "-g", GetoptLong::REQUIRED_ARGUMENT],
+  ["--help", "-?", GetoptLong::NO_ARGUMENT]
+)
+
+options = {
+  :graph => RDF::Repository.new,
+}
+
+input = nil
+
+opts.each do |opt, arg|
+  case opt
+  when '--execute'       then input = arg
+  when "--default-graph" then options[:graph] = RDF::Graph.load(arg)
+  when '--dump'          then $dump = true
+  when '--sse'           then options[:sse] = true
+  when '--to-sse'        then options[:to_sse] = true
+  when '--debug'         then options[:debug] = true
+  when '--verbose'       then options[:verbose] = true
+  when "--help"
+    puts "Usage: #{$0} [options] file-or-uri ..."
+    puts "Options:"
+    puts "      --execute,-e:         Use option argument as the SPARQL input if no files are given"
+    puts "      --default-graph:      Load default graph"
+    puts "      --dump:               Dump raw output, otherwise serialize to SSE"
+    puts "      --debug:              Display detailed debug output"
+    puts "      --sse:                Input is in SSE format"
+    puts "      --to-sse:             Generate SSE instead of running query"
+    puts "      --debug:              Display detailed debug output"
+    puts "      --verbose:            Display details of processing"
+    puts "      --help,-?:            This message"
+    exit(0)
+  end
+end
+
+if ARGV.empty?
+  s = input ? input : $stdin.read
+  run(s, options)
+else
+  ARGV.each do |test_file|
+    puts "parse #{test_file}"
+    run(RDF::Util::File.open_file(test_file).read, options.merge(:base_uri => RDF::URI(test_file)))
+  end
+end
+puts

data/lib/sparql.rb

@@ -1,28 +1,111 @@
-# This file is part of Sparql.rb.
-# 
-# Sparql.rb is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# Sparql.rb is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with Sparql.rb.  If not, see <http://www.gnu.org/licenses/>.
+require 'sparql/extensions'
 
+##
+# A SPARQL for RDF.rb.
+#
+# @see http://www.w3.org/TR/rdf-sparql-query
+module SPARQL
+  autoload :Algebra, 'sparql/algebra'
+  autoload :Grammar, 'sparql/grammar'
+  autoload :Results, 'sparql/results'
+  autoload :VERSION, 'sparql/version'
 
-require 'rubygems'
-require 'pathname'
+  # @see http://rubygems.org/gems/sparql-client
+  autoload :Client,  'sparql/client'
 
-class Pathname
-  def /(path)
-    (self + path).expand_path
+  ##
+  # Parse the given SPARQL `query` string.
+  #
+  # @example
+  #   parser = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
+  #   result = parser.parse
+  #
+  # @param  [IO, StringIO, String, #to_s]  query
+  # @param  [Hash{Symbol => Object}] options
+  # @return [SPARQL::Query]
+  #   The resulting query may be executed against
+  #   a `queryable` object such as an RDF::Graph
+  #   or RDF::Repository. 
+  # @raise  [Parser::Error] on invalid input
+  def self.parse(query, options = {})
+    query = Grammar::Parser.new(query, options).parse
   end
-end # class Pathname
 
-dir = Pathname(__FILE__).dirname.expand_path / 'sparql'
+  ##
+  # Parse and execute the given SPARQL `query` string against `queriable`.
+  #
+  # Requires a queryable object (such as an RDF::Repository), into which the dataset will be loaded.
+  #
+  # Optionally takes a list of URIs to load as default or named graphs
+  # into `queryable`.
+  #
+  # Note, if default or named graphs are specified as options (protocol elements),
+  # or the query references specific default or named graphs the graphs are either
+  # presumed to be existant in `queryable` or are loaded into `queryable` depending
+  # on the presense and value of the :load_datasets option.
+  #
+  # Attempting to load into an immutable `queryable` will result in a RDF::TypeError.
+  #
+  # @example
+  #   repository = RDF::Repository.new
+  #   results = SPARQL.execute("SELECT * WHERE { ?s ?p ?o }", repository)
+  #   result = parser.parse
+  #
+  # @param  [IO, StringIO, String, #to_s]  query
+  # @param  [Hash{Symbol => Object}] options
+  # @option options  [RDF::Queryable]  :queryable
+  # @option options [RDF::URI, String, Array<RDF::URI, String>] :load_datasets
+  #   One or more URIs used to initialize a new instance of `queryable` in the default context.
+  # @option options [RDF::URI, String, Array<RDF::URI, String>] :default_graph_uri
+  #   One or more URIs used to initialize a new instance of `queryable` in the default context.
+  # @option options [RDF::URI, String, Array<RDF::URI, String>] :named_graph_uri
+  #   One or more URIs used to initialize the `queryable` as a named context.
+  # @return [RDF::Graph, RDF::Query::Solutions, Boolean]
+  #   Note, results may be used with SPARQL.serialize_results to obtain appropriate
+  #   output encoding.
+  # @raise  [SPARQL::MalformedQuery] on invalid input
+  def self.execute(query, queryable, options = {})
+    query = self.parse(query, options)
+    queryable = queryable || RDF::Repository.new
+    
+    if options.has_key?(:load_datasets)
+      queryable = queryable.class.new
+      [options[:default_graph_uri]].flatten.each do |uri|
+        queryable.load(uri)
+      end
+      [options[:named_graph_uri]].flatten.each do |uri|
+        queryable.load(uri, :context => uri)
+      end
+    end
+    solutions = query.execute(queryable)
+  rescue SPARQL::Grammar::Parser::Error => e
+    raise MalformedQuery, e.message
+  rescue RDF::TypeError => e
+    raise QueryRequestRefused, e.message
+  end
+
+  ##
+  # MalformedQuery
+  #
+  # When the value of the query type is not a legal sequence of characters in the language defined by the
+  # SPARQL grammar, the MalformedQuery or QueryRequestRefused fault message must be returned. According to the
+  # Fault Replaces Message Rule, if a WSDL fault is returned, including MalformedQuery, an Out Message must not
+  # be returned.
+  class MalformedQuery < Exception
+    def title
+      "Malformed Query".freeze
+    end
+  end
+
+  ##
+  # QueryRequestRefused
+  #
+  # returned when a client submits a request that the service refuses to process.
+  class QueryRequestRefused < Exception
+    def title
+      "Query Request Refused".freeze
+    end
+  end
+end
 
-require dir / 'execute_sparql'
+require 'sparql/extensions'