NAME

Graph::DIMACS - read DIMACS format graphs

SYNOPSIS

use Graph::DIMACS;
my ($num_vertices, @edges);
Graph::DIMACS::read_graph(filename         => 'foo.clq',
                          num_vertices_ref => \$num_vertices,
                          edge_aref        => \@edges);

DESCRIPTION

This module reads DIMACS format graph files, either text or binary form.

Text or binary is detected automatically. Both represent a graph with vertices numbered 1 to n. The text form is edges given one per line. The binary form is a text header followed by an upper triangular adjacency matrix of bits. Both can have self-loops. The text form can have multi-edges.

Various DIMACS challenges have further information in the file. The current code reads enough for the clique challenge.

FUNCTIONS

Reading

$success = Graph::DIMACS::read_graph(key => value, ...)

Read DIMACS text or binary graph. The key/value options are

filename           => filename (string)
fh                 => filehandle (glob ref)
str                => string
num_vertices_ref   => scalar ref
num_vertices_func  => coderef
edge_aref          => array ref
edge_func          => coderef
error_func         => coderef
comments_ref       => scalar ref
comments_func      => coderef

The return value is

1         if graph successfully read
0         if end of file (no graph)
croak()   if invalid content or file error
undef     if error_func returns instead of dying

filename, fh or str is the input. The output is the number of vertices and a list of edges. For binary input fh should be in a suitable binmode() already and str should generally be bytes rather than wide-chars.

The number of vertices n is stored to num_vertices_ref or call to num_vertices_func, or both.

$$num_vertices_ref = $n;
$num_vertices_func->($n);

Each edge is pushed onto edge_aref or call to edge_func, or both. $from and $to are integers in the range 1 to n. Any previous contents of edge_aref are discarded.

push @$edge_aref, [ $from, $to ];
$edge_func->($from, $to);

error_func is called for any file error or invalid content.

$error_func->($str, $str, ...);

The default error_func is croak(). If error_func returns then the return from read_graph() is undef.

For num_vertices_ref and edge_aref a my can be included in the ref-taking in the usual way if desired,

# "my" included in refs
read_graph(filename         => 'foo.clq.b',
           num_vertices_ref => \my $num_vertices,
           edge_aref        => \my @edges);

This is compact and is similar to the common open my $fh, ... declaring an output variable in the call which is its first use.

In perl -T taint mode, $num_vertices, $comments and edge $from,$to outputs are tainted in the usual way when reading a file, a tainted str, or an fh handle to a file or a tie of something tainted.

EXPORTS

Nothing is exported by default, but the functions can be requested in usual Exporter style,

use Graph::DIMACS 'read_graph','write_graph';

SEE ALSO

Graph::Graph6,

HOME PAGE

http://user42.tuxfamily.org/graph-graph6/index.html

LICENSE

Copyright 2015, 2016, 2017, 2018 Kevin Ryde

Graph-Graph6 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, or (at your option) any later version.

Graph-Graph6 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 Graph-Graph6. If not, see http://www.gnu.org/licenses/.