NAME

Graph::Easy::Parser - Parse graph from textual description

SYNOPSIS

        # creating a graph from a textual description
        use Graph::Easy::Parser;
        my $parser = Graph::Easy::Parser->new();

        my $graph = $parser->from_text(
                '[ Bonn ] => [ Berlin ]'.
                '[ Berlin ] => [ Rostock ]'.
        );
        print $graph->as_ascii( );

DESCRIPTION

Graph::Easy::Parser lets you parse simple textual descriptions of graphs, and constructs a Graph::Easy object from them.

The resulting object can than be used to layout and output the graph.

Input

The input consists of text describing the graph, encoded in UTF-8.

        [ Bonn ]      --> [ Berlin ]
        [ Frankfurt ] <=> [ Dresden ]
        [ Bonn ]      --> [ Frankfurt ]
        [ Bonn ]      = > [ Frankfurt ]

The output will be a Graph::Easy object, see there for what you can do with it.

nodes

Nodes are rendered (or "quoted", if you wish) with enclosing square brackets:

        [ Single node ]
        [ Node A ] --> [ Node B ]

edges

The edges between the nodes can have the following styles:

        ->              solid
        =>              double
        .>              dotted
        ~>              wave

        - >             dashed
        .->             dot-dash
        ..->            dot-dot-dash
        = >             double-dash

There is also the style "bold". Unlike the others, this can only be set via the (optional) edge attributes:

        [ AB ] --> { style: bold; } [ ABC ]

You can repeat each of the style-patterns as much as you like:

        --->
        ==>
        =>
        ~~~~~>
        ..-..-..->

Note that in patterns longer than one character, the entire pattern must be repeated e.g. all characters of the pattern must be present. Thus:

        ..-..-..->      # valid dot-dot-dash
        ..-..-..>       # invalid!

        .-.-.->         # valid dot-dash
        .-.->           # invalid!

In additon to the styles, the following two directions are possible:

         --             edge without arrow heads
         -->            arrow at target node (end point)
        <-->            arrow on both the source and target node
                        (end and start point)

Of course you can combine all directions with all styles. However, note that edges without arrows cannot use the shortcuts for styles:

        ---             # valid
        .-.-            # valid
        .-              # invalid!
        -               # invalid!
        ~               # invalid!

Just remember to use at least two repititions of the full pattern for arrow-less edges.

You can also give edges a label, either by inlining it into the style, or by setting it via the attributes:

        [ AB ] --> { style: bold; label: foo; } [ ABC ]

        -- foo -->
        ... baz ...>

        -- solid -->
        == double ==>
        .. dotted ..>
        ~~ wave ~~>

        -  dashed - >
        =  double-dash = >
        .- dot-dash .->
        ..- dot-dot-dash ..->

Note that the two patterns on the left and right of the label must be the same, and that there is a space between the left pattern and the label, as well as the label and the right pattern.

You may use inline label only with edges that have an arrow. Thus:

        <-- label -->   # valid
        -- label -->    # valid

        -- label --     # invalid!

To use a label with an edge without arrow heads, use the attributes:

        [ AB ] -- { label: edgelabel; } [ CD ]

Please see the manual for a full description of the syntax rules.

Output

The output will be a Graph::Easy object, see there for what you can do with it.

EXAMPLES

See Graph::Easy for an extensive list of examples.

METHODS

Graph::Easy::Parser supports the following methods:

new()

        use Graph::Easy::Parser;
        my $parser = Graph::Easy::Parser->new();

Creates a new parser object. The only valid parameter is debug, when set to true it will enable debug output to STDERR:

        my $parser = Graph::Easy::Parser->new( debug => 1 );
        $parser->from_text('[A] -> [ B ]');

reset()

        $parser->reset();

Reset the status of the parser, clear errors etc. Automatically called when you call any of the from_XXX() methods below.

from_text()

        my $graph = $parser->from_text( $text );

Create a Graph::Easy object from the textual description in $text.

Returns undef for error, you can find out what the error was with error().

This method will reset any previous error, and thus the $parser object can be re-used to parse different texts by just calling from_text() multiple times.

from_file()

        my $graph = $parser->from_file( $filename );
        my $graph = Graph::Easy::Parser->from_file( $filename );

Creates a Graph::Easy object from the textual description in the file $filename.

The second calling style will create a temporary Graph::Easy::Parser object, parse the file and return the resulting Graph::Easy object.

Returns undef for error, you can find out what the error was with error() when using the first calling style.

error()

        my $error = $parser->error();

Returns the last error, or the empty string if no error occured.

parse_error()

        $parser->parse_error( $msg_nr, @params);

Sets an error message from a message number and replaces embedded templates like ##param1## with the passed parameters.

_parse_attributes()

        my $attributes = $parser->_parse_attributes( $txt, $class );
  

Internal usage only. Takes a text like this:

        attribute: value;  attribute2 : value2;

and returns a hash with the attributes.

EXPORT

Exports nothing.

SEE ALSO

Graph::Easy.

AUTHOR

Copyright (C) 2004 - 2005 by Tels http://bloodgate.com

See the LICENSE file for information.

cpanm Graph::Easy

perl -MCPAN -e shell
install Graph::Easy