Add graph:make-from-deps convenience function

* src/graph.xsl (graph:make-from-deps): Added with documentation.
* test/graph{-test.xsl,.xspec}: Updated accordingly.

src/graph.xsl

@@ -245,4 +245,38 @@
                           ()" />
 </function>
 
+<!--
+  @ref{graph:dep-lookup} can be used together with the convenience
+    function @ref{graph:make-from-deps} to produce a graph that
+    contains all dependencies for a given symbol list.
+  Used together with @ref{graph:reverse},
+    a reverse dependency graph can be easily created that provides a
+    useful ``used by'' relationship.
+-->
+
+<!--
+  Create a dependency graph containing all dependencies of the given
+    symbol list @var{$symbols}.
+  The graph contains the union of the minimal subset of all package
+    subgraphs@mdash{}only vertices representing a symbol in
+    @var{$symbols} or its direct dependencies are included.
+
+  This function is @emph{not} recursive;
+    it assumes that the given symbol list @var{$symbols} is sufficient
+    for whatever operation is being performed.
+
+  The lookup function @var{$lookup} is invoked once per symbol in
+    @var{$symbols} with the @code{preproc:sym} to look up.
+  The final result is used to produce a new normalized graph,
+    with any duplicate vertices and edges removed.
+-->
+<function name="graph:make-from-deps" as="element( preproc:sym-deps )*">
+  <param name="lookup"  as="item()+" />
+  <param name="symbols" as="element( preproc:sym )*" />
+
+  <sequence select="graph:make-from-vertices(
+                      for $symbol in $symbols
+                        return f:apply( $lookup, $symbol ) )" />
+</function>
+
 </stylesheet>

test/graph-test.xsl

@@ -194,6 +194,18 @@
 </variable>
 
 
+<variable name="foo:expected-lookup" as="element()">
+  <preproc:sym-ref name="foo" lookup="ok" />
+</variable>
+
+
+<variable name="foo:sym-list" as="element()+">
+  <preproc:sym name="foo" />
+  <preproc:sym name="bar" />
+  <preproc:sym name="baz" />
+</variable>
+
+
 <function name="foo:lookup">
   <param name="yield"  as="element()" />
   <param name="symbol" as="element( preproc:sym )" />
@@ -206,4 +218,14 @@
   </preproc:sym-deps>
 </function>
 
+
+<function name="foo:lookup-sym">
+  <param name="yield"  as="element()" />
+  <param name="symbol" as="element( preproc:sym )" />
+
+  <preproc:sym-dep name="{$symbol/@name}">
+    <sequence select="$yield" />
+  </preproc:sym-dep>
+</function>
+
 </stylesheet>

test/graph.xspec

@@ -174,7 +174,7 @@
     </scenario>
 
 
-    <scenario label="given single graph with duplicate vectors">
+    <scenario label="given single graph with duplicate vertices">
       <call function="graph:union">
         <param name="graphs"
                select="$foo:graph-with-dupes" />
@@ -248,10 +248,6 @@
 
 
       <scenario label="in a separate package">
-        <variable name="foo:expected-lookup" as="element()">
-          <foo:lookup-ok />
-        </variable>
-
         <scenario label="where dependencies exist">
           <call function="graph:dep-lookup">
             <param name="lookup"
@@ -266,9 +262,28 @@
           </call>
 
           <expect label="returns external dependenices"
-                  test="exists( $x:result/foo:lookup-ok )" />
+                  test="deep-equal( $x:result/*, $foo:expected-lookup )" />
         </scenario>
       </scenario>
     </scenario>
   </scenario>
+
+
+  <scenario label="graph:make-from-deps">
+    <call function="graph:make-from-deps">
+      <param name="lookup"
+             select="foo:lookup-sym( $foo:expected-lookup )" />
+
+      <param name="symbols"
+             select="$foo:sym-list" />
+    </call>
+
+    <expect label="produces a graph"
+            test="$x:result instance of element( preproc:sym-deps )" />
+
+    <expect label="looks up each symbol"
+            test="every $vertex in $x:result/preproc:sym-dep
+                    satisfies
+                      deep-equal( $vertex/*, $foo:expected-lookup )" />
+  </scenario>
 </description>