dpla-sparql-client 1.1.3.2.pre.dpla.1

data/lib/sparql/client/query.rb

@@ -0,0 +1,412 @@
+module SPARQL; class Client
+  ##
+  # A SPARQL query builder.
+  #
+  # @example Iterating over all found solutions
+  #   query.each_solution { |solution| puts solution.inspect }
+  #
+  class Query < RDF::Query
+    ##
+    # @return [Symbol]
+    # @see    http://www.w3.org/TR/sparql11-query/#QueryForms
+    attr_reader :form
+
+    ##
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+
+    ##
+    # @return [Array<[key, RDF::Value]>]
+    attr_reader :values
+
+    ##
+    # Creates a boolean `ASK` query.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#ask
+    def self.ask(options = {})
+      self.new(:ask, options)
+    end
+
+    ##
+    # Creates a tuple `SELECT` query.
+    #
+    # @param  [Array<Symbol>]          variables
+    # @return [Query]
+    #
+    # @overload self.select(*variables, options)
+    #   @param  [Array<Symbol>]          variables
+    #   @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#select
+    def self.select(*variables)
+      options = variables.last.is_a?(Hash) ? variables.pop : {}
+      self.new(:select, options).select(*variables)
+    end
+
+    ##
+    # Creates a `DESCRIBE` query.
+    #
+    # @param  [Array<Symbol, RDF::URI>] variables
+    # @return [Query]
+    #
+    # @overload self.describe(*variables, options)
+    #   @param  [Array<Symbol, RDF::URI>] variables
+    #   @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#describe
+    def self.describe(*variables)
+      options = variables.last.is_a?(Hash) ? variables.pop : {}
+      self.new(:describe, options).describe(*variables)
+    end
+
+    ##
+    # Creates a graph `CONSTRUCT` query.
+    #
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    # @return [Query]
+    #
+    # @overload self.construct(*variables, options)
+    #   @param  [Array<RDF::Query::Pattern, Array>] patterns
+    #   @param  [Hash{Symbol => Object}]            options
+    #   @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#construct
+    def self.construct(*patterns)
+      options = patterns.last.is_a?(Hash) ? patterns.pop : {}
+      self.new(:construct, options).construct(*patterns) # FIXME
+    end
+
+    ##
+    # @param  [Symbol, #to_s]          form
+    # @overload self.construct(*variables, options)
+    #   @param  [Symbol, #to_s]          form
+    #   @param  [Hash{Symbol => Object}] options
+    # @yield  [query]
+    # @yieldparam [Query]
+    def initialize(form = :ask, options = {}, &block)
+      @subqueries = []
+      @form = form.respond_to?(:to_sym) ? form.to_sym : form.to_s.to_sym
+      super([], options, &block)
+    end
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#ask
+    def ask
+      @form = :ask
+      self
+    end
+
+    ##
+    # @param  [Array<Symbol>] variables
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#select
+    def select(*variables)
+      @values = variables.map { |var| [var, RDF::Query::Variable.new(var)] }
+      self
+    end
+
+    ##
+    # @param  [Array<Symbol>] variables
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#describe
+    def describe(*variables)
+      @values = variables.map { |var|
+        [var, var.is_a?(RDF::URI) ? var : RDF::Query::Variable.new(var)]
+      }
+      self
+    end
+
+    ##
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#construct
+    def construct(*patterns)
+      options[:template] = build_patterns(patterns)
+      self
+    end
+
+    # @param [RDF::URI] uri
+    # @return [Query]
+    # @see http://www.w3.org/TR/sparql11-query/#specifyingDataset
+    def from(uri)
+      options[:from] = uri
+      self
+    end
+
+    ##
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns_queries
+    #   splat of zero or more patterns followed by zero or more queries.
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#GraphPattern
+    def where(*patterns_queries)
+      subqueries, patterns = patterns_queries.partition {|pq| pq.is_a? SPARQL::Client::Query}
+      @patterns += build_patterns(patterns)
+      @subqueries += subqueries
+      self
+    end
+
+    alias_method :whether, :where
+
+    ##
+    # @param  [Array<Symbol, String>] variables
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#modOrderBy
+    def order(*variables)
+      options[:order_by] = variables
+      self
+    end
+
+    alias_method :order_by, :order
+
+    ##
+    # @param  [Array<Symbol, String>] variables
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#groupby
+    def group(*variables)
+      options[:group_by] = variables
+      self
+    end
+
+    alias_method :group_by, :group
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#modDuplicates
+    def distinct(state = true)
+      options[:distinct] = state
+      self
+    end
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#modDuplicates
+    def reduced(state = true)
+      options[:reduced] = state
+      self
+    end
+
+    ##
+    # @param  [RDF::Value] graph_uri_or_var
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#queryDataset
+    def graph(graph_uri_or_var)
+      options[:graph] = case graph_uri_or_var
+        when Symbol then RDF::Query::Variable.new(graph_uri_or_var)
+        when String then RDF::URI(graph_uri_or_var)
+        when RDF::Value then graph_uri_or_var
+        else raise ArgumentError
+      end
+      self
+    end
+
+    ##
+    # @param  [Integer, #to_i] start
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#modOffset
+    def offset(start)
+      slice(start, nil)
+    end
+
+    ##
+    # @param  [Integer, #to_i] length
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#modResultLimit
+    def limit(length)
+      slice(nil, length)
+    end
+
+    ##
+    # @param  [Integer, #to_i] start
+    # @param  [Integer, #to_i] length
+    # @return [Query]
+    def slice(start, length)
+      options[:offset] = start.to_i if start
+      options[:limit] = length.to_i if length
+      self
+    end
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#prefNames
+    def prefix(string)
+      (options[:prefixes] ||= []) << string
+      self
+    end
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#optionals
+    def optional(*patterns)
+      (options[:optionals] ||= []) << build_patterns(patterns)
+      self
+    end
+
+    ##
+    # @return expects_statements?
+    def expects_statements?
+      [:construct, :describe].include?(form)
+    end
+
+    ##
+    # @private
+    def build_patterns(patterns)
+      patterns.map do |pattern|
+        case pattern
+          when RDF::Query::Pattern then pattern
+          else RDF::Query::Pattern.new(*pattern.to_a)
+        end
+      end
+    end
+
+    ##
+    # @private
+    def filter(string)
+      ((options[:filters] ||= []) << string) if string and not string.empty?
+      self
+    end
+
+    ##
+    # @return [Boolean]
+    def true?
+      case result
+        when TrueClass, FalseClass then result
+        when RDF::Literal::Boolean then result.true?
+        when Enumerable then !result.empty?
+        else false
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    def false?
+      !true?
+    end
+
+    ##
+    # @return [Enumerable<RDF::Query::Solution>]
+    def solutions
+      result
+    end
+
+    ##
+    # @yield  [statement]
+    # @yieldparam [RDF::Statement]
+    # @return [Enumerator]
+    def each_statement(&block)
+      result.each_statement(&block)
+    end
+
+    # Enumerates over each matching query solution.
+    #
+    # @yield  [solution]
+    # @yieldparam [RDF::Query::Solution] solution
+    # @return [Enumerator]
+    def each_solution(&block)
+      @solutions = result
+      super
+    end
+
+    ##
+    # @return [Object]
+    def result
+      @result ||= execute
+    end
+
+    ##
+    # @return [Object]
+    def execute
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the string representation of this query.
+    #
+    # @return [String]
+    def to_s
+      buffer = [form.to_s.upcase]
+
+      case form
+        when :select, :describe
+          only_count = values.empty? && options[:count]
+          buffer << 'DISTINCT' if options[:distinct] and not only_count
+          buffer << 'REDUCED'  if options[:reduced]
+          buffer << ((values.empty? and not options[:count]) ? '*' : values.map { |v| SPARQL::Client.serialize_value(v[1]) }.join(' '))
+          if options[:count]
+            options[:count].each do |var, count|
+              buffer << '( COUNT(' + (options[:distinct] ? 'DISTINCT ' : '') +
+                (var.is_a?(String) ? var : "?#{var}") + ') AS ' + (count.is_a?(String) ? count : "?#{count}") + ' )'
+            end
+          end
+        when :construct
+          buffer << '{'
+          buffer += SPARQL::Client.serialize_patterns(options[:template])
+          buffer << '}'
+      end
+
+      buffer << "FROM #{SPARQL::Client.serialize_value(options[:from])}" if options[:from]
+
+      unless patterns.empty? && form == :describe
+        buffer << 'WHERE {'
+
+        if options[:graph]
+          buffer << 'GRAPH ' + SPARQL::Client.serialize_value(options[:graph])
+          buffer << '{'
+        end
+
+        @subqueries.each do |sq|
+          buffer << "{ #{sq.to_s} } ."
+        end
+
+        buffer += SPARQL::Client.serialize_patterns(patterns)
+        if options[:optionals]
+          options[:optionals].each do |patterns|
+            buffer << 'OPTIONAL {'
+            buffer += SPARQL::Client.serialize_patterns(patterns)
+            buffer << '}'
+          end
+        end
+        if options[:filters]
+          buffer += options[:filters].map { |filter| "FILTER(#{filter})" }
+        end
+        if options[:graph]
+          buffer << '}' # GRAPH
+        end
+
+        buffer << '}' # WHERE
+      end
+
+      if options[:group_by]
+        buffer << 'GROUP BY'
+        buffer += options[:group_by].map { |var| var.is_a?(String) ? var : "?#{var}" }
+      end
+
+      if options[:order_by]
+        buffer << 'ORDER BY'
+        buffer += options[:order_by].map { |var| var.is_a?(String) ? var : "?#{var}" }
+      end
+
+      buffer << "OFFSET #{options[:offset]}" if options[:offset]
+      buffer << "LIMIT #{options[:limit]}"   if options[:limit]
+      options[:prefixes].reverse.each { |e| buffer.unshift("PREFIX #{e}") } if options[:prefixes]
+
+      buffer.join(' ')
+    end
+
+    ##
+    # Outputs a developer-friendly representation of this query to `stderr`.
+    #
+    # @return [void]
+    def inspect!
+      warn(inspect)
+      self
+    end
+
+    ##
+    # Returns a developer-friendly representation of this query.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, to_s)
+    end
+  end
+end; end

data/lib/sparql/client/repository.rb

@@ -0,0 +1,302 @@
+module SPARQL; class Client
+  ##
+  # A read-only repository view of a SPARQL endpoint.
+  #
+  # @see RDF::Repository
+  class Repository < RDF::Repository
+    # @return [SPARQL::Client]
+    attr_reader :client
+
+    ##
+    # @param  [String, #to_s]          endpoint
+    # @param  [Hash{Symbol => Object}] options
+    def initialize(endpoint, options = {})
+      @options = options.dup
+      @update_client = SPARQL::Client.new(options.delete(:update_endpoint), options) if options[:update_endpoint]
+      @client  = SPARQL::Client.new(endpoint, options)
+    end
+
+    ##
+    # Returns the client for the update_endpoint if specified, otherwise the
+    # {client}.
+    #
+    # @return [SPARQL::Client]
+    def update_client
+      @update_client || @client
+    end
+
+    ##
+    # Queries `self` using the given basic graph pattern (BGP) query,
+    # yielding each matched solution to the given block.
+    #
+    # Overrides Queryable::query_execute to use SPARQL::Client::query
+    #
+    # @param  [RDF::Query] query
+    #   the query to execute
+    # @param  [Hash{Symbol => Object}] options ({})
+    #   Any other options passed to `query.execute`
+    # @yield  [solution]
+    # @yieldparam  [RDF::Query::Solution] solution
+    # @yieldreturn [void] ignored
+    # @return [void] ignored
+    # @see    RDF::Queryable#query
+    # @see    RDF::Query#execute
+    def query_execute(query, options = {}, &block)
+      return nil unless block_given?
+      q = SPARQL::Client::Query.select(query.variables).where(*query.patterns)
+      client.query(q, options).each do |solution|
+        yield solution
+      end
+    end
+
+    ##
+    # Enumerates each RDF statement in this repository.
+    #
+    # @yield  [statement]
+    # @yieldparam [RDF::Statement] statement
+    # @see    RDF::Repository#each
+    def each(&block)
+      client.construct([:s, :p, :o]).where([:s, :p, :o]).each_statement(&block)
+    end
+
+    ##
+    # @private
+    # @see RDF::Enumerable#supports?
+    def supports?(feature)
+      case feature.to_sym
+        # statement contexts / named graphs
+        when :context   then false
+        when :inference then false  # forward-chaining inference
+        when :validity  then false
+        else false
+      end
+    end
+
+    ##
+    # Returns `true` if this repository contains the given subject.
+    #
+    # @param  [RDF::Resource] subject
+    # @return [Boolean]
+    # @see    RDF::Repository#has_subject?
+    def has_subject?(subject)
+      client.ask.whether([subject, :p, :o]).true?
+    end
+
+    ##
+    # Returns `true` if this repository contains the given predicate.
+    #
+    # @param  [RDF::URI] predicate
+    # @return [Boolean]
+    # @see    RDF::Repository#has_predicate?
+    def has_predicate?(predicate)
+      client.ask.whether([:s, predicate, :o]).true?
+    end
+
+    ##
+    # Returns `true` if this repository contains the given object.
+    #
+    # @param  [RDF::Value] object
+    # @return [Boolean]
+    # @see    RDF::Repository#has_object?
+    def has_object?(object)
+      client.ask.whether([:s, :p, object]).true?
+    end
+
+    ##
+    # Iterates over each subject in this repository.
+    #
+    # @yield  [subject]
+    # @yieldparam [RDF::Resource] subject
+    # @return [Enumerator]
+    # @see    RDF::Repository#each_subject?
+    def each_subject(&block)
+      if block_given?
+        client.select(:s, :distinct => true).where([:s, :p, :o]).each_solution { |solution| block.call(solution[:s]) }
+      end
+      enum_subject
+    end
+
+    ##
+    # Iterates over each predicate in this repository.
+    #
+    # @yield  [predicate]
+    # @yieldparam [RDF::URI] predicate
+    # @return [Enumerator]
+    # @see    RDF::Repository#each_predicate?
+    def each_predicate(&block)
+      if block_given?
+        client.select(:p, :distinct => true).where([:s, :p, :o]).each_solution { |solution| block.call(solution[:p]) }
+      end
+      enum_predicate
+    end
+
+    ##
+    # Iterates over each object in this repository.
+    #
+    # @yield  [object]
+    # @yieldparam [RDF::Value] object
+    # @return [Enumerator]
+    # @see    RDF::Repository#each_object?
+    def each_object(&block)
+      if block_given?
+        client.select(:o, :distinct => true).where([:s, :p, :o]).each_solution { |solution| block.call(solution[:o]) }
+      end
+      enum_object
+    end
+
+    ##
+    # Returns `true` if this repository contains the given `triple`.
+    #
+    # @param  [Array<RDF::Resource, RDF::URI, RDF::Value>] triple
+    # @return [Boolean]
+    # @see    RDF::Repository#has_triple?
+    def has_triple?(triple)
+      client.ask.whether(triple.to_a[0...3]).true?
+    end
+
+    ##
+    # Returns `true` if this repository contains the given `statement`.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [Boolean]
+    # @see    RDF::Repository#has_statement?
+    def has_statement?(statement)
+      has_triple?(statement.to_triple)
+    end
+
+    ##
+    # Returns the number of statements in this repository.
+    #
+    # @return [Integer]
+    # @see    RDF::Repository#count?
+    def count
+      begin
+        binding = client.query("SELECT COUNT(*) WHERE { ?s ?p ?o }").first.to_hash
+        binding[binding.keys.first].value.to_i
+      rescue SPARQL::Client::MalformedQuery => e
+        # SPARQL 1.0 does not include support for aggregate functions:
+        count = 0
+        each_statement { count += 1 } # TODO: optimize this
+        count
+      end
+    end
+
+    alias_method :size,   :count
+    alias_method :length, :count
+
+    ##
+    # Returns `true` if this repository contains no statements.
+    #
+    # @return [Boolean]
+    # @see    RDF::Repository#empty?
+    def empty?
+      client.ask.whether([:s, :p, :o]).false?
+    end
+
+    ##
+    # Queries `self` for RDF statements matching the given `pattern`.
+    #
+    # @example
+    #     repository.query([nil, RDF::DOAP.developer, nil])
+    #     repository.query(:predicate => RDF::DOAP.developer)
+    #
+    # @fixme This should use basic SPARQL query mechanism.
+    #
+    # @param  [Pattern] pattern
+    # @see    RDF::Queryable#query_pattern
+    # @yield  [statement]
+    # @yieldparam [Statement]
+    # @return [Enumerable<Statement>]
+    def query_pattern(pattern, &block)
+      pattern = pattern.dup
+      pattern.subject   ||= RDF::Query::Variable.new
+      pattern.predicate ||= RDF::Query::Variable.new
+      pattern.object    ||= RDF::Query::Variable.new
+      pattern.initialize!
+      query = client.construct(pattern).where(pattern)
+
+      if block_given?
+        query.each_statement(&block)
+      else
+        query.solutions.to_a.extend(RDF::Enumerable, RDF::Queryable)
+      end
+    end
+
+    ##
+    # Returns `false` to indicate that this is a read-only repository.
+    #
+    # @return [Boolean]
+    # @see    RDF::Mutable#mutable?
+    def writable?
+      true
+    end
+
+    ##
+    # @private
+    # @see RDF::Mutable#clear
+    def clear_statements
+      update_client.clear(:all)
+    end
+
+    ##
+    # Deletes RDF statements from `self`.
+    # If any statement contains a {Query::Variable}, it is
+    # considered to be a pattern, and used to query
+    # self to find matching statements to delete.
+    #
+    # @param  [Enumerable<RDF::Statement>] statements
+    # @raise  [TypeError] if `self` is immutable
+    # @return [Mutable]
+    def delete(*statements)
+      delete_statements(statements) unless statements.empty?
+      return self
+    end
+
+    protected
+
+    ##
+    # Deletes the given RDF statements from the underlying storage.
+    #
+    # Overridden here to use SPARQL/UPDATE
+    #
+    # @param  [RDF::Enumerable] statements
+    # @return [void]
+    def delete_statements(statements)
+
+      constant = statements.all? do |value|
+        # needs to be flattened... urgh
+        !value.respond_to?(:each_statement) && begin
+          statement = RDF::Statement.from(value)
+          statement.constant? && !statement.has_blank_nodes?
+        end
+      end
+
+      if constant
+        update_client.delete_data(statements)
+      else
+        update_client.delete_insert(statements)
+      end
+    end
+
+    ##
+    # Inserts the given RDF statements into the underlying storage or output
+    # stream.
+    #
+    # Overridden here to use SPARQL/UPDATE
+    #
+    # @param  [RDF::Enumerable] statements
+    # @return [void]
+    # @since  0.1.6
+    def insert_statements(statements)
+      update_client.insert_data(statements)
+    end
+
+    ##
+    # @private
+    # @see RDF::Mutable#insert
+    def insert_statement(statement)
+      update_client.insert_data([statement])
+    end
+
+  end
+end; end