diff --git a/PackageInfo.g b/PackageInfo.g index cfb5046..ed94b02 100644 --- a/PackageInfo.g +++ b/PackageInfo.g @@ -31,6 +31,8 @@ Persons := [ rec( FirstNames := "Matthew", LastName := "Pancer", + WWWHome := "https://github.com/mpan322", + # TODO make personal website Email := "mp322@st-andrews.ac.uk", IsAuthor := true, IsMaintainer := true, diff --git a/gap/dot.gd b/gap/dot.gd index b91b7f8..74ed67b 100644 --- a/gap/dot.gd +++ b/gap/dot.gd @@ -28,21 +28,21 @@ #! @ChapterTitle The Graphviz Package #! @Section Graphviz Categories - -#! @BeginGroup Filters -#! @Description Every object in graphviz belongs to the IsGraphvizObject -#! category. The categories following it are for further specificity on the -#! type of objects. These are graphs, digraphs, nodes and edges respectively. -#! All are direct subcategories of IsGraphvizObject excluding IsGraphvizDigraph -#! which is a subcategory of is IsGraphvizGraph. - +#! @Description Every object in graphviz belongs to this category. DeclareCategory("IsGraphvizObject", IsObject); +#! @BeginGroup +#! @GroupTitle Graphs, digraphs and contexts +#! @Description These categories are for objects with graph like behaviour eg. +#! they can contain nodes, edges, subgraphs, etc. DeclareCategory("IsGraphvizGraphDigraphOrContext", IsGraphvizObject); DeclareCategory("IsGraphvizGraph", IsGraphvizGraphDigraphOrContext); DeclareCategory("IsGraphvizDigraph", IsGraphvizGraphDigraphOrContext); DeclareCategory("IsGraphvizContext", IsGraphvizGraphDigraphOrContext); +#! @EndGroup +#! @BeginGroup +#! @GroupTitle Nodes and edges DeclareCategory("IsGraphvizNodeOrEdge", IsGraphvizObject); DeclareCategory("IsGraphvizNode", IsGraphvizNodeOrEdge); DeclareCategory("IsGraphvizEdge", IsGraphvizNodeOrEdge); @@ -73,6 +73,8 @@ DeclareOperation("GraphvizDigraph", []); #! objects. #! @Subsection For all graphviz objects. +#! Operations below are applicable to all graphviz +#! objects. #! @Arguments obj #! @Returns the name of the provided graphviz object @@ -84,30 +86,31 @@ DeclareOperation("GraphvizName", [IsGraphvizObject]); #! @Description Gets the attributes of the provided graphviz object. DeclareOperation("GraphvizAttrs", [IsGraphvizObject]); -#! @Subsection For only graphs and digraphs. +#! @Subsection For only graphs, digraphs and contexts. +#! This section covers the operations for getting information +#! specific to graphviz graphs, digraphs and contexts. #! @Arguments graph -#! @Returns the nodes of the provided graphviz graph. +#! @Returns the nodes of the provided graphviz graph +#! as a mapping from node ids to names. #! @Description Gets the nodes of the provided graphviz graph. -# From https://graphviz.org/doc/info/lang.html -# An ID is one of the following: -# Any string of alphabetic ([a-zA-Z\200-\377]) characters, underscores ('_') or -# digits([0-9]), not beginning with a digit; -# a numeral [-]?(.[0-9]⁺ | [0-9]⁺(.[0-9]*)? ); -# any double-quoted string ("...") possibly containing escaped quotes (\")¹; -# an HTML string (<...>). -# TODO specify +#! What constitutes a valid node ID +#! is defined here "https://graphviz.org/doc/info/lang.html". DeclareOperation("GraphvizNodes", [IsGraphvizGraphDigraphOrContext]); #! @Arguments graph #! @Returns the subgraphs of the provided graphviz graph. #! @Description gets the subgraphs of a provided graphviz graph. +#! Subgraphs are returned as a mapping from subgraph names to +#! corresponding objects. DeclareOperation("GraphvizSubgraphs", [IsGraphvizGraphDigraphOrContext]); #! @Arguments graph #! @Returns the contexts of the provided graphviz graph, digraph or context. #! @Description gets the contexts of a provided graphviz graph, digraph #! or context. +#! Subgraphs are returned as a mapping from context names to +#! corresponding objects. DeclareOperation("GraphvizContexts", [IsGraphvizGraphDigraphOrContext]); #! @Arguments graph, name @@ -116,18 +119,27 @@ DeclareOperation("GraphvizContexts", [IsGraphvizGraphDigraphOrContext]); #! Searches through the tree of subgraphs connected to this subgraph for a graph #! with the provided name. #! It returns the graph if it exists. -#! If no such graph exists then it will return fail. +#! If no such graph exists then it will return fail. DeclareOperation("GraphvizFindSubgraphRecursive", [IsGraphvizGraphDigraphOrContext, IsObject]); +#! @BeginGroup +#! @GroupTitle Getting Graphviz Edges #! @Arguments graph #! @Returns the edges of the provided graphviz graph. -#! @Description Gets the edges of the provided graphviz graph. +#! @Description +#! Gets the edges of the provided graphviz graph. +#! Returns a list of edge objects. +#! If a head and tail are provided will only return edges +#! between those two nodes. DeclareOperation("GraphvizEdges", [IsGraphvizGraphDigraphOrContext]); +#! @Arguments graph, head, tail DeclareOperation("GraphvizEdges", [IsGraphvizGraphDigraphOrContext, IsObject, IsObject]); +#! @EndGroup #! @Subsection For only edges. +#! This section contains getters only applicable to graphviz edges. #! @Arguments edge #! @Returns the head of the provided graphviz edge. @@ -143,46 +155,82 @@ DeclareOperation("GraphvizTail", [IsGraphvizEdge]); #! This section covers operations for modifying graphviz objects. #! @Subsection For modifying graphs. +#! Operations below only pertain to graphs, digraphs and contexts. #! @Arguments graph, name #! @Returns the modified graph. #! @Description Sets the name of a graphviz graph or digraph. DeclareOperation("GraphvizSetName", [IsGraphvizGraphDigraphOrContext, IsObject]); -#! @Arguments graph, node -#! @Returns the modified graph. -#! @Description Adds a node to the graph. -#! If a node with the same name is already present the operation fails. +#! @Arguments graph, id +#! @Returns the new node. +#! @Description Adds a node to the graph with ID id. +#! If the id parameter is not string it will be converted to one. +#! If a node with the same id is already present the operation fails. +#! What constitutes a valid node ID +#! is defined here "https://graphviz.org/doc/info/lang.html". +#! Currently nodes cannot be added directly to graphs, so +#! if id is of type GraphvizNode it will fail. DeclareOperation("GraphvizAddNode", [IsGraphvizGraphDigraphOrContext, IsObject]); -#! @Arguments graph, edge -#! @Returns the modified graph. -#! @Description Adds an edge to the graph. -#! If no nodes with the same name are in the graph then the edge's nodes will be -#! added to the graph. If different nodes with the same name are in the graph -#! then the operation fails. -#! TODO I dont believe this is accurate - think it will connect existing ones -#! underlying private function would fail though - TODO double check. +#! @Arguments graph, head, tail +#! @Returns the new edge. +#! @Description adds an edge to the graph. +#! The head and tail can be +#! general objects, strings or graphviz nodes. +#! If the head and tail are general objects, they will +#! be converted to strings. +#! Strings are then interpreted as node IDs. +#! If no nodes with the same id are in the (di)graph, nodes automatically will be +#! added to the graph. +#! If there are nodes with the same id, they will be used. DeclareOperation("GraphvizAddEdge", [IsGraphvizGraphDigraphOrContext, IsObject, IsObject]); -#! @Arguments graph, filter, name +#! @BeginGroup +#! @GroupTitle Adding Subgraphs +#! @Arguments graph, name #! @Returns the new subgraph. #! @Description Adds a subgraph to a graph. +#! The type of structure (graph or digraph) will be the same as the parent graph. +#! At the moment it is not possible to add an existing graph as a +#! subgraph of another graph. DeclareOperation("GraphvizAddSubgraph", [IsGraphvizGraphDigraphOrContext, IsObject]); +#! @Arguments graph DeclareOperation("GraphvizAddSubgraph", [IsGraphvizGraphDigraphOrContext]); +#! @EndGroup -#! @Arguments graph, filter, name +#! @BeginGroup +#! @GroupTitle Adding Contexts +#! @Arguments graph, name #! @Returns the new context. #! @Description Adds a context to a graph. +#! A context can be thought as being similar to a subgraph +#! when manipulating it in this package. +#! However, when rendered contexts do not +#! create a subgraph in outputted DOT code. +#! Instead their nodes are rendered inline within the parent graph. +#! This allows for scoping node and edge attributes +#! without modifying the rendering behaviour. +#! The type of graph edge (directed or undirected) +#! will be the same as the parent graph. +#! At the moment it is not possible to add an existing context to +#! a new graph. DeclareOperation("GraphvizAddContext", [IsGraphvizGraphDigraphOrContext, IsObject]); +#! @Arguments graph DeclareOperation("GraphvizAddContext", [IsGraphvizGraphDigraphOrContext]); +#! @EndGroup #! @Arguments graph, node #! @Returns the modified graph. #! @Description Removes the node from the graph. +#! The node attribute may be an object, string or graphviz node. +#! Objects will be converted to strings. +#! Strings are then interpreted as the id of the node to remove. +#! All edges containing the node are also removed. +#! If no such node exists the operation fails. DeclareOperation("GraphvizRemoveNode", [IsGraphvizGraphDigraphOrContext, IsObject]); @@ -192,29 +240,41 @@ DeclareOperation("GraphvizRemoveNode", DeclareOperation("GraphvizFilterEdges", [IsGraphvizGraphDigraphOrContext, IsFunction]); -#! @Arguments graph, head_name, tail_name +#! @Arguments graph, head_id, tail_id #! @Returns the modified graph. -#! @Description Filters the graph's edges, removing edges between nodes with -#! the specified names. +#! @Description +#! Filters the graph's edges, removing edges between nodes with +#! the specified ids. +#! If no edges exist between the two nodes, the operation fails. DeclareOperation("GraphvizRemoveEdges", [IsGraphvizGraphDigraphOrContext, IsObject, IsObject]); -#! @Subsection For modifying object attributes. +#! @Subsection Modifying object attributes +#! Operations for modifying attributes. +#! @BeginGroup +#! @GroupTitle Setting Attributes #! @Arguments obj, attrs #! @Returns the modified object. #! @Description -#! Updates the attributes of the object. -#! All current attributes remain. -#! If an attribute already exists and a new value is provided, the old value -#! will be overwritten. +#! Updates the attributes of the object. +#! All current attributes remain. +#! If an attribute already exists and a new value is provided, the old value +#! will be overwritten. DeclareOperation("GraphvizSetAttrs", [IsGraphvizObject, IsRecord]); +#! @Arguments obj, name, value DeclareOperation("GraphvizSetAttr", [IsGraphvizObject, IsObject, IsObject]); +#! @Arguments obj, name DeclareOperation("GraphvizSetAttr", [IsGraphvizObject, IsObject]); +#! @EndGroup #! @Arguments obj, attr #! @Returns the modified object. -#! @Description Removes an attribute from the object provided. +#! @Description +#! Removes an attribute from the object provided. +#! If no attributes are removed then the operation fails. +#! Attributes may be removed by key or by +#! key-value pair eg. "label" or "label=\"test\"". DeclareOperation("GraphvizRemoveAttr", [IsGraphvizObject, IsObject]); #! @Section Outputting @@ -225,26 +285,63 @@ DeclareOperation("AsString", [IsGraphvizGraphDigraphOrContext]); #! @Arguments obj #! @Returns the graphviz representation of the object. #! @Description -#! Unimplemented operation which depending packages can implement. -#! Should output the graphviz package representation of the object. +#! Unimplemented operation which depending packages can implement. +#! Should output the graphviz package representation of the object. DeclareOperation("Graphviz", [IsObject]); +#! @Arguments graph, colours +#! @Returns the modified object +#! @Description +#! Sets the colors of the nodes in the (di)graph. +#! If there are a different number of colours than nodes the operation fails. +#! Also sets the node style to filled. DeclareOperation("GraphvizSetNodeColors", [IsGraphvizGraphDigraphOrContext, IsList]); + +#! @Arguments graph, labels +#! @Returns the modified object +#! @Description +#! Sets the labels of the nodes in the (di)graph. +#! If there are fewer labels than nodes the operation fails. +#! If there is an invalid label the operation halts there and fails. +#! What constitutes a valid label can be found here, +#! "https://graphviz.org/doc/info/lang.html". DeclareOperation("GraphvizSetNodeLabels", [IsGraphvizGraphDigraphOrContext, IsList]); +#! @Arguments color +#! @Returns true or false +#! @Description +#! Determines if the color provided is a valid graphviz color. +#! Valid graphviz colors are described here, +#! "http://graphviz.org/doc/info/colors.html". DeclareGlobalFunction("ErrorIfNotValidColor"); -# TODO doc -DeclareOperation("\[\]", [IsGraphvizNode, IsObject]); -# TODO doc -DeclareOperation("\[\]\:\=", [IsGraphvizNode, IsObject, IsObject]); +#! @Section Shorthand +#! Shorthand for common operations. -# TODO doc +#! @BeginGroup +#! @GroupTitle Getting attributes +#! @Arguments edge, attr +#! @Returns the value associated with the provided attribute. +#! @Description +#! Gets the value associated with the attribute attr. DeclareOperation("\[\]", [IsGraphvizEdge, IsObject]); -# TODO doc +#! @Arguments node, attr +DeclareOperation("\[\]", [IsGraphvizNode, IsObject]); +#! @EndGroup + +#! @BeginGroup +#! @GroupTitle Setting attributes +#! @Arguments node, attr +#! @Description +#! Sets the value associated with the attribute attr. +DeclareOperation("\[\]\:\=", [IsGraphvizNode, IsObject, IsObject]); +#! @Arguments edge, attr DeclareOperation("\[\]\:\=", [IsGraphvizEdge, IsObject, IsObject]); -# TODO doc +#! @Arguments graph, node_name +#! @Returns The associated node or fail if no such node exists. +#! @Description +#! Gets a node from a (di)graph by id. DeclareOperation("\[\]", [IsGraphvizGraphDigraphOrContext, IsObject]);