340 lines
11 KiB
XML
340 lines
11 KiB
XML
<?xml version="1.0"?>
|
||
<!--
|
||
Dependency graph
|
||
|
||
Copyright (C) 2014-2023 Ryan Specialty, LLC.
|
||
|
||
This file is part of TAME.
|
||
|
||
TAME is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with this program. If not, see
|
||
<http://www.gnu.org/licenses/>.
|
||
-->
|
||
<stylesheet version="2.0"
|
||
xmlns="http://www.w3.org/1999/XSL/Transform"
|
||
xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
||
xmlns:f="http://mikegerwitz.com/hoxsl/apply"
|
||
xmlns:graph="http://www.lovullo.com/tame/graph"
|
||
xmlns:preproc="http://www.lovullo.com/rater/preproc">
|
||
|
||
<import href="../hoxsl/src/apply.xsl" />
|
||
<import href="graph.xsl.apply" />
|
||
|
||
|
||
<!--
|
||
@node Dependency Graph
|
||
@appendix Dependency Graph
|
||
|
||
The dependency graph is a directed graph consisting of
|
||
every known symbol,
|
||
post-expansion (@pxref{Macro Expansion}).
|
||
Cycles are produced only by function recursion and otherwise cause an
|
||
error, so the graph is studied as a DAG (directed acyclic graph)
|
||
with few exceptions.
|
||
|
||
Vertices in the dependency graph are represented by
|
||
@code{preproc:sym-dep} nodes,
|
||
and edges by child @code{preproc:sym-ref} nodes.
|
||
Graphs are represented by @code{preproc:sym-deps}.
|
||
The graph of each package is considered to be a subgraph of the
|
||
entire dependency graph for a particular system.@c
|
||
@footnote{The node names are for compatibility with legacy systems
|
||
and may change in the future; always use the graph API, and only
|
||
use the node QNames for type checks.}
|
||
-->
|
||
|
||
|
||
<!--
|
||
Create a graph from the given vertex set @var{$vertices}.
|
||
The resulting graph will be normalized with duplicate vertices and
|
||
edges removed,
|
||
making it suitable for ad hoc graph generation.@c
|
||
@footnote{This is done by calling @ttref{graph:union#1}.}
|
||
-->
|
||
<function name="graph:make-from-vertices"
|
||
as="element( preproc:sym-deps )">
|
||
<param name="vertices" as="element( preproc:sym-dep )*" />
|
||
|
||
<variable name="graph" as="element( preproc:sym-deps )">
|
||
<preproc:sym-deps>
|
||
<sequence select="$vertices" />
|
||
</preproc:sym-deps>
|
||
</variable>
|
||
|
||
<!-- dedupe/normalize -->
|
||
<sequence select="graph:union( $graph )" />
|
||
</function>
|
||
|
||
|
||
<!--
|
||
Produce a new graph that is the transpose of
|
||
@var{$graph}@mdash{}that is,
|
||
the graph @var{$graph} with the direction of all of its edges
|
||
reversed.
|
||
|
||
This is useful for processing what symbols are @emph{used by} other
|
||
symbols.
|
||
|
||
For example:
|
||
|
||
@float Figure, fig:reverse-graph
|
||
@verbatim
|
||
G: A->B->C->E
|
||
\
|
||
`->D
|
||
|
||
G': A<-B<-C<-E
|
||
^
|
||
`D
|
||
@end verbatim
|
||
@caption{G' is the transpose of G}
|
||
@end float
|
||
|
||
Edge attributes (@code{preproc:sym-ref/@@*)} will be set to the
|
||
union of all attributes on all edges of the same @code{@@name} in
|
||
@code{$graph}.
|
||
@emph{If edge attributes do not share the same value,
|
||
the behavior is undefined.}
|
||
-->
|
||
<function name="graph:reverse" as="element( preproc:sym-deps )">
|
||
<param name="graph" as="element( preproc:sym-deps )" />
|
||
|
||
<variable name="reversed" as="element( preproc:sym-dep )*">
|
||
<for-each-group select="$graph//preproc:sym-ref"
|
||
group-by="@name">
|
||
<preproc:sym-dep name="{@name}">
|
||
<for-each select="current-group()/ancestor::preproc:sym-dep">
|
||
<preproc:sym-ref>
|
||
<sequence select="current-group()/@*" />
|
||
|
||
<!-- keep our name (overrides the above) -->
|
||
<attribute name="name" select="@name" />
|
||
</preproc:sym-ref>
|
||
</for-each>
|
||
</preproc:sym-dep>
|
||
</for-each-group>
|
||
</variable>
|
||
|
||
<preproc:sym-deps>
|
||
<!-- vertices in $graph with no dependencies will not be in
|
||
$reversed -->
|
||
<for-each select="$graph/preproc:sym-dep[ not(
|
||
@name = $reversed/preproc:sym-ref/@name ) ]">
|
||
<preproc:sym-dep name="{@name}" />
|
||
</for-each>
|
||
|
||
<sequence select="$reversed" />
|
||
</preproc:sym-deps>
|
||
</function>
|
||
|
||
|
||
<!--
|
||
Merge sequence of graphs @var{$graphs} into a single graph by taking
|
||
the union of all vertices and edges.
|
||
Directionality will be preserved.
|
||
|
||
Edge attributes (@code{preproc:sym-ref/@@*)} will be set to the
|
||
union of all attributes on all edges of the same @code{@@name}.
|
||
@emph{If edge attributes do not share the same value,
|
||
the behavior is undefined.}
|
||
|
||
For example:
|
||
|
||
@float Figure, fig:union-graph
|
||
@verbatim
|
||
G₁: A->B->C
|
||
G₂: C->A
|
||
G₃: B->C->D
|
||
|
||
G∪: A->B->C->D
|
||
^____/
|
||
@end verbatim
|
||
@caption{(G₁ ∪ G₂ ∪ G₃)}
|
||
@end float
|
||
|
||
This function also removes duplicate vertices and edges,
|
||
so it can be used with a single (or multiple) graphs to normalize
|
||
and tidy things up.
|
||
Any unknown XML nodes are removed.
|
||
-->
|
||
<function name="graph:union" as="element( preproc:sym-deps )*">
|
||
<param name="graphs" as="element( preproc:sym-deps )*" />
|
||
|
||
<preproc:sym-deps>
|
||
<for-each-group select="$graphs/preproc:sym-dep"
|
||
group-by="@name">
|
||
<preproc:sym-dep name="{@name}">
|
||
<for-each-group select="current-group()/preproc:sym-ref"
|
||
group-by="@name">
|
||
<preproc:sym-ref>
|
||
<sequence select="current-group()/@*" />
|
||
|
||
<!-- keep our name (overrides the above) -->
|
||
<attribute name="name" select="@name" />
|
||
</preproc:sym-ref>
|
||
</for-each-group>
|
||
</preproc:sym-dep>
|
||
</for-each-group>
|
||
</preproc:sym-deps>
|
||
</function>
|
||
|
||
|
||
<!--
|
||
@menu
|
||
* Package Subgraphs:: Managing package dependencies
|
||
@end menu
|
||
-->
|
||
|
||
<!--
|
||
@node Package Subgraphs
|
||
@section Package Subgraphs
|
||
|
||
Each package has its own independent dependency graph.
|
||
These vertices may have @dfn{virtual edges} to other packages'
|
||
graphs@mdash{}edges that will be formed once combined the
|
||
referenced graph;
|
||
these edges are indicated with @code{preproc:sym-ref/@@src}.
|
||
|
||
Graph operations are usually performed on single packages,
|
||
but it is occionally necessary to traverse packages to recurisvely
|
||
resolve dependencies.
|
||
@ttref{graph:dep-lookup#3} makes this easy:
|
||
|
||
TODO: Generic graph functions.
|
||
-->
|
||
|
||
<!--
|
||
Retrieve dependenices for @var{$symbol} on the @var{$graph},
|
||
using the lookup function @var{$lookup} to resolve external
|
||
subgraphs.
|
||
@var{$lookup} will be used only if the symbol cannot be found in
|
||
@var{$graph},
|
||
in which case the result of @var{$lookup} will used used in a
|
||
recursive call as the new @var{$graph}.
|
||
|
||
From a graph perspective,
|
||
the dependencies are edges on the @var{$symbol} vertex.
|
||
|
||
Parameters are organized for partial application.
|
||
-->
|
||
<function name="graph:dep-lookup" as="element( preproc:sym-dep )?">
|
||
<param name="lookup" />
|
||
<param name="graph" as="element( preproc:sym-deps )" />
|
||
<param name="symbol" as="element( preproc:sym )" />
|
||
|
||
<variable name="deps" as="element( preproc:sym-dep )?"
|
||
select="$graph/preproc:sym-dep
|
||
[ @name = $symbol/@name ]" />
|
||
|
||
<sequence select="if ( exists( $deps ) ) then
|
||
$deps
|
||
else if ( $lookup ) then
|
||
graph:dep-lookup( $lookup,
|
||
f:apply( $lookup, $symbol ),
|
||
$symbol )
|
||
else
|
||
()" />
|
||
</function>
|
||
|
||
<!--
|
||
@ttref{graph:dep-lookup#3} can be used together with the convenience
|
||
function @ttref{graph:make-from-deps#2} to produce a graph that
|
||
contains all dependencies for a given symbol list.
|
||
Used together with @ttref{graph:reverse#1},
|
||
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>
|
||
|
||
|
||
<!--
|
||
@menu
|
||
* Graph Lookups:: Graph constructors using symbol lookups
|
||
@end menu
|
||
-->
|
||
|
||
<!--
|
||
@node Graph Lookups
|
||
@subsection Graph Lookups
|
||
-->
|
||
|
||
<!--
|
||
The provided graph lookups are constructors that use symbols to
|
||
locate a graph. Using partial application, they are convenient for
|
||
use in @ttref{graph:dep-lookup#3} 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>
|