Dreadnaut support

[pramothragavan]

Broadly speaking, a dreadnaut file starts with "configuration" information about the graph, such as the number of vertices (denoted by 'n'), the start index for vertex numbering (denoted by '$') and whether or not a graph is a digraph (denoted by the presence of 'd'). The configuration section always ends with a 'g'. The rest of the file gives information concerning individual vertices in the form of adjacency lists. For example:

n=2
$=1
d
g
1: 1 2;
2: 2;

would represent a 1-indexed digraph with 2 vertices with edges {1,1}, {1,2}, {2,2}.

General overview:

Decoder:

• DIGRAPHS_ParseDreadnautConfig aims to get values for either '$' (which indicates the start index for vertex numbering) or 'n' (which indicates the number of vertices). Note that '$' defaults to 0 and that I chose to reindex all graphs such that vertex numbering starts at one (which I think is convention for the Digraphs package?)
• DIGRAPHS_LegalDreadnautEdge aims to filter out illegal edges and throws an error if an edge is illegal. An example of an illegal edge might be a loop for an undirected graph or an edge containing a vertex that is not allowed within the constraints of the values of '$' and 'n'. (In the case of illegal edges, nauty throws a warning message and then ignores the edge so I was trying to replicate this behaviour).
• DIGRAPHS_SplitDreadnautLines effectively takes a line of dreadnaut (e.g. "1: 2 3 5; 4: 2 1 3; 2: 3;") and aims to split this into parts which are to be handled individually (in this case the parts would be ["1: 2 3 5;", "4: 2 1 3;", "2: 3;"]). The idea here is that although usually these parts would each be on their own line, it's techincally fine for some or all of them to share a line (with or without a semicolon) so I thought it made more sense to condense everything onto one line and then split into parts. There are various auxiliary commands that can be used within the dreadnaut format alongside the definition of the graph (more info here) which I mostly chose to neglect, with the exception of 'f' which defines a partition of vertices. Note that '$$' at the end of a file means reindex the graph to start counting at 0 (which I ignored).
• DIGRAPHS_ParseDreadnautGraph intends to parse the non-configuration part of the file, which has been split into parts after being fed through to DIGRAPHS_SplitDreadnautLines

These are all combined in ReadDreadnautGraph.

Encoder:
WriteDreadnautGraph takes a digraph and encodes into dreadnaut format.

I'm in the process of writing documentation!

[james-d-mitchell]

Some comments delivered verbally, this looks really good, just some minor things to do.

[pramothragavan]

#485 I think this is basically complete, but I don't really like some of the behaviour with ReadDigraphs. As @james-d-mitchell requested verbally, I've implemented the hashsets WholeFileEncoders and WholeFileDecoders, which currently only contain WriteDreadnautGraph and ReadDreadnautGraph respectively, but is a bit more futureproof than the current implementation (hopefully DIMACS can also feature in ReadDigraphs?). There are also corresponding functions IsWholeFileEncoder and IsWholeFileDecoder.

Initially, the idea was that we need to handle whole file decoders separately to single line decoders in ReadDigraphs. However, it transpires that if multiple graphs were given in a .dre file, dreadnaut would just read in the last one (effectively overwriting the previous graph each time). This behaviour is mirrored by ReadDreadnautGraph (with an InfoWarning issued) and by extension ReadDigraphs, but this outcome feels unexpected.

I also think there is ambiguity as to whether you should specify DigraphFromDreadnautString or ReadDreadnautGraph as the optional decoder argument in ReadDigraphs. I think having two encoders/decoders might be overcomplicating things, especially given that ReadDigraphs could always be used instead of ReadDreadnautGraph. Same for writes.