sparql 0.0.1 → 0.0.2

data/lib/sparql/algebra/sxp_extensions.rb

@@ -0,0 +1,35 @@
+##
+# Extensions for Ruby's `NilClass` class.
+class NilClass
+  ##
+  # Returns the SXP representation of this object.
+  #
+  # @return [String]
+  def to_sxp
+    RDF.nil.to_s
+  end
+end
+
+##
+# Extensions for Ruby's `FalseClass` class.
+class FalseClass
+  ##
+  # Returns the SXP representation of this object.
+  #
+  # @return [String]
+  def to_sxp
+    'false'
+  end
+end
+
+##
+# Extensions for Ruby's `TrueClass` class.
+class TrueClass
+  ##
+  # Returns the SXP representation of this object.
+  #
+  # @return [String]
+  def to_sxp
+    'true'
+  end
+end

data/lib/sparql/algebra/version.rb

@@ -0,0 +1,20 @@
+module SPARQL; module Algebra
+  module VERSION
+    VERSION_FILE = File.join(File.expand_path(File.dirname(__FILE__)), "..", "..", "..", "VERSION")
+    MAJOR, MINOR, TINY, EXTRA = File.read(VERSION_FILE).chop.split(".")
+
+    STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')
+
+    ##
+    # @return [String]
+    def self.to_s() STRING end
+
+    ##
+    # @return [String]
+    def self.to_str() STRING end
+
+    ##
+    # @return [Array(Integer, Integer, Integer)]
+    def self.to_a() [MAJOR, MINOR, TINY] end
+  end
+end; end

data/lib/sparql/extensions.rb

@@ -0,0 +1,102 @@
+require 'rdf'
+require 'sparql/results'
+
+##
+# Extensions for `RDF::Queryable`
+module RDF::Queryable
+  ##
+  # Concise Bounded Description
+  #
+  # Given a particular node (the starting node) in a particular RDF graph (the source graph), a subgraph of
+  # that particular graph, taken to comprise a concise bounded description of the resource denoted by the
+  # starting node, can be identified as follows:
+  #
+  #   1. Include in the subgraph all statements in the source graph where the subject of the statement is the
+  #      starting node;
+  #   2. Recursively, for all statements identified in the subgraph thus far having a blank node object,
+  #      include in the subgraph all statements in the source graph where the subject of the statement is the
+  #      blank node in question and which are not already included in the subgraph.
+  #   3. Recursively, for all statements included in the subgraph thus far, for all reifications of each
+  #      statement in the source graph, include the concise bounded description beginning from the
+  #      rdf:Statement node of each reification. (we skip this step)
+  #
+  # This results in a subgraph where the object nodes are either URI references, literals, or blank nodes not
+  # serving as the subject of any statement in the graph.
+  #
+  # Used to implement the SPARQL `describe` operator.
+  #
+  # @param [Array<RDF::Term>] *terms
+  #   List of terms to include in the results.
+  # @param [Hash{Symbol => Object}] options
+  # @option options [Boolean] :non_subjects (true)
+  #   If `term` is not a `subject` within `self`
+  #   then add all `subject`s referencing the term as a `predicate` or `object`.
+  # @option options [RDF::Graph] graph
+  #   Graph containing statements already considered.
+  # @yield [statement]
+  # @yieldparam [RDF::Statement] statement
+  # @yieldreturn [void] ignored
+  # @return [RDF::Graph]
+  #
+  # @see http://www.w3.org/Submission/CBD/
+  def concise_bounded_description(*terms, &block)
+    options = terms.last.is_a?(Hash) ? terms.pop.dup : {}
+    options[:non_subjects] = true unless options.has_key?(:non_subjects)
+
+    graph = options[:graph] || RDF::Graph.new
+
+    if options[:non_subjects]
+      query_terms = terms.dup
+
+      # Find terms not in self as a subject and recurse with their subjects
+      terms.reject {|term| self.first(:subject => term)}.each do |term|
+        self.query(:predicate => term) do |statement|
+          query_terms << statement.subject
+        end
+
+        self.query(:object => term) do |statement|
+          query_terms << statement.subject
+        end
+      end
+      
+      terms = query_terms.uniq
+    end
+
+    # Don't consider term if already in graph
+    terms.reject {|term| graph.first(:subject => term)}.each do |term|
+      # Find statements from queryiable with term as a subject
+      self.query(:subject => term) do |statement|
+        yield(statement) if block_given?
+        graph << statement
+        
+        # Include reifications of this statement
+        RDF::Query.new({
+          :s => {
+            RDF.type => RDF["Statement"],
+            RDF.subject => statement.subject,
+            RDF.predicate => statement.predicate,
+            RDF.object => statement.object,
+          }
+        }).execute(self).each do |solution|
+          # Recurse to include this subject
+          recurse_opts = options.merge(:non_subjects => false, :graph => graph)
+          self.concise_bounded_description(solution[:s], recurse_opts, &block)
+        end
+
+        # Recurse if object is a BNode and it is not already in subjects
+        if statement.object.node?
+          recurse_opts = options.merge(:non_subjects => false, :graph => graph)
+          self.concise_bounded_description(statement.object, recurse_opts, &block)
+        end
+      end
+    end
+    
+    graph
+  end
+end
+
+##
+# Extensions for `RDF::Query::Solutions`.
+class RDF::Query::Solutions
+  include SPARQL::Results
+end

data/lib/sparql/grammar.rb

@@ -0,0 +1,298 @@
+require 'rdf' # @see http://rubygems.org/gems/rdf
+require 'sparql/algebra'
+require 'json'
+require 'sxp'
+
+module SPARQL
+  ##
+  # A SPARQL grammar for RDF.rb.
+  #
+  # ## Representation
+  # The parser natively generates  native SPARQL S-Expressions (SSE),
+  # a hierarch of `SPARQL::Algebra::Operator` instances
+  # which can be executed against a queryable object, such as a Repository identically
+  # to `RDF::Query`.
+  # 
+  # Other elements within the hierarchy
+  # are generated using RDF objects, such as `RDF::URI`, `RDF::Node`, `RDF::Literal`, and `RDF::Query`.
+  # 
+  # See {SPARQL::Grammar::Parser} for a full listing
+  # of algebra operations and RDF objects generated by the parser.
+  # 
+  # The native SSE representation may be serialized to a textual representation of SSE as
+  # serialized general S-Expressions (SXP).
+  # The SXP generated closely follows that of [OpenJena ARQ](http://openjena.org/wiki/SSE), which is intended principally for
+  # running the SPARQL rules. Additionally, SSE is generated for CONSTRUCT, ASK, DESCRIBE and FROM operators.
+  # 
+  # SXP is generated by serializing the parser result as follows:
+  # 
+  #     sse = SPARQL::Grammar.parse("SELECT * WHERE { ?s ?p ?o }")
+  #     sxp = sse.to_sxp
+  # 
+  # The following examples illustrate SPARQL transformations:
+  # 
+  # SPARQL:
+  #     SELECT * WHERE { ?a ?b ?c }
+  # 
+  # SSE:
+  #     RDF::Query.new {
+  #       pattern [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c")]
+  #     }
+  # 
+  # SXP:
+  #     (bgp (triple ?a ?b ?c))
+  # 
+  # SPARQL:
+  #     SELECT * FROM <a> WHERE { ?a ?b ?c }
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Dataset.new(
+  #       [RDF::URI("a")],
+  #       RDF::Query.new {
+  #         pattern [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c")]
+  #       }
+  #     )
+  # 
+  # SXP:
+  #     (dataset (<a>) (bgp (triple ?a ?b ?c)))
+  # 
+  # SPARQL:
+  #     SELECT * FROM NAMED <a> WHERE { ?a ?b ?c }
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Dataset.new(
+  #       [[:named, RDF::URI("a")]],
+  #       RDF::Query.new {
+  #         pattern [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c")]
+  #       }
+  #     )
+  # 
+  # SXP:
+  #     (dataset ((named <a>)) (bgp (triple ?a ?b ?c)))
+  # 
+  # SPARQL:
+  #     SELECT DISTINCT * WHERE {?a ?b ?c}
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Distinct.new(
+  #       RDF::Query.new {
+  #         pattern [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c")]
+  #       }
+  #     )
+  # 
+  # SXP:
+  #     (distinct (bgp (triple ?a ?b ?c)))
+  # 
+  # SPARQL:
+  #     SELECT ?a ?b WHERE {?a ?b ?c}
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Project.new(
+  #       [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b")], 
+  #       RDF::Query.new {
+  #         pattern [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c")]
+  #       }
+  #     )
+  # 
+  # SXP:
+  #     (project (?a ?b) (bgp (triple ?a ?b ?c)))
+  # 
+  # SPARQL:
+  #     CONSTRUCT {?a ?b ?c} WHERE {?a ?b ?c FILTER (?a)}
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Construct.new(
+  #       [RDF::Query::Pattern.new(RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c"))],
+  #       SPARQL::Algebra::Operator::Filter.new(
+  #         RDF::Query::Variable.new("a"),
+  #         RDF::Query.new {
+  #           pattern [RDF::Query::Variable.new("a"), RDF::Query::Variable.new("b"), RDF::Query::Variable.new("c")]
+  #         }
+  #       )
+  #     )
+  # 
+  # SXP:
+  #     (construct ((triple ?a ?b ?c)) (filter ?a (bgp (triple ?a ?b ?c))))
+  # 
+  # SPARQL:
+  #     SELECT * WHERE {<a> <b> <c> OPTIONAL {<d> <e> <f>}}
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::LeftJoin.new(
+  #       RDF::Query.new {
+  #         pattern [RDF::URI("a"), RDF::URI("b"), RDF::URI("c")]
+  #       },
+  #       RDF::Query.new {
+  #         pattern [RDF::URI("d"), RDF::URI("e"), RDF::URI("f")]
+  #       }
+  #     )
+  # 
+  # SXP:
+  #     (leftjoin (bgp (triple <a> <b> <c>)) (bgp (triple <d> <e> <f>)))
+  # 
+  # SPARQL:
+  #     SELECT * WHERE {<a> <b> <c> {<d> <e> <f>}}
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Join.new(
+  #       RDF::Query.new {
+  #         pattern [RDF::URI("a"), RDF::URI("b"), RDF::URI("c")]
+  #       },
+  #       RDF::Query.new {
+  #         pattern [RDF::URI("d"), RDF::URI("e"), RDF::URI("f")]
+  #       }
+  #     )
+  # 
+  # SXP:
+  #     (join (bgp (triple <a> <b> <c>)) (bgp (triple <d> <e> <f>)))
+  # 
+  # SPARQL:
+  #     PREFIX : <http://example/> 
+  # 
+  #     SELECT * 
+  #     { 
+  #        { ?s ?p ?o }
+  #       UNION
+  #        { GRAPH ?g { ?s ?p ?o } }
+  #     }
+  # 
+  # SSE:
+  #     SPARQL::Algebra::Operator::Prefix.new(
+  #       [[:":", RDF::URI("http://example/")]],
+  #       SPARQL::Algebra::Operator::Union.new(
+  #         RDF::Query.new {
+  #           pattern [RDF::Query::Variable.new("s"), RDF::Query::Variable.new("p"), RDF::Query::Variable.new("o")]
+  #         },
+  #         RDF::Query.new(:context => RDF::Query::Variable.new("g")) {
+  #           pattern [RDF::Query::Variable.new("s"), RDF::Query::Variable.new("p"), RDF::Query::Variable.new("o")]
+  #         }
+  #       )
+  #     )
+  # 
+  # SXP:
+  #     (prefix ((: <http://example/>))
+  #       (union
+  #         (bgp (triple ?s ?p ?o))
+  #         (graph ?g
+  #           (bgp (triple ?s ?p ?o)))))
+  # 
+  # ## Implementation Notes
+  # The parser is driven through a rules table contained in lib/sparql/grammar/parser/meta.rb. This includes
+  # branch rules to indicate productions to be taken based on a current production.
+  # 
+  # The meta.rb file is generated from etc/sparql-selectors.n3 which is the result of parsing
+  # http://www.w3.org/2000/10/swap/grammar/sparql.n3 (along with bnf-token-rules.n3) using cwm using the following command sequence:
+  # 
+  #     cwm ../grammar/sparql.n3 bnf-token-rules.n3 --think --purge --data > sparql-selectors.n3
+  # 
+  # sparql-selectors.n3 is itself used to generate lib/sparql/grammar/parser/meta.rb using script/build_meta.
+  # 
+  # Note that The SWAP version of sparql.n3 is an older version of the grammar with the newest in http://www.w3.org/2001/sw/DataAccess/rq23/parsers/sparql.ttl,
+  # which uses the EBNF form. Sparql.n3 file has been updated by hand to be consistent with the etc/sparql.ttl version.
+  # A future direction will be to generate rules from etc/sparql.ttl to generate branch tables similar to those
+  # expressed in meta.rb, but this requires rules not currently available.
+  # 
+  # ## Next Steps for Parsing EBNF
+  # A more modern approach is to use the EBNF grammar (e.g., etc/sparql.bnf) to generate a Turtle/N3 representation of the grammar, transform
+  # this to and LL1 representation and use this to create meta.rb.
+  # 
+  # Using SWAP utilities, this would seemingly be done as follows:
+  # 
+  #     python http://www.w3.org/2000/10/swap/grammar/ebnf2turtle.py \
+  #       http://www.w3.org/2001/sw/DataAccess/rq23/parsers/sparql.bnf \
+  #       en \
+  #       'http://www.w3.org/2001/sw/DataAccess/parsers/sparql#' > etc/sparql.ttl
+  # 
+  #     python http://www.w3.org/2000/10/swap/cwm.py etc/sparql.ttl \
+  #       http://www.w3.org/2000/10/swap/grammar/ebnf2bnf.n3 \
+  #       http://www.w3.org/2000/10/swap/grammar/first_follow.n3 \
+  #       --think --data > etc/sparql-ll1.n3
+  # 
+  # At this point, a variation of script/build_meta should be able to extract first/follow information to re-create the meta branch tables.
+  # 
+  # @see http://www.w3.org/TR/rdf-sparql-query/#grammar
+  module Grammar
+    autoload :Lexer,   'sparql/grammar/lexer'
+    autoload :Parser,  'sparql/grammar/parser'
+    autoload :Meta,    'sparql/grammar/parser/meta'
+    autoload :VERSION, 'sparql/grammar/version'
+
+    METHODS   = %w(SELECT CONSTRUCT DESCRIBE ASK).map(&:to_sym)
+    KEYWORDS  = %w(BASE PREFIX LIMIT OFFSET DISTINCT REDUCED
+                   ORDER BY ASC DESC FROM NAMED WHERE GRAPH
+                   OPTIONAL UNION FILTER).map(&:to_sym).unshift(*METHODS)
+    FUNCTIONS = %w(STR LANGMATCHES LANG DATATYPE BOUND sameTerm
+                   isIRI isURI isBLANK isLITERAL REGEX).map(&:to_sym)
+
+    # Make all defined non-autoloaded constants immutable:
+    constants.each { |name| const_get(name).freeze unless autoload?(name) }
+
+    ##
+    # Parse the given SPARQL `query` string.
+    #
+    # @example
+    #   result = SPARQL::Grammar.parse("SELECT * WHERE { ?s ?p ?o }")
+    #
+    # @param  [IO, StringIO, Lexer, Array, String, #to_s] query
+    #   Query may be an array of lexed tokens, a lexer, or a
+    #   string or open file.
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Parser]
+    # @raise  [Parser::Error] on invalid input
+    def self.parse(query, options = {}, &block)
+      Parser.new(query, options).parse
+    end
+
+    ##
+    # Parses input from the given file name or URL.
+    #
+    # @param  [String, #to_s] filename
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see `RDF::Reader#initialize` and `RDF::Format.for`)
+    # @option options [Symbol] :format (:ntriples)
+    # @yield  [reader]
+    # @yieldparam  [RDF::Reader] reader
+    # @yieldreturn [void] ignored
+    # @raise  [RDF::FormatError] if no reader found for the specified format
+    def self.open(filename, options = {}, &block)
+      RDF::Util::File.open_file(filename, options) do |file|
+        self.parse(file, options, &block)
+      end
+    end
+
+    ##
+    # Returns `true` if the given SPARQL `query` string is valid.
+    #
+    # @example
+    #     SPARQL::Grammar.valid?("SELECT ?s WHERE { ?s ?p ?o }")  #=> true
+    #     SPARQL::Grammar.valid?("SELECT s WHERE { ?s ?p ?o }")   #=> false
+    #
+    # @param  [String, #to_s]          query
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Boolean]
+    def self.valid?(query, options = {})
+      Parser.new(query, options).valid?
+    end
+
+    ##
+    # Tokenizes the given SPARQL `query` string.
+    #
+    # @example
+    #     lexer = SPARQL::Grammar.tokenize("SELECT * WHERE { ?s ?p ?o }")
+    #     lexer.each_token do |token|
+    #       puts token.inspect
+    #     end
+    #
+    # @param  [String, #to_s]          query
+    # @param  [Hash{Symbol => Object}] options
+    # @yield  [lexer]
+    # @yieldparam [Lexer] lexer
+    # @return [Lexer]
+    # @raise  [Lexer::Error] on invalid input
+    def self.tokenize(query, options = {}, &block)
+      Lexer.tokenize(query, options, &block)
+    end
+    
+    class SPARQL_GRAMMAR < RDF::Vocabulary("http://www.w3.org/2000/10/swap/grammar/sparql#"); end
+  end # Grammar
+end # SPARQL