ld-patch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2eb0185c5e3d87a311c57b6460363bf5e479fd0a
+  data.tar.gz: fd9772612616488a2ce9c595fa01ff3ebfff3879
+SHA512:
+  metadata.gz: 9a0aece9207a9d91d34706b19051f54c95934ca4cd017555eefda8aa0a032f1c2c4cbbddd4cdb2492ba966f3866e3ba8af30df806b420c8b76612a54d73b19d2
+  data.tar.gz: 98914c762b9fc8152c5399727c374dce01364d9ce6416e829c1ca3c4fbef686ef6dc78b4558cf9ce917b6f7f22da560f064bf0d4f1d2e18951a487978eac760f

data/AUTHORS

@@ -0,0 +1 @@
+* Gregg Kellogg <gregg@greggkellogg.net>

data/LICENSE

@@ -0,0 +1,25 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org>
+

data/README.md

@@ -0,0 +1,81 @@
+# LD Patch for RDF.rb
+
+This is a [Ruby][] implementation of [LD Patch][] for [RDF.rb][].
+
+[![Gem Version](https://badge.fury.io/rb/ld-patch.png)](http://badge.fury.io/rb/ld-patch)
+[![Build Status](https://travis-ci.org/ruby-rdf/ld-patch.png?branch=master)](http://travis-ci.org/ruby-rdf/ld-patch)
+[![Coverage Status](https://coveralls.io/repos/ruby-rdf/ld-patch/badge.svg)](https://coveralls.io/r/ruby-rdf/ld-patch)
+
+## Description
+
+This gem implements the [LD Patch][] specification with a couple of changes and/or limitations:
+
+* The `INDEX` terminal was replaced by `INTEGER`. Having two terminals matching the same token strings causes a conflict. As a result, a _slice_ may contain positive integers, as well as unsigned and negative-integers.
+* The _graph_ rule is changed to the following:
+
+      [18]    graph           ::=     triples  ('.' triples?)*
+
+  This is necessary as the specified production is not context-free. As a result, it is possible for a graph to contain multiple trailing "`.`".
+
+[LD Patch][] is useful inside a Rack container where it can respond to `POST` messages to affect the modification of a _target graph_ identified using the URL of the `POST`.
+
+## Features
+
+* 100% free and unencumbered [public domain](http://unlicense.org/) software.
+* Complete [Linked Data Patch Format][LD Patch] parsing and execution
+* Implementation Report: {file:etc/earl.html EARL}
+* Compatible with Ruby >= 2.0.0.
+
+## Documentation
+Full documentation available on [Rubydoc.info][LD-Patch doc]
+
+## Implementation Notes
+The reader uses the [EBNF][] gem to generate first, follow and branch tables, and uses the `Parser` and `Lexer` modules to implement the LD Patch parser.
+
+The parser takes branch and follow tables generated from the [LD Patch Grammar](file.ld-patch.html) described in the [specification][LD Patch]. Branch and Follow tables are specified in the generated {LD::Patch::Meta}.
+
+## Dependencies
+
+* [Ruby](http://ruby-lang.org/) (>= 2.0.0)
+* [RDF.rb](http://rubygems.org/gems/rdf) (>= 1.1.15)
+* [EBNF][] (>= 0.3.0)
+* [SPARQL][] (>= 1.1.7)
+* [SXP][] (>= 0.1.5)
+* [RDF::XSD][] (>= 1.1.4)
+
+## Mailing List
+* <http://lists.w3.org/Archives/Public/public-rdf-ruby/>
+
+## Author
+* [Gregg Kellogg](http://github.com/gkellogg) - <http://greggkellogg.net/>
+
+## Contributing
+This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange development and release activity. All submissions _must_ be on a feature branch based on the _develop_ branch to ease staging and integration.
+
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+* Do document every method you add using [YARD][] annotations. Read the [tutorial][YARD-GS] or just look at the existing code for examples.
+* Don't touch the `.gemspec`, `VERSION` or `AUTHORS` files. If you need to change them, do so on your private branch only.
+* Do feel free to add yourself to the `CREDITS` file and the corresponding list in the the `README`. Alphabetical order applies.
+* Do note that in order for us to merge any non-trivial changes (as a rule of thumb, additions larger than about 15 lines of code), we need an explicit [public domain dedication][PDD] on record from you.
+
+## License
+This is free and unencumbered public domain software. For more information,
+see <http://unlicense.org/> or the accompanying {file:LICENSE} file.
+
+A copy of the [LD Patch EBNF](file:etc/ld-patch.ebnf) and derived parser files are included in the repository, which are not covered under the UNLICENSE. These files are covered via the [W3C Document License](http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231).
+
+[Ruby]:           http://ruby-lang.org/
+[RDF]:            http://www.w3.org/RDF/
+[YARD]:           http://yardoc.org/
+[YARD-GS]:        http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:             http://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html
+[RDF.rb]:         http://rubygems.org/gems/rdf
+[RDF::XSD]:       http://rubygems.org/gems/rdf-xsd
+[EBNF]:           http://rubygems.org/gems/ebnf
+[SPARQL]:         http://rubygems.org/gems/sparql
+[Linked Data]:    http://rubygems.org/gems/linkeddata
+[SSE]:            http://openjena.org/wiki/SSE
+[SXP]:            http://rubygems.org/gems/sxp-ruby
+[LD Patch]:       http://www.w3.org/TR/ldpatch/
+[LD-Patch doc]:   http://rubydoc.info/github/ruby-rdf/ld-patch

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/ldpatch

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "..", 'lib')))
+require 'ld/patch'
+begin
+  require 'linkeddata'
+rescue LoadError
+  require 'rdf/ntriples'
+  require 'rdf/turtle'
+end
+require 'getoptlong'
+
+def run(input, options = {})
+  if options[:debug]
+    puts "input graph:\n#{options[:graph].dump(:ttl, standard_prefixes: true)}\n" if options[:graph]
+    puts "query:\n#{input}\n"
+  end
+  options[:graph] ||= RDF::Graph.new
+
+  if options[:verbose]
+    puts ("\nPATCH:\n" + input) 
+  end
+
+  patch = if options[:sse]
+    SPARQL::Algebra.parse(input, options)
+  else
+    # Only do grammar debugging if we're generating SSE
+    LD::Patch.parse(input, options)
+  end
+
+  puts ("\nSSE:\n" + patch.to_sse) if options[:debug] || options[:to_sse]
+
+  unless options[:to_sse]
+    res = patch.execute(options[:graph], debug: options[:debug])
+    puts res.inspect if options[:verbose]
+    puts res.dump(:ttl, base_uri: patch.base_uri, prefixes: patch.prefixes, standard_prefixes: true)
+  end
+end
+
+opts = GetoptLong.new(
+  ["--debug", GetoptLong::NO_ARGUMENT],
+  ["--dump", GetoptLong::NO_ARGUMENT],
+  ["--execute", "-e", GetoptLong::REQUIRED_ARGUMENT],
+  ["--progress", GetoptLong::NO_ARGUMENT],
+  ["--sse", GetoptLong::NO_ARGUMENT],
+  ["--to-sse", GetoptLong::NO_ARGUMENT],
+  ["--validate", GetoptLong::NO_ARGUMENT],
+  ["--verbose", GetoptLong::NO_ARGUMENT],
+  ["--help", "-?", GetoptLong::NO_ARGUMENT]
+)
+
+options = {
+  graph: RDF::Repository.new,
+}
+
+input = nil
+
+opts.each do |opt, arg|
+  case opt
+  when '--debug'         then options[:debug] = true
+  when '--dump'          then $dump = true
+  when '--execute'       then input = arg
+  when '--progress'      then options[:debug] ||= 2
+  when '--sse'           then options[:sse] = true
+  when '--to-sse'        then options[:to_sse] = true
+  when '--validate'      then options[:validate] = true
+  when '--verbose'       then options[:verbose] = true
+  when "--help"
+    puts "Usage: #{$0} [options] file-or-uri ..."
+    puts "Options:"
+    puts "      --execute,-e:         Use option argument as the SPARQL input if no files are given"
+    puts "      --dump:               Dump raw output, otherwise serialize to SSE"
+    puts "      --debug:              Display detailed debug output"
+    puts "      --sse:                Input is in SSE format"
+    puts "      --to-sse:             Generate SSE instead of running query"
+    puts "      --verbose:            Display details of processing"
+    puts "      --help,-?:            This message"
+    exit(0)
+  end
+end
+
+if ARGV.empty?
+  s = input ? input : $stdin.read
+  run(s, options)
+else
+  ARGV.each do |test_file|
+    puts "parse #{test_file}"
+    run(RDF::Util::File.open_file(test_file).read, options.merge(base_uri: RDF::URI(test_file)))
+  end
+end
+puts

data/lib/ld/patch.rb

@@ -0,0 +1,79 @@
+$:.unshift(File.expand_path("../..", __FILE__))
+require 'rdf'
+require 'sparql'
+require 'sparql/algebra'
+require 'sxp'
+
+module LD
+  # **`LD::Patch`** is a Linked Data Patch extension for RDF.rb.
+  #
+  # @author [Gregg Kellogg](http://greggkellogg.net/)
+  module Patch
+    autoload :Algebra,      'ld/patch/algebra'
+    autoload :Meta,         'ld/patch/meta'
+    autoload :Parser,       'ld/patch/parser'
+    autoload :Terminals,    'ld/patch/terminals'
+    autoload :Version,      'ld/patch/version'
+
+    ##
+    # Parse the given LD Patch `input` string.
+    #
+    # @example
+    #   query = LD::Patch.parse("Add { <http://example.org/s2> <http://example.org/p2> <http://example.org/o2> } .")
+    #
+    # @param  [IO, StringIO, String, #to_s]  input
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Object]
+    #   The parsed Patch
+    def self.parse(input, options = {})
+      LD::Patch::Parser.new(input, options).parse
+    end
+
+    class Error < StandardError
+      # The status code associated with this error
+      attr_reader :code
+
+      ##
+      # Initializes a new patch error instance.
+      #
+      # @param  [String, #to_s]          message
+      # @param  [Hash{Symbol => Object}] options
+      # @option options [Integer]        :code (422)
+      def initialize(message, options = {})
+        @code = options.fetch(:status_code, 422)
+        super(message.to_s)
+      end
+    end
+
+    # Indicates bad syntax found in LD Patch document
+    class ParseError < Error
+      ##
+      # The invalid token which triggered the error.
+      #
+      # @return [String]
+      attr_reader :token
+
+      ##
+      # The line number where the error occurred.
+      #
+      # @return [Integer]
+      attr_reader :lineno
+
+      ##
+      # Initializes a new parser error instance.
+      #
+      # @param  [String, #to_s]          message
+      # @param  [Hash{Symbol => Object}] options
+      # @option options [String]         :token  (nil)
+      # @option options [Integer]        :lineno (nil)
+      # @option options [Integer]        :code (400)
+      def initialize(message, options = {})
+        @token      = options[:token]
+        @lineno     = options[:lineno] || (@token.lineno if @token.respond_to?(:lineno))
+        super(message.to_s, code: options.fetch(:code, 400))
+      end
+    end
+  end
+end
+
+

data/lib/ld/patch/algebra.rb

@@ -0,0 +1,24 @@
+$:.unshift(File.expand_path("../..", __FILE__))
+require 'sparql/algebra'
+require 'sxp'
+
+module LD::Patch
+  # Based on the SPARQL Algebra, operators for executing a patch
+  #
+  # @author [Gregg Kellogg](http://greggkellogg.net/)
+  module Algebra
+    autoload :Add,        'ld/patch/algebra/add'
+    autoload :Bind,       'ld/patch/algebra/bind'
+    autoload :Constraint, 'ld/patch/algebra/constraint'
+    autoload :Cut,        'ld/patch/algebra/cut'
+    autoload :Delete,     'ld/patch/algebra/delete'
+    autoload :Index,      'ld/patch/algebra/index'
+    autoload :Patch,      'ld/patch/algebra/patch'
+    autoload :Path,       'ld/patch/algebra/path'
+    autoload :Prefix,     'ld/patch/algebra/prefix'
+    autoload :Reverse,    'ld/patch/algebra/reverse'
+    autoload :UpdateList, 'ld/patch/algebra/update_list'
+  end
+end
+
+

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

@@ -0,0 +1,59 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `add` operator.
+  #
+  # The Add operation is used to add triples to the target graph with or without allowing duplicates.
+  #
+  # @example
+  #   (add ((<a> <b> <c>)))
+  #
+  class Add < SPARQL::Algebra::Operator::Unary
+    include SPARQL::Algebra::Update
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :add
+
+    ##
+    # 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] :new
+    #   Specifies that triples may not 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 the :new option is specified and any triples already exist in queryable or if unbound variables are used
+    # @see    http://www.w3.org/TR/sparql11-update/
+    def execute(queryable, options = {})
+      debug(options) {"Add"}
+      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[:new]
+        triples.each do |triple|
+          raise LD::Patch::Error, "Target graph contains added triple #{triple.to_ntriples}" if queryable.has_statement?(triple)
+        end
+      end
+
+      queryable.insert(*triples)
+      bindings
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+module LD::Patch::Algebra
+
+  ##
+  # The LD Patch `bind` operator.
+  #
+  # The Bind operation is used to bind a single term to a variable.
+  #
+  # @example simple value to variable binding
+  #   Bind ?x <http://example.org/s> . #=>
+  #   (bind ?x <http://example.org/s> ())
+  #
+  # @example constant path (filter-forward.ldpatch)
+  #   Bind ?x <http://example.org/s> / <http://example.org/p1> . #=>
+  #   (bind ?x <http://example.org/s> (<http://example.org/p1>))
+  #
+  # @example list index (path-at.ldpatch)
+  #   Bind ?x <http://example.org/s> / 1 . #=>
+  #   (bind ?x <http://example.org/s> ((index 1)))
+  #
+  # @example reverse (path-backward.ldpath)
+  #   Bind ?x <http://example.org/s> / ^<http://example.org/p1> . #=>
+  #   (bind ?x <http://example.org/s> ((reverse <http://example.org/p1>)))
+  #
+  # @example constraint (path-filter-equal.ldpatch)
+  #   Bind ?x <http://example.org/s> / <http://example.org/p2> [  / <http://example.org/l> = "b" ] . #=>
+  #   (bind ?x <http://example.org/s> (
+  #     <http://example.org/p2>
+  #     (constraint (<http://example.org/l>) "b")))
+  #
+  # @example constraint (path-filter.ldpatch)
+  #   Bind ?x <http://example.org/s> / <http://example.org/p2> [  / <http://example.org/p1> ] . #=>
+  #   (bind ?x <http://example.org/s> (
+  #     <http://example.org/p2>
+  #     (constraint (<http://example.org/l>))))
+  #
+  # @example starting with a literal
+  #   Bind ?x "a" / ^<http://example.org/l> / ^<http://example.org/p2> . #=>
+  #   (bind ?x "a" (
+  #     (reverse <http://example.org/l>)
+  #     (reverse <http://example.org/p2>)))
+  #
+  # @example unicity (path-unicity.ldpath)
+  #   Bind ?x <http://example.org/s> / <http://example.org/p1> ! . #=>
+  #   SELECT ?x
+  #   WHERE {<http//example.org/s> <http://example.org/p1> ?x}
+  #   GROUP BY ?x
+  #   HAVING COUNT(?x) = 1
+  #   (bind ?x ?0
+  #     ((pattern <http://example.org/s> <http://example.org/p1> ??0)
+  #      (unique ??0)))
+  class Bind < SPARQL::Algebra::Operator::Ternary
+    include SPARQL::Algebra::Query
+    include SPARQL::Algebra::Evaluatable
+
+    NAME = :bind
+
+    ##
+    # Maps the value to a single output term by executing the path and updates `bindings` with `var` set to that output term
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to write
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [RDF::Query::Solutions] :bindings
+    # @return [RDF::Query::Solutions] A single solution including passed bindings with `var` bound to the solution.
+    # @raise [Error]
+    #   If path does not evaluate to a single term or if unbound variables are used.
+    # @see    http://www.w3.org/TR/sparql11-update/
+    def execute(queryable, options = {})
+      debug(options) {"Bind"}
+      bindings = options.fetch(:bindings)
+      solution = bindings.first
+      var, value, path = operands
+
+      # Bind variables to path
+      if value.variable?
+        raise LD::Patch::Error.new("Operand uses unbound variable #{value.inspect}", code: 400) unless solution.bound?(value)
+        value = solution[value]
+      end
+
+      path = path.dup.replace_vars! do |v|
+        raise Error, "Operand uses unbound variable #{v.inspect}" unless solution.bound?(v)
+        solution[v]
+      end
+      results = path.execute(queryable, terms: [value])
+      raise LD::Patch::Error, "Bind path bound to #{results.length} terms, expected just one" unless results.length == 1
+      RDF::Query::Solutions.new [solution.merge(var.to_sym => results.first.path)]
+    end
+  end
+end