openlogic-rdf 0.3.6

data/lib/rdf/ntriples.rb

@@ -0,0 +1,104 @@
+module RDF
+  ##
+  # **`RDF::NTriples`** provides support for the N-Triples serialization
+  # format.
+  #
+  # N-Triples is a line-based plain-text format for encoding an RDF graph.
+  # It is a very restricted, explicit and well-defined subset of both
+  # [Turtle](http://www.w3.org/TeamSubmission/turtle/) and
+  # [Notation3](http://www.w3.org/TeamSubmission/n3/) (N3).
+  #
+  # The MIME content type for N-Triples files is `text/plain` and the
+  # recommended file extension is `.nt`.
+  #
+  # An example of an RDF statement in N-Triples format:
+  #
+  #     <http://rubyforge.org/> <http://purl.org/dc/terms/title> "RubyForge" .
+  #
+  # Installation
+  # ------------
+  #
+  # This is the only RDF serialization format that is directly supported by
+  # RDF.rb. Support for other formats is available in the form of add-on
+  # gems, e.g. 'rdf-xml' or 'rdf-json'.
+  #
+  # Documentation
+  # -------------
+  #
+  # * {RDF::NTriples::Format}
+  # * {RDF::NTriples::Reader}
+  # * {RDF::NTriples::Writer}
+  #
+  # @example Requiring the `RDF::NTriples` module explicitly
+  #   require 'rdf/ntriples'
+  #
+  # @see http://www.w3.org/TR/rdf-testcases/#ntriples
+  # @see http://en.wikipedia.org/wiki/N-Triples
+  # @see http://librdf.org/ntriples/
+  #
+  # @author [Arto Bendiken](http://ar.to/)
+  module NTriples
+    require 'iconv' unless "".respond_to?(:encode )# needed on Ruby 1.8.x
+    require 'rdf/ntriples/format'
+    autoload :Reader, 'rdf/ntriples/reader'
+    autoload :Writer, 'rdf/ntriples/writer'
+
+    ##
+    # Reconstructs an RDF value from its serialized N-Triples
+    # representation.
+    #
+    # @param  [String] data
+    # @return [RDF::Value]
+    # @see    RDF::NTriples::Reader.unserialize
+    # @since  0.1.5
+    def self.unserialize(data)
+      Reader.unserialize(data)
+    end
+
+    ##
+    # Returns the serialized N-Triples representation of the given RDF
+    # value.
+    #
+    # @param  [RDF::Value] value
+    # @return [String]
+    # @see    RDF::NTriples::Writer.serialize
+    # @since  0.1.5
+    def self.serialize(value)
+      Writer.serialize(value)
+    end
+
+    ##
+    # @param  [String] string
+    # @return [String]
+    # @see    RDF::NTriples::Reader.unescape
+    # @since  0.2.2
+    def self.unescape(string)
+      Reader.unescape(string)
+    end
+
+    ##
+    # @param  [String] string
+    # @return [String]
+    # @see    RDF::NTriples::Writer.escape
+    # @since  0.2.2
+    def self.escape(string)
+      Writer.escape(string)
+    end
+  end # NTriples
+
+  ##
+  # Extensions for `RDF::Value`.
+  module Value
+    ##
+    # Returns the N-Triples representation of this value.
+    #
+    # This method is only available when the 'rdf/ntriples' serializer has
+    # been explicitly required.
+    #
+    # @return [String]
+    # @since  0.2.1
+    def to_ntriples
+      RDF::NTriples.serialize(self)
+    end
+  end # Value
+end # RDF

data/lib/rdf/query/pattern.rb

@@ -0,0 +1,329 @@
+module RDF; class Query
+  ##
+  # An RDF query pattern.
+  class Pattern < RDF::Statement
+    ##
+    # @private
+    # @since 0.2.2
+    def self.from(pattern, options = {})
+      case pattern
+        when Pattern then pattern
+        when Array, Statement
+          self.new(pattern[0], pattern[1], pattern[2], options.merge(:context => pattern[3]))
+        when Hash    then self.new(options.merge(pattern))
+        else raise ArgumentError, "expected RDF::Query::Pattern, RDF::Statement, Hash, or Array, but got #{pattern.inspect}"
+      end
+    end
+
+    ##
+    # @overload initialize(options = {})
+    #   @param  [Hash{Symbol => Object}]     options
+    #   @option options [Variable, Resource] :subject   (nil)
+    #   @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 = {})
+    #   @param  [Variable, Resource]         subject
+    #   @param  [Variable, URI]              predicate
+    #   @param  [Variable, Term]             object
+    #   @param  [Hash{Symbol => Object}]     options
+    #   @option options [Variable, Resource] :context   (nil)
+    #   @option options [Boolean]            :optional  (false)
+    def initialize(subject = nil, predicate = nil, object = nil, options = {})
+      super
+    end
+
+    ##
+    # @private
+    def initialize!
+      @context   = Variable.new(@context)   if @context.is_a?(Symbol)
+      @subject   = Variable.new(@subject)   if @subject.is_a?(Symbol)
+      @predicate = Variable.new(@predicate) if @predicate.is_a?(Symbol)
+      @object    = Variable.new(@object)    if @object.is_a?(Symbol)
+      super
+    end
+
+    ##
+    # Any additional options for this pattern.
+    #
+    # @return [Hash]
+    attr_reader :options
+
+    ##
+    # The estimated cost of this pattern (for query optimization).
+    #
+    # @return [Numeric]
+    attr_accessor :cost
+
+    ##
+    # Returns `true` if this is a blank pattern, with all terms being `nil`.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def blank?
+      subject.nil? && predicate.nil? && object.nil? && context.nil?
+    end
+
+    ##
+    # Returns `true` if this is a constant pattern, with all terms being
+    # either URIs, blank nodes, or literals.
+    #
+    # A constant pattern is structurally and functionally equivalent to an
+    # RDF statement.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def constant?
+      !(variable?)
+    end
+
+    ##
+    # Returns `true` if this is a variable pattern, with any term being
+    # `nil` or a variable.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def variable?
+      subject.nil? || predicate.nil? || object.nil? || context.nil? || has_variables?
+    end
+
+    ##
+    # Returns `true` if this pattern contains any variables.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def has_variables?
+      subject.is_a?(Variable) ||
+        predicate.is_a?(Variable) ||
+        object.is_a?(Variable) ||
+        context.is_a?(Variable)
+    end
+    alias_method :variables?, :has_variables?
+
+    ##
+    # Returns `true` if this is an optional pattern.
+    #
+    # @example
+    #   Pattern.new(:s, :p, :o).optional?                     #=> false
+    #   Pattern.new(:s, :p, :o, :optional => true).optional?  #=> true
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def optional?
+      !!options[:optional]
+    end
+
+    ##
+    # Executes this query pattern on the given `queryable` object.
+    #
+    # 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'))
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => RDF::Term}] bindings
+    #   optional variable bindings to use
+    # @yield  [statement]
+    #   each matching statement
+    # @yieldparam [RDF::Statement] statement
+    #   an RDF statement matching this pattern
+    # @return [Enumerator]
+    #   an enumerator yielding matching statements
+    # @see    RDF::Queryable#query
+    # @since  0.3.0
+    def execute(queryable, bindings = {}, &block)
+      query = {
+        :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
+      if variable_count == variables.size
+        # If so, we can just let the repository implementation handle
+        # everything and yield matching statements directly:
+        queryable.query(query, &block)
+
+      # No, some terms actually refer to the same variable...
+      else
+        # Figure out which terms refer to the same variable:
+        terms = variables.each_key.find do |name|
+          terms = variable_terms(name)
+          break terms if terms.size > 1
+        end
+        queryable.query(query) do |statement|
+          # Only yield those matching statements where the variable
+          # constraint is also satisfied:
+          # FIXME: `Array#uniq` uses `#eql?` and `#hash`, not `#==`
+          if matches = terms.map { |term| statement.send(term) }.uniq.size.equal?(1)
+            block.call(statement)
+          end
+        end
+      end
+    end
+
+    ##
+    # Returns a query solution constructed by binding any variables in this
+    # pattern with the corresponding terms in the given `statement`.
+    #
+    # @example
+    #   pattern.solution(statement)
+    #
+    # @param  [RDF::Statement] statement
+    #   an RDF statement to bind terms from
+    # @return [RDF::Query::Solution]
+    # @since  0.3.0
+    def solution(statement)
+      RDF::Query::Solution.new do |solution|
+        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
+
+    ##
+    # Returns the variable terms in this pattern.
+    #
+    # @example
+    #   Pattern.new(RDF::Node.new, :p, 123).variable_terms    #=> [:predicate]
+    #
+    # @param  [Symbol, #to_sym] name
+    #   an optional variable name
+    # @return [Array<Symbol>]
+    # @since  0.3.0
+    def variable_terms(name = nil)
+      terms = []
+      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
+
+    ##
+    # Returns the number of variables in this pattern.
+    #
+    # Note: this does not count distinct variables, and will therefore e.g.
+    # return 3 even if two terms are actually the same variable.
+    #
+    # @return [Integer] (0..3)
+    def variable_count
+      count = 0
+      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
+    alias_method :arity,       :variable_count
+
+    ##
+    # Returns all variables in this pattern.
+    #
+    # Note: this returns a hash containing distinct variables only.
+    #
+    # @return [Hash{Symbol => Variable}]
+    def variables
+      variables = {}
+      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
+
+    ##
+    # Returns `true` if this pattern contains bindings.
+    #
+    # @return [Boolean] `true` or `false`
+    def bindings?
+      !bindings.empty?
+    end
+
+    ##
+    # Returns the number of bindings in this pattern.
+    #
+    # @return [Integer] (0..3)
+    def binding_count
+      bindings.size
+    end
+
+    ##
+    # Returns all bindings in this pattern.
+    #
+    # @return [Hash{Symbol => RDF::Term}]
+    def bindings
+      bindings = {}
+      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
+
+    ##
+    # Returns `true` if all variables in this pattern are bound.
+    #
+    # @return [Boolean] `true` or `false`
+    def bound?
+      !variables.empty? && variables.values.all?(&:bound?)
+    end
+
+    ##
+    # Returns all bound variables in this pattern.
+    #
+    # @return [Hash{Symbol => Variable}]
+    def bound_variables
+      variables.reject { |name, variable| variable.unbound? }
+    end
+
+    ##
+    # Returns `true` if all variables in this pattern are unbound.
+    #
+    # @return [Boolean] `true` or `false`
+    def unbound?
+      !variables.empty? && variables.values.all?(&:unbound?)
+    end
+
+    ##
+    # Returns all unbound variables in this pattern.
+    #
+    # @return [Hash{Symbol => Variable}]
+    def unbound_variables
+      variables.reject { |name, variable| variable.bound? }
+    end
+
+    ##
+    # Returns a string representation of this pattern.
+    #
+    # @return [String]
+    def to_s
+      StringIO.open do |buffer| # FIXME in RDF::Statement
+        buffer << 'OPTIONAL ' if optional?
+        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
+  end # Pattern
+end; end # RDF::Query

data/lib/rdf/query/solution.rb

@@ -0,0 +1,252 @@
+class RDF::Query
+  ##
+  # An RDF query solution.
+  #
+  # @example Iterating over every binding in the solution
+  #   solution.each_binding  { |name, value| puts value.inspect }
+  #   solution.each_variable { |variable| puts variable.value.inspect }
+  #
+  # @example Iterating over every value in the solution
+  #   solution.each_value    { |value| puts value.inspect }
+  #
+  # @example Checking whether a variable is bound or unbound
+  #   solution.bound?(:title)
+  #   solution.unbound?(:mbox)
+  #
+  # @example Retrieving the value of a bound variable
+  #   solution[:mbox]
+  #   solution.mbox
+  #
+  # @example Retrieving all bindings in the solution as a `Hash`
+  #   solution.to_hash       #=> {:mbox => "jrhacker@example.org", ...}
+  #
+  class Solution
+    # Undefine all superfluous instance methods:
+    undef_method(*(instance_methods.map(&:to_sym) - [:__id__, :__send__, :__class__, :__eval__,
+      :object_id, :dup, :instance_eval, :inspect, :to_s,
+      :class, :is_a?, :respond_to?, :respond_to_missing?]))
+
+    include Enumerable
+
+    ##
+    # Initializes the query solution.
+    #
+    # @param  [Hash{Symbol => RDF::Term}] bindings
+    # @yield  [solution]
+    def initialize(bindings = {}, &block)
+      @bindings = bindings.to_hash
+
+      if block_given?
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+      end
+    end
+
+    # @private
+    attr_reader :bindings
+
+    ##
+    # Enumerates over every variable binding in this solution.
+    #
+    # @yield  [name, value]
+    # @yieldparam [Symbol] name
+    # @yieldparam [RDF::Term] value
+    # @return [Enumerator]
+    def each_binding(&block)
+      @bindings.each(&block)
+    end
+    alias_method :each, :each_binding
+
+    ##
+    # Enumerates over every variable name in this solution.
+    #
+    # @yield  [name]
+    # @yieldparam [Symbol] name
+    # @return [Enumerator]
+    def each_name(&block)
+      @bindings.each_key(&block)
+    end
+    alias_method :each_key, :each_name
+
+    ##
+    # Enumerates over every variable value in this solution.
+    #
+    # @yield  [value]
+    # @yieldparam [RDF::Term] value
+    # @return [Enumerator]
+    def each_value(&block)
+      @bindings.each_value(&block)
+    end
+
+    ##
+    # Returns `true` if this solution contains bindings for any of the given
+    # `variables`.
+    #
+    # @param  [Array<Symbol, #to_sym>] variables
+    #   an array of variables to check
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def has_variables?(variables)
+      variables.any? { |variable| bound?(variable) }
+    end
+
+    ##
+    # Enumerates over every variable in this solution.
+    #
+    # @yield  [variable]
+    # @yieldparam [Variable]
+    # @return [Enumerator]
+    def each_variable(&block)
+      @bindings.each do |name, value|
+        block.call(Variable.new(name, value))
+      end
+    end
+
+    ##
+    # Returns `true` if the variable `name` is bound in this solution.
+    #
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @return [Boolean] `true` or `false`
+    def bound?(name)
+      !unbound?(name)
+    end
+
+    ##
+    # Returns `true` if the variable `name` is unbound in this solution.
+    #
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @return [Boolean] `true` or `false`
+    def unbound?(name)
+      @bindings[name.to_sym].nil?
+    end
+
+    ##
+    # Returns the value of the variable `name`.
+    #
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @return [RDF::Term]
+    def [](name)
+      @bindings[name.to_sym]
+    end
+
+    ##
+    # Binds or rebinds the variable `name` to the given `value`.
+    #
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @param  [RDF::Term] value
+    # @return [RDF::Term]
+    # @since  0.3.0
+    def []=(name, value)
+      @bindings[name.to_sym] = value
+    end
+
+    ##
+    # Merges the bindings from the given `other` query solution into this
+    # one, overwriting any existing ones having the same name.
+    #
+    # @param  [RDF::Query::Solution, #to_hash] other
+    #   another query solution or hash bindings
+    # @return [void] self
+    # @since  0.3.0
+    def merge!(other)
+      @bindings.merge!(other.to_hash)
+      self
+    end
+
+    ##
+    # Merges the bindings from the given `other` query solution with a copy
+    # of this one.
+    #
+    # @param  [RDF::Query::Solution, #to_hash] other
+    #   another query solution or hash bindings
+    # @return [RDF::Query::Solution]
+    # @since  0.3.0
+    def merge(other)
+      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
+      @bindings.to_a
+    end
+
+    ##
+    # @return [Hash{Symbol => RDF::Term}}
+    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]
+    def inspect
+      sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, @bindings.inspect)
+    end
+
+  protected
+
+    ##
+    # @param  [Symbol] name
+    # @return [RDF::Term]
+    def method_missing(name, *args, &block)
+      if args.empty? && @bindings.has_key?(name.to_sym)
+        @bindings[name.to_sym]
+      else
+        super # raises NoMethodError
+      end
+    end
+  end # Solution
+end # RDF::Query