rdf 1.0.0 → 1.0.1

data/CREDITS

@@ -1,4 +1,5 @@
 * Călin Ardelean <calinucs@gmail.com>
+* Mark Borkum <m.i.borkum@soton.ac.uk>
 * Danny Gagne <danny@dannygagne.com>
 * Joey Geiger <jgeiger@gmail.com>
 * Fumihiro Kato <fumi@fumi.me>

data/README

@@ -227,6 +227,7 @@ The meta-gem [LinkedData][LinkedData doc] includes many of these gems.
 ### RDF Querying
 
 * {RDF::Query}
+  * {RDF::Query::HashPatternNormalizer}
   * {RDF::Query::Pattern}
   * {RDF::Query::Solution}
   * {RDF::Query::Solutions}
@@ -302,6 +303,7 @@ follows:
 ## Contributors
 
 * [Călin Ardelean](http://github.com/clnx) - <http://github.com/clnx>
+* [Mark Borkum](http://github.com/markborkum) - <http://github.com/markborkum>
 * [Danny Gagne](http://github.com/danny) - <http://www.dannygagne.com/>
 * [Joey Geiger](http://github.com/jgeiger) - <http://github.com/jgeiger>
 * [Fumihiro Kato](http://github.com/fumi) - <http://fumi.me/>

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

data/lib/rdf/nquads.rb

@@ -4,7 +4,7 @@ module RDF
   #
   # This has not yet been implemented as of RDF.rb 0.3.x.
   module NQuads
-    include NTriples
+    include RDF::NTriples
 
     ##
     # N-Quads format specification.

data/lib/rdf/query.rb

@@ -3,7 +3,7 @@ module RDF
   # An RDF basic graph pattern (BGP) query.
   #
   # Named queries either match against a specifically named
-  # contexts if the name is an RDF::Term or bound RDF::Query::Variable.
+  # contexts if the name is an RDF::Resource or bound RDF::Query::Variable.
   # Names that are against unbound variables match either default
   # or named contexts.
   # The name of `false` will only match against the default context.
@@ -72,6 +72,7 @@ module RDF
     autoload :Solution,  'rdf/query/solution'
     autoload :Solutions, 'rdf/query/solutions'
     autoload :Variable,  'rdf/query/variable'
+    autoload :HashPatternNormalizer, 'rdf/query/hash_pattern_normalizer'
 
     ##
     # Executes a query on the given `queryable` graph or repository.
@@ -125,10 +126,10 @@ module RDF
     #   @param  [Hash{Symbol => Object}] options
     #     any additional keyword options
     #   @option options [RDF::Query::Solutions] :solutions (Solutions.new)
-    #   @option options [RDF::Term, RDF::Query::Variable, Boolean] :context (nil)
+    #   @option options [RDF::Resource, RDF::Query::Variable, false] :context (nil)
     #     Default context for matching against queryable.
     #     Named queries either match against a specifically named
-    #     contexts if the name is an RDF::Term or bound RDF::Query::Variable.
+    #     contexts if the name is an {RDF::Resource} or bound {RDF::Query::Variable}.
     #     Names that are against unbound variables match either detault
     #     or named contexts.
     #     The name of `false` will only match against the default context.
@@ -142,10 +143,10 @@ module RDF
     #   @param  [Hash{Symbol => Object}] options
     #     any additional keyword options
     #   @option options [RDF::Query::Solutions] :solutions (Solutions.new)
-    #   @option options [RDF::Term, RDF::Query::Variable, Boolean] :context (nil)
+    #   @option options [RDF::Resource, RDF::Query::Variable, false] :context (nil)
     #     Default context for matching against queryable.
     #     Named queries either match against a specifically named
-    #     contexts if the name is an RDF::Term or bound RDF::Query::Variable.
+    #     contexts if the name is an {RDF::Resource} or bound {RDF::Query::Variable}.
     #     Names that are against unbound variables match either detault
     #     or named contexts.
     #   @yield  [query]
@@ -159,7 +160,7 @@ module RDF
       context = @options.delete(:context)
 
       @patterns  = case patterns.first
-        when Hash  then compile_hash_patterns(patterns.first.dup)
+        when Hash  then compile_hash_patterns(HashPatternNormalizer.normalize!(patterns.first.dup, @options))
         when Array then patterns.first
         else patterns
       end
@@ -231,7 +232,7 @@ module RDF
     # Executes this query on the given `queryable` graph or repository.
     #
     # Named queries either match against a specifically named
-    # contexts if the name is an RDF::Term or bound RDF::Query::Variable.
+    # contexts if the name is an RDF::Resource or bound RDF::Query::Variable.
     # Names that are against unbound variables match either detault
     # or named contexts.
     # The name of `false` will only match against the default context.
@@ -242,12 +243,16 @@ module RDF
     #   any additional keyword options
     # @option options [Hash{Symbol => RDF::Term}] bindings
     #   optional variable bindings to use
+    # @option options [RDF::Resource, RDF::Query::Variable, false] context (nil)
+    #   Specific context for matching against queryable;
+    #   overrides default context defined on query.
     # @option options [Hash{Symbol => RDF::Term}] solutions
     #   optional initial solutions for chained queries
     # @return [RDF::Query::Solutions]
     #   the resulting solution sequence
     # @see    http://www.holygoat.co.uk/blog/entry/2005-10-25-1
     def execute(queryable, options = {})
+      validate!
       options = options.dup
 
       # just so we can call #keys below without worrying
@@ -259,13 +264,14 @@ module RDF
       @solutions = options[:solutions] || (Solutions.new << RDF::Query::Solution.new({}))
 
       patterns = @patterns
+      context = options.fetch(:context, self.context)
 
       # Add context to pattern, if necessary
-      unless self.context.nil?
+      unless context.nil?
         if patterns.empty?
-          patterns = [Pattern.new(nil, nil, nil, :context => self.context)]
+          patterns = [Pattern.new(nil, nil, nil, :context => context)]
         elsif patterns.first.context.nil?
-          patterns.first.context = self.context
+          patterns.first.context = context
         end
       end
       
@@ -286,9 +292,16 @@ module RDF
         end
 
         old_solutions.each do |solution|
+          found_match = false
           pattern.execute(queryable, solution) do |statement|
+            found_match = true
             @solutions << solution.merge(pattern.solution(statement))
           end
+          # If this pattern was optional, and we didn't find any matches,
+          # just copy it over as-is.
+          if !found_match && pattern.optional?
+            @solutions << solution
+          end
         end
 
         #puts "solutions after #{pattern} are #{@solutions.to_a.inspect}"
@@ -378,6 +391,43 @@ module RDF
     end
     alias_method :each, :each_solution
 
+    ##
+    # Duplicate query, including patterns and solutions
+    # @return [RDF::Query]
+    def dup
+      patterns = @patterns.map {|p| p.dup}
+      patterns << @options.merge(:solutions => @solutions.dup)
+      Query.new(*patterns)
+    end
+
+    ##
+    # Validate this query, making sure it can be executed by our query engine.
+    # This method is public so that it may be called by implementations of
+    # RDF::Queryable#query_execute that bypass our built-in query engine.
+    #
+    # @return [void]
+    # @raise [ArgumentError] This query cannot be executed.
+    def validate!
+      # Our first pattern, if it exists, cannot be an optional pattern.
+      if @patterns.length > 0 && @patterns[0].optional?
+        raise ArgumentError.new("Query must not begin with an optional pattern")
+      end
+
+      # All optional patterns must appear after the regular patterns.  We
+      # could test this more cleanly using Ruby 1.9-specific features, but
+      # we want to run under Ruby 1.8, too.
+      i = 0
+      i += 1 while i < @patterns.length && !@patterns[i].optional?
+      while i < @patterns.length
+        unless @patterns[i].optional?
+          raise ArgumentError.new("Optional patterns must appear at end of query")
+        end
+        i += 1
+      end
+
+      nil
+    end
+
   protected
 
     ##

data/lib/rdf/query/hash_pattern_normalizer.rb

@@ -0,0 +1,191 @@
+module RDF; class Query
+  ##
+  # An RDF query pattern normalizer.
+  class HashPatternNormalizer
+    ##
+    # A counter that can be incremented and decremented.
+    class Counter
+      ##
+      # The offset (or initial value) for this counter.
+      #
+      # @return [Numeric]
+      attr_reader :offset
+      
+      ##
+      # The increment for this counter.
+      #
+      # @return [Numeric]
+      attr_reader :increment
+      
+      ##
+      # @param [Numeric] offset
+      #   the offset (or initial value) for this counter.
+      # @param [Numeric] increment
+      #   the increment for this counter.
+      def initialize(offset = 0, increment = 1)
+        @offset = offset
+        @increment = increment
+        
+        @value = @offset
+      end
+
+      ##
+      # Decrements this counter, and returns the new value. 
+      #
+      # @return [RDF::Query::HashPatternNormalizer::Counter]
+      def decrement!
+        @value -= @increment
+        
+        self
+      end
+      
+      ##
+      # Increments this counter, and returns the new value. 
+      #
+      # @return [RDF::Query::HashPatternNormalizer::Counter]
+      def increment!
+        @value += @increment
+        
+        self
+      end
+      
+      ##
+      # Returns a floating point representation of this counter.
+      #
+      # @return [Float]
+      def to_f
+        @value.to_f
+      end
+      
+      ##
+      # Returns an integer representation of this counter.
+      #
+      # @return [Integer]
+      def to_i
+        @value.to_i
+      end
+      
+      ## Returns a string representation of this counter.
+      #
+      # @return [String]
+      def to_s
+        @value.to_s
+      end
+    end # RDF::Query::HashPatternNormalizer::Counter
+    
+    class << self
+      ##
+      # Returns the normalization of the specified `hash_pattern`.
+      #
+      # @param [Hash{Symbol => Object}] hash_pattern (Hash.new)
+      #   the query pattern as a hash.
+      # @param [Hash{Symbol => Object}] options (Hash.new)
+      #   any additional normalization options.
+      # @option options [String] :anonymous_subject_format ("__%s__")
+      #   the string format for anonymous subjects.
+      # @return [Hash{Symbol => Object}]
+      #   the resulting query pattern as a normalized hash.
+      def normalize!(hash_pattern = {}, options = {})
+        raise ArgumentError, "invalid hash pattern: #{hash_pattern.inspect}" unless hash_pattern.is_a?(Hash)
+        
+        counter = RDF::Query::HashPatternNormalizer::Counter.new
+        
+        anonymous_subject_format = (options[:anonymous_subject_format] || '__%s__').to_s
+        
+        hash_pattern.inject({}) { |acc, pair|
+          subject, predicate_to_object = pair
+          
+          ensure_absence_of_duplicate_subjects!(acc, subject)
+          normalized_predicate_to_object = normalize_hash!(predicate_to_object, acc, counter, anonymous_subject_format)
+          ensure_absence_of_duplicate_subjects!(acc, subject)
+          
+          acc[subject] = normalized_predicate_to_object
+          acc
+        }
+      end
+      
+      private
+      
+      ##
+      # @private
+      def ensure_absence_of_duplicate_subjects!(acc, subject)
+        raise "duplicate subject #{subject.inspect} in normalized hash pattern: #{acc.inspect}" if acc.key?(subject)
+        
+        return
+      end
+      
+      ##
+      # @private
+      def normalize_array!(array, *args)
+        raise ArgumentError, "invalid array pattern: #{array.inspect}" unless array.is_a?(Array)
+        
+        array.collect { |object| 
+          normalize_object!(object, *args)
+        }
+      end
+      
+      ##
+      # @private
+      def normalize_hash!(hash, *args)
+        raise ArgumentError, "invalid hash pattern: #{hash.inspect}" unless hash.is_a?(Hash)
+        
+        hash.inject({}) { |acc, pair|
+          acc[pair.first] = normalize_object!(pair.last, *args)
+          acc
+        }
+      end
+      
+      ##
+      # @private
+      def normalize_object!(object, *args)
+        case object
+          when Array then normalize_array!(object, *args)
+          when Hash  then replace_hash_with_anonymous_subject!(object, *args)
+                     else object
+        end
+      end
+      
+      ##
+      # @private      
+      def replace_hash_with_anonymous_subject!(hash, acc, counter, anonymous_subject_format)
+        raise ArgumentError, "invalid hash pattern: #{hash.inspect}" unless hash.is_a?(Hash)
+        
+        subject = (anonymous_subject_format % counter.increment!).to_sym
+        
+        ensure_absence_of_duplicate_subjects!(acc, subject)
+        normalized_hash = normalize_hash!(hash, acc, counter, anonymous_subject_format)
+        ensure_absence_of_duplicate_subjects!(acc, subject)
+        
+        acc[subject] = normalized_hash
+
+        subject
+      end
+    end
+    
+    ##
+    # The options for this hash pattern normalizer.
+    #
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+    
+    ##
+    # @param [Hash{Symbol => Object}] options (Hash.new)
+    #   any additional normalization options.
+    # @option options [String] :anonymous_subject_format ("__%s__")
+    #   the string format for anonymous subjects.
+    def initialize(options = {})
+      @options = options.dup
+    end
+    
+    ##
+    # Equivalent to calling `self.class.normalize!(hash_pattern, self.options)`.
+    #
+    # @param [Hash{Symbol => Object}] hash_pattern
+    #   the query pattern as a hash.
+    # @return [Hash{Symbol => Object}]
+    #   the resulting query pattern as a normalized hash.
+    def normalize!(hash_pattern = {})
+      self.class.normalize!(hash_pattern, @options)
+    end
+  end # RDF::Query::HashPatternNormalizer
+end; end # RDF::Query

data/lib/rdf/query/solution.rb

@@ -171,6 +171,13 @@ class RDF::Query
       self.class.new(@bindings.dup).merge!(other)
     end
 
+    ##
+    # Duplicate solution, preserving patterns
+    # @return [RDF::Statement]
+    def dup
+      merge({})
+    end
+
     ##
     # Compatible Mappings
     # Two solution mappings u1 and u2 are compatible if, for every variable v in dom(u1) and in dom(u2), u1(v) = u2(v).

data/lib/rdf/writer.rb

@@ -224,7 +224,7 @@ module RDF
     # Returns the base URI used for this writer.
     #
     # @example
-    #   reader.prefixes[:dc]  #=> RDF::URI('http://purl.org/dc/terms/')
+    #   writer.prefixes[:dc]  #=> RDF::URI('http://purl.org/dc/terms/')
     #
     # @return [Hash{Symbol => RDF::URI}]
     # @since  0.3.4

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdf
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-19 00:00:00.000000000 Z
+date: 2013-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -130,6 +130,7 @@ files:
 - lib/rdf/ntriples/reader.rb
 - lib/rdf/ntriples/writer.rb
 - lib/rdf/ntriples.rb
+- lib/rdf/query/hash_pattern_normalizer.rb
 - lib/rdf/query/pattern.rb
 - lib/rdf/query/solution.rb
 - lib/rdf/query/solutions.rb
@@ -185,9 +186,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -3489670263527444797
 requirements: []
 rubyforge_project: rdf
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: A Ruby library for working with Resource Description Framework (RDF) data.