sparql-client 2.0.2 → 3.1.0

data/lib/sparql/client/query.rb

@@ -1,4 +1,4 @@
-module SPARQL; class Client
+class SPARQL::Client
   ##
   # A SPARQL query builder.
   #
@@ -17,12 +17,6 @@ module SPARQL; class Client
     # @return [Hash{Symbol => Object}]
     attr_reader :options
 
-    ##
-    # Values returned from previous query.
-    #
-    # @return [Array<[key, RDF::Value]>]
-    attr_reader :values
-
     ##
     # Creates a boolean `ASK` query.
     #
@@ -32,8 +26,8 @@ module SPARQL; class Client
     # @param  [Hash{Symbol => Object}] options (see {#initialize})
     # @return [Query]
     # @see    http://www.w3.org/TR/sparql11-query/#ask
-    def self.ask(options = {})
-      self.new(:ask, options)
+    def self.ask(**options)
+      self.new(:ask, **options)
     end
 
     ##
@@ -42,17 +36,22 @@ module SPARQL; class Client
     # @example SELECT * WHERE { ?s ?p ?o . }
     #   Query.select.where([:s, :p, :o])
     #
+    # @example SELECT ?s WHERE {?s ?p ?o .}
+    #   Query.select(:s).where([:s, :p, :o])
+    #
+    # @example SELECT COUNT(?uri as ?c) WHERE {?uri a owl:Class}
+    #   Query.select(count: {uri: :c}).where([:uri, RDF.type, RDF::OWL.Class])
+    #
     # @param  [Array<Symbol>]          variables
     # @return [Query]
     #
-    # @overload self.select(*variables, options)
+    # @overload self.select(*variables, **options)
     #   @param  [Array<Symbol>]          variables
     #   @param  [Hash{Symbol => Object}] options (see {#initialize})
     #   @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)
+    def self.select(*variables, **options)
+      self.new(:select, **options).select(*variables)
     end
 
     ##
@@ -64,14 +63,13 @@ module SPARQL; class Client
     # @param  [Array<Symbol, RDF::URI>] variables
     # @return [Query]
     #
-    # @overload self.describe(*variables, options)
+    # @overload self.describe(*variables, **options)
     #   @param  [Array<Symbol, RDF::URI>] variables
     #   @param  [Hash{Symbol => Object}] options (see {#initialize})
     #   @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)
+    def self.describe(*variables, **options)
+      self.new(:describe, **options).describe(*variables)
     end
 
     ##
@@ -83,27 +81,30 @@ module SPARQL; class Client
     # @param  [Array<RDF::Query::Pattern, Array>] patterns
     # @return [Query]
     #
-    # @overload self.construct(*variables, options)
+    # @overload self.construct(*variables, **options)
     #   @param  [Array<RDF::Query::Pattern, Array>] patterns
     #   @param  [Hash{Symbol => Object}] options (see {#initialize})
     #   @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
+    def self.construct(*patterns, **options)
+      self.new(:construct, **options).construct(*patterns) # FIXME
     end
 
     ##
     # @param  [Symbol, #to_s]          form
-    # @overload self.construct(*variables, options)
+    # @overload self.construct(*variables, **options)
     #   @param  [Symbol, #to_s]          form
     #   @param  [Hash{Symbol => Object}] options (see {Client#initialize})
+    #   @option options [Hash{Symbol => Symbol}] :count
+    #     Contents are symbols relating a variable described within the query,
+    #     to the projected variable.
+    #     
     # @yield  [query]
     # @yieldparam [Query]
-    def initialize(form = :ask, options = {}, &block)
+    def initialize(form = :ask, **options, &block)
       @subqueries = []
       @form = form.respond_to?(:to_sym) ? form.to_sym : form.to_s.to_sym
-      super([], options, &block)
+      super([], **options, &block)
     end
 
     ##
@@ -121,11 +122,21 @@ module SPARQL; class Client
     # @example SELECT * WHERE { ?s ?p ?o . }
     #   query.select.where([:s, :p, :o])
     #
-    # @param  [Array<Symbol>] variables
+    # @example SELECT ?s WHERE {?s ?p ?o .}
+    #   query.select(:s).where([:s, :p, :o])
+    #
+    # @example SELECT COUNT(?uri as ?c) WHERE {?uri a owl:Class}
+    #   query.select(count: {uri: :c}).where([:uri, RDF.type, RDF::OWL.Class])
+    #
+    # @param  [Array<Symbol>, Hash{Symbol => RDF::Query::Variable}] 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)] }
+      @values = if variables.length == 1 && variables.first.is_a?(Hash)
+        variables.to_a
+      else
+        variables.map { |var| [var, RDF::Query::Variable.new(var)] }
+      end
       self
     end
 
@@ -172,19 +183,55 @@ module SPARQL; class Client
     #   query.select.where([:s, :p, :o])
     #   query.select.whether([:s, :p, :o])
     #
+    # @example SELECT * WHERE { { SELECT * WHERE { ?s ?p ?o . } } . ?s ?p ?o . }
+    #   subquery = query.select.where([:s, :p, :o])
+    #   query.select.where([:s, :p, :o], subquery)
+    #
+    # @example SELECT * WHERE { { SELECT * WHERE { ?s ?p ?o . } } . ?s ?p ?o . }
+    #   query.select.where([:s, :p, :o]) do |q|
+    #     q.select.where([:s, :p, :o])
+    #   end
+    #
+    # Block form can be used for chaining calls in addition to creating sub-select queries.
+    #
+    # @example SELECT * WHERE { ?s ?p ?o . } ORDER BY ?o
+    #   query.select.where([:s, :p, :o]) do
+    #     order(:o)
+    #   end
+    #
     # @param  [Array<RDF::Query::Pattern, Array>] patterns_queries
     #   splat of zero or more patterns followed by zero or more queries.
+    # @yield [query]
+    #   Yield form with or without argument; without an argument, evaluates within the query.
+    # @yieldparam [SPARQL::Client::Query] query Actually a delegator to query. Methods other than `#select` are evaluated against `self`. For `#select`, a new Query is created, and the result added as a subquery.
     # @return [Query]
     # @see    http://www.w3.org/TR/sparql11-query/#GraphPattern
-    def where(*patterns_queries)
+    def where(*patterns_queries, &block)
       subqueries, patterns = patterns_queries.partition {|pq| pq.is_a? SPARQL::Client::Query}
       @patterns += build_patterns(patterns)
       @subqueries += subqueries
+
+      if block_given?
+        decorated_query = WhereDecorator.new(self)
+        case block.arity
+          when 1 then block.call(decorated_query)
+          else decorated_query.instance_eval(&block)
+        end
+      end
       self
     end
 
     alias_method :whether, :where
 
+    # @private
+    class WhereDecorator < SimpleDelegator
+      def select(*variables)
+        query = SPARQL::Client::Query.select(*variables)
+        __getobj__.instance_variable_get(:@subqueries) << query
+        query
+      end
+    end
+
     ##
     # @example SELECT * WHERE { ?s ?p ?o . } ORDER BY ?o
     #   query.select.where([:s, :p, :o]).order(:o)
@@ -194,7 +241,7 @@ module SPARQL; class Client
     #   query.select.where([:s, :p, :o]).order_by(:o, :p)
     #
     # @example SELECT * WHERE { ?s ?p ?o . } ORDER BY ASC(?o) DESC(?p)
-    #   query.select.where([:s, :p, :o]).order_by(:o => :asc, :p => :desc)
+    #   query.select.where([:s, :p, :o]).order_by(o: :asc, p: :desc)
     #
     # @param  [Array<Symbol, String>] variables
     # @return [Query]
@@ -320,16 +367,38 @@ module SPARQL; class Client
     end
 
     ##
-    # @example PREFIX dc: <http://purl.org/dc/elements/1.1/> PREFIX foaf: <http://xmlns.com/foaf/0.1/> SELECT * WHERE \{ ?s ?p ?o . \}
-    #   query.select.
-    #     prefix(dc: RDF::URI("http://purl.org/dc/elements/1.1/")).
-    #     prefix(foaf: RDF::URI("http://xmlns.com/foaf/0.1/")).
-    #     where([:s, :p, :o])
+    # @overload prefix(prefix: uri)
+    #   @example PREFIX dc: <http://purl.org/dc/elements/1.1/> PREFIX foaf: <http://xmlns.com/foaf/0.1/> SELECT * WHERE \{ ?s ?p ?o . \}
+    #     query.select.
+    #       prefix(dc: RDF::URI("http://purl.org/dc/elements/1.1/")).
+    #       prefix(foaf: RDF::URI("http://xmlns.com/foaf/0.1/")).
+    #       where([:s, :p, :o])
     #
-    # @return [Query]
+    #   @param [RDF::URI] uri
+    #   @param [Symbol, String] prefix
+    #   @return [Query]
+    #
+    # @overload prefix(string)
+    #   @example PREFIX dc: <http://purl.org/dc/elements/1.1/> PREFIX foaf: <http://xmlns.com/foaf/0.1/> SELECT * WHERE \{ ?s ?p ?o . \}
+    #     query.select.
+    #       prefix("dc: <http://purl.org/dc/elements/1.1/>").
+    #       prefix("foaf: <http://xmlns.com/foaf/0.1/>").
+    #       where([:s, :p, :o])
+    #
+    #   @param [string] string
+    #   @return [Query]
     # @see    http://www.w3.org/TR/sparql11-query/#prefNames
-    def prefix(string)
-      (options[:prefixes] ||= []) << string
+    def prefix(val)
+      options[:prefixes] ||= []
+      if val.kind_of? String
+        options[:prefixes] << val
+      elsif val.kind_of? Hash
+        val.each do |k, v|
+          options[:prefixes] << "#{k}: <#{v}>"
+        end
+      else
+        raise ArgumentError, "prefix must be a kind of String or a Hash"
+      end
       self
     end
 
@@ -338,10 +407,206 @@ module SPARQL; class Client
     #   query.select.where([:s, :p, :o]).
     #     optional([:s, RDF.type, :o], [:s, RDF::Vocab::DC.abstract, :o])
     #
+    # The block form can be used for adding filters:
+    #
+    # @example ASK WHERE { ?s ?p ?o . OPTIONAL { ?s ?p ?o . FILTER(regex(?s, 'Abiline, Texas'))} }
+    #   query.ask.where([:s, :p, :o]).optional([:s, :p, :o]) do
+    #     filter("regex(?s, 'Abiline, Texas')")
+    #   end
+    #
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    #   splat of zero or more patterns followed by zero or more queries.
+    # @yield [query]
+    #   Yield form with or without argument; without an argument, evaluates within the query.
+    # @yieldparam [SPARQL::Client::Query] query used for creating filters on the optional patterns.
     # @return [Query]
     # @see    http://www.w3.org/TR/sparql11-query/#optionals
-    def optional(*patterns)
+    def optional(*patterns, &block)
       (options[:optionals] ||= []) << build_patterns(patterns)
+
+      if block_given?
+        # Steal options[:filters]
+        query_filters = options[:filters]
+        options[:filters] = []
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+        options[:optionals].last.concat(options[:filters])
+        options[:filters] = query_filters
+      end
+
+      self
+    end
+
+    ##
+    # @example SELECT * WHERE \{ ?book dc:title ?title \} UNION \{ ?book dc11:title ?title \}
+    #   query.select.where([:book, RDF::Vocab::DC.title, :title]).
+    #     union([:book, RDF::Vocab::DC11.title, :title])
+    #
+    # @example SELECT * WHERE \{ ?book dc:title ?title \} UNION \{ ?book dc11:title ?title . FILTER(langmatches(lang(?title), 'EN'))\}
+    #   query1 = SPARQL::Client::Query.select.
+    #     where([:book, RDF::Vocab::DC11.title, :title]).
+    #     filter("langmatches(?title, 'en')")
+    #   query.select.where([:book, RDF::Vocab::DC.title, :title]).union(query1)
+    #
+    # The block form can be used for more complicated queries, using the `select` form (note, use either block or argument forms, not both):
+    #
+    # @example SELECT * WHERE \{ ?book dc:title ?title \} UNION \{ ?book dc11:title ?title . FILTER(langmatches(lang(?title), 'EN'))\}
+    #   query1 = SPARQL::Client::Query.select.where([:book, RDF::Vocab::DC11.title, :title]).filter("langmatches(?title, 'en')")
+    #   query.select.where([:book, RDF::Vocab::DC.title, :title]).union do |q|
+    #     q.select.
+    #       where([:book, RDF::Vocab::DC11.title, :title]).
+    #       filter("langmatches(?title, 'en')")
+    #   end
+    #
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    #   splat of zero or more patterns followed by zero or more queries.
+    # @yield [query]
+    #   Yield form with or without argument; without an argument, evaluates within the query.
+    # @yieldparam [SPARQL::Client::Query] query used for adding select clauses.
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#optionals
+    def union(*patterns, &block)
+      options[:unions] ||= []
+
+      if block_given?
+        raise ArgumentError, "#union requires either arguments or a block, not both." unless patterns.empty?
+        # Evaluate calls in a new query instance
+        query = self.class.select
+        case block.arity
+          when 1 then block.call(query)
+          else query.instance_eval(&block)
+        end
+        options[:unions] << query
+      elsif patterns.all? {|p| p.is_a?(SPARQL::Client::Query)}
+        # With argument form, all must be patterns or queries
+        options[:unions] += patterns
+      elsif patterns.all? {|p| p.is_a?(Array)}
+        # With argument form, all must be patterns, or queries
+        options[:unions] << self.class.select.where(*patterns)
+      else
+        raise ArgumentError, "#union arguments are triple patters or queries, not both."
+      end
+
+      self
+    end
+
+    ##
+    # @example SELECT * WHERE \{ ?book dc:title ?title . MINUS \{ ?book dc11:title ?title \} \}
+    #   query.select.where([:book, RDF::Vocab::DC.title, :title]).
+    #     minus([:book, RDF::Vocab::DC11.title, :title])
+    #
+    # @example SELECT * WHERE \{ ?book dc:title ?title MINUS \{ ?book dc11:title ?title . FILTER(langmatches(lang(?title), 'EN')) \} \}
+    #   query1 = SPARQL::Client::Query.select.
+    #     where([:book, RDF::Vocab::DC11.title, :title]).
+    #     filter("langmatches(?title, 'en')")
+    #   query.select.where([:book, RDF::Vocab::DC.title, :title]).minus(query1)
+    #
+    # The block form can be used for more complicated queries, using the `select` form (note, use either block or argument forms, not both):
+    #
+    # @example SELECT * WHERE \{ ?book dc:title ?title MINUS \{ ?book dc11:title ?title . FILTER(langmatches(lang(?title), 'EN'))\} \}
+    #   query1 = SPARQL::Client::Query.select.where([:book, RDF::Vocab::DC11.title, :title]).filter("langmatches(?title, 'en')")
+    #   query.select.where([:book, RDF::Vocab::DC.title, :title]).minus do |q|
+    #     q.select.
+    #       where([:book, RDF::Vocab::DC11.title, :title]).
+    #       filter("langmatches(?title, 'en')")
+    #   end
+    #
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    #   splat of zero or more patterns followed by zero or more queries.
+    # @yield [query]
+    #   Yield form with or without argument; without an argument, evaluates within the query.
+    # @yieldparam [SPARQL::Client::Query] query used for adding select clauses.
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#optionals
+    def minus(*patterns, &block)
+      options[:minuses] ||= []
+
+      if block_given?
+        raise ArgumentError, "#minus requires either arguments or a block, not both." unless patterns.empty?
+        # Evaluate calls in a new query instance
+        query = self.class.select
+        case block.arity
+          when 1 then block.call(query)
+          else query.instance_eval(&block)
+        end
+        options[:minuses] << query
+      elsif patterns.all? {|p| p.is_a?(SPARQL::Client::Query)}
+        # With argument form, all must be patterns or queries
+        options[:minuses] += patterns
+      elsif patterns.all? {|p| p.is_a?(Array)}
+        # With argument form, all must be patterns, or queries
+        options[:minuses] << self.class.select.where(*patterns)
+      else
+        raise ArgumentError, "#minus arguments are triple patters or queries, not both."
+      end
+
+      self
+    end
+
+    ##
+    # Specify inline data for a query
+    #
+    # @overload values
+    #   Values returned from previous query.
+    #
+    #   @return [Array<Array(key, RDF::Value)>]
+    #
+    # @overload values(vars, *data)
+    #   @example single variable with multiple values
+    #     query.select
+    #      .where([:s, RDF::URI('http://purl.org/dc/terms/title'), :title])
+    #      .values(:title, "This title", "Another title")
+    #
+    #   @example multiple variables with multiple values
+    #     query.select
+    #      .where([:s, RDF::URI('http://purl.org/dc/terms/title'), :title],
+    #             [:s, RDF.type, :type])
+    #      .values([:type, :title],
+    #              [RDF::URI('http://pcdm.org/models#Object'), "This title"],
+    #              [RDF::URI('http://pcdm.org/models#Collection', 'Another title'])
+    #
+    #   @example multiple variables with UNDEF
+    #     query.select
+    #      .where([:s, RDF::URI('http://purl.org/dc/terms/title'), :title],
+    #             [:s, RDF.type, :type])
+    #      .values([:type, :title],
+    #              [nil "This title"],
+    #              [RDF::URI('http://pcdm.org/models#Collection', nil])
+    #
+    #   @param [Symbol, Array<Symbol>] vars
+    #   @param [Array<RDF::Term, String, nil>] *data
+    #   @return [Query]
+    def values(*args)
+      return @values if args.empty?
+      vars, *data = *args
+      vars = Array(vars).map {|var| RDF::Query::Variable.new(var)}
+      if vars.length == 1
+        # data may be a in array form or simple form
+        if data.any? {|d| d.is_a?(Array)} && !data.all? {|d| d.is_a?(Array)}
+          raise ArgumentError, "values data must all be in array form or all simple"
+        end
+        data = data.map {|d| Array(d)}
+      end
+
+      # Each data value must be an array with the same number of entries as vars
+      unless data.all? {|d| d.is_a?(Array) && d.all? {|dd| dd.is_a?(RDF::Value) || dd.is_a?(String) || dd.nil?}}
+        raise ArgumentError, "values data must each be an array of terms, strings, or nil"
+      end
+
+      # Turn strings into Literals
+      data = data.map do |d|
+        d.map do |nil_literal_or_term|
+          case nil_literal_or_term
+          when nil then nil
+          when String then RDF::Literal(nil_literal_or_term)
+          when RDF::Value then graph_uri_or_var
+          else raise ArgumentError
+          end
+        end
+      end
+      options[:values] = [vars, *data]
       self
     end
 
@@ -352,15 +617,17 @@ module SPARQL; class Client
     end
 
     ##
-    # @private
+    # @private 
     def build_patterns(patterns)
       patterns.map {|pattern| RDF::Query::Pattern.from(pattern)}
     end
 
     ##
-    # @private
+    # @example ASK WHERE { ?s ?p ?o . FILTER(regex(?s, 'Abiline, Texas')) }
+    #   query.ask.where([:s, :p, :o]).filter("regex(?s, 'Abiline, Texas')")
+    # @return [Query]
     def filter(string)
-      ((options[:filters] ||= []) << string) if string and not string.empty?
+      ((options[:filters] ||= []) << Filter.new(string)) if string and not string.empty?
       self
     end
 
@@ -445,33 +712,11 @@ module SPARQL; class Client
       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 += self.to_s_ggp.unshift('WHERE')
+      end
 
-        buffer << '}' # WHERE
+      options.fetch(:unions, []).each do |query|
+        buffer += query.to_s_ggp.unshift('UNION')
       end
 
       if options[:group_by]
@@ -483,7 +728,7 @@ module SPARQL; class Client
         buffer << 'ORDER BY'
         options[:order_by].map { |elem|
           case elem
-            # .order_by({ :var1 => :asc, :var2 => :desc})
+            # .order_by({ var1: :asc, var2: :desc})
             when Hash
               elem.each { |key, val|
                 # check provided values
@@ -524,6 +769,55 @@ module SPARQL; class Client
       buffer.join(' ')
     end
 
+    # Serialize a Group Graph Pattern
+    # @private
+    def to_s_ggp
+      buffer = ["{"]
+
+      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(&:to_s)
+      end
+      if options[:values]
+        vars = options[:values].first.map {|var| SPARQL::Client.serialize_value(var)}
+        buffer << "VALUES (#{vars.join(' ')}) {"
+        options[:values][1..-1].each do |data_block_value|
+          buffer << '('
+          buffer << data_block_value.map do |value|
+            value.nil? ? 'UNDEF' : SPARQL::Client.serialize_value(value)
+          end.join(' ')
+          buffer << ')'
+        end
+        buffer << '}'
+      end
+      if options[:graph]
+        buffer << '}' # GRAPH
+      end
+
+      options.fetch(:minuses, []).each do |query|
+        buffer += query.to_s_ggp.unshift('MINUS')
+      end
+
+      buffer << '}'
+      buffer
+    end
+
     ##
     # Outputs a developer-friendly representation of this query to `stderr`.
     #
@@ -540,5 +834,16 @@ module SPARQL; class Client
     def inspect
       sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, to_s)
     end
+
+    # Allow Filters to be 
+    class Filter < SPARQL::Client::QueryElement
+      def initialize(*args)
+        super
+      end
+
+      def to_s
+        "FILTER(#{elements.join(' ')})"
+      end
+    end
   end
-end; end
+end