1Graph::Easy::Parser(3)User Contributed Perl DocumentationGraph::Easy::Parser(3)
2
3
4

NAME

6       Graph::Easy::Parser - Parse Graph::Easy from textual description
7

SYNOPSIS

9               # creating a graph from a textual description
10               use Graph::Easy::Parser;
11               my $parser = Graph::Easy::Parser->new();
12
13               my $graph = $parser->from_text(
14                       '[ Bonn ] => [ Berlin ]'.
15                       '[ Berlin ] => [ Rostock ]'.
16               );
17               print $graph->as_ascii();
18
19               print $parser->from_file('mygraph.txt')->as_ascii();
20
21               # Also works automatically on graphviz code:
22               print Graph::Easy::Parser->from_file('mygraph.dot')->as_ascii();
23

DESCRIPTION

25       "Graph::Easy::Parser" lets you parse simple textual descriptions of
26       graphs, and constructs a "Graph::Easy" object from them.
27
28       The resulting object can than be used to layout and output the graph.
29
30   Input
31       The input consists of text describing the graph, encoded in UTF-8.
32
33       Example:
34
35               [ Bonn ]      --> [ Berlin ]
36               [ Frankfurt ] <=> [ Dresden ]
37               [ Bonn ]      --> [ Frankfurt ]
38               [ Bonn ]      = > [ Frankfurt ]
39
40       Graphviz
41
42       In addition there is a bit of magic that detects graphviz code, so
43       input of the following form will also work:
44
45               digraph Graph1 {
46                       "Bonn" -> "Berlin"
47               }
48
49       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
54               graph {
55                       "Bonn" -> "Berlin"
56               }
57
58       See Graph::Easy::Parser::Graphviz for more information about parsing
59       graphs in the DOT language.
60
61       VCG
62
63       In addition there is a bit of magic that detects VCG code, so input of
64       the following form will also work:
65
66               graph: {
67                       node: { title: Bonn; }
68                       node: { title: Berlin; }
69                       edge: { sourcename: Bonn; targetname: Berlin; }
70               }
71
72       See Graph::Easy::Parser::VCG for more information about parsing graphs
73       in the VCG language.
74
75   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
79       nodes
80         Nodes are rendered (or "quoted", if you wish) with enclosing square
81         brackets:
82
83                 [ Single node ]
84                 [ Node A ] --> [ Node B ]
85
86         Anonymous nodes do not have a name and cannot be referred to again:
87
88                 [ ] -> [ Bonn ] -> [ ]
89
90         This creates three nodes, two of them anonymous.
91
92       edges
93         The edges between the nodes can have the following styles:
94
95                 ->              solid
96                 =>              double
97                 .>              dotted
98                 ~>              wave
99
100                 - >             dashed
101                 .->             dot-dash
102                 ..->            dot-dot-dash
103                 = >             double-dash
104
105         There are also the styles "bold", "wide" and "broad". Unlike the
106         others, these can only be set via the (optional) edge attributes:
107
108                 [ AB ] --> { style: bold; } [ ABC ]
109
110         You can repeat each of the style-patterns as much as you like:
111
112                 --->
113                 ==>
114                 =>
115                 ~~~~~>
116                 ..-..-..->
117
118         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
122                 ..-..-..->      # valid dot-dot-dash
123                 ..-..-..>       # invalid!
124
125                 .-.-.->         # valid dot-dash
126                 .-.->           # invalid!
127
128         In addition to the styles, the following two directions are possible:
129
130                  --             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
135         Of course you can combine all directions with all styles. However,
136         note that edges without arrows cannot use the shortcuts for styles:
137
138                 ---             # valid
139                 .-.-            # valid
140                 .-              # invalid!
141                 -               # invalid!
142                 ~               # invalid!
143
144         Just remember to use at least two repititions of the full pattern for
145         arrow-less edges.
146
147         You can also give edges a label, either by inlining it into the
148         style, or by setting it via the attributes:
149
150                 [ AB ] --> { style: bold; label: foo; } [ ABC ]
151
152                 -- foo -->
153                 ... baz ...>
154
155                 -- solid -->
156                 == double ==>
157                 .. dotted ..>
158                 ~~ wave ~~>
159
160                 -  dashed - >
161                 =  double-dash = >
162                 .- dot-dash .->
163                 ..- dot-dot-dash ..->
164
165         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
169         You may use inline label only with edges that have an arrow. Thus:
170
171                 <-- label -->   # valid
172                 -- label -->    # valid
173
174                 -- label --     # invalid!
175
176         To use a label with an edge without arrow heads, use the attributes:
177
178                 [ AB ] -- { label: edgelabel; } [ CD ]
179
180       groups
181         Round brackets are used to group nodes together:
182
183                 ( Cities:
184
185                         [ Bonn ] -> [ Berlin ]
186                 )
187
188         Anonymous groups do not have a name and cannot be referred to again:
189
190                 ( [ Bonn ] ) -> [ Berlin ]
191
192         This creates an anonymous group with the node "Bonn" in it, and links
193         it to the node "Berlin".
194
195       Please see Graph::Easy::Manual for a full description of the syntax
196       rules.
197
198   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

EXAMPLES

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

METHODS

207       "Graph::Easy::Parser" supports the following methods:
208
209   new()
210               use Graph::Easy::Parser;
211               my $parser = Graph::Easy::Parser->new();
212
213       Creates a new parser object. The valid parameters are:
214
215               debug
216               fatal_errors
217
218       The first will enable debug output to STDERR:
219
220               my $parser = Graph::Easy::Parser->new( debug => 1 );
221               $parser->from_text('[A] -> [ B ]');
222
223       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
226               my $parser = Graph::Easy::Parser->new( fatal_errors => 0 );
227               $parser->from_text(' foo ' );
228               print $parser->error();
229
230       See also catch_messages() for how to catch errors and warnings.
231
232   reset()
233               $parser->reset();
234
235       Reset the status of the parser, clear errors etc. Automatically called
236       when you call any of the from_XXX() methods below.
237
238   use_class()
239               $parser->use_class('node', 'Graph::Easy::MyNode');
240
241       Override the class to be used to constructs objects while parsing. The
242       first parameter can be one of the following:
243
244               node
245               edge
246               graph
247               group
248
249       The second parameter should be a class that is a subclass of the
250       appropriate base class:
251
252               package Graph::Easy::MyNode;
253
254               use base qw/Graph::Easy::Node/;
255
256               # override here methods for your node class
257
258               ######################################################
259               # when overriding nodes, we also need ::Anon
260
261               package Graph::Easy::MyNode::Anon;
262
263               use base qw/Graph::Easy::MyNode/;
264               use base qw/Graph::Easy::Node::Anon/;
265
266               ######################################################
267               # and :::Empty
268
269               package Graph::Easy::MyNode::Empty;
270
271               use base qw/Graph::Easy::MyNode/;
272
273               ######################################################
274               package main;
275
276               use Graph::Easy::Parser;
277               use Graph::Easy;
278
279               use Graph::Easy::MyNode;
280               use Graph::Easy::MyNode::Anon;
281               use Graph::Easy::MyNode::Empty;
282
283               my $parser = Graph::Easy::Parser;
284
285               $parser->use_class('node', 'Graph::Easy::MyNode');
286
287               my $graph = $parser->from_text(...);
288
289       The object $graph will now contain nodes that are of your custom class
290       instead of plain "Graph::Easy::Node".
291
292       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
297   from_text()
298               my $graph = $parser->from_text( $text );
299
300       Create a Graph::Easy object from the textual description in $text.
301
302       Returns undef for error, you can find out what the error was with
303       error().
304
305       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
309   from_file()
310               my $graph = $parser->from_file( $filename );
311               my $graph = Graph::Easy::Parser->from_file( $filename );
312
313       Creates a Graph::Easy object from the textual description in the file
314       $filename.
315
316       The second calling style will create a temporary "Graph::Easy::Parser"
317       object, parse the file and return the resulting "Graph::Easy" object.
318
319       Returns undef for error, you can find out what the error was with
320       error() when using the first calling style.
321
322   error()
323               my $error = $parser->error();
324
325       Returns the last error, or the empty string if no error occurred.
326
327       If you want to catch warnings from the parser, enable catching of
328       warnings or errors:
329
330               $parser->catch_messages(1);
331
332               # Or individually:
333               # $parser->catch_warnings(1);
334               # $parser->catch_errors(1);
335
336               # something which warns or throws an error:
337               ...
338
339               if ($parser->error())
340                 {
341                 my @errors = $parser->errors();
342                 }
343               if ($parser->warning())
344                 {
345                 my @warnings = $parser->warnings();
346                 }
347
348       See Graph::Easy::Base for more details on error/warning message
349       capture.
350
351   parse_error()
352               $parser->parse_error( $msg_nr, @params);
353
354       Sets an error message from a message number and replaces embedded
355       templates like "##param1##" with the passed parameters.
356
357   _parse_attributes()
358               my $attributes = $parser->_parse_attributes( $txt, $class );
359               my ($att, $multiples) = $parser->_parse_attributes( $txt, $class );
360
361       Internal usage only. Takes a text like this:
362
363               attribute: value;  attribute2 : value2;
364
365       and returns a hash with the attributes.
366
367       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

EXPORT

371       Exports nothing.
372

SEE ALSO

374       Graph::Easy. Graph::Easy::Parser::Graphviz and
375       Graph::Easy::Parser::VCG.
376

AUTHOR

378       Copyright (C) 2004 - 2007 by Tels <http://bloodgate.com>
379
380       See the LICENSE file for information.
381
382
383
384perl v5.36.0                      2023-02-02            Graph::Easy::Parser(3)
Impressum