shex 0.4.0 → 0.6.1

data/lib/shex/algebra/and.rb

@@ -19,7 +19,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    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

data/lib/shex/algebra/annotation.rb

@@ -7,7 +7,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    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')

data/lib/shex/algebra/each_of.rb

@@ -8,7 +8,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    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

data/lib/shex/algebra/language.rb

@@ -0,0 +1,22 @@
+module ShEx::Algebra
+  ##
+  class Language < Operator::Unary
+    NAME = :language
+
+    ##
+    # matches any literal having a language tag that matches value
+    def match?(value, depth: 0)
+      status "", depth: depth
+      if case expr = operands.first
+        when RDF::Literal then value.language == expr.to_s.to_sym
+        else false
+        end
+        status "matched #{value}", depth: depth
+        true
+      else
+        status "not matched #{value}", depth: depth
+        false
+      end
+    end
+  end
+end

data/lib/shex/algebra/node_constraint.rb

@@ -1,3 +1,4 @@
+# -*- encoding: utf-8 -*-
 module ShEx::Algebra
   ##
   class NodeConstraint < Operator
@@ -8,7 +9,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    def self.from_shexj(operator, **options)
       raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == 'NodeConstraint'
       super
     end
@@ -58,7 +59,7 @@ module ShEx::Algebra
       return true unless dt
 
       not_satisfied "Node was #{value.inspect}, expected datatype #{dt}", depth: depth unless
-        value.is_a?(RDF::Literal) && value.datatype == RDF::URI(dt)
+        value.is_a?(RDF::Literal) && value.datatype == RDF::URI(dt) && value.valid?
       status "right datatype: #{value}: #{dt}", depth: depth
       true
     end
@@ -68,11 +69,18 @@ module ShEx::Algebra
     # Checks all length/minlength/maxlength/pattern facets against the string representation of the value.
     # @return [Boolean] `true` if satisfied, `false` if it does not apply
     # @raise [ShEx::NotSatisfied] if not satisfied
+    # @todo using the XPath regexp engine supports additional flags "s" and "q"
     def satisfies_string_facet?(value, depth: 0)
       length    = op_fetch(:length)
       minlength = op_fetch(:minlength)
       maxlength = op_fetch(:maxlength)
-      pattern   = op_fetch(:pattern)
+      pat = (operands.detect {|op| op.is_a?(Array) && op[0] == :pattern} || [])
+      pattern = pat[1]
+
+      flags = 0
+      flags |= Regexp::EXTENDED   if pat[2].to_s.include?("x")
+      flags |= Regexp::IGNORECASE if pat[2].to_s.include?("i")
+      flags |= Regexp::MULTILINE  if pat[2].to_s.include?("m")
 
       return true if (length || minlength || maxlength || pattern).nil?
 
@@ -80,6 +88,7 @@ module ShEx::Algebra
       when RDF::Node then value.id
       else value.to_s
       end
+
       not_satisfied "Node #{v_s.inspect} length not #{length}", depth: depth if
         length && v_s.length != length.to_i
       not_satisfied"Node #{v_s.inspect} length < #{minlength}", depth: depth if
@@ -87,7 +96,7 @@ module ShEx::Algebra
       not_satisfied "Node #{v_s.inspect} length > #{maxlength}", depth: depth if
         maxlength && v_s.length > maxlength.to_i
       not_satisfied "Node #{v_s.inspect} does not match #{pattern}", depth: depth if
-        pattern && !Regexp.new(pattern).match(v_s)
+        pattern && !Regexp.new(pattern, flags).match(v_s)
       status "right string facet: #{value}", depth: depth
       true
     end

data/lib/shex/algebra/not.rb

@@ -8,7 +8,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    def self.from_shexj(operator, **options)
       raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == 'ShapeNot'
       raise ArgumentError, "missing shapeExpr in #{operator.inspect}" unless operator.has_key?('shapeExpr')
       super
@@ -19,7 +19,7 @@ module ShEx::Algebra
     # @param  (see ShapeExpression#satisfies?)
     # @return (see ShapeExpression#satisfies?)
     # @raise  (see ShapeExpression#satisfies?)
-    # @see [https://shexspec.github.io/spec/#shape-expression-semantics]
+    # @see [http://shex.io/shex-semantics/#shape-expression-semantics]
     def satisfies?(focus, depth: 0)
       status ""
       op = expressions.last

data/lib/shex/algebra/one_of.rb

@@ -8,7 +8,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    def self.from_shexj(operator, **options)
       raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == 'OneOf'
       raise ArgumentError, "missing expressions in #{operator.inspect}" unless operator.has_key?('expressions')
       super

data/lib/shex/algebra/operator.rb

@@ -26,7 +26,7 @@ module ShEx::Algebra
     # @overload initialize(*operands)
     #   @param  [Array<RDF::Term>] operands
     #
-    # @overload initialize(*operands, options)
+    # @overload initialize(*operands, **options)
     #   @param  [Array<RDF::Term>] operands
     #   @param  [Hash{Symbol => Object}] options
     #     any additional options
@@ -244,7 +244,7 @@ module ShEx::Algebra
     # @return [String]
     def to_sxp
       begin
-        require 'sxp' # @see http://rubygems.org/gems/sxp
+        require 'sxp' # @see https://rubygems.org/gems/sxp
       rescue LoadError
         abort "SPARQL::Algebra::Operator#to_sxp requires the SXP gem (hint: `gem install sxp')."
       end
@@ -260,24 +260,29 @@ module ShEx::Algebra
     # @option options [RDF::URI] :base
     # @option options [Hash{String => RDF::URI}] :prefixes
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    def self.from_shexj(operator, **options)
       options[:context] ||= JSON::LD::Context.parse(ShEx::CONTEXT)
       operands = []
       id = nil
 
       operator.each do |k, v|
         case k
-        when /length|pattern|clusive|digits/   then operands << [k.to_sym, RDF::Literal(v)]
-        when 'id'                              then id = iri(v, options)
-        when 'min', 'max'                      then operands << [k.to_sym, v]
+        when /length|clusive|digits/           then operands << [k.to_sym, RDF::Literal(v)]
+        when 'id'                              then id = iri(v, **options)
+        when 'flags'                           then ; # consumed in pattern below
+        when 'min', 'max'                      then operands << [k.to_sym, (v == -1 ? '*' : v)]
         when 'inverse', 'closed'               then operands << k.to_sym
         when 'nodeKind'                        then operands << v.to_sym
-        when 'object'                          then operands << value(v, options)
+        when 'object'                          then operands << value(v, **options)
+        when 'languageTag'                     then operands << v
+        when 'pattern'
+          # Include flags as well
+          operands << [:pattern, RDF::Literal(v), operator['flags']].compact
         when 'start'
           if v.is_a?(String)
-            operands << Start.new(iri(v, options))
+            operands << Start.new(iri(v, **options))
           else
-            operands << Start.new(ShEx::Algebra.from_shexj(v, options))
+            operands << Start.new(ShEx::Algebra.from_shexj(v, **options))
           end
         when '@context'                        then
           options[:context] = JSON::LD::Context.parse(v)
@@ -285,39 +290,47 @@ module ShEx::Algebra
         when 'shapes'
           operands << case v
           when Array
-            [:shapes] + v.map {|vv| ShEx::Algebra.from_shexj(vv, options)}
+            [:shapes] + v.map {|vv| ShEx::Algebra.from_shexj(vv, **options)}
           else
             raise "Expected value of shapes #{v.inspect}"
           end
         when 'stem', 'name'
           # Value may be :wildcard for stem
-          operands << (v.is_a?(Symbol) ? v : iri(v, options))
-        when 'predicate' then operands << [:predicate, iri(v, options)]
+          if [IriStem, IriStemRange, SemAct].include?(self)
+            operands << (v.is_a?(Symbol) ? v : value(v, **options))
+          else
+            operands << v
+          end
+        when 'predicate' then operands << [:predicate, iri(v, **options)]
         when 'extra', 'datatype'
           v = [v] unless v.is_a?(Array)
-          operands << (v.map {|op| iri(op, options)}).unshift(k.to_sym)
+          operands << (v.map {|op| iri(op, **options)}).unshift(k.to_sym)
         when 'exclusions'
           v = [v] unless v.is_a?(Array)
           operands << v.map do |op|
-            op.is_a?(Hash) ?
-              ShEx::Algebra.from_shexj(op, options) :
-              value(op, options)
+            if op.is_a?(Hash) && op.has_key?('type')
+              ShEx::Algebra.from_shexj(op, **options)
+            elsif [IriStem, IriStemRange].include?(self)
+              value(op, **options)
+            else
+              RDF::Literal(op)
+            end
           end.unshift(:exclusions)
         when 'semActs', 'startActs', 'annotations'
           v = [v] unless v.is_a?(Array)
-          operands += v.map {|op| ShEx::Algebra.from_shexj(op, options)}
+          operands += v.map {|op| ShEx::Algebra.from_shexj(op, **options)}
         when 'expression', 'expressions', 'shapeExpr', 'shapeExprs', 'valueExpr'
           v = [v] unless v.is_a?(Array)
           operands += v.map do |op|
             # It's a URI reference to a Shape
-            op.is_a?(String) ? iri(op, options) : ShEx::Algebra.from_shexj(op, options) 
+            op.is_a?(String) ? iri(op, **options) : ShEx::Algebra.from_shexj(op, **options) 
           end
         when 'code'
           operands << v
         when 'values'
           v = [v] unless v.is_a?(Array)
           operands += v.map do |op|
-            Value.new(value(op, options))
+            Value.new(value(op, **options))
           end
         end
       end
@@ -345,11 +358,18 @@ module ShEx::Algebra
         when Array
           # First element should be a symbol
           case sym = op.first
-          when :datatype,
-               :pattern         then obj[op.first.to_s] = op.last.to_s
-          when :exclusions      then obj['exclusions'] = Array(op[1..-1]).map {|v| serialize_value(v)}
+          when :datatype        then obj['datatype'] = op.last.to_s
+          when :exclusions
+            obj['exclusions'] = Array(op[1..-1]).map do |v|
+              case v
+              when Operator then v.to_h
+              else v.to_s
+              end
+            end
           when :extra           then (obj['extra'] ||= []).concat Array(op[1..-1]).map(&:to_s)
-            # FIXME Shapes should be an array, not a hash
+          when :pattern
+            obj['pattern'] = op[1]
+            obj['flags'] = op[2] if op[2]
           when :shapes          then obj['shapes'] = Array(op[1..-1]).map {|v| v.to_h}
           when :minlength,
                :maxlength,
@@ -360,7 +380,7 @@ module ShEx::Algebra
                :maxexclusive,
                :totaldigits,
                :fractiondigits  then obj[op.first.to_s] = op.last.object
-          when :min, :max       then obj[op.first.to_s] = op.last
+          when :min, :max       then obj[op.first.to_s] = op.last == '*' ? -1 : op.last
           when :predicate       then obj[op.first.to_s] = op.last.to_s
           when :base, :prefix
             # Ignore base and prefix
@@ -378,13 +398,18 @@ module ShEx::Algebra
           end
         when RDF::Value
           case self
-          when Stem, StemRange  then obj['stem'] = op.to_s
+          when Stem, StemRange
+            obj['stem'] =  case op
+            when Operator then op.to_h
+            else op.to_s
+            end
           when SemAct           then obj[op.is_a?(RDF::URI) ? 'name' : 'code'] = op.to_s
           when TripleConstraint then obj['valueExpr'] = op.to_s
           when Shape            then obj['expression'] = op.to_s
           when EachOf, OneOf    then (obj['expressions'] ||= []) << op.to_s
           when And, Or          then (obj['shapeExprs'] ||= []) << op.to_s
           when Not              then obj['shapeExpr'] = op.to_s
+          when Language         then obj['languageTag'] = op.to_s
           else
             raise "How to serialize Value #{op.inspect} to json for #{self}"
           end
@@ -451,14 +476,14 @@ module ShEx::Algebra
     # @option options [JSON::LD::Context] :context
     # @return [RDF::Value]
     def iri(value, options = @options)
-      self.class.iri(value, options)
+      self.class.iri(value, **options)
     end
 
     # Create URIs
     # @param  (see #iri)
     # @option (see #iri)
     # @return (see #iri)
-    def self.iri(value, options)
+    def self.iri(value, **options)
       # If we have a base URI, use that when constructing a new URI
       base_uri = options[:base_uri]
 
@@ -467,7 +492,7 @@ module ShEx::Algebra
         # A JSON-LD node reference
         v = options[:context].expand_value(value)
         raise "Expected #{value.inspect} to be a JSON-LD Node Reference" unless JSON::LD::Utils.node_reference?(v)
-        self.iri(v['@id'], options)
+        self.iri(v['@id'], **options)
       when RDF::URI
         if base_uri && value.relative?
           base_uri.join(value)
@@ -505,26 +530,26 @@ module ShEx::Algebra
     # @option options [Hash{String => RDF::URI}] :prefixes
     # @return [RDF::Value]
     def value(value, options = @options)
-      self.class.value(value, options)
+      self.class.value(value, **options)
     end
 
     # Create Values, with "clever" matching to see if it might be a value, IRI or BNode.
     # @param  (see #value)
     # @option (see #value)
     # @return (see #value)
-    def self.value(value, options)
+    def self.value(value, **options)
       # If we have a base URI, use that when constructing a new URI
       case value
       when Hash
         # Either a value object or a node reference
-        if value['uri']
-          iri(value['uri'], options)
-        elsif value['value']
-          RDF::Literal(value['value'], datatype: value['type'], language: value['language'])
+        if value['uri'] || value['@id']
+          iri(value['uri'] || value['@id'], **options)
+        elsif value['value'] || value['@value']
+          RDF::Literal(value['value'] || value['@value'], datatype: value['type'] || value['@type'], language: value['language'] || value['@language'])
         else
-          ShEx::Algebra.from_shexj(value, options)
+          ShEx::Algebra.from_shexj(value, **options)
         end
-      else iri(value, options)
+      else iri(value, **options)
       end
     end
 
@@ -541,6 +566,8 @@ module ShEx::Algebra
           merge(value.has_language? ? {'language' => value.language.to_s} : {})
         when RDF::Resource
           value.to_s
+        when String
+          {'value' => value}
         else value.to_h
       end
     end
@@ -566,7 +593,6 @@ module ShEx::Algebra
 
     ##
     # Enumerate via depth-first recursive descent over operands, yielding each operator
-    # @param [Integer] depth incrementeded for each depth of operator, and provided to block if Arity is 2
     # @yield operator
     # @yieldparam [Object] operator
     # @return [Enumerator]
@@ -634,12 +660,12 @@ module ShEx::Algebra
       self
     end
 
-  protected
-    def dup
-      operands = @operands.map {|o| o.dup rescue o}
-      self.class.new(*operands, id: @id)
-    end
+  def dup
+    operands = @operands.map {|o| o.dup rescue o}
+    self.class.new(*operands, id: @id)
+  end
 
+  protected
     ##
     # A unary operator.
     #
@@ -654,7 +680,7 @@ module ShEx::Algebra
       #   the first operand
       # @param  [Hash{Symbol => Object}] options
       #   any additional options (see {Operator#initialize})
-      def initialize(arg1, options = {})
+      def initialize(arg1, **options)
         raise ArgumentError, "wrong number of arguments (given 2, expected 1)" unless options.is_a?(Hash)
         super
       end
@@ -676,7 +702,7 @@ module ShEx::Algebra
       #   the second operand
       # @param  [Hash{Symbol => Object}] options
       #   any additional options (see {Operator#initialize})
-      def initialize(arg1, arg2, options = {})
+      def initialize(arg1, arg2, **options)
         raise ArgumentError, "wrong number of arguments (given 3, expected 2)" unless options.is_a?(Hash)
         super
       end

data/lib/shex/algebra/or.rb

@@ -19,7 +19,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    def self.from_shexj(operator, **options)
       raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == 'ShapeOr'
       raise ArgumentError, "missing shapeExprs in #{operator.inspect}" unless operator.is_a?(Hash) && operator.has_key?('shapeExprs')
       super

data/lib/shex/algebra/schema.rb

@@ -19,7 +19,7 @@ module ShEx::Algebra
     # Creates an operator instance from a parsed ShExJ representation
     # @param (see Operator#from_shexj)
     # @return [Operator]
-    def self.from_shexj(operator, options = {})
+    def self.from_shexj(operator, **options)
       raise ArgumentError unless operator.is_a?(Hash) && operator['type'] == "Schema"
       super
     end
@@ -36,19 +36,22 @@ module ShEx::Algebra
     ##
     # Match on schema. Finds appropriate shape for node, and matches that shape.
     #
-    # @param [RDF::Term] focus
     # @param [RDF::Queryable] graph
-    # @param [Hash{RDF::Resource => RDF::Resource}] map
+    # @param [Hash{RDF::Term => <RDF::Resource>}, Array<Array(RDF::Term, RDF::Resource)>] map
+    #   A set of (`term`, `resource`) pairs where `term` is a node within `graph`, and `resource` identifies a shape
+    # @param [Array<RDF::Term>] focus ([])
+    # 	One or more nodes within `graph` for which to run the start expression.
     # @param [Array<Schema, String>] shapeExterns ([])
     #   One or more schemas, or paths to ShEx schema resources used for finding external shapes.
-    # @return [Operand] Returns operand graph annotated with satisfied and unsatisfied operations.
+    # @return [Hash{RDF::Term => Array<ShapeResult>}] Returns _ShapeResults_, a hash of graph nodes to the results of their associated shapes
     # @param [Hash{Symbol => Object}] options
     # @option options [String] :base_uri (for resolving focus)
-    # @raise [ShEx::NotSatisfied] along with operand graph described for return
-    def execute(focus, graph, map, shapeExterns: [], depth: 0, **options)
-      @graph, @shapes_entered = graph, {}
+    # @raise [ShEx::NotSatisfied] along with individual shape results
+    def execute(graph, map, focus: [], shapeExterns: [], depth: 0, **options)
+      @graph, @shapes_entered, results = graph, {}, {}
       @external_schemas = shapeExterns
-      focus = value(focus, options)
+      @extensions = {}
+      focus = Array(focus).map {|f| value(f, **options)}
 
       logger = options[:logger] || @options[:logger]
       each_descendant do |op|
@@ -57,7 +60,6 @@ module ShEx::Algebra
       end
 
       # Initialize Extensions
-      @extensions = {}
       each_descendant do |op|
         next unless op.is_a?(SemAct)
         name = op.operands.first.to_s
@@ -67,36 +69,74 @@ module ShEx::Algebra
       end
 
       # If `n` is a Blank Node, we won't find it through normal matching, find an equivalent node in the graph having the same id
-      graph_focus = graph.enum_term.detect {|t| t.node? && t.id == focus.id} if focus.is_a?(RDF::Node)
-      graph_focus ||= focus
-
-      # Make sure they're URIs
-      @map = (map || {}).inject({}) {|memo, (k,v)| memo.merge(value(k) => iri(v))}
+      @map = case map
+      when Hash
+        map.inject({}) do |memo, (node, shapes)|
+          gnode = graph.enum_term.detect {|t| t.node? && t.id == node.id} if node.is_a?(RDF::Node)
+          node = gnode if gnode
+          memo.merge(node => Array(shapes))
+        end
+      when Array
+        map.inject({}) do |memo, (node, shape)|
+          gnode = graph.enum_term.detect {|t| t.node? && t.id == node.id} if node.is_a?(RDF::Node)
+          node = gnode if gnode
+          (memo[node] ||= []).concat(Array(shape))
+          memo
+        end
+      when nil then {}
+      else
+        structure_error "Unrecognized shape map: #{map.inspect}"
+      end
 
       # First, evaluate semantic acts
       semantic_actions.all? do |op|
         op.satisfies?([], depth: depth + 1)
       end
 
-      # Keep a new Schema, specifically for recording actions
-      satisfied_schema = Schema.new
       # Next run any start expression
-      if start
-        satisfied_schema.operands << start.satisfies?(focus, depth: depth + 1)
+      if !focus.empty?
+        if start
+          focus.each do |node|
+            node = graph.enum_term.detect {|t| t.node? && t.id == node.id} if node.is_a?(RDF::Node)
+            sr = ShapeResult.new(RDF::URI("http://www.w3.org/ns/shex#Start"))
+            (results[node] ||= []) << sr
+            begin
+              sr.expression = start.satisfies?(node, depth: depth + 1)
+              sr.result = true
+            rescue ShEx::NotSatisfied => e
+              sr.expression = e.expression
+              sr.result = false
+            end
+          end
+        else
+          structure_error "Focus nodes with no start"
+        end
       end
 
-      # Add shape result(s)
-      satisfied_shapes = {}
-      satisfied_schema.operands << [:shapes, satisfied_shapes] unless shapes.empty?
-
       # Match against all shapes associated with the ids for focus
-      Array(@map[focus]).each do |id|
-        enter_shape(id, focus) do |shape|
-          satisfied_shapes[id] = shape.satisfies?(graph_focus, depth: depth + 1)
+      @map.each do |node, shapes|
+        results[node] ||= []
+        shapes.each do |id|
+          enter_shape(id, node) do |shape|
+            sr = ShapeResult.new(id)
+            results[node] << sr
+            begin
+              sr.expression = shape.satisfies?(node, depth: depth + 1)
+              sr.result = true
+            rescue ShEx::NotSatisfied => e
+              sr.expression = e.expression
+              sr.result = false
+            end
+          end
         end
       end
-      status "schema satisfied", depth: depth
-      satisfied_schema
+
+      if results.values.flatten.all? {|sr| sr.result}
+        status "schema satisfied", depth: depth
+        results
+      else
+        raise ShEx::NotSatisfied.new("Graph does not conform to schema", expression: results)
+      end
     ensure
       # Close Semantic Action extensions
       @extensions.values.each {|ext| ext.close(schema: self, depth: depth, **options)}
@@ -105,16 +145,12 @@ module ShEx::Algebra
     ##
     # Match on schema. Finds appropriate shape for node, and matches that shape.
     #
-    # @param [RDF::Resource] focus
-    # @param [RDF::Queryable] graph
-    # @param [Hash{RDF::Resource => RDF::Resource}] map
-    # @param [Array<Schema, String>] shapeExterns ([])
-    #   One or more schemas, or paths to ShEx schema resources used for finding external shapes.
+    # @param (see ShEx::Algebra::Schema#execute)
     # @param [Hash{Symbol => Object}] options
     # @option options [String] :base_uri
     # @return [Boolean]
-    def satisfies?(focus, graph, map, shapeExterns: [], **options)
-      execute(focus, graph, map, options.merge(shapeExterns: shapeExterns))
+    def satisfies?(graph, map, **options)
+      execute(graph, map, **options)
     rescue ShEx::NotSatisfied
       false
     end
@@ -198,4 +234,41 @@ module ShEx::Algebra
       super
     end
   end
+
+  # A shape result
+  class ShapeResult
+    # The label of the shape within the schema, or a URI indicating a start shape
+    # @return [RDF::Resource]
+    attr_reader :shape
+
+    # Does the node conform to the shape
+    # @return [Boolean]
+    attr_accessor :result
+
+    # The annotated {Operator} indicating processing results
+    # @return [ShEx::Algebra::Operator]
+    attr_accessor :expression
+
+    # Holds the result of processing a shape
+    # @param [RDF::Resource] shape
+    # @return [ShapeResult]
+    def initialize(shape)
+      @shape = shape
+    end
+
+    # The SXP of {#expression}
+    # @return [String]
+    def reason
+      SXP::Generator.string(expression.to_sxp_bin)
+    end
+
+    ##
+    # Returns the binary S-Expression (SXP) representation of this result.
+    #
+    # @return [Array]
+    # @see    https://en.wikipedia.org/wiki/S-expression
+    def to_sxp_bin
+      [:ShapeResult, shape, result, expression].map(&:to_sxp_bin)
+    end
+  end
 end