#314: Made focusNode an explicit param of exprEval, SPARQL-based expressions now pre-bind all scope vars (#370)

Closes #314

* #314: Made focusNode an explicit param of exprEval, SPARQL-based expressions now pre-bind all scope vars

* #314: Fixes

* #314: Clarified role of active graph

* #314: active graph -> focus graph

* Apply suggestions from code review

Co-authored-by: Ted Thibodeau Jr <[email protected]>

* Updated sh:expression to [ true ] list instead of "or" semantics

---------

Co-authored-by: Ted Thibodeau Jr <[email protected]>

Author: HolgerKnublauch

shacl12-core/index.html

@@ -1359,7 +1359,7 @@ <h4>Node targets (sh:targetNode)</h4>
 							If <code>s</code> is a <a>shape</a> in a <a>shapes graph</a> <code>SG</code> and <code>s</code> has
 							<a>value</a> <code>expr</code> for <code>sh:targetNode</code> in <code>SG</code>,
 							then the <a>output nodes</a> of <code>expr</code> are <a>targets</a>
-							for the data graph <code>DG</code> as <a>active graph</a>.
+							for the data graph <code>DG</code> as <a>focus graph</a>.
 						</div>
 						<p><em>The remainder of this section is informative.</em></p>
 						<p>
@@ -2406,14 +2406,15 @@ <h2>Node Expressions</h2>
 			</div>
 			<div class="def" id="node-expression-evaluation">
 				<div class="def-header">EVALUATION OF NODE EXPRESSIONS</div>
-				The <dfn>evaluation</dfn> of a node expression is defined as a function <code>evalExpr(expr, activeGraph, scope) -> outputNodes</code>
+				The <dfn>evaluation</dfn> of a node expression is defined as a function <code>evalExpr(expr, focusGraph, focusNode, scope) -> outputNodes</code>
 				where
 				<ul>
 					<li><code>expr</code> is a <a>node expression</a> in a <a>shapes graph</a>.
 					During evaluation, the engine can access <a>triples</a> related to <code>expr</code> in the <a>shapes graph</a>.</li>
-					<li><code>activeGraph</code> is a <a>graph</a>, called the <dfn>active graph</dfn>.</li>
+					<li><code>focusGraph</code> is a <a>graph</a>, called the <dfn>focus graph</dfn>. This is the default query graph for the evaluation of the node expression.</li>
+					<li><code>focusNode</code> is a <a>node</a>, called the <dfn>input focus node</dfn>. This variable may have no value.</li>
 					<li><code>scope</code> is a map from <a href="https://www.w3.org/TR/sparql12-query/#defn_QueryVariable">variable names</a> to individual <a>nodes</a>.
-						The value of the variable <code>focusNode</code> (if it exists) is called the <dfn>input focus node</dfn>.
+					The empty map is written as <code>{}</code>.
 					</li>
 				</ul>
 				The result of the evaluation of a node expression is a list of <a>nodes</a> (possibly empty and with duplicates) called the <dfn>output nodes</dfn>.
@@ -2440,7 +2441,7 @@ <h3>IRI Expressions</h3>
 						The <a>output nodes</a> of an <a>IRI expression</a> are the list consisting of exactly the <a>node expression</a> itself:
 						<br/>
 						<br/>
-						<code>evalExpr(expr, activeGraph, scope) -> [expr]</code>
+						<code>evalExpr(expr, focusGraph, focusNode, scope) -> [expr]</code>
 					</p>
 				</div>
 			</section>
@@ -2459,7 +2460,7 @@ <h3>Literal Expressions</h3>
 						The <a>output nodes</a> of a <a>literal expression</a> are the list consisting of exactly the <a>node expression</a> itself:
 						<br/>
 						<br/>
-						<code>evalExpr(expr, activeGraph, scope) -> [expr]</code>
+						<code>evalExpr(expr, focusGraph, focusNode, scope) -> [expr]</code>
 					</p>
 				</div>
 			</section>
@@ -2919,13 +2920,11 @@ <h4>Value Nodes of Property Shapes</h4>
 						</li>
 						<li>
 							If <code>e</code> is the <a>value</a> of <code>sh:values</code> at the <a>property shape</a>,
-							then add the <a>output nodes</a> of <code>evalExpr(e, <a>data graph</a>, scope)</code> where <code>scope</code>
-							contains the <a>focus node</a> as the value of the variable <code>focusNode</code>.
+							then add the <a>output nodes</a> of <code>evalExpr(e, <a>data graph</a>, <a>focus node</a>, {})</code>.
 						</li>
 						<li>
 							If the set is still empty and <code>d</code> is the <a>value</a> of <code>sh:defaultValue</code> at the <a>property shape</a>,
-							then add the <a>output nodes</a> of <code>evalExpr(d, <a>data graph</a>, scope)</code> where <code>scope</code>
-							contains the <a>focus node</a> as the value of the variable <code>focusNode</code>.
+							then add the <a>output nodes</a> of <code>evalExpr(d, <a>data graph</a>, <a>focus node</a>, {})</code>.
 						</li>
 					</ol>
 				</section>
@@ -6003,7 +6002,7 @@ <h4>sh:expression</h4>
 						Based on <a>node expressions</a>, this section introduces a <a>constraint component</a> called
 						<dfn data-lt="expression constraint">expression constraints</dfn>.
 						Expression constraints can be used in any <a>shape</a> to declare the condition that the
-						<a>node expression</a> specified via <code>sh:expression</code> has <code>true</code> as one of its output nodes.
+						<a>node expression</a> specified via <code>sh:expression</code> has <code>true</code> as its only output node.
 						The evaluation of these node expressions is repeated for all <a>value nodes</a> of the <a>shape</a>
 						as the <a>focus node</a>.
 					</p>
@@ -6031,9 +6030,8 @@ <h4>sh:expression</h4>
 						<div class="def-text-body" data-validator="Expression">
 							Let <code>expr</code> be the <a>value</a> of <code>sh:expression</code>.
 							For each <a>value node</a> <code>v</code> 
-							and <code>scope</code> contains <code>v</code> as the value of <code>focusNode</code>
-							where <code>evalExpr(expr, activeGraph, scope)</code>
-							does not return <code>true</code> as one of its <a>output nodes</a>,
+							where <code>evalExpr(expr, <a>data graph</a>>, v, {})</code>
+							does not return the list consisting of exactly <code>true</code> as its <a>output nodes</a>,
 							there is a <a>validation result</a> that has <code>v</code> as its <code>sh:value</code>
 							and a <a>deep copy</a> of <code>expr</code> in the results graph as its <code>sh:sourceConstraint</code>.
 							If the <code>expr</code> has <a>values</a> for <code>sh:message</code> in the <a>shapes graph</a>,

shacl12-sparql/index.html

@@ -408,6 +408,7 @@ <h3>Terminology</h3>
 						<dfn data-cite="shacl12-core#dfn-function-name" data-lt="node expression function name">function name</dfn>,
 						<dfn data-cite="shacl12-core#dfn-key-parameter" data-lt="key parameter">key parameter</dfn>,
 						<dfn data-cite="shacl12-core#dfn-output-nodes" data-lt="output nodes">output nodes</dfn>,
+						<dfn data-cite="shacl12-core#dfn-focus-graph" data-lt="focus graph">focus graph</dfn>,
 						<dfn data-cite="shacl12-core#dfn-conform" data-lt="conform|conforms">conform</dfn>,
 						<dfn data-cite="shacl12-core#dfn-failure" data-lt="failure|failures">failure</dfn>,
 						<dfn data-cite="shacl12-core#dfn-shacl-instance" data-lt="shacl instance">SHACL instance</dfn>,
@@ -1229,11 +1230,13 @@ <h3>Select Expressions</h3>
 					<div class="def-header">EVALUATION OF SELECT EXPRESSIONS</div>
 					<p>
 						The <a>output nodes</a> of a <a>select expression</a> are the list <code>resultNodes</code> consisting of exactly the bindings of the (only)
-						variable that is projected from the SELECT clause.
-						If present in the <a>scope</a>, the value of the scope variable <code>focusNode</code> MUST be <a>pre-bound</a> as the value of the SPARQL variable <code>this</code>.
+						variable that is projected from the <code>SELECT</code> clause when the query is evaluated against the <a>focus graph</a>.
+						The value of <code>focusNode</code> is <a>pre-bound</a> as the value of the SPARQL variable <code>this</code>.
+						The value of each scope variable is <a>pre-bound</a> as a SPARQL variable with the same name and value.
+						A <a>failure</a> is produced when one of the scope variables is called <code>this</code>.
 						<br/>
 						<br/>
-						<code>evalExpr(expr, activeGraph, scope) -> resultNodes</code>
+						<code>evalExpr(expr, focusGraph, focusNode, scope) -> resultNodes</code>
 					</p>
 				</div>
 				<p><em>The remainder of this section is informative.</em></p>
@@ -1340,11 +1343,14 @@ <h3>SPARQL Expr Expressions</h3>
 					<div class="def-header">EVALUATION OF SPARQL EXPR EXPRESSIONS</div>
 					<p>
 						The <a>output nodes</a> of an <a>SPARQL expr expression</a> are the list <code>resultNodes</code> consisting of exactly the bindings of the (only)
-						variable that is projected from the SELECT clause of the <code>select</code> query as defined <a href="#syntax-rule-SPARQLExprExpression-template">above</a>.
-						If present in the <a>scope</a>, the value of the scope variable <code>focusNode</code> MUST be <a>pre-bound</a> as the value of the SPARQL variable <code>this</code>.
+						variable that is projected from the <code>SELECT</code> clause of the <code>select</code> query as defined <a href="#syntax-rule-SPARQLExprExpression-template">above</a>
+						when the query is evaluated against the <a>focus graph</a>.
+						The value of <code>focusNode</code> is <a>pre-bound</a> as the value of the SPARQL variable <code>this</code>.
+						The value of each scope variable is <a>pre-bound</a> as a SPARQL variable with the same name and value.
+						A <a>failure</a> is produced when one of the scope variables is called <code>this</code>.
 						<br/>
 						<br/>
-						<code>evalExpr(expr, activeGraph, scope) -> resultNodes</code>
+						<code>evalExpr(expr, focusGraph, focusNode, scope) -> resultNodes</code>
 					</p>
 				</div>
 				<p><em>The remainder of this section is informative.</em></p>