rdf 0.3.3 → 0.3.4

data/lib/rdf/query/pattern.rb

@@ -22,6 +22,7 @@ module RDF; class Query
     #   @option options [Variable, URI]      :predicate (nil)
     #   @option options [Variable, Term]     :object    (nil)
     #   @option options [Variable, Resource] :context   (nil)
+    #     A context of nil matches any context, a context of false, matches only the default context.
     #   @option options [Boolean]            :optional  (false)
     #
     # @overload initialize(subject, predicate, object, options = {})
@@ -118,10 +119,12 @@ module RDF; class Query
     ##
     # Executes this query pattern on the given `queryable` object.
     #
-    # By default any variable terms in this pattern will be treated as `nil`
-    # wildcards when executing the query. If the optional `bindings` are
-    # given, variables will be substituted with their values when executing
-    # the query.
+    # Values are matched using using Queryable#query_pattern.
+    #
+    # If the optional `bindings` are given, variables will be substituted with their values
+    # when executing the query.
+    #
+    # To match triples only in the default context, set context to `false'.
     #
     # @example
     #   Pattern.new(:s, :p, :o).execute(RDF::Repository.load('data.nt'))
@@ -140,11 +143,11 @@ module RDF; class Query
     # @since  0.3.0
     def execute(queryable, bindings = {}, &block)
       query = {
-        :subject   => subject   && subject.variable?   ? bindings[subject.to_sym]   : subject,
-        :predicate => predicate && predicate.variable? ? bindings[predicate.to_sym] : predicate,
-        :object    => object    && object.variable?    ? bindings[object.to_sym]    : object,
-        # TODO: context handling?
-      }
+        :subject   => subject.is_a?(Variable)   && bindings[subject.to_sym]   ? bindings[subject.to_sym]   : subject,
+        :predicate => predicate.is_a?(Variable) && bindings[predicate.to_sym] ? bindings[predicate.to_sym] : predicate,
+        :object    => object.is_a?(Variable)    && bindings[object.to_sym]    ? bindings[object.to_sym]    : object,
+        :context   => context.is_a?(Variable)   && bindings[context.to_sym]   ? bindings[context.to_sym]   : context,
+      }.delete_if{|k,v| v.nil?}
 
       # Do all the variable terms refer to distinct variables?
       variables = self.variables
@@ -184,9 +187,10 @@ module RDF; class Query
     # @since  0.3.0
     def solution(statement)
       RDF::Query::Solution.new do |solution|
-        solution[subject.to_sym]   = statement.subject   if subject.variable?
-        solution[predicate.to_sym] = statement.predicate if predicate.variable?
-        solution[object.to_sym]    = statement.object    if object.variable?
+        solution[subject.to_sym]   = statement.subject   if subject.is_a?(Variable)
+        solution[predicate.to_sym] = statement.predicate if predicate.is_a?(Variable)
+        solution[object.to_sym]    = statement.object    if object.is_a?(Variable)
+        solution[context.to_sym]   = statement.context   if context.is_a?(Variable)
       end
     end
 
@@ -205,6 +209,7 @@ module RDF; class Query
       terms << :subject   if subject.is_a?(Variable)   && (!name || name.eql?(subject.name))
       terms << :predicate if predicate.is_a?(Variable) && (!name || name.eql?(predicate.name))
       terms << :object    if object.is_a?(Variable)    && (!name || name.eql?(object.name))
+      terms << :context   if context.is_a?(Variable)   && (!name || name.eql?(context.name))
       terms
     end
 
@@ -220,6 +225,7 @@ module RDF; class Query
       count += 1 if subject.is_a?(Variable)
       count += 1 if predicate.is_a?(Variable)
       count += 1 if object.is_a?(Variable)
+      count += 1 if context.is_a?(Variable)
       count
     end
     alias_method :cardinality, :variable_count
@@ -236,6 +242,7 @@ module RDF; class Query
       variables.merge!(subject.variables)   if subject.is_a?(Variable)
       variables.merge!(predicate.variables) if predicate.is_a?(Variable)
       variables.merge!(object.variables)    if object.is_a?(Variable)
+      variables.merge!(context.variables)   if context.is_a?(Variable)
       variables
     end
 
@@ -264,6 +271,7 @@ module RDF; class Query
       bindings.merge!(subject.bindings)   if subject.is_a?(Variable)
       bindings.merge!(predicate.bindings) if predicate.is_a?(Variable)
       bindings.merge!(object.bindings)    if object.is_a?(Variable)
+      bindings.merge!(context.bindings)   if context.is_a?(Variable)
       bindings
     end
 
@@ -306,9 +314,14 @@ module RDF; class Query
     def to_s
       StringIO.open do |buffer| # FIXME in RDF::Statement
         buffer << 'OPTIONAL ' if optional?
-        buffer << (subject.is_a?(Variable)   ? subject.to_s :   "<#{subject}>") << ' '
-        buffer << (predicate.is_a?(Variable) ? predicate.to_s : "<#{predicate}>") << ' '
-        buffer << (object.is_a?(Variable)    ? object.to_s :    "<#{object}>") << ' .'
+        buffer << [subject, predicate, object].map do |r|
+          r.is_a?(RDF::Query::Variable) ? r.to_s : RDF::NTriples.serialize(r)
+        end.join(" ")
+        buffer << case context
+          when nil, false then " ."
+          when Variable then " #{context.to_s} ."
+          else " #{RDF::NTriples.serialize(context)} ."
+        end
         buffer.string
       end
     end

data/lib/rdf/query/solution.rb

@@ -171,6 +171,33 @@ class RDF::Query
       self.class.new(@bindings.dup).merge!(other)
     end
 
+    ##
+    # Compatible Mappings
+    # Two solution mappings μ1 and μ2 are compatible if, for every variable v in dom(μ1) and in dom(μ2), μ1(v) = μ2(v).
+    #
+    # @param [RDF::Query::Solution, #to_hash] other
+    #   another query solution or hash bindings
+    # @return [Boolean]
+    def compatible?(other)
+      @bindings.all? do |k, v|
+        !other.to_hash.has_key?(k) || other[k].eql?(v)
+      end
+    end
+    
+    ##
+    # Isomorphic Mappings
+    # Two solution mappings μ1 and μ2 are isomorphic if,
+    # for every variable v in dom(μ1) and in dom(μ2), μ1(v) = μ2(v).
+    #
+    # @param [RDF::Query::Solution, #to_hash] other
+    #   another query solution or hash bindings
+    # @return [Boolean]
+    def isomorphic_with?(other)
+      @bindings.all? do |k, v|
+        !other.to_hash.has_key?(k) || other[k].eql?(v)
+      end
+    end
+    
     ##
     # @return [Array<Array(Symbol, RDF::Term)>}
     def to_a
@@ -182,6 +209,26 @@ class RDF::Query
     def to_hash
       @bindings.dup
     end
+    
+    ##
+    # Integer hash of this solution
+    # @return [Integer]
+    def hash
+      @bindings.hash
+    end
+    
+    ##
+    # Equivalence of solution
+    def eql?(other)
+      other.is_a?(Solution) && @bindings.eql?(other.bindings)
+    end
+    alias_method :==, :eql?
+
+    ##
+    # Equals of solution
+    def ==(other)
+      other.is_a?(Solution) && @bindings == other.bindings
+    end
 
     ##
     # @return [String]

data/lib/rdf/query/solutions.rb

@@ -16,13 +16,15 @@ module RDF; class Query
   #   solutions.filter { |solution| solution.age.datatype == RDF::XSD.integer }
   #   solutions.filter { |solution| solution.name.language == :es }
   #
-  # @example Reordering solutions based on a variable
+  # @example Reordering solutions based on a variable or proc
   #   solutions.order_by(:updated)
   #   solutions.order_by(:updated, :created)
+  #   solutions.order_by(:updated, lambda {|a, b| b <=> a})
   #
-  # @example Selecting particular variables only
+  # @example Selecting/Projecting particular variables only
   #   solutions.select(:title)
   #   solutions.select(:title, :description)
+  #   solutions.project(:title)
   #
   # @example Eliminating duplicate solutions
   #   solutions.distinct
@@ -58,6 +60,22 @@ module RDF; class Query
       super
     end
 
+    ##
+    # Returns hash of bindings from each solution. Each bound variable will have
+    # an array of bound values representing those from each solution, where a given
+    # solution will have just a single value for each bound variable
+    # @return [Hash{Symbol => Array<RDF::Term>}]
+    def bindings
+      bindings = {}
+      each do |solution|
+        solution.each do |key, value|
+          bindings[key] ||= []
+          bindings[key] << value
+        end
+      end
+      bindings
+    end
+    
     ##
     # Filters this solution sequence by the given `criteria`.
     #
@@ -87,18 +105,35 @@ module RDF; class Query
     ##
     # Reorders this solution sequence by the given `variables`.
     #
-    # @param  [Array<Symbol, #to_sym>] variables
+    # Variables may be symbols or {Query::Variable} instances.
+    # A variable may also be a Procedure/Lambda, compatible with {::Enumerable#sort}.
+    # This takes two arguments (solutions) and returns -1, 0, or 1 equivalently to <=>.
+    #
+    # If called with a block, variables are ignored, and the block is invoked with
+    # pairs of solutions. The block is expected to return -1, 0, or 1 equivalently to <=>.
+    #
+    # @param  [Array<Proc, Query::Variable, Symbol, #to_sym>] variables
+    # @yield  [solution]
+    # @yieldparam  [RDF::Query::Solution] q
+    # @yieldparam  [RDF::Query::Solution] b
+    # @yieldreturn [Integer] -1, 0, or 1 depending on value of comparator
     # @return [void] `self`
-    def order(*variables)
-      if variables.empty?
+    def order(*variables, &block)
+      if variables.empty? && !block_given?
         raise ArgumentError, "wrong number of arguments (0 for 1)"
       else
-        # TODO: support for descending sort, e.g. `order(:s => :asc, :p => :desc)`
-        variables.map!(&:to_sym)
         self.sort! do |a, b|
-          a = variables.map { |variable| a[variable].to_s } # FIXME
-          b = variables.map { |variable| b[variable].to_s } # FIXME
-          a <=> b
+          if block_given?
+            block.call((a.is_a?(Solution) ? a : Solution.new(a)), (b.is_a?(Solution) ? b : Solution.new(b)))
+          else
+            # Try each variable until a difference is found.
+            variables.inject(nil) do |memo, v|
+              memo || begin
+                comp = v.is_a?(Proc) ? v.call(a, b) : (v = v.to_sym; a[v] <=> b[v])
+                comp == 0 ? false : comp
+              end
+            end || 0
+          end
         end
       end
       self

data/lib/rdf/query/variable.rb

@@ -102,6 +102,23 @@ class RDF::Query
       value.nil?
     end
 
+    ##
+    # Returns `true` if this variable is distinguished.
+    #
+    # @return [Boolean]
+    def distinguished?
+      @distinguished.nil? || @distinguished
+    end
+
+    ##
+    # Sets if variable is distinguished or non-distinguished.
+    # By default, variables are distinguished
+    #
+    # @return [Boolean]
+    def distinguished=(value)
+      @distinguished = value
+    end
+
     ##
     # Rebinds this variable to the given `value`.
     #
@@ -153,14 +170,21 @@ class RDF::Query
 
     ##
     # Returns `true` if this variable is equivalent to a given `other`
-    # variable.
+    # variable. Or, to another Term if bound, or to any other Term
     #
     # @param  [Object] other
     # @return [Boolean] `true` or `false`
     # @since  0.3.0
     def eql?(other)
-      other.is_a?(RDF::Query::Variable) && @name.eql?(other.name)
+      if unbound?
+        other.is_a?(RDF::Term) # match any Term when unbound
+      elsif other.is_a?(RDF::Query::Variable)
+        @name.eql?(other.name)
+      else
+        value.eql?(other)
+      end
     end
+    alias_method :==, :eql?
 
     ##
     # Compares this variable with the given value.
@@ -169,7 +193,7 @@ class RDF::Query
     # @return [Boolean]
     def ===(other)
       if unbound?
-        true # match anything when unbound
+        other.is_a?(RDF::Term) # match any Term when unbound
       else
         value === other
       end
@@ -178,9 +202,20 @@ class RDF::Query
     ##
     # Returns a string representation of this variable.
     #
+    # Distinguished variables are indicated with a single `?`.
+    #
+    # Non-distinguished variables are indicated with a double `??`
+    #
+    # @example
+    #   v = Variable.new("a")
+    #   v.to_s => '?a'
+    #   v.distinguished = false
+    #   v.to_s => '??a'
+    #
     # @return [String]
     def to_s
-      unbound? ? "?#{name}" : "?#{name}=#{value}"
+      prefix = distinguished? ? '?' : "??"
+      unbound? ? "#{prefix}#{name}" : "#{prefix}#{name}=#{value}"
     end
   end # Variable
 end # RDF::Query

data/lib/rdf/reader.rb

@@ -55,6 +55,8 @@ module RDF
     ##
     # Finds an RDF reader class based on the given criteria.
     #
+    # If the reader class has a defined format, use that.
+    #
     # @overload for(format)
     #   Finds an RDF reader class based on a symbolic name.
     #
@@ -75,16 +77,23 @@ module RDF
     #   @option options [Symbol, #to_sym] :file_extension (nil)
     #   @option options [String, #to_s]   :content_type   (nil)
     #   @return [Class]
+    #   @option options [String]          :sample (nil)
+    #     A sample of input used for performing format detection.
+    #     If we find no formats, or we find more than one, and we have a sample, we can
+    #     perform format detection to find a specific format to use, in which case
+    #     we pick the first one we find
+    #   @return [Class]
+    #   @yieldreturn [String] another way to provide a sample, allows lazy for retrieving the sample.
     #
     # @return [Class]
-    def self.for(options = {})
-      if format = Format.for(options)
+    def self.for(options = {}, &block)
+      if format = self.format || Format.for(options, &block)
         format.reader
       end
     end
 
     ##
-    # Retrieves the RDF serialization format class for this writer class.
+    # Retrieves the RDF serialization format class for this reader class.
     #
     # @return [Class]
     def self.format(klass = nil)
@@ -118,7 +127,12 @@ module RDF
         format_options = options.dup
         format_options[:content_type] ||= file.content_type if file.respond_to?(:content_type)
         format_options[:file_name] ||= filename
-        reader = self.for(format_options[:format] || format_options)
+        reader = self.for(format_options[:format] || format_options) do
+          # Return a sample from the input file
+          sample = file.read(1000)
+          file.rewind
+          sample
+        end
         if reader
           reader.new(file, options, &block)
         else
@@ -127,6 +141,23 @@ module RDF
       end
     end
 
+    ##
+    # Returns a symbol appropriate to use with RDF::Reader.for()
+    # @return [Symbol]
+    def self.to_sym
+      elements = self.to_s.split("::")
+      sym = elements.pop
+      sym = elements.pop if sym == 'Reader'
+      sym.downcase.to_s.to_sym
+    end
+
+    ##
+    # Returns a symbol appropriate to use with RDF::Reader.for()
+    # @return [Symbol]
+    def to_sym
+      self.class.to_sym
+    end
+    
     ##
     # Initializes the reader.
     #
@@ -177,6 +208,18 @@ module RDF
     # @since  0.3.0
     attr_reader :options
 
+    ##
+    # Returns the base URI determined by this reader.
+    #
+    # @example
+    #   reader.prefixes[:dc]  #=> RDF::URI('http://purl.org/dc/terms/')
+    #
+    # @return [Hash{Symbol => RDF::URI}]
+    # @since  0.3.0
+    def base_uri
+      @options[:base_uri]
+    end
+
     ##
     # Returns the URI prefixes currently defined for this reader.
     #

data/lib/rdf/repository.rb

@@ -70,6 +70,8 @@ module RDF
     # Loads one or more RDF files into a new transient in-memory repository.
     #
     # @param  [String, Array<String>] filenames
+    # @param  [Hash{Symbol => Object}] options
+    #   Options from {RDF::Reader#initialize}, {RDF::Format.for} and {RDF::Repository#initialize}
     # @yield  [repository]
     # @yieldparam [Repository]
     # @return [void]
@@ -324,6 +326,8 @@ module RDF
     protected
 
       ##
+      # Match elements with eql?, not ==
+      # Context of `false` matches default context. Unbound variable matches non-false context
       # @private
       # @see RDF::Queryable#query
       def query_pattern(pattern, &block)
@@ -334,16 +338,16 @@ module RDF
 
         cs = @data.has_key?(context) ? {context => @data[context]} : @data.dup
         cs.each do |c, ss|
-          next unless context.nil? || context == c
+          next unless context.nil? || context == false && !c || context.eql?(c)
           ss = ss.has_key?(subject) ? {subject => ss[subject]} : ss.dup
           ss.each do |s, ps|
-            next unless subject.nil? || subject == s
+            next unless subject.nil? || subject.eql?(s)
             ps = ps.has_key?(predicate) ? {predicate => ps[predicate]} : ps.dup
             ps.each do |p, os|
-              next unless predicate.nil? || predicate == p
+              next unless predicate.nil? || predicate.eql?(p)
               os = os.dup # TODO: is this really needed?
               os.each do |o|
-                next unless object.nil? || object == o
+                next unless object.nil? || object.eql?(o)
                 block.call(RDF::Statement.new(s, p, o, :context => c.equal?(DEFAULT_CONTEXT) ? nil : c))
               end
             end