Terminology
Here is a short list of terms that will be used throughout the following documents:
- node - a node or vertex in a graph like [ Bonn ]
- edge - an edge connects two
nodes
(or one node with itself) like in [ Bonn ] -> [ Berlin ] - name - unique name of a
node
- label - the text that is displayed as the
node
, if not set, the nodename
will be used - port - each spot on a
node
where oneedge
can start or end - cell - one cell in the layout (which looks like a checker board)
- path - needs to be found to connect two
nodes
in alayout
- (edge) piece - each
path
can consist of more than onecell
and each of these will contain on piece of theedge
- layout - a physical representation of a graph (typical in a 2D plane)
- Parser - parses graphs from a textual description and turns them into an internal representation
- Layouter - lays out the
nodes
andedges
of a graph - hinting - giving the layouter hints on how to generate a specific layout
- A* - general algorithm to find a
path
Input and Output
Here is an overview of the data flow. Input is shown green, while direct output of Graph::Easy
is shown orange. The nodes in white are part of Graph::Easy.
Nodes in yellow show some possible output formats enabled via third-party
applications like 'dot'.

There are currently two ways to create the internal data necessary for Graph::Easy to work with it:
- Create perl code
- Write a text in the format Graph::Easy understands and use Graph::Easy::Parser to parse it
Here is a bit of example Perl code:
use strict; use Graph::Easy; my $graph = Graph::Easy->new(); $graph->add_edge('Bonn', 'Berlin'); my $edge = Graph::Easy::Edge->new( label => 'train' ); $graph->add_edge('Berlin', 'Bonn', $edge);
And here is the corrosponding textual description:
[ Berlin ] -- train --> [ Bonn ] [ Bonn ] --> [ Berlin ]
As you can see, the textual description is a bit shorter. Wether you want to convert your input data to text and then parse it, or convert it directly with Perl code is up to you, of course.
Likewise, once you have your data in an Graph::Easy object, you can output it in the format you desire.
Note that the textual description format allows you a round-trip: you can feed it to the Parser, and then generate again text from the resulting Graph::Easy object.
Storage vs. Layout
Graph::Easy did use the Graph module
to internally store and manage the graph data. Since v0.25, it no longer does so, instead
it stores the nodes/edges simply as Perl hashes and then accesses them directly.
If you want to know why, please ready this page.
Note that the Graph
module does only store a
representation of the graph, but not a particular layout.
For instance the following graph (given in the Graph::Easy syntax, more on that below):
[ A ] -> [ C ] -> [ D ] [ C ] -> [ E ]
can be laid out in (probably infinitely) many ways. Here are two examples:

+---+ +---+ +---+ | A | --> | C | --> | D | +---+ +---+ +---+ | | v +---+ | E | +---+
Layouts
To generate a specific layout, you need a module that provides this functionality. There are some possibilities for generating a layout from a graph via Perl:
- Graph::Easy
- dot (via graphviz)
- Graph-Layderer
- Graph-Layout-Aesthetic
There might be more - when I started with Graph::Easy this were the options.
Unlike the others, Graph::Easy works on a checker-board tiled layout.
Note that the traditional way of placing the nodes anywhere does not enable you
to generate ASCII output, nor HTML. Well, it might be possible, but it is quite hard to
do when the edges don't run straight but all over the place :-)
That's one of the reasons for the existance of Graph::Easy. :-P
Nodes and Edges
Usually each node name is unique, there cannot be two nodes with the same name. Since it is sometimes desired to have two nodes with the same text appearing in the layout, you can override the text displayed with a label:
[ Bonn ] { label: Berlin; } -> [ Berlin ]
This will be rendered like this:

+--------+ +--------+ | Berlin | --> | Berlin | +--------+ +--------+
Most graphing packages also allow multi-edges. A multi-edge graph simply allows two edges going from the same starting node to the same target node:
[ Rostock ] -> [ Wismut ] [ Rostock ] -> [ Wismut ]

+---------------+ | v +---------+ +--------+ | Rostock | --> | Wismut | +---------+ +--------+
In addition to that, self-loops are usefull for state-machines and flowcharts. A self-loop is one edge going from one node back to the same node again:
[ Chemnitz ] -> [ Chemnitz ]

+------+ v | +----------+ | Chemnitz | +----------+