--- name: "Graph::Easy::Parser" section: "3pm" platform: "linux" package: "libgraph-easy-perl" version: "0.76-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Graph::Easy::Parser" --- # Graph::Easy::Parser(3pm) Parse Graph::Easy from textual description ## NAME Graph::Easy::Parser - Parse Graph::Easy 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(); 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 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. 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 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 ] ``` - 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 `"Graph::Easy::Parser"` supports the following methods: ### new() ``` use Graph::Easy::Parser; my $parser = Graph::Easy::Parser->new(); ``` Creates a new parser object. The valid parameters are: ``` debug fatal_errors ``` The first will enable debug output to STDERR: ``` my $parser = Graph::Easy::Parser->new( debug => 1 ); $parser->from_text('[A] -> [ B ]'); ``` Setting `"fatal_errors"` to 0 will make parsing errors not die, but just set an error string, which can be retrieved with **error()**. ``` my $parser = Graph::Easy::Parser->new( fatal_errors => 0 ); $parser->from_text(' foo ' ); print $parser->error(); ``` See also **catch\_messages()** for how to catch errors and warnings. ### reset() ``` $parser->reset(); ``` Reset the status of the parser, clear errors etc. Automatically called when you call any of the `"from_XXX()"` methods below. ### use\_class() ``` $parser->use_class('node', 'Graph::Easy::MyNode'); ``` Override the class to be used to constructs objects while parsing. The first parameter can be one of the following: ``` node edge graph group ``` The second parameter should be a class that is 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(...); ``` The object `$graph` will now contain nodes that are of your custom class instead of plain `"Graph::Easy::Node"`. When overriding nodes, you also should provide subclasses for `"Graph::Easy::Node::Anon"` and `"Graph::Easy::Node::Empty"`, and make these subclasses of your custom node class as shown above. For edges, groups and graphs, you need just one subclass. ### 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 occurred. If you want to catch warnings from the parser, 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. ### 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 ); my ($att, $multiples) = $parser->_parse_attributes( $txt, $class ); ``` **Internal usage only**. Takes a text like this: ``` attribute: value; attribute2 : value2; ``` and returns a hash with the attributes. In list context, also returns the max count of multiple attributes, e.g. 3 when it encounters something like `"red|green|blue"`. When ## EXPORT Exports nothing. ## SEE ALSO Graph::Easy. Graph::Easy::Parser::Graphviz and Graph::Easy::Parser::VCG. ## AUTHOR Copyright (C) 2004 - 2007 by Tels \ See the LICENSE file for information.