Add graph:lookup-from-doc

* src/graph.xsl (graph:lookup-from-doc): Added
* test/graph-doc.xml: Added
* test/graph-test.xsl: Associated test data
* test/graph.xspec: Associated tests added

src/graph.xsl

@@ -28,6 +28,7 @@
             xmlns:preproc="http://www.lovullo.com/rater/preproc">
 
 <import href="../hoxsl/src/apply.xsl" />
+<import href="graph.xsl.apply" />
 
 
 <!--
@@ -279,4 +280,60 @@
                         return f:apply( $lookup, $symbol ) )" />
 </function>
 
+
+<!--
+@menu
+* Graph Lookups:: Graph constructors using symbol lookups
+@end menu
+-->
+
+<!--
+  @node Graph Lookups
+  @subsubsection Graph Lookups
+-->
+
+<!--
+  The provided graph lookups are constructors that use symbols to
+  locate a graph.  Using partial application, they are convenient for
+  use in @ref{graph:dep-lookup} to resolve external graphs.
+-->
+
+<!--
+  Look up a graph on a document indicated by a source symbol
+    @var{$symbol/@@src}.
+  The document will be loaded relative to @var{$rel-node} with the
+    file extension @var{$package-ext}.
+
+  There are no restrictions on the root node of the document,
+    but the @code{preproc:sym-deps} node is expected to be a child of
+    the root.
+
+  This function does not care if @var{$symbol} actually resolves to
+    anything in the destination package@mdash{
+      }such is up to the caller to decide.
+  If the referenced document contains no graph
+    (@code{preproc:sym-deps}), the empty sequence will be returned.
+  If the referenced document does not exist,
+    the result is implementation-defined.
+
+  Customarily, @var{$doc-ext} is ``xmlo'' (the compiled object file)
+    and @var{$rel-node} is the package from which @var{$symbol} was
+    obtained.
+-->
+<function name="graph:lookup-from-doc" as="element( preproc:sym-deps )?">
+  <param name="doc-ext"  as="xs:string" />
+  <param name="rel-node" as="node()" />
+  <param name="symbol"   as="element( preproc:sym )" />
+
+  <variable name="src" as="xs:string?"
+            select="$symbol/@src" />
+
+  <sequence select="if ( $src ) then
+                        document( concat( $src, '.', $doc-ext ),
+                                  $rel-node )
+                          /node()/preproc:sym-deps
+                      else
+                        ()" />
+</function>
+
 </stylesheet>

test/graph-doc.xml

@@ -0,0 +1,10 @@
+<!--
+  Stub document for graph test
+-->
+<root xmlns:preproc="https://www.lovullo.com/rater/preproc">
+  <preproc:sym-deps>
+    <preproc:sym-dep name="foo">
+      <preproc:sym-ref name="bar" />
+    </preproc:sym-dep>
+  </preproc:sym-deps>
+</root>

test/graph-test.xsl

@@ -29,7 +29,6 @@
 
 <!-- SUT -->
 <import href="../src/graph.xsl" />
-
 <import href="graph-test.xsl.apply" />
 
 
@@ -48,6 +47,13 @@
                    src="not-here" />
 
       <preproc:sym name="missing-deps" />
+
+      <preproc:sym name="doc-sym"
+                   src="graph-doc" />
+
+      <!-- should _not_ be defined in source document -->
+      <preproc:sym name="doc-sym-unknown"
+                   src="graph-doc" />
     </preproc:symtable>
 
     <preproc:sym-deps>

test/graph.xspec

@@ -286,4 +286,67 @@
                     satisfies
                       deep-equal( $vertex/*, $foo:expected-lookup )" />
   </scenario>
+
+
+  <scenario label="graph:lookup-from-doc">
+    <variable name="expected-doc" as="document-node()"
+              select="document( 'graph-doc.xml', root() )" />
+
+    <scenario label="given a known external symbol">
+      <call function="graph:lookup-from-doc">
+        <param name="doc-ext"
+               select="'xml'" />
+
+        <param name="rel-node"
+               select="root()" />
+
+        <param name="symbol"
+               select="$foo:document/preproc:symtable
+                         /preproc:sym[ @name = 'doc-sym' ]" />
+      </call>
+
+      <expect label="looks up subgraph from document"
+              test="deep-equal( $x:result,
+                                $expected-doc/*/preproc:sym-deps )" />
+    </scenario>
+
+
+    <!-- since we're looking up the graph, we don't really care if the symbol
+         exissts in it or not (that is a caller concern) -->
+    <scenario label="given an unknown external symbol">
+      <call function="graph:lookup-from-doc">
+        <param name="doc-ext"
+               select="'xml'" />
+
+        <param name="rel-node"
+               select="root()" />
+
+        <param name="symbol"
+               select="$foo:document/preproc:symtable
+                         /preproc:sym[ @name = 'doc-sym-unknown' ]" />
+      </call>
+
+      <expect label="looks up subgraph from document"
+              test="deep-equal( $x:result,
+                                $expected-doc/*/preproc:sym-deps )" />
+    </scenario>
+
+
+    <scenario label="given a symbol with no @src">
+      <call function="graph:lookup-from-doc">
+        <param name="doc-ext"
+               select="'xml'" />
+
+        <param name="rel-node"
+               select="root()" />
+
+        <param name="symbol"
+               select="$foo:document/preproc:symtable
+                         /preproc:sym[ @name = 'local' ]" />
+      </call>
+
+      <expect label="produces empty sequence"
+              test="empty( $x:result )" />
+    </scenario>
+  </scenario>
 </description>