1Graph::Easy::Parser(3)User Contributed Perl DocumentationGraph::Easy::Parser(3)
2
6 Graph::Easy::Parser - Parse Graph::Easy from textual description
7
9 # creating a graph from a textual description
10 use Graph::Easy::Parser;
11 my $parser = Graph::Easy::Parser->new();
12 my $graph = $parser->from_text(
14 '[ Bonn ] => [ Berlin ]'.
15 '[ Berlin ] => [ Rostock ]'.
16 );
17 print $graph->as_ascii();
18 print $parser->from_file('mygraph.txt')->as_ascii();
20 # Also works automatically on graphviz code:
22 print Graph::Easy::Parser->from_file('mygraph.dot')->as_ascii();
23
25 "Graph::Easy::Parser" lets you parse simple textual descriptions of
26 graphs, and constructs a "Graph::Easy" object from them.
27 The resulting object can than be used to layout and output the graph.
29 Input
31 The input consists of text describing the graph, encoded in UTF-8.
32 Example:
34 [ Bonn ] --> [ Berlin ]
36 [ Frankfurt ] <=> [ Dresden ]
37 [ Bonn ] --> [ Frankfurt ]
38 [ Bonn ] = > [ Frankfurt ]
39 Graphviz
41 In addition there is a bit of magic that detects graphviz code, so
43 input of the following form will also work:
44 digraph Graph1 {
46 "Bonn" -> "Berlin"
47 }
48 Note that the magic detection only works for named graphs or graph with
50 "digraph" at their start, so the following will not be detected as
51 graphviz code because it looks exactly like valid Graph::Easy code at
52 the start:
53 graph {
55 "Bonn" -> "Berlin"
56 }
57 See Graph::Easy::Parser::Graphviz for more information about parsing
59 graphs in the DOT language.
60 VCG
62 In addition there is a bit of magic that detects VCG code, so input of
64 the following form will also work:
65 graph: {
67 node: { title: Bonn; }
68 node: { title: Berlin; }
69 edge: { sourcename: Bonn; targetname: Berlin; }
70 }
71 See Graph::Easy::Parser::VCG for more information about parsing graphs
73 in the VCG language.
74 Input Syntax
76 This is a very brief description of the syntax for the Graph::Easy
77 language, for a full specification, please see Graph::Easy::Manual.
78 nodes
80 Nodes are rendered (or "quoted", if you wish) with enclosing square
81 brackets:
82 [ Single node ]
84 [ Node A ] --> [ Node B ]
85 Anonymous nodes do not have a name and cannot be referred to again:
87 [ ] -> [ Bonn ] -> [ ]
89 This creates three nodes, two of them anonymous.
91 edges
93 The edges between the nodes can have the following styles:
94 -> solid
96 => double
97 .> dotted
98 ~> wave
99 - > dashed
101 .-> dot-dash
102 ..-> dot-dot-dash
103 = > double-dash
104 There are also the styles "bold", "wide" and "broad". Unlike the
106 others, these can only be set via the (optional) edge attributes:
107 [ AB ] --> { style: bold; } [ ABC ]
109 You can repeat each of the style-patterns as much as you like:
111 --->
113 ==>
114 =>
115 ~~~~~>
116 ..-..-..->
117 Note that in patterns longer than one character, the entire pattern
119 must be repeated e.g. all characters of the pattern must be present.
120 Thus:
121 ..-..-..-> # valid dot-dot-dash
123 ..-..-..> # invalid!
124 .-.-.-> # valid dot-dash
126 .-.-> # invalid!
127 In addition to the styles, the following two directions are possible:
129 -- edge without arrow heads
131 --> arrow at target node (end point)
132 <--> arrow on both the source and target node
133 (end and start point)
134 Of course you can combine all directions with all styles. However,
136 note that edges without arrows cannot use the shortcuts for styles:
137 --- # valid
139 .-.- # valid
140 .- # invalid!
141 - # invalid!
142 ~ # invalid!
143 Just remember to use at least two repititions of the full pattern for
145 arrow-less edges.
146 You can also give edges a label, either by inlining it into the
148 style, or by setting it via the attributes:
149 [ AB ] --> { style: bold; label: foo; } [ ABC ]
151 -- foo -->
153 ... baz ...>
154 -- solid -->
156 == double ==>
157 .. dotted ..>
158 ~~ wave ~~>
159 - dashed - >
161 = double-dash = >
162 .- dot-dash .->
163 ..- dot-dot-dash ..->
164 Note that the two patterns on the left and right of the label must be
166 the same, and that there is a space between the left pattern and the
167 label, as well as the label and the right pattern.
168 You may use inline label only with edges that have an arrow. Thus:
170 <-- label --> # valid
172 -- label --> # valid
173 -- label -- # invalid!
175 To use a label with an edge without arrow heads, use the attributes:
177 [ AB ] -- { label: edgelabel; } [ CD ]
179 groups
181 Round brackets are used to group nodes together:
182 ( Cities:
184 [ Bonn ] -> [ Berlin ]
186 )
187 Anonymous groups do not have a name and cannot be referred to again:
189 ( [ Bonn ] ) -> [ Berlin ]
191 This creates an anonymous group with the node "Bonn" in it, and links
193 it to the node "Berlin".
194 Please see Graph::Easy::Manual for a full description of the syntax
196 rules.
197 Output
199 The output will be a Graph::Easy object (unless overridden with
200 "use_class()"), see the documentation for Graph::Easy what you can do
201 with it.
202
204 See Graph::Easy for an extensive list of examples.
205
207 "Graph::Easy::Parser" supports the following methods:
208 new()
210 use Graph::Easy::Parser;
211 my $parser = Graph::Easy::Parser->new();
212 Creates a new parser object. The valid parameters are:
214 debug
216 fatal_errors
217 The first will enable debug output to STDERR:
219 my $parser = Graph::Easy::Parser->new( debug => 1 );
221 $parser->from_text('[A] -> [ B ]');
222 Setting "fatal_errors" to 0 will make parsing errors not die, but just
224 set an error string, which can be retrieved with error().
225 my $parser = Graph::Easy::Parser->new( fatal_errors => 0 );
227 $parser->from_text(' foo ' );
228 print $parser->error();
229 See also catch_messages() for how to catch errors and warnings.
231 reset()
233 $parser->reset();
234 Reset the status of the parser, clear errors etc. Automatically called
236 when you call any of the "from_XXX()" methods below.
237 use_class()
239 $parser->use_class('node', 'Graph::Easy::MyNode');
240 Override the class to be used to constructs objects while parsing. The
242 first parameter can be one of the following:
243 node
245 edge
246 graph
247 group
248 The second parameter should be a class that is a subclass of the
250 appropriate base class:
251 package Graph::Easy::MyNode;
253 use base qw/Graph::Easy::Node/;
255 # override here methods for your node class
257 ######################################################
259 # when overriding nodes, we also need ::Anon
260 package Graph::Easy::MyNode::Anon;
262 use base qw/Graph::Easy::MyNode/;
264 use base qw/Graph::Easy::Node::Anon/;
265 ######################################################
267 # and :::Empty
268 package Graph::Easy::MyNode::Empty;
270 use base qw/Graph::Easy::MyNode/;
272 ######################################################
274 package main;
275 use Graph::Easy::Parser;
277 use Graph::Easy;
278 use Graph::Easy::MyNode;
280 use Graph::Easy::MyNode::Anon;
281 use Graph::Easy::MyNode::Empty;
282 my $parser = Graph::Easy::Parser;
284 $parser->use_class('node', 'Graph::Easy::MyNode');
286 my $graph = $parser->from_text(...);
288 The object $graph will now contain nodes that are of your custom class
290 instead of plain "Graph::Easy::Node".
291 When overriding nodes, you also should provide subclasses for
293 "Graph::Easy::Node::Anon" and "Graph::Easy::Node::Empty", and make
294 these subclasses of your custom node class as shown above. For edges,
295 groups and graphs, you need just one subclass.
296 from_text()
298 my $graph = $parser->from_text( $text );
299 Create a Graph::Easy object from the textual description in $text.
301 Returns undef for error, you can find out what the error was with
303 error().
304 This method will reset any previous error, and thus the $parser object
306 can be re-used to parse different texts by just calling "from_text()"
307 multiple times.
308 from_file()
310 my $graph = $parser->from_file( $filename );
311 my $graph = Graph::Easy::Parser->from_file( $filename );
312 Creates a Graph::Easy object from the textual description in the file
314 $filename.
315 The second calling style will create a temporary "Graph::Easy::Parser"
317 object, parse the file and return the resulting "Graph::Easy" object.
318 Returns undef for error, you can find out what the error was with
320 error() when using the first calling style.
321 error()
323 my $error = $parser->error();
324 Returns the last error, or the empty string if no error occurred.
326 If you want to catch warnings from the parser, enable catching of
328 warnings or errors:
329 $parser->catch_messages(1);
331 # Or individually:
333 # $parser->catch_warnings(1);
334 # $parser->catch_errors(1);
335 # something which warns or throws an error:
337 ...
338 if ($parser->error())
340 {
341 my @errors = $parser->errors();
342 }
343 if ($parser->warning())
344 {
345 my @warnings = $parser->warnings();
346 }
347 See Graph::Easy::Base for more details on error/warning message
349 capture.
350 parse_error()
352 $parser->parse_error( $msg_nr, @params);
353 Sets an error message from a message number and replaces embedded
355 templates like "##param1##" with the passed parameters.
356 _parse_attributes()
358 my $attributes = $parser->_parse_attributes( $txt, $class );
359 my ($att, $multiples) = $parser->_parse_attributes( $txt, $class );
360 Internal usage only. Takes a text like this:
362 attribute: value; attribute2 : value2;
364 and returns a hash with the attributes.
366 In list context, also returns the max count of multiple attributes,
368 e.g. 3 when it encounters something like "red|green|blue". When
369
371 Exports nothing.
372
374 Graph::Easy. Graph::Easy::Parser::Graphviz and
375 Graph::Easy::Parser::VCG.
376
378 Copyright (C) 2004 - 2007 by Tels <http://bloodgate.com>
379 See the LICENSE file for information.
381perl v5.34.0 2021-07-22 Graph::Easy::Parser(3)