ld-patch 0.1.0

data/lib/ld/patch/algebra/constraint.rb

@@ -0,0 +1,56 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `constraint` operator.
+  #
+  # A constraint is a query operator which either ensures that there is a single input node ("!" operator) or finds a set of nodes for a given `path`, optionally filtering those nodes with a particular predicate value.
+  #
+  # @example existence of path solutions
+  #     (constraint (path :p))
+  #
+  #   Maps input terms to output terms using `(path :p)` returning those input terms that have at least a single solution.
+  #
+  # @example paths with property value
+  #     (constraint (path :p) 1)
+  #
+  #   Maps input terms to output terms using `(path :p)` and filters the input terms where the output term is `1`.
+  #
+  # @example unique terms
+  #
+  #     (constraint unique)
+  #
+  #   Returns the single term from the input terms if there is a single input term.
+  class Constraint < SPARQL::Algebra::Operator
+    include SPARQL::Algebra::Query
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :constraint
+
+    ##
+    # If the first operand is :unique
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Array<RDF::Term>] starting terms
+    # @return [RDF::Query::Solutions] solutions with `:term` mapping
+    def execute(queryable, options = {})
+      debug(options) {"Constraint"}
+      terms = Array(options.fetch(:terms))
+      op, value = operands
+
+      results = if op == :unique
+        terms.length == 1 ? terms : []
+      else
+        # op is a path, filter input terms based on the presense or absense of output terms. Additionally, if a constraint value is given, output terms must equal that value
+        terms.select do |term|
+          output_terms = op.execute(queryable, options.merge(terms: [term])).map(&:path)
+          output_terms = output_terms.select {|t| t == value} if value
+          !output_terms.empty?
+        end
+      end
+      RDF::Query::Solutions.new(results.map {|t| RDF::Query::Solution.new(path: t)})
+    end
+  end
+end

data/lib/ld/patch/algebra/cut.rb

@@ -0,0 +1,56 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `cut` operator.
+  #
+  # The Cut operation is recursively remove triples from some starting node.
+  #
+  # @example
+  #   (cut ?a)
+  #
+  class Cut < SPARQL::Algebra::Operator::Unary
+    include SPARQL::Algebra::Update
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :cut
+
+    ##
+    # Executes this upate on the given `writable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @return [RDF::Query::Solutions] A single solution including passed bindings with `var` bound to the solution.
+    # @raise [IOError]
+    #   If no triples are identified, or the operand is an unbound variable or the operand is an unbound variable.
+    # @see    http://www.w3.org/TR/sparql11-update/
+    def execute(queryable, options = {})
+      debug(options) {"Cut"}
+      bindings = options.fetch(:bindings)
+      solution = bindings.first
+      var = operand(0)
+
+      # Bind variable
+      raise LD::Patch::Error.new("Operand uses unbound variable #{var.inspect}", code: 400) unless solution.bound?(var)
+      var = solution[var]
+
+      cut_count = 0
+      # Get triples to delete using consice bounded description
+      queryable.concise_bounded_description(var) do |statement|
+        queryable.delete(statement)
+        cut_count += 1
+      end
+
+      # Also delete triples having var in the object position
+      queryable.query(object: var).each do |statement|
+        queryable.delete(statement)
+        cut_count += 1
+      end
+
+      raise LD::Patch::Error, "Cut removed no triples" unless cut_count > 0
+
+      bindings
+    end
+  end
+end

data/lib/ld/patch/algebra/delete.rb

@@ -0,0 +1,59 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `delete` operator (incuding `deleteExisting`).
+  #
+  # The Add operation is used to delete triples from the target graph with or without checking to see if the exist already.
+  #
+  # @example
+  #   (add ((<a> <b> <c>)))
+  #
+  class Delete < SPARQL::Algebra::Operator::Unary
+    include SPARQL::Algebra::Update
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :delete
+
+    ##
+    # Executes this upate on the given `writable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Boolean] :existing
+    #   Specifies that triples must already exist in the target graph
+    # @return [RDF::Query::Solutions] A single solution including passed bindings with `var` bound to the solution.
+    # @raise [Error]
+    #   If `existing` is specified, and any triple is not found in the traget graph, or if unbound variables are used.
+    # @see    http://www.w3.org/TR/sparql11-update/
+    def execute(queryable, options = {})
+      debug(options) {"Delete"}
+      bindings = options.fetch(:bindings)
+      solution = bindings.first
+
+      # Bind variables to triples
+      triples = operand(0).dup.replace_vars! do |var|
+        case var
+        when RDF::Query::Pattern
+          s = var.bind(solution)
+          raise LD::Patch::Error.new("Operand uses unbound pattern #{var.inspect}", code: 400) if s.variable?
+          s
+        when RDF::Query::Variable
+          raise LD::Patch::Error.new("Operand uses unbound variable #{var.inspect}", code: 400) unless solution.bound?(var)
+          solution[var]
+        end
+      end
+
+      # If `:new` is specified, verify that no triple in triples exists in queryable
+      if @options[:existing]
+        triples.each do |triple|
+          raise LD::Patch::Error, "Target graph does not contain triple #{triple.to_ntriples}" unless queryable.has_statement?(triple)
+        end
+      end
+
+      queryable.delete(*triples)
+      bindings
+    end
+  end
+end

data/lib/ld/patch/algebra/index.rb

@@ -0,0 +1,34 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `index` operator.
+  #
+  # Presuming that the input term identifies an rdf:List, returns the list element indexted by the single operand, or an empty solution set
+  class Index < SPARQL::Algebra::Operator::Unary
+    include SPARQL::Algebra::Query
+
+    NAME = :index
+
+    ##
+    # Executes this upate on the given `writable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Array<RDF::Term>] starting terms
+    # @return [RDF::Query::Solutions] solutions with `:term` mapping
+    def execute(queryable, options = {})
+      debug(options) {"Index"}
+      terms = Array(options.fetch(:terms))
+      index = operand(0)
+
+      results = terms.map do |term|
+        list = RDF::List.new(term, queryable)
+        list.at(index.to_i)
+      end.flatten
+
+      RDF::Query::Solutions.new(results.map {|t| RDF::Query::Solution.new(path: t)})
+    end
+  end
+end

data/lib/ld/patch/algebra/patch.rb

@@ -0,0 +1,40 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `patch` operator.
+  #
+  # Transactionally iterates over all operands building bindings along the way
+  class Patch < SPARQL::Algebra::Operator
+    include SPARQL::Algebra::Update
+
+    NAME = :patch
+
+    ##
+    # Executes this upate on the given `writable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @return [RDF::Queryable]
+    #   Returns queryable.
+    # @raise [Error]
+    #   If any error is caught along the way, and rolls back the transaction
+    def execute(queryable, options = {})
+      debug(options) {"Delete"}
+
+      # FIXME: due to insufficient transaction support, this is implemented by running through operands twice: the first using a clone of the graph, and the second acting on the graph directly
+      graph = RDF::Graph.new << queryable
+      loop do
+        operands.inject(RDF::Query::Solutions.new([RDF::Query::Solution.new])) do |bindings, op|
+          # Invoke operand using bindings from prvious operation
+          op.execute(graph, options.merge(bindings: bindings))
+        end
+
+        break if graph.equal?(queryable)
+        graph = queryable
+      end
+      queryable
+    end
+  end
+end

data/lib/ld/patch/algebra/path.rb

@@ -0,0 +1,71 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `path` operator.
+  #
+  # The Path creates a closure over path operands querying `queryable` for terms having a relationship with the input `terms` based on each operand. The terms extracted from the first operand are used as inputs for the next operand until a final set of terms is found. These terms are returned as `RDF:Query::Solution` bound the the variable `?path`
+  #
+  # @example empty path
+  #     (path)
+  #
+  #   Returns input terms
+  #
+  # @example forward path
+  #     (path :p)
+  #
+  #   Queries `queryable` for objects where the input terms are subjects and the predicate is `:p`
+  #
+  # @example reverse path
+  #     (path (reverse :p))
+  #
+  #   Queries `queryable` for subjects where input terms are objects and the predicate is `:p`, by executing the `reverse` operand using input terms to get a set of output terms.
+  #
+  # @example constraint
+  #     (path (constraint (path) :c, 1))
+  #
+  #   Returns the input terms satisfying the constrant.
+  #
+  # @example chained path elements
+  #     (path :p :q (constraint (path) :c, 1))
+  #
+  #   Maps terms using `(path :p)`, using them as terms for `(path :q)`, then subsets these based on the constraint.
+  class Path < SPARQL::Algebra::Operator
+    include SPARQL::Algebra::Query
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :path
+
+    ##
+    # Executes this operator using the given variable `bindings` and a starting term, returning zero or more terms at the end of the path.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param [Hash{Symbol => Object}] options ({})
+    #   options passed from query
+    # @option options [Array<RDF::Term>] starting terms
+    # @return [RDF::Query::Solutions] solutions with `:term` mapping
+    def execute(queryable, options = {})
+      solutions = RDF::Query::Solutions.new
+
+      # Iterate updating terms, then create solutions from matched terms
+      operands.inject(Array(options.fetch(:terms))) do |terms, op|
+        case op
+        when RDF::URI
+          terms.map do |subject|
+            queryable.query(subject: subject, predicate: op).map(&:object)
+          end.flatten
+        when SPARQL::Algebra::Query
+          # Get path solutions for each term for op
+          op.execute(queryable, options.merge(terms: terms)).map do |soln|
+            soln.path
+          end.flatten
+        else
+          raise NotImplementedError, "Unknown path operand #{op.inspect}"
+        end
+      end.each do |term|
+        solutions << RDF::Query::Solution.new(path: term)
+      end
+      solutions
+    end
+  end
+end

data/lib/ld/patch/algebra/prefix.rb

@@ -0,0 +1,48 @@
+module LD::Patch::Algebra
+  ##
+  # The LD Patch `prefix` operator.
+  #
+  # @example
+  #   (prefix ((: <http://example/>))
+  #     (graph ?g
+  #       (bgp (triple ?s ?p ?o))))
+  #
+  # @see http://www.w3.org/TR/rdf-sparql-query/#QSynIRI
+  class Prefix < SPARQL::Algebra::Operator::Binary
+    include SPARQL::Algebra::Update
+    
+    NAME = :prefix
+
+    ##
+    # Executes this query on the given `queryable` graph or repository.
+    # Really a pass-through, as this is a syntactic object used for providing
+    # context for URIs.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @yield  [solution]
+    #   each matching solution, statement or boolean
+    # @yieldparam  [RDF::Statement, RDF::Query::Solution, Boolean] solution
+    # @yieldreturn [void] ignored
+    # @return [RDF::Query::Solutions]
+    #   the resulting solution sequence
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    def execute(queryable, options = {}, &block)
+      debug(options) {"Prefix"}
+      @solutions = queryable.query(operands.last, options.merge(depth: options[:depth].to_i + 1), &block)
+    end
+    
+    ##
+    # Returns an optimized version of this query.
+    #
+    # If optimize operands, and if the first two operands are both Queries, replace
+    # with the unique sum of the query elements
+    #
+    # @return [Union, RDF::Query] `self`
+    def optimize
+      operands.last.optimize
+    end
+  end # Prefix
+end

data/lib/ld/patch/algebra/reverse.rb

@@ -0,0 +1,39 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `reverse` operator
+  #
+  # Finds all the terms which are the subject of triples where the `operand` is the predicate and input terms are objects.
+  #
+  # @example
+  #     (reverse :p)
+  #
+  #   Queries `queryable` for subjects where input terms are objects and the predicate is `:p`, by executing the `reverse` operand using input terms to get a set of output terms.
+  class Reverse < SPARQL::Algebra::Operator::Unary
+    include SPARQL::Algebra::Query
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :reverse
+
+    ##
+    # Executes this upate on the given `writable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Array<RDF::Term>] starting terms
+    # @return [RDF::Query::Solutions] solutions with `:term` mapping
+    def execute(queryable, options = {})
+      debug(options) {"Reverse"}
+      op = operand(0)
+      terms = Array(options.fetch(:terms))
+
+      results = terms.map do |object|
+        queryable.query(object: object, predicate: op).map(&:subject)
+      end.flatten
+
+      RDF::Query::Solutions.new(results.map {|t| RDF::Query::Solution.new(path: t)})
+    end
+  end
+end

data/lib/ld/patch/algebra/update_list.rb

@@ -0,0 +1,77 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `updateList` operator.
+  #
+  # The UpdateList operation is used to splice a new list into a subset of an existing list.
+  #
+  class UpdateList < SPARQL::Algebra::Operator
+    include SPARQL::Algebra::Update
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :updateList
+
+    ##
+    # Executes this upate on the given `writable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @return [RDF::Query::Solutions] A single solution including passed bindings with `var` bound to the solution.
+    # @raise [Error]
+    #   If the subject and predicate provided to an UpdateList do not have a unique object, or if this object is not a well-formed collection.
+    #   If an index in a slice expression is greater than the length of the rdf:List or otherwise out of bound.
+    # @see    http://www.w3.org/TR/sparql11-update/
+    def execute(queryable, options = {})
+      debug(options) {"UpdateList"}
+      bindings = options.fetch(:bindings)
+      solution = bindings.first
+      var_or_iri, predicate, slice1, slice2, collection = operands
+
+      # Bind variables to path
+      if var_or_iri.variable?
+        raise LD::Patch::Error("Operand uses unbound variable #{var_or_iri.inspect}", code: 400) unless solution.bound?(var_or_iri)
+        var_or_iri = solution[variable]
+      end
+
+      list_heads = queryable.query(subject: var_or_iri, predicate: predicate).map {|s| s.object}
+
+      raise LD::Patch::Error, "UpdateList ambigious value for #{var_or_iri.to_ntriples} and #{predicate.to_ntriples}" if list_heads.length > 1
+      raise LD::Patch::Error, "UpdateList no value found for #{var_or_iri.to_ntriples} and #{predicate.to_ntriples}" if list_heads.empty?
+      lh = list_heads.first
+      list = RDF::List.new(lh, queryable)
+      raise LD::Patch::Error, "Invalid list" unless list.valid?
+
+      start = case
+      when slice1.nil? || slice1 == RDF.nil then list.length
+      when slice1 < 0 then list.length + slice1.to_i
+      else slice1.to_i
+      end
+
+      finish = case
+      when slice2.nil? || slice2 == RDF.nil then list.length
+      when slice2 < 0 then list.length + slice2.to_i
+      else slice2.to_i
+      end
+
+      raise LD::Patch::Error.new("UpdateList slice indexes out of order #{start}..#{finish}}", code: 400) if finish < start
+      
+      length = finish - start
+      raise LD::Patch::Error, "UpdateList out of bounds #{start}..#{finish}}" if start + length > list.length
+      raise LD::Patch::Error, "UpdateList out of bounds #{start}..#{finish}}" if start < 0
+
+      # Uses #[]= logic in RDF::List
+      list[start, length] = collection
+      new_lh = list.subject
+
+      # If lh was rdf:nil, then we may have a new list head. Similarly, if the list was emptied, we now need to replace the head
+      if lh != new_lh
+        queryable.delete(RDF::Statement(var_or_iri, predicate, lh))
+        queryable.insert(RDF::Statement(var_or_iri, predicate, new_lh))
+      end
+
+      bindings
+    end
+  end
+end