add DotHighlightedDigraph method

doc/display.xml

@@ -244,3 +244,31 @@ gap> FileString("dot/preset.dot", DotProrderDigraph(gr));
     </Description>
   </ManSection>
 <#/GAPDoc>
+
+<#GAPDoc Label="DotHighlightedDigraph">
+  <ManSection>
+    <Oper Name="DotHighlightedDigraph" Arg="digraph, verts [, colour1, colour2]"/>
+    <Returns>A string.</Returns>
+    <Description>
+      <C>DotHighlightedDigraph</C> produces a graphical represenation of the
+      digraph <A>digraph</A>, where the vertices in the list <A>verts</A>, and
+      edges between them, are drawn with colour <A>colour1</A> and all other
+      vertices and edges in <A>digraph</A> are drawn with colour <A>colour2</A>.
+      If <A>colour1</A> and <A>colour2</A> are not given then
+      <C>DotHighlightedDigraph</C> uses black and grey respectively. <P/>
+
+      Note that <C>DotHighlightedDigraph</C> does not validate the colours
+      <A>colour1</A> and <A>colour2</A> - consult the GraphViz documentation to
+      see what is available.
+
+      See <Ref Attr="DotDigraph"/> for more details on the output.<P/>
+
+      <Log><![CDATA[
+gap> digraph := Digraph([[2, 3], [2], [1, 3]]);
+<digraph with 3 vertices, 5 edges>
+gap> FileString("dot/my_digraph.dot",
+> DotHighlightedDigraph(digraph, [1, 2], "red", "black"));
+264]]></Log>
+    </Description>
+  </ManSection>
+<#/GAPDoc>

doc/z-chap9.xml

@@ -6,6 +6,7 @@
     <#Include Label="DotSymmetricDigraph">
     <#Include Label="DotPartialOrderDigraph">
     <#Include Label="DotPreorderDigraph">
+    <#Include Label="DotHighlightedDigraph">
   </Section>
 
   <Section><Heading>Reading and writing graphs to a file</Heading>

gap/display.gd

@@ -14,3 +14,6 @@ DeclareAttribute("DotSymmetricDigraph", IsDigraph);
 DeclareAttribute("DotPartialOrderDigraph", IsDigraph);
 DeclareAttribute("DotPreorderDigraph", IsDigraph);
 DeclareSynonym("DotQuasiorderDigraph", DotPreorderDigraph);
+DeclareOperation("DotHighlightedDigraph", [IsDigraph, IsList]);
+DeclareOperation("DotHighlightedDigraph",
+                 [IsDigraph, IsList, IsString, IsString]);

gap/display.gi

@@ -271,3 +271,87 @@ function(digraph)
   Append(str, "}");
   return str;
 end);
+
+InstallMethod(DotHighlightedDigraph, "for a digraph and list",
+[IsDigraph, IsList],
+function(digraph, list)
+  return DotHighlightedDigraph(digraph, list, "black", "grey");
+end);
+
+InstallMethod(DotHighlightedDigraph, "for a digraph, list, and two strings",
+[IsDigraph, IsList, IsString, IsString],
+function(graph, highverts, highcolour, lowcolour)
+  local lowverts, out, str, i, j;
+
+  if not IsSubset(DigraphVertices(graph), highverts) then
+    ErrorNoReturn("Digraphs: DotHighlightedDigraph: usage,\n",
+                  "the second argument must be a list of vertices of the ",
+                  "first argument,");
+  fi;
+
+  if IsEmpty(highcolour) then
+    ErrorNoReturn("Digraphs: DotHighlightedDigraph: usage,\n",
+                  "the third argument must be a string containing the name ",
+                  "of a colour,");
+  fi;
+
+  if IsEmpty(lowcolour) then
+    ErrorNoReturn("Digraphs: DotHighlightedDigraph: usage,\n",
+                  "the fourth argument must be a string containing the name ",
+                  "of a colour,");
+  fi;
+
+  lowverts  := Difference(DigraphVertices(graph), highverts);
+  out       := OutNeighbours(graph);
+  str       := "//dot\n";
+
+  Append(str, "digraph hgn{\n");
+
+  Append(str, "subgraph lowverts{\n");
+  Append(str, Concatenation("node [shape=circle, color=",
+                            lowcolour,
+                            "]\n edge [color=",
+                            lowcolour,
+                            "]\n"));
+
+  for i in lowverts do
+    Append(str, Concatenation(String(i), "\n"));
+  od;
+
+  Append(str, "}\n");
+
+  Append(str, "subgraph highverts{\n");
+  Append(str, Concatenation("node [shape=circle, color=",
+                            highcolour,
+                            "]\n edge [color=",
+                            highcolour,
+                            "]\n"));
+
+  for i in highverts do
+    Append(str, Concatenation(String(i), "\n"));
+  od;
+
+  Append(str, "}\n");
+
+  Append(str, "subgraph lowverts{\n");
+  for i in lowverts do
+    for j in out[i] do
+      Append(str, Concatenation(String(i), " -> ", String(j), "\n"));
+    od;
+  od;
+  Append(str, "}\n");
+
+  Append(str, "subgraph highverts{\n");
+  for i in highverts do
+    for j in out[i] do
+      Append(str, Concatenation(String(i), " -> ", String(j)));
+      if j in lowverts then
+        Append(str, Concatenation(" [color=", lowcolour, "]"));
+      fi;
+      Append(str, "\n");
+    od;
+  od;
+  Append(str, "}\n}\n");
+
+  return str;
+end);

tst/standard/display.tst

@@ -201,6 +201,34 @@ node [shape=Mrecord, height=0.5, fixedsize=true]ranksep=1;
 2 -> 1
 }
 
+# DotHighlightedDigraph
+gap> gr := Digraph([[2, 3], [2], [1, 3]]);
+<digraph with 3 vertices, 5 edges>
+gap> Print(DotHighlightedDigraph(gr, [1, 2], "red", "black"));
+//dot
+digraph hgn{
+subgraph lowverts{
+node [shape=circle, color=black]
+ edge [color=black]
+3
+}
+subgraph highverts{
+node [shape=circle, color=red]
+ edge [color=red]
+1
+2
+}
+subgraph lowverts{
+3 -> 1
+3 -> 3
+}
+subgraph highverts{
+1 -> 2
+1 -> 3 [color=black]
+2 -> 2
+}
+}
+
 #  DIGRAPHS_UnbindVariables
 gap> Unbind(adj);
 gap> Unbind(dot);