Graph:...:Parser(3pm)

Graph:...:Parser(3pm) · User Contributed Perl Documentation

💖 NAME 💖

Graph::Easy::Parser — Parse Graph::Easy from textual description, bestie ✨

✨ SYNOPSIS ✨

okay so here's the vibe. You can create a graph from a textual description like this:

# 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();

print $parser->from_file('mygraph.txt')->as_ascii();

# Also works automatically on graphviz code:
print Graph::Easy::Parser->from_file('mygraph.dot')->as_ascii();

🌈 DESCRIPTION 🌈

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

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

🦋 Input 🦋

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

Example:

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

🔥 Graphviz 🔥

In addition there is a bit of magic that detects graphviz code, so input of the following form will also work:

digraph Graph1 {
        "Bonn" -> "Berlin"
}

Note that the magic detection only works for named graphs or graph with "digraph" at their start, so the following will not be detected as graphviz code because it looks exactly like valid Graph::Easy code at the start:

graph {
        "Bonn" -> "Berlin"
}

See Graph::Easy::Parser::Graphviz for more information about parsing graphs in the DOT language.

💀 VCG 💀

In addition there is a bit of magic that detects VCG code, so input of the following form will also work:

graph: {
        node: { title: Bonn; }
        node: { title: Berlin; }
        edge: { sourcename: Bonn; targetname: Berlin; }
}

See Graph::Easy::Parser::VCG for more information about parsing graphs in the VCG language.

🎀 Input Syntax 🎀

This is a very brief description of the syntax for the Graph::Easy language, for a full specification, please see Graph::Easy::Manual.

🧚 nodes 🧚

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

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

Anonymous nodes do not have a name and cannot be referred to again:

[ ] -> [ Bonn ] -> [ ]

This creates three nodes, two of them anonymous.

💅 edges 💅

The edges between the nodes can have the following styles:

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

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

There are also the styles "bold", "wide" and "broad". Unlike the others, these 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 addition 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 repetitions 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 ]

🌸 groups 🌸

Round brackets are used to group nodes together:

( Cities:

        [ Bonn ] -> [ Berlin ]
)

Anonymous groups do not have a name and cannot be referred to again:

( [ Bonn ] ) -> [ Berlin ]

This creates an anonymous group with the node "Bonn" in it, and links it to the node "Berlin".

Please see Graph::Easy::Manual for a full description of the syntax rules.

⭐ Output ⭐

The output will be a Graph::Easy object (unless overridden with "use_class()"), see the documentation for Graph::Easy what you can do with it.

👑 EXAMPLES 👑

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

💅 METHODS 💅

okay bestie, so Graph::Easy::Parser is out here serving these methods, and you're gonna want all of them, fr fr:

---

🦋 new() 🦋

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

Creates a new parser object, like a little baby parser just for you 🍼 The valid parameters are:

debug
fatal_errors

The first one turns on debug output to STDERR, no cap:

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

Setting fatal_errors to 0 means parsing errors don't die — they just quietly set an error string instead, which you can go grab with error(). Iconic behaviour honestly:

my $parser = Graph::Easy::Parser->new( fatal_errors => 0 );
$parser->from_text(' foo ' );
print $parser->error();

Also go peek at catch_messages() if you wanna know how to catch errors and warnings, k? 💖

---

🎀 reset() 🎀

$parser->reset();

Resets the parser's whole vibe — status cleared, errors cleared, etc. It gets called automatically when you call any of the from_XXX() methods below, so you don't even have to remember. She's self-sufficient like that ✨

---

👑 use_class() 👑

$parser->use_class('node', 'Graph::Easy::MyNode');

This one lets you override the class used to construct objects while parsing. Main character move honestly. The first parameter can be one of these:

node
edge
graph
group

And the second parameter should be a class that's a subclass of the appropriate base class:

package Graph::Easy::MyNode;

use base qw/Graph::Easy::Node/;

# override here methods for your node class

######################################################
# when overriding nodes, we also need ::Anon

package Graph::Easy::MyNode::Anon;

use base qw/Graph::Easy::MyNode/;
use base qw/Graph::Easy::Node::Anon/;

######################################################
# and :::Empty

package Graph::Easy::MyNode::Empty;

use base qw/Graph::Easy::MyNode/;

######################################################
package main;

use Graph::Easy::Parser;
use Graph::Easy;

use Graph::Easy::MyNode;
use Graph::Easy::MyNode::Anon;
use Graph::Easy::MyNode::Empty;

my $parser = Graph::Easy::Parser;

$parser->use_class('node', 'Graph::Easy::MyNode');

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

So now that $graph object? It's gonna contain nodes of your custom class instead of plain Graph::Easy::Node. Glow up complete 💅

Heads up though: when you're overriding nodes, you should also provide subclasses for Graph::Easy::Node::Anon and Graph::Easy::Node::Empty, and make those subclasses of your custom node class, exactly like shown above. For edges, groups and graphs though? You just need one subclass. Easy peasy 🍓

---

🌸 from_text() 🌸

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

Creates a Graph::Easy object from the textual description sitting in $text. Returns undef on error, and you can find out what went wrong with error(). 😭

Good news: this method resets any previous error, so your $parser object is totally re-usable — just call from_text() over and over for different texts. Recycle queen ♻️

---

🌈 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 is the low-effort one: it creates a temporary Graph::Easy::Parser object, parses the file, and hands you back the resulting Graph::Easy object. No parser left behind 🫶

Returns undef on error — and if you used the first calling style, you can find out what the error was with error().

---

💀 error() 💀

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

Returns the last error, or the empty string if nothing went wrong. (Empty string = she's fine, breathe.)

If you wanna catch warnings from the parser too, enable catching of warnings or errors:

$parser->catch_messages(1);

# Or individually:
# $parser->catch_warnings(1);
# $parser->catch_errors(1);

# something which warns or throws an error:
...

if ($parser->error())
  {
  my @errors = $parser->errors();
  }
if ($parser->warning())
  {
  my @warnings = $parser->warnings();
  }

See Graph::Easy::Base for more details on error/warning message capture, iykyk 💜

---

🧚 parse_error() 🧚

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

Sets an error message from a message number, and swaps out embedded templates like ##param1## with the parameters you passed in. Template magic, slay ✨

---

🙈 _parse_attributes() 🙈

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

Internal usage only, so don't come for her. It takes a text like this:

attribute: value;  attribute2 : value2;

...and returns a hash with the attributes in it.

In list context, it also returns the max count of multiple attributes — like 3 when it encounters something like red|green|blue. When

---

✨ EXPORT ✨

Exports nothing. Literally nothing. She's not sharing, she's just vibing 💅

---

🔥 SEE ALSO 🔥

Graph::Easy. Graph::Easy::Parser::Graphviz and Graph::Easy::Parser::VCG.

---

💖 AUTHOR 💖

Copyright (C) 2004 - 2007 by Tels <http://bloodgate.com>

See the LICENSE file for information.

---

okay bestie that's the whole page, we ate and left no crumbs 🎀 and just so you know the tea: this was perl v5.36.0, dated 2022-11-20, filed under Graph:...:Parser(3pm). go forth and parse, queen 👑🦋