Graph::Easy - Manual - Overview

# Graph::Easy - Manual

## Overview

### 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 many ways to create the internal data necessary for `Graph::Easy` to work with it:

- Create perl code
- Write a text in the native format of Graph::Easy and use Graph::Easy::Parser to parse it
- Write a text in the graphviz format and use Graph::Easy::Parser to parse it
- Write a text in the GDL or VCG format and use Graph::Easy::Parser to parse it

A very convienent way on working with graph descriptions in various text formats (and converting between them!) is the command-line utility C. This script is installed as part of Graph::Easy. For details on using it, please refer to the graph-easy manual.

Here is a bit of example Perl code:

    use strict;
    use Graph::Easy;

    my $graph = Graph::Easy->new();

    $graph->add_edge('Bonn', 'Berlin');
    $graph->add_edge('Berlin', 'Bonn', 'train' );

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 text again 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 this project. :-P

Please continue with the chapter about the feature set.