.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Graph::Easy::Parser 3"
.TH Graph::Easy::Parser 3 "2016-08-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Graph::Easy::Parser \- Parse Graph::Easy from textual description
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&        # creating a graph from a textual description
\&        use Graph::Easy::Parser;
\&        my $parser = Graph::Easy::Parser\->new();
\&
\&        my $graph = $parser\->from_text(
\&                \*(Aq[ Bonn ] => [ Berlin ]\*(Aq.
\&                \*(Aq[ Berlin ] => [ Rostock ]\*(Aq.
\&        );
\&        print $graph\->as_ascii();
\&
\&        print $parser\->from_file(\*(Aqmygraph.txt\*(Aq)\->as_ascii();
\&
\&        # Also works automatically on graphviz code:
\&        print Graph::Easy::Parser\->from_file(\*(Aqmygraph.dot\*(Aq)\->as_ascii();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Graph::Easy::Parser\*(C'\fR lets you parse simple textual descriptions
of graphs, and constructs a \f(CW\*(C`Graph::Easy\*(C'\fR object from them.
.PP
The resulting object can than be used to layout and output the graph.
.SS "Input"
.IX Subsection "Input"
The input consists of text describing the graph, encoded in \s-1UTF\-8.\s0
.PP
Example:
.PP
.Vb 4
\&        [ Bonn ]      \-\-> [ Berlin ]
\&        [ Frankfurt ] <=> [ Dresden ]
\&        [ Bonn ]      \-\-> [ Frankfurt ]
\&        [ Bonn ]      = > [ Frankfurt ]
.Ve
.PP
\fIGraphviz\fR
.IX Subsection "Graphviz"
.PP
In addition there is a bit of magic that detects graphviz code, so
input of the following form will also work:
.PP
.Vb 3
\&        digraph Graph1 {
\&                "Bonn" \-> "Berlin"
\&        }
.Ve
.PP
Note that the magic detection only works for \fBnamed\fR graphs or graph
with \*(L"digraph\*(R" 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:
.PP
.Vb 3
\&        graph {
\&                "Bonn" \-> "Berlin"
\&        }
.Ve
.PP
See Graph::Easy::Parser::Graphviz for more information about parsing
graphs in the \s-1DOT\s0 language.
.PP
\fI\s-1VCG\s0\fR
.IX Subsection "VCG"
.PP
In addition there is a bit of magic that detects \s-1VCG\s0 code, so
input of the following form will also work:
.PP
.Vb 5
\&        graph: {
\&                node: { title: Bonn; }
\&                node: { title: Berlin; }
\&                edge: { sourcename: Bonn; targetname: Berlin; }
\&        }
.Ve
.PP
See Graph::Easy::Parser::VCG for more information about parsing
graphs in the \s-1VCG\s0 language.
.SS "Input Syntax"
.IX Subsection "Input Syntax"
This is a \fBvery\fR brief description of the syntax for the Graph::Easy
language, for a full specification, please see Graph::Easy::Manual.
.IP "nodes" 2
.IX Item "nodes"
Nodes are rendered (or \*(L"quoted\*(R", if you wish) with enclosing square brackets:
.Sp
.Vb 2
\&        [ Single node ]
\&        [ Node A ] \-\-> [ Node B ]
.Ve
.Sp
Anonymous nodes do not have a name and cannot be referred to again:
.Sp
.Vb 1
\&        [ ] \-> [ Bonn ] \-> [ ]
.Ve
.Sp
This creates three nodes, two of them anonymous.
.IP "edges" 2
.IX Item "edges"
The edges between the nodes can have the following styles:
.Sp
.Vb 4
\&        \->              solid
\&        =>              double
\&        .>              dotted
\&        ~>              wave
\&
\&        \- >             dashed
\&        .\->             dot\-dash
\&        ..\->            dot\-dot\-dash
\&        = >             double\-dash
.Ve
.Sp
There are also the styles \f(CW\*(C`bold\*(C'\fR, \f(CW\*(C`wide\*(C'\fR and \f(CW\*(C`broad\*(C'\fR. Unlike the others,
these can only be set via the (optional) edge attributes:
.Sp
.Vb 1
\&        [ AB ] \-\-> { style: bold; } [ ABC ]
.Ve
.Sp
You can repeat each of the style-patterns as much as you like:
.Sp
.Vb 5
\&        \-\-\->
\&        ==>
\&        =>
\&        ~~~~~>
\&        ..\-..\-..\->
.Ve
.Sp
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:
.Sp
.Vb 2
\&        ..\-..\-..\->      # valid dot\-dot\-dash
\&        ..\-..\-..>       # invalid!
\&
\&        .\-.\-.\->         # valid dot\-dash
\&        .\-.\->           # invalid!
.Ve
.Sp
In addition to the styles, the following two directions are possible:
.Sp
.Vb 4
\&         \-\-             edge without arrow heads
\&         \-\->            arrow at target node (end point)
\&        <\-\->            arrow on both the source and target node
\&                        (end and start point)
.Ve
.Sp
Of course you can combine all directions with all styles. However,
note that edges without arrows cannot use the shortcuts for styles:
.Sp
.Vb 5
\&        \-\-\-             # valid
\&        .\-.\-            # valid
\&        .\-              # invalid!
\&        \-               # invalid!
\&        ~               # invalid!
.Ve
.Sp
Just remember to use at least two repititions of the full pattern
for arrow-less edges.
.Sp
You can also give edges a label, either by inlining it into the style,
or by setting it via the attributes:
.Sp
.Vb 1
\&        [ AB ] \-\-> { style: bold; label: foo; } [ ABC ]
\&
\&        \-\- foo \-\->
\&        ... baz ...>
\&
\&        \-\- solid \-\->
\&        == double ==>
\&        .. dotted ..>
\&        ~~ wave ~~>
\&
\&        \-  dashed \- >
\&        =  double\-dash = >
\&        .\- dot\-dash .\->
\&        ..\- dot\-dot\-dash ..\->
.Ve
.Sp
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.
.Sp
You may use inline label only with edges that have an arrow. Thus:
.Sp
.Vb 2
\&        <\-\- label \-\->   # valid
\&        \-\- label \-\->    # valid
\&
\&        \-\- label \-\-     # invalid!
.Ve
.Sp
To use a label with an edge without arrow heads, use the attributes:
.Sp
.Vb 1
\&        [ AB ] \-\- { label: edgelabel; } [ CD ]
.Ve
.IP "groups" 2
.IX Item "groups"
Round brackets are used to group nodes together:
.Sp
.Vb 1
\&        ( Cities:
\&
\&                [ Bonn ] \-> [ Berlin ]
\&        )
.Ve
.Sp
Anonymous groups do not have a name and cannot be referred to again:
.Sp
.Vb 1
\&        ( [ Bonn ] ) \-> [ Berlin ]
.Ve
.Sp
This creates an anonymous group with the node \f(CW\*(C`Bonn\*(C'\fR in it, and
links it to the node \f(CW\*(C`Berlin\*(C'\fR.
.PP
Please see Graph::Easy::Manual for a full description of the syntax rules.
.SS "Output"
.IX Subsection "Output"
The output will be a Graph::Easy object (unless overridden
with \f(CW\*(C`use_class()\*(C'\fR), see the documentation for Graph::Easy what you can do
with it.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
See Graph::Easy for an extensive list of examples.
.SH "METHODS"
.IX Header "METHODS"
\&\f(CW\*(C`Graph::Easy::Parser\*(C'\fR supports the following methods:
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 2
\&        use Graph::Easy::Parser;
\&        my $parser = Graph::Easy::Parser\->new();
.Ve
.PP
Creates a new parser object. The valid parameters are:
.PP
.Vb 2
\&        debug
\&        fatal_errors
.Ve
.PP
The first will enable debug output to \s-1STDERR:\s0
.PP
.Vb 2
\&        my $parser = Graph::Easy::Parser\->new( debug => 1 );
\&        $parser\->from_text(\*(Aq[A] \-> [ B ]\*(Aq);
.Ve
.PP
Setting \f(CW\*(C`fatal_errors\*(C'\fR to 0 will make parsing errors not die, but
just set an error string, which can be retrieved with \fIerror()\fR.
.PP
.Vb 3
\&        my $parser = Graph::Easy::Parser\->new( fatal_errors => 0 );
\&        $parser\->from_text(\*(Aq foo \*(Aq );
\&        print $parser\->error();
.Ve
.PP
See also \fIcatch_messages()\fR for how to catch errors and warnings.
.SS "\fIreset()\fP"
.IX Subsection "reset()"
.Vb 1
\&        $parser\->reset();
.Ve
.PP
Reset the status of the parser, clear errors etc. Automatically called
when you call any of the \f(CW\*(C`from_XXX()\*(C'\fR methods below.
.SS "\fIuse_class()\fP"
.IX Subsection "use_class()"
.Vb 1
\&        $parser\->use_class(\*(Aqnode\*(Aq, \*(AqGraph::Easy::MyNode\*(Aq);
.Ve
.PP
Override the class to be used to constructs objects while parsing. The
first parameter can be one of the following:
.PP
.Vb 4
\&        node
\&        edge
\&        graph
\&        group
.Ve
.PP
The second parameter should be a class that is a subclass of the
appropriate base class:
.PP
.Vb 1
\&        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(\*(Aqnode\*(Aq, \*(AqGraph::Easy::MyNode\*(Aq);
\&
\&        my $graph = $parser\->from_text(...);
.Ve
.PP
The object \f(CW$graph\fR will now contain nodes that are of your
custom class instead of plain \f(CW\*(C`Graph::Easy::Node\*(C'\fR.
.PP
When overriding nodes, you also should provide subclasses
for \f(CW\*(C`Graph::Easy::Node::Anon\*(C'\fR and \f(CW\*(C`Graph::Easy::Node::Empty\*(C'\fR,
and make these subclasses of your custom node class as shown
above. For edges, groups and graphs, you need just one subclass.
.SS "\fIfrom_text()\fP"
.IX Subsection "from_text()"
.Vb 1
\&        my $graph = $parser\->from_text( $text );
.Ve
.PP
Create a Graph::Easy object from the textual description in \f(CW$text\fR.
.PP
Returns undef for error, you can find out what the error was
with \fIerror()\fR.
.PP
This method will reset any previous error, and thus the \f(CW$parser\fR object
can be re-used to parse different texts by just calling \f(CW\*(C`from_text()\*(C'\fR
multiple times.
.SS "\fIfrom_file()\fP"
.IX Subsection "from_file()"
.Vb 2
\&        my $graph = $parser\->from_file( $filename );
\&        my $graph = Graph::Easy::Parser\->from_file( $filename );
.Ve
.PP
Creates a Graph::Easy object from the textual description in the file
\&\f(CW$filename\fR.
.PP
The second calling style will create a temporary \f(CW\*(C`Graph::Easy::Parser\*(C'\fR object,
parse the file and return the resulting \f(CW\*(C`Graph::Easy\*(C'\fR object.
.PP
Returns undef for error, you can find out what the error was
with \fIerror()\fR when using the first calling style.
.SS "\fIerror()\fP"
.IX Subsection "error()"
.Vb 1
\&        my $error = $parser\->error();
.Ve
.PP
Returns the last error, or the empty string if no error occurred.
.PP
If you want to catch warnings from the parser, enable catching
of warnings or errors:
.PP
.Vb 1
\&        $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();
\&          }
.Ve
.PP
See Graph::Easy::Base for more details on error/warning message capture.
.SS "\fIparse_error()\fP"
.IX Subsection "parse_error()"
.Vb 1
\&        $parser\->parse_error( $msg_nr, @params);
.Ve
.PP
Sets an error message from a message number and replaces embedded
templates like \f(CW\*(C`##param1##\*(C'\fR with the passed parameters.
.SS "\fI_parse_attributes()\fP"
.IX Subsection "_parse_attributes()"
.Vb 2
\&        my $attributes = $parser\->_parse_attributes( $txt, $class );
\&        my ($att, $multiples) = $parser\->_parse_attributes( $txt, $class );
.Ve
.PP
\&\fBInternal usage only\fR. Takes a text like this:
.PP
.Vb 1
\&        attribute: value;  attribute2 : value2;
.Ve
.PP
and returns a hash with the attributes.
.PP
In list context, also returns the max count of multiple attributes, e.g.
3 when it encounters something like \f(CW\*(C`red|green|blue\*(C'\fR. When
.SH "EXPORT"
.IX Header "EXPORT"
Exports nothing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Graph::Easy. Graph::Easy::Parser::Graphviz and Graph::Easy::Parser::VCG.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 2004 \- 2007 by Tels <http://bloodgate.com>
.PP
See the \s-1LICENSE\s0 file for information.