rdf-n3 2.2.0 → 3.1.2

data/lib/rdf/n3/algebra/log/implies.rb

@@ -0,0 +1,102 @@
+module RDF::N3::Algebra::Log
+  ##
+  # Logical implication.
+  #
+  # This is the relation between the antecedent (subject) and conclusion (object) of a rule. The application of a rule to a knowledge-base is as follows. For every substitution which, applied to the antecedent, gives a formula which is a subset of the knowledge-base, then the result of applying that same substitution to the conclusion may be added to the knowledge-base.
+  #
+  # related: See log:conclusion.
+  class Implies < SPARQL::Algebra::Operator::Binary
+    include SPARQL::Algebra::Query
+    include SPARQL::Algebra::Update
+    include RDF::N3::Algebra::Builtin
+
+    NAME = :logImplies
+    URI = RDF::N3::Log.implies
+
+    ##
+    # Returns solutions from subject. Solutions are created by evaluating subject against `queryable`.
+    #
+    # Solutions are kept within this instance, and used for conclusions. Note that the evaluated solutions do not affect that of the invoking formula, as the solution spaces are disjoint.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @option options [RDF::Query::Solutions] solutions
+    #   optional initial solutions for chained queries
+    # @return [RDF::Solutions] distinct solutions
+    def execute(queryable, solutions:, **options)
+      @queryable = queryable
+      @solutions = RDF::Query::Solutions(solutions.map do |solution|
+        log_debug(NAME, "solution") {SXP::Generator.string(solution.to_sxp_bin)}
+        subject = operand(0).evaluate(solution.bindings, formulae: formulae)
+        object = operand(1).evaluate(solution.bindings, formulae: formulae)
+        log_info(NAME,  "subject") {SXP::Generator.string(subject.to_sxp_bin)}
+        log_info(NAME, "object") {SXP::Generator.string(object.to_sxp_bin)}
+
+        # Nothing to do if variables aren't resolved.
+        next unless subject && object
+
+        solns = log_depth {subject.execute(queryable, solutions: RDF::Query::Solutions(solution), **options)}
+
+        # Execute object as well (typically used for log:outputString)
+        solns.each do |soln|
+          log_depth {object.execute(queryable, solutions: RDF::Query::Solutions(soln), **options)}
+        end
+
+        # filter solutions where not all variables in antecedant are bound.
+        vars = subject.universal_vars
+        solns = RDF::Query::Solutions(solns.to_a.select do |soln|
+          vars.all? {|v| soln.bound?(v)}
+        end)
+        solns
+      end.flatten.compact.uniq)
+      log_info(NAME) {SXP::Generator.string(@solutions.to_sxp_bin)}
+
+      # Return original solutions, without bindings
+      solutions
+    end
+
+    ##
+    # Clear out any cached solutions.
+    # This principaly is for log:conclusions
+    def clear_solutions
+      super
+      @solutions = nil
+    end
+
+    ##
+    # Yields statements from the object based on solutions determined from the subject. Each solution formed by querying `queryable` from the subject is  used to create a graph, which must be a subgraph of `queryable`. If so, that solution is used to generate triples from the object formula which are yielded.
+    #
+    # @yield  [statement]
+    #   each matching statement
+    # @yieldparam  [RDF::Statement] solution
+    # @yieldreturn [void] ignored
+    def each(solutions: RDF::Query::Solutions(), &block)
+      # Merge solutions in with those for the evaluation of this implication
+      # Clear out solutions so they don't get remembered erroneously.
+      solutions, @solutions = Array(@solutions), nil
+      log_depth do
+        super(solutions: RDF::Query::Solutions(RDF::Query::Solution.new), &block)
+
+        solutions.each do |solution|
+          log_info("(logImplies each) solution") {SXP::Generator.string solution.to_sxp_bin}
+          object = operand(1).evaluate(solution.bindings, formulae: formulae)
+          log_info("(logImplies each) object") {SXP::Generator.string object.to_sxp_bin}
+
+          # Yield inferred statements
+          log_depth do
+            object.each(solutions: RDF::Query::Solutions(solution)) do |statement|
+              log_debug(("(logImplies each) infer\s")) {statement.to_sxp}
+              block.call(RDF::Statement.from(statement.to_quad, inferred: true))
+            end
+          end
+        end
+      end
+    end
+
+    # Graph name associated with this operation, using the name of the parent
+    # @return [RDF::Resource]
+    def graph_name; parent.graph_name; end
+  end
+end

data/lib/rdf/n3/algebra/log/includes.rb

@@ -0,0 +1,70 @@
+module RDF::N3::Algebra::Log
+  ##
+  # The subject formula includes the object formula.
+  #
+  # Formula A includes formula B if there exists some substitution which when applied to B creates a formula B' such that for every statement in B' is also in A, every variable universally (or existentially) quantified in B' is quantified in the same way in A. 
+  #
+  # Variable substitution is applied recursively to nested compound terms such as formulae, lists and sets.
+  #
+  # (Understood natively by cwm when in in the antecedent of a rule. You can use this to peer inside nested formulae.)
+  class Includes < RDF::N3::Algebra::ResourceOperator
+    NAME = :logIncludes
+    URI = RDF::N3::Log.includes
+
+    ##
+    # Both subject and object must be formulae.
+    #
+    # @param [RDF::Term] resource
+    # @param [:subject, :object] position
+    # @return [RDF::Term]
+    # @see RDF::N3::ResourceOperator#evaluate
+    def resolve(resource, position:)
+      resource if resource.formula?
+    end
+
+    # Both subject and object are inputs.
+    def input_operand
+      RDF::N3::List.new(values: operands)
+    end
+
+    ##
+    # Creates a repository constructed by substituting variables and in that subject with known IRIs and queries object against that repository. Either retuns a single solution, or no solutions.
+    #
+    # @note this does allow object to have variables not in the subject, if they could have been substituted away.
+    #
+    # @param  [RDF::N3::Algebra::Formula] subject
+    #   a formula
+    # @param  [RDF::N3::Algebra::Formula] object
+    #   a formula
+    # @return [RDF::Literal::Boolean]
+    def apply(subject, object)
+      subject_var_map = subject.variables.values.inject({}) {|memo, v| memo.merge(v => RDF::URI(v.name))}
+      object_vars = object.variables.keys
+      log_debug(NAME,  "subject var map") {SXP::Generator.string(subject_var_map.to_sxp_bin)}
+      log_debug(NAME, "object vars") {SXP::Generator.string(object_vars.to_sxp_bin)}
+      # create a queryable from subject, replacing variables with IRIs for thsoe variables.
+      queryable = RDF::Repository.new do |r|
+        log_depth do
+          subject.each do |stmt|
+            parts = stmt.to_quad.map do |part|
+              part.is_a?(RDF::Query::Variable) ? subject_var_map.fetch(part) : part
+            end
+            r << RDF::Statement.from(parts)
+          end
+        end
+      end
+
+      # Query object against subject
+      solns = log_depth {queryable.query(object, **@options)}
+      log_info("(#{NAME} solutions)") {SXP::Generator.string solns.to_sxp_bin}
+
+      if !solns.empty? && (object_vars - solns.variable_names).empty?
+        # Return solution
+        solns.first
+      else
+        # Return false,
+        RDF::Literal::FALSE
+      end
+    end
+  end
+end

data/lib/rdf/n3/algebra/log/n3_string.rb

@@ -0,0 +1,34 @@
+module RDF::N3::Algebra::Log
+  ##
+  # The subject formula, expressed as N3, gives this string.
+  class N3String < RDF::N3::Algebra::ResourceOperator
+    NAME = :logN3String
+    URI = RDF::N3::Log.n3String
+
+    ##
+    # Serializes the subject formula into an N3 string representation.
+    #
+    # @param [RDF::N3::List] resource
+    # @return [RDF::Term]
+    def resolve(resource, position: :subject)
+      case position
+      when :subject
+        return nil unless resource.formula?
+        as_literal(RDF::N3::Writer.buffer {|w| resource.each {|st| w << st}})
+      when :object
+        return nil unless resource.literal? || resource.variable?
+        resource
+      end
+    end
+
+    ##
+    # Subject must evaluate to a formula and object to a literal.
+    #
+    # @param [RDF::Term] subject
+    # @param [RDF::Term] object
+    # @return [Boolean]
+    def valid?(subject, object)
+      subject.formula? && (object.variable? || object.literal?)
+    end
+  end
+end

data/lib/rdf/n3/algebra/log/not_equal_to.rb

@@ -0,0 +1,23 @@
+module RDF::N3::Algebra::Log
+  ##
+  # Equality in this sense is actually the same URI. A cwm built-in logical operator.
+  class NotEqualTo < SPARQL::Algebra::Operator::SameTerm
+    include RDF::N3::Algebra::Builtin
+    NAME = :logNotEqualTo
+    URI = RDF::N3::Log.notEqualto
+
+    ##
+    # Returns `true` if the operands are not the same RDF term; returns
+    # `false` otherwise.
+    #
+    # @param  [RDF::Term] term1
+    #   an RDF term
+    # @param  [RDF::Term] term2
+    #   an RDF term
+    # @return [RDF::Literal::Boolean] `true` or `false`
+    # @raise  [TypeError] if either operand is unbound
+    def apply(term1, term2)
+      RDF::Literal(!term1.eql?(term2))
+    end
+  end
+end

data/lib/rdf/n3/algebra/log/not_includes.rb

@@ -0,0 +1,27 @@
+module RDF::N3::Algebra::Log
+  ##
+  # The object formula is NOT a subset of subject. True iff log:includes is false. The converse of log:includes.
+  # (Understood natively by cwm. The subject formula may contain variables.)
+  #
+  # (In cwm, variables must of course end up getting bound before the log:include test can be done, or an infinite result set would result)
+  #
+  # Related: See includes
+  class NotIncludes < Includes
+    NAME = :logNotIncludes
+    URI = RDF::N3::Log.notIncludes
+
+    ##
+    # Uses log:includes and returns a solution if log:includes fails
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @option options [RDF::Query::Solutions] solutions
+    #   optional initial solutions for chained queries
+    # @return [RDF::Solutions] distinct solutions
+    def execute(queryable, solutions:, **options)
+      super.empty? ? RDF::Query::Solutions(RDF::Query::Solution.new) : RDF::Query::Solutions.new
+    end
+  end
+end

data/lib/rdf/n3/algebra/log/output_string.rb

@@ -0,0 +1,40 @@
+module RDF::N3::Algebra::Log
+  ##
+  # The subject is a key and the object is a string, where the strings are to be output in the order of the keys.
+  class OutputString < RDF::N3::Algebra::ResourceOperator
+    NAME = :logOutputString
+    URI = RDF::N3::Log.outputString
+
+    ##
+    # Resolves inputs as strings.
+    #
+    # @param [RDF::Term] resource
+    # @param [:subject, :object] position
+    # @return [RDF::Term]
+    # @see RDF::N3::ResourceOperator#evaluate
+    def resolve(resource, position:)
+      SPARQL::Algebra::Expression.cast(RDF::XSD.string, resource) if resource.term?
+    end
+
+    ##
+    # Returns `term2`, but adds `term2` as an output keyed on `term1`.
+    #
+    # @param  [RDF::Term] term1
+    #   an RDF term
+    # @param  [RDF::Term] term2
+    #   an RDF term
+    # @return [RDF::Literal::Boolean] `true` or `false`
+    # @raise  [TypeError] if either operand is not an RDF term or operands are not comperable
+    #
+    # @see RDF::Term#==
+    def apply(term1, term2)
+      (@options[:strings][term1.to_s] ||= []) << term2.to_s
+      term2
+    end
+
+    # Both subject and object are inputs.
+    def input_operand
+      RDF::N3::List.new(values: operands)
+    end
+  end
+end

data/lib/rdf/n3/algebra/log/parsed_as_n3.rb

@@ -0,0 +1,36 @@
+module RDF::N3::Algebra::Log
+  ##
+  # The subject string, parsed as N3, gives this formula.
+  class ParsedAsN3 < RDF::N3::Algebra::ResourceOperator
+    NAME = :logParsedAsN3
+    URI = RDF::N3::Log.parsedAsN3
+
+    ##
+    # Parses the subject into a new formula.
+    #
+    # Returns nil if resource does not validate, given its position
+    #
+    # @param [RDF::N3::List] resource
+    # @return [RDF::Term]
+    def resolve(resource, position: :subject)
+      case position
+      when :subject
+        return nil unless resource.literal?
+        begin
+          repo = RDF::N3::Repository.new
+          repo << RDF::N3::Reader.new(resource.to_s, **@options.merge(list_terms: true,  logger: false))
+          log_debug("logParsedAsN3") {SXP::Generator.string repo.statements.to_sxp_bin}
+          content_hash = resource.hash # used as name of resulting formula
+          form = RDF::N3::Algebra::Formula.from_enumerable(repo, graph_name: RDF::Node.intern(content_hash))
+          log_info(NAME) {"form hash (#{resource}): #{form.hash}"}
+          form
+        rescue RDF::ReaderError
+          nil
+        end
+      when :object
+        return nil unless resource.literal? || resource.is_a?(RDF::Query::Variable)
+        resource
+      end
+    end
+  end
+end

data/lib/rdf/n3/algebra/log/semantics.rb

@@ -0,0 +1,40 @@
+module RDF::N3::Algebra::Log
+  ##
+  # The log:semantics of a document is the formula. achieved by parsing representation of the document. For a document in Notation3, log:semantics is the log:parsedAsN3 of the log:contents of the document. For a document in RDF/XML, it is parsed according to the RDF/XML specification to yield an RDF formula (a subclass of N3 log:Formula).
+  #
+  # [Aside: Philosophers will be distracted here into worrying about the meaning of meaning. At least we didn't call this function "meaning"! In as much as N3 is used as an interlingua for interoperability for different systems, this for an N3 based system is the meaning  expressed by a document.]
+  #
+  # (Cwm knows how to go get a document and parse N3 and RDF/XML it in order to evaluate this. Other languages for web documents  may be defined whose N3 semantics are therefore also calculable, and so they could be added in due course. See for example GRDDL, RDFa, etc)
+  class Semantics < RDF::N3::Algebra::ResourceOperator
+    NAME = :logSemantics
+    URI = RDF::N3::Log.semantics
+
+    ##
+    # Parses the subject into a new formula.
+    #
+    # Returns nil if resource does not validate, given its position
+    #
+    # @param [RDF::N3::List] resource
+    # @return [RDF::Term]
+    def resolve(resource, position: :subject)
+      case position
+      when :subject
+        return nil unless resource.literal? || resource.uri?
+        begin
+          repo = RDF::N3::Repository.new
+          repo << RDF::Reader.open(resource, **@options.merge(list_terms: true, base_uri: resource, logger: false))
+          content_hash = repo.statements.hash # used as name of resulting formula
+          form = RDF::N3::Algebra::Formula.from_enumerable(repo, graph_name: RDF::Node.intern(content_hash))
+          log_debug(NAME) {"form hash (#{resource}): #{form.hash}"}
+          form
+        rescue IOError, RDF::ReaderError => e
+          log_error(NAME) {"error loading #{resource}: #{e}"}
+          nil
+        end
+      when :object
+        return nil unless resource.literal? || resource.variable?
+        resource
+      end
+    end
+  end
+end

data/lib/rdf/n3/algebra/math/absolute_value.rb

@@ -0,0 +1,36 @@
+module RDF::N3::Algebra::Math
+  ##
+  # The object is calulated as the absolute value of the subject.
+  #
+  # @see https://www.w3.org/TR/xpath-functions/#func-abs
+  class AbsoluteValue < RDF::N3::Algebra::ResourceOperator
+    NAME = :mathAbsoluteValue
+    URI = RDF::N3::Math.absoluteValue
+
+    ##
+    # The math:absoluteValue operator takes string or number and calculates its absolute value.
+    #
+    # @param [RDF::Term] resource
+    # @param [:subject, :object] position
+    # @return [RDF::Term]
+    # @see RDF::N3::ResourceOperator#evaluate
+    def resolve(resource, position:)
+      case position
+      when :subject
+        return nil unless resource.literal?
+        as_literal(resource.as_number.abs)
+      when :object
+        return nil unless resource.literal? || resource.variable?
+        resource
+      end
+    end
+
+    ##
+    # Input is either the subject or object
+    #
+    # @return [RDF::Term]
+    def input_operand
+      RDF::N3::List.new(values: operands)
+    end
+  end
+end

data/lib/rdf/n3/algebra/math/acos.rb

@@ -0,0 +1,26 @@
+module RDF::N3::Algebra::Math
+  ##
+  # The object is calulated as the arc cosine value of the subject.
+  class ACos < RDF::N3::Algebra::ResourceOperator
+    NAME = :mathACos
+    URI = RDF::N3::Math.acos
+
+    ##
+    # The math:acos operator takes string or number and calculates its arc cosine.
+    #
+    # @param [RDF::Term] resource
+    # @param [:subject, :object] position
+    # @return [RDF::Term]
+    # @see RDF::N3::ResourceOperator#evaluate
+    def resolve(resource, position:)
+      case position
+      when :subject
+        return nil unless resource.literal?
+        as_literal(Math.acos(resource.as_number.object))
+      when :object
+        return nil unless resource.literal? || resource.variable?
+        resource
+      end
+    end
+  end
+end