shex 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ba75ebd8c6632f82452b8cc6a19dbe69e86258d
-  data.tar.gz: a924845f0d0ffd7caa35926b98829345ee3d427a
+  metadata.gz: 5d83ac4fdd795f4d27280e23fc431a42faa72dd7
+  data.tar.gz: 61b80075c76f018481226ed563fa7ec44fe0c35f
 SHA512:
-  metadata.gz: 1e844351dfd63a5c158a088b6d83375e3f96382d1a56c3e7aaa8e037f4c3ae380bac4f04d1da9db3727053400563b96565d291cb7537974c920df636bf7d3614
-  data.tar.gz: 3797b22ce44300b723770608ee42a3fd03418f0c8497e4a370fdf960f47ad324c67b07ec061ca498a8fa2d683b97a4fab7c95ced34123840e2c968120e162418
+  metadata.gz: 2a158d18cdfbe1c0ae951549bbafc0e8d2d312cc08d259eefe76729e192db380b60a63b0d4a525cc4c49eee8f3092b9fd82cee03fe174cf8ab334c57bb943a4f
+  data.tar.gz: 5078624090859f18d37daf162baadcca943533c4bd35eb3e52299c737a18b3c7ab85e1d3e0d4819f3d7a12b9c97e308e580b7d408a43d866ee1264331bb01d73

data/README.md

@@ -19,10 +19,12 @@ This is a pure-Ruby library for working with the [Shape Expressions Language][Sh
 
 The ShEx gem implements a [ShEx][ShExSpec] Shape Expression engine.
 
-* `ShEx::Parser` parses ShExC formatted documents generating executable operators which can be serialized as [S-Expressions](http://en.wikipedia.org/wiki/S-expression).
+* `ShEx::Parser` parses ShExC and ShExJ formatted documents generating executable operators which can be serialized as [S-Expressions](http://en.wikipedia.org/wiki/S-expression).
 * `ShEx::Algebra` executes operators against Any `RDF::Graph`, including compliant [RDF.rb][].
+* [Implementation Report](file.earl.html)
 
-## Example
+## Examples
+### Validating a node using ShExC
 
     require 'rubygems'
     require 'rdf/turtle'
@@ -46,6 +48,121 @@ The ShEx gem implements a [ShEx][ShExSpec] Shape Expression engine.
     }
     schema.satisfies?("http://rubygems.org/gems/shex", graph, map)
     # => true
+### Validating a node using ShExC
+
+    require 'rubygems'
+    require 'rdf/turtle'
+    require 'shex'
+
+    shexj: %({
+      "type": "Schema",
+      "prefixes": {
+        "doap": "http://usefulinc.com/ns/doap#",
+        "dc": "http://purl.org/dc/terms/"
+      },
+      "shapes": {
+        "TestShape": {
+          "type": "Shape",
+          "extra": ["http://www.w3.org/1999/02/22-rdf-syntax-ns#type"],
+          "expression": {
+            "type": "EachOf",
+            "expressions": [
+              {
+                "type": "TripleConstraint",
+                "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+                "valueExpr": {
+                  "type": "NodeConstraint",
+                  "values": ["http://usefulinc.com/ns/doap#Project"]
+                }
+              },
+              {
+                "type": "OneOf",
+                "expressions": [
+                  {
+                    "type": "EachOf",
+                    "expressions": [
+                      {
+                        "type": "TripleConstraint",
+                        "predicate": "http://usefulinc.com/ns/doap#name",
+                        "valueExpr": {"type": "NodeConstraint", "nodeKind": "literal"}
+                      },
+                      {
+                        "type": "TripleConstraint",
+                        "predicate": "http://usefulinc.com/ns/doap#description",
+                        "valueExpr": {"type": "NodeConstraint", "nodeKind": "literal"}
+                      }
+                    ]
+                  },
+                  {
+                    "type": "EachOf",
+                    "expressions": [
+                      {
+                        "type": "TripleConstraint",
+                        "predicate": "http://purl.org/dc/terms/title",
+                        "valueExpr": {"type": "NodeConstraint", "nodeKind": "literal"}
+                      },
+                      {
+                        "type": "TripleConstraint",
+                        "predicate": "http://purl.org/dc/terms/description",
+                        "valueExpr": {"type": "NodeConstraint", "nodeKind": "literal"}
+                      }
+                    ]
+                  }
+                ],
+                "min": 1, "max": "*"
+              },
+              {
+                "type": "TripleConstraint",
+                "predicate": "http://usefulinc.com/ns/doap#category",
+                "valueExpr": {"type": "NodeConstraint", "nodeKind": "iri"},
+                "min": 0, "max": "*"
+              },
+              {
+                "type": "TripleConstraint",
+                "predicate": "http://usefulinc.com/ns/doap#developer",
+                "valueExpr": {"type": "NodeConstraint", "nodeKind": "iri"},
+                "min": 1, "max": "*"
+              },
+              {
+                "type": "TripleConstraint",
+                "predicate": "http://usefulinc.com/ns/doap#implements",
+                "valueExpr": {
+                  "type": "NodeConstraint",
+                  "values": ["https://shexspec.github.io/spec/"]
+                }
+              }
+            ]
+          }
+        }
+      }
+    })
+    graph = RDF::Graph.load("etc/doap.ttl")
+    schema = ShEx.parse(shexj, format: :shexj)
+    map = {"http://rubygems.org/gems/shex" => "TestShape"}
+    schema.satisfies?("http://rubygems.org/gems/shex", graph, map)
+    # => true
+
+## Extensions
+ShEx has an extension mechanism using [Semantic Actions](https://shexspec.github.io/spec/#semantic-actions). Extensions may be implemented in Ruby ShEx by sub-classing {ShEx::Extension} and implementing {ShEx::Extension#visit} and possibly {ShEx::Extension#initialize}, {ShEx::Extension#enter}, {ShEx::Extension#exit}, and {ShEx::Extension#close}. The `#visit` method will be called as part of the `#satisfies?` operation.
+
+    require 'shex'
+    class ShEx::Test < ShEx::Extension("http://shex.io/extensions/Test/")
+      # (see ShEx::Extension#initialize)
+      def initialize(schema: nil, logger: nil, depth: 0, **options)
+        ...
+      end
+
+      # (see ShEx::Extension#visit)
+      def visit(code: nil, matched: nil, expression: nil, depth: 0, **options)
+        ...
+      end
+    end
+
+The `#enter` method will be called on any {ShEx::Algebra::TripleExpression} that includes a {ShEx::Algebra::SemAct} referencing the extension, while the `#exit` method will be called on exit, even if not satisfied.
+
+The `#initialize` method is called when {ShEx::Algebra::Schema#execute} starts and `#close` called on exit, even if not satisfied.
+
+To make sure your extension is found, make sure to require it before the shape is executed.
 
 ## Documentation
 

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/etc/doap.ttl

@@ -8,7 +8,7 @@
 @prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
 
 <http://rubygems.org/gems/shex> a doap:Project, earl:TestSubject, earl:Software ;
-  doap:name          "ShEx" ;
+  doap:name          "ShEx.rb" ;
   doap:homepage      <http://ruby-rdf.github.com/shex> ;
   doap:license       <http://creativecommons.org/licenses/publicdomain/> ;
   doap:shortdesc     "ShEx is a Shape Expression engine for Ruby."@en ;
@@ -26,7 +26,7 @@
   doap:maintainer    <http://greggkellogg.net/foaf#me> ;
   doap:documenter    <http://greggkellogg.net/foaf#me> ;
   foaf:maker         <http://greggkellogg.net/foaf#me> ;
-  dc:title           "ShEx" ;
+  dc:title           "ShEx.rb" ;
   dc:description     "ShEx is an Shape Expression engine for the RDF.rb library suite."@en ;
   dc:date            "2016-12-09"^^xsd:date ;
   dc:creator         <http://greggkellogg.net/foaf#me> ;

data/lib/shex.rb

@@ -6,9 +6,16 @@ module ShEx
   autoload :Algebra,    'shex/algebra'
   autoload :Meta,       'shex/meta'
   autoload :Parser,     'shex/parser'
+  autoload :Extension,  'shex/extensions/extension'
   autoload :Terminals,  'shex/terminals'
   autoload :VERSION,    'shex/version'
 
+  # Location of the ShEx JSON-LD context
+  CONTEXT = "https://shexspec.github.io/context.jsonld"
+
+  # Extensions defined in this gem
+  EXTENSIONS = %w{test}
+
   ##
   # Parse the given ShEx `query` string.
   #
@@ -24,10 +31,14 @@ module ShEx
   # @return (see ShEx::Parser#parse)
   # @raise  (see ShEx::Parser#parse)
   def self.parse(expression, format: 'shexc', **options)
-    case format
+    case format.to_s
     when 'shexc' then Parser.new(expression, options).parse
     when 'shexj'
+      expression = expression.read if expression.respond_to?(:read)
+      Algebra.from_shexj(JSON.parse expression)
     when 'sxp'
+      expression = expression.read if expression.respond_to?(:read)
+      Algebra.from_sxp(JSON.parse expression)
     else raise "Unknown expression format: #{format.inspect}"
     end
   end
@@ -85,6 +96,15 @@ module ShEx
     shex.satisfies?(focus, queryable, {focus => shape}, options)
   end
 
+  ##
+  # Alias for `ShEx::Extension.create`.
+  #
+  # @param (see ShEx::Extension#create)
+  # @return [Class]
+  def self.Extension(uri)
+    Extension.send(:create, uri)
+  end
+
   class Error < StandardError
     # The status code associated with this error
     attr_reader :code
@@ -167,7 +187,6 @@ module ShEx
     # ParseError includes `token` and `lineno` associated with the expression.
     #
     # @param  [String, #to_s]          message
-    # @param  [Hash{Symbol => Object}] options
     # @param [String]                  token  (nil)
     # @param [Integer]                 lineno (nil)
     def initialize(message, token: nil, lineno: nil)

data/lib/shex/algebra.rb

@@ -9,7 +9,6 @@ module ShEx
   module Algebra
     autoload :And, 'shex/algebra/and'
     autoload :Annotation, 'shex/algebra/annotation'
-    autoload :Base, 'shex/algebra/base'
     autoload :EachOf, 'shex/algebra/each_of'
     autoload :Inclusion, 'shex/algebra/inclusion'
     autoload :Not, 'shex/algebra/not'
@@ -17,7 +16,6 @@ module ShEx
     autoload :OneOf, 'shex/algebra/one_of'
     autoload :Operator, 'shex/algebra/operator'
     autoload :Or, 'shex/algebra/or'
-    autoload :Prefix, 'shex/algebra/prefix'
     autoload :Satisfiable, 'shex/algebra/satisfiable'
     autoload :Schema, 'shex/algebra/schema'
     autoload :SemAct, 'shex/algebra/semact'
@@ -29,8 +27,48 @@ module ShEx
     autoload :StemRange, 'shex/algebra/stem_range'
     autoload :TripleConstraint, 'shex/algebra/triple_constraint'
     autoload :TripleExpression, 'shex/algebra/triple_expression'
-    autoload :UnaryShape, 'shex/algebra/unary_shape'
     autoload :Value, 'shex/algebra/value'
+
+
+    ##
+    # Creates an operator instance from a parsed ShExJ representation
+    #
+    # @example Simple TripleConstraint
+    #   rep = JSON.parse(%({
+    #           "type": "TripleConstraint",
+    #           "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
+    #         }
+    #   ))
+    #   TripleConstraint.from(rep) #=> (tripleConstraint a)
+    # @param [Hash] operator
+    # @param [Hash] options ({})
+    # @option options [RDF::URI] :base
+    # @option options [Hash{String => RDF::URI}] :prefixes
+    # @return [Operator]
+    def self.from_shexj(operator, options = {})
+      raise ArgumentError unless operator.is_a?(Hash)
+      klass = case operator['type']
+      when 'Annotation'       then Annotation
+      when 'EachOf'           then EachOf
+      when 'Inclusion'        then Inclusion
+      when 'NodeConstraint'   then NodeConstraint
+      when 'OneOf'            then OneOf
+      when 'Schema'           then Schema
+      when 'SemAct'           then SemAct
+      when 'Shape'            then Shape
+      when 'ShapeAnd'         then And
+      when 'ShapeNot'         then Not
+      when 'ShapeOr'          then Or
+      when 'ShapeRef'         then ShapeRef
+      when 'Stem'             then Stem
+      when 'StemRange'        then StemRange
+      when 'TripleConstraint' then TripleConstraint
+      when 'Wildcard'         then StemRange
+      else raise ArgumentError, "unknown type #{operator['type']}"
+      end
+
+      klass.from_shexj(operator, options)
+    end
   end
 end
 

data/lib/shex/algebra/and.rb

@@ -6,9 +6,22 @@ module ShEx::Algebra
 
     def initialize(*args, **options)
       case
-      when args.length <= 1
-        raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 1..)"
+      when args.length < 2
+        raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 2..)"
       end
+
+      # All arguments must be Satisfiable
+      raise ArgumentError, "All operands must be Shape operands" unless args.all? {|o| o.is_a?(Satisfiable)}
+      super
+    end
+
+    ##
+    # Creates an operator instance from a parsed ShExJ representation
+    # @param (see Operator#from_shexj)
+    # @return [Operator]
+    def self.from_shexj(operator, options = {})
+      raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == 'ShapeAnd'
+      raise ArgumentError, "missing shapeExprs in #{operator.inspect}" unless operator.has_key?('shapeExprs')
       super
     end
 
@@ -17,20 +30,28 @@ module ShEx::Algebra
     # @param  (see Satisfiable#satisfies?)
     # @return (see Satisfiable#satisfies?)
     # @raise  (see Satisfiable#satisfies?)
-    def satisfies?(focus)
+    def satisfies?(focus, depth: 0)
       status ""
       expressions = operands.select {|o| o.is_a?(Satisfiable)}
       satisfied = []
+      unsatisfied = expressions.dup
 
       # Operand raises NotSatisfied, so no need to check here.
       expressions.each do |op|
-        satisfied << op.satisfies?(focus)
+        satisfied << op.satisfies?(focus, depth: depth)
+        unsatisfied.shift
       end
-      satisfy satisfied: satisfied
+      satisfy focus: focus, satisfied: satisfied, depth: depth
     rescue ShEx::NotSatisfied => e
       not_satisfied e.message,
+                    focus:       focus, 
                     satisfied:   satisfied,
-                    unsatisfied: (expressions - satisfied)
+                    unsatisfied: unsatisfied,
+                    depth:       depth
+    end
+
+    def json_type
+      "ShapeAnd"
     end
   end
 end

data/lib/shex/algebra/annotation.rb

@@ -2,5 +2,24 @@ module ShEx::Algebra
   ##
   class Annotation < Operator
     NAME = :annotation
+
+    ##
+    # Creates an operator instance from a parsed ShExJ representation
+    # @param (see Operator#from_shexj)
+    # @return [Operator]
+    def self.from_shexj(operator, options = {})
+      raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == "Annotation"
+      raise ArgumentError, "missing predicate in #{operator.inspect}" unless operator.has_key?('predicate')
+      raise ArgumentError, "missing object in #{operator.inspect}" unless operator.has_key?('object')
+      super
+    end
+
+    def to_h
+      {
+        'type' => json_type,
+        'predicate' => operands.first.to_s,
+        'object' => serialize_value(operands.last)
+      }
+    end
   end
 end

data/lib/shex/algebra/each_of.rb

@@ -4,39 +4,51 @@ module ShEx::Algebra
     include TripleExpression
     NAME = :eachOf
 
+    ##
+    # Creates an operator instance from a parsed ShExJ representation
+    # @param (see Operator#from_shexj)
+    # @return [Operator]
+    def self.from_shexj(operator, options = {})
+      raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == 'EachOf'
+      raise ArgumentError, "missing expressions in #{operator.inspect}" unless operator.has_key?('expressions')
+      super
+    end
+
     ##
     # expr is an EachOf and there is some partition of T into T1, T2,… such that for every expression expr1, expr2,… in shapeExprs, matches(Tn, exprn, m)...
     #
-    # @param [Array<RDF::Statement>] statements
-    # @return [Array<RDF::Statement>]
-    # @raise [ShEx::NotMatched]
-    def matches(statements)
-      status ""
+    # @param  (see TripleExpression#matches)
+    # @return (see TripleExpression#matches)
+    # @raise  (see TripleExpression#matches)
+    def matches(arcs_in, arcs_out, depth: 0)
+      status "", depth: depth
       results, satisfied, unsatisfied = [], [], []
       num_iters, max = 0, maximum
 
+      # enter semantic acts
+      semantic_actions.each {|op| op.enter(arcs_in: arcs_in, arcs_out: arcs_out, depth: depth + 1)}
+
       while num_iters < max
         begin
           matched_this_iter = []
           operands.select {|o| o.is_a?(TripleExpression)}.all? do |op|
             begin
-              matched_op = op.matches(statements - matched_this_iter)
+              matched_op = op.matches(arcs_in - matched_this_iter, arcs_out - matched_this_iter, depth: depth + 1)
               satisfied << matched_op
               matched_this_iter += matched_op.matched
             rescue ShEx::NotMatched => e
-              status "not matched: #{e.message}"
-              op = op.dup
-              op.unmatched = statements - matched_this_iter
-              unsatisfied << op
+              status "not matched: #{e.message}", depth: depth
+              unsatisfied << e.expression
               raise
             end
           end
           results += matched_this_iter
-          statements -= matched_this_iter
+          arcs_in -= matched_this_iter
+          arcs_out -= matched_this_iter
           num_iters += 1
-          status "matched #{results.length} statements after #{num_iters} iterations"
+          status "matched #{results.length} statements after #{num_iters} iterations", depth: depth
         rescue ShEx::NotMatched => e
-          status "no match after #{num_iters} iterations (ignored)"
+          status "no match after #{num_iters} iterations (ignored)", depth: depth
           break
         end
       end
@@ -47,15 +59,16 @@ module ShEx::Algebra
       end
 
       # Last, evaluate semantic acts
-      semantic_actions.all? do |op|
-        op.satisfies?(results)
-      end unless results.empty?
+      semantic_actions.each {|op| op.satisfies?(nil, matched: results, depth: depth + 1)}
 
-      satisfy matched: results, satisfied: satisfied
+      satisfy matched: results, satisfied: satisfied, depth: depth
     rescue ShEx::NotMatched, ShEx::NotSatisfied => e
       not_matched e.message,
-                  matched:   results,   unmatched:   (statements - results),
-                  satisfied: satisfied, unsatisfied: unsatisfied
+                  matched:   results,   unmatched:   ((arcs_in + arcs_out).uniq - results),
+                  satisfied: satisfied, unsatisfied: unsatisfied,
+                  depth:     depth
+    ensure
+      semantic_actions.each {|op| op.exit(matched: matched, depth: depth + 1)}
     end
   end
 end