NAME
GraphViz2::Marpa::Parser - A Perl parser for Graphviz dot files. Input comes from GraphViz2::Marpa::Lexer.
Synopsis
- o Display help
-
perl scripts/lex.pl -h perl scripts/parse.pl -h perl scripts/g2m.pl -h
- o Run the lexer
-
perl scripts/lex.pl -input_file x.gv -lexed_file x.lex x.gv is a Graphviz dot file. x.lex will be a CSV file of lexed tokens.
- o Run the parser without running the lexer or the default renderer
-
perl scripts/parse.pl -lexed_file x.lex -parsed_file x.parse x.parse will be a CSV file of parsed tokens.
- o Run the parser and the default renderer
-
perl scripts/parse.pl -lexed_file x.lex -parsed_file x.parse -output_file x.rend x.rend will be a Graphviz dot file.
- o Run the lexer, parser and default renderer
-
perl scripts/g2m.pl -input_file x.gv -lexed_file x.lex -parsed_file x.parse -output_file x.rend
Description
GraphViz2::Marpa::Lexer provides a Marpa::XS-based parser for http://www.graphviz.org/ dot files.
The input is expected to be, via RAM or a CSV file, from GraphViz2::Marpa::Lexer.
Demo lexer/parser output: http://savage.net.au/Perl-modules/html/graphviz2.marpa/index.html.
State Transition Table: http://savage.net.au/Perl-modules/html/graphviz2.marpa/default.stt.html.
Command line options and object attributes: http://savage.net.au/Perl-modules/html/graphviz2.marpa/code.attributes.html.
My article on this set of modules: http://www.perl.com/pub/2012/10/an-overview-of-lexing-and-parsing.html.
The Marpa grammar as an image: http://savage.net.au/Ron/html/graphviz2.marpa/Marpa.Grammar.svg. This image was created with Graphviz via GraphViz2.
Installation
Install GraphViz2::Marpa as you would for any Perl
module:
Run:
cpanm GraphViz2::Marpa
or run:
sudo cpan GraphViz2::Marpa
or unpack the distro, and then either:
perl Build.PL
./Build
./Build test
sudo ./Build install
or:
perl Makefile.PL
make (or dmake or nmake)
make test
make install
Constructor and Initialization
new()
is called as my($parser) = GraphViz2::Marpa::Parser -> new(k1 => v1, k2 => v2, ...)
.
It returns a new object of type GraphViz2::Marpa::Parser
.
Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. maxlevel()]):
- o lexed_file => $aLexedOutputFileName
-
Specify the name of a CSV file of lexed tokens to read. This file can be output from the lexer.
Default: ''.
The default means the file is not read.
The value supplied by the 'tokens' option takes preference over the 'lexed_file' option.
See the distro for data/*.lex.
- o logger => $aLoggerObject
-
Specify a logger compatible with Log::Handler, for the parser and renderer to use.
Default: A logger of type Log::Handler which writes to the screen.
To disable logging, just set 'logger' to the empty string (not undef).
- o maxlevel => $logOption1
-
This option affects Log::Handler.
See the Log::Handler::Levels docs.
Default: 'notice'.
- o minlevel => $logOption2
-
This option affects Log::Handler.
See the Log::Handler::Levels docs.
Default: 'error'.
No lower levels are used.
- o output_file => aRenderedOutputFileName
-
Specify the name of a file to be passed to the renderer.
Default: ''.
The default means the renderer is not called.
- o parsed_file => aParsedOutputFileName
-
Specify the name of a CSV file of parsed tokens to write. This file can be input to the default renderer.
Default: ''.
The default means the file is not written.
- o renderer => $aRendererObject
-
Specify a renderer for the parser to use.
Default: A object of type GraphViz2::Marpa::Renderer::GraphViz2.
- o report_items => $Boolean
-
Log the items recognised by the lexer.
Default: 0.
- o tokens => anArrayrefOfLexedTokens
-
Specify an arrayref of tokens output by the lexer.
The value supplied by the 'tokens' option takes preference over the 'lexed_file' option.
Methods
items()
Returns an arrayref of parsed tokens. Each element of this arrayref is a hashref. See "How is the parsed graph stored in RAM?" for details.
These parsed tokens do not bear a one-to-one relationship to the lexed tokens returned by the lexer's "GraphViz2::Marpa::Lexer" in items() method. However, they are (necessarily) very similar.
If you provide an output file by using the 'parsed_file' option to "new()", or the "parsed_file()" method, the file will have 2 columns, type and value.
E.g.: If the arrayref looks like:
...
{count => 10, name => '', type => 'start_attribute', value => '['},
{count => 11, name => '', type => 'attribute_id' , value => 'color'},
{count => 13, name => '', type => 'attribute_value', value => 'red'},
{count => 14, name => '', type => 'end_attribute' , value => ']'},
...
then the output file will look like:
"type","value"
...
start_attribute , "["
attribute_id , "color"
attribute_value , "red"
end_attribute , "]"
...
Usage:
my($parser) = GraphViz2::Marpa::Parser -> new(...);
# $parser -> items actually returns an object of type Set::Array.
if ($parser -> run == 0)
{
my(@items) = @{$parser -> items};
}
lexed_file([$lex_file_name])
'lexed_file' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the name of the CSV file of lexed tokens to read. This file can be output by the lexer.
The value supplied by the 'tokens' option takes preference over the 'lexed_file' option.
logger([$logger_object])
Here, the [] indicate an optional parameter.
Get or set the logger object.
To disable logging, just set 'logger' to the empty string, in the call to "new()".
This logger is passed to the default renderer.
maxlevel([$string])
'maxlevel' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the value used by the logger object.
This option is only used if GraphViz2::Marpa:::Lexer or GraphViz2::Marpa::Parser use or create an object of type Log::Handler. See Log::Handler::Levels.
minlevel([$string])
'minlevel' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the value used by the logger object.
This option is only used if GraphViz2::Marpa:::Lexer or GraphViz2::Marpa::Parser use or create an object of type Log::Handler. See Log::Handler::Levels.
new()
See "Constructor and Initialization" for details on the parameters accepted by "new()".
output_file([$file_name])
'output_file' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the name of the file to be passed to the renderer.
parsed_file([$file_name])
'parsed_file' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the name of the file of parsed tokens for the parser to write. This file can be input to the renderer.
renderer([$renderer_object])
'renderer' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the renderer object.
This renderer renders the tokens output by the parser.
report_items([$Boolean])
'report_items' is a parameter to "new()". See "Constructor and Initialization" for details.
The [] indicate an optional parameter.
Get or set the value which determines whether or not to log the items recognised by the parser.
run()
This is the only method the caller needs to call. All parameters are supplied to "new()" (or other methods).
Returns 0 for success and 1 for failure.
tokens([$arrayrefOfLexedTokens])
'tokens' is a parameter to "new()". See "Constructor and Initialization" for details.
Here, the [] indicate an optional parameter.
Get or set the arrayref of lexed tokens to process.
The value supplied by the 'tokens' option takes preference over the 'lexed_file' option.
utils([$aUtilsObject])
Here, the [] indicate an optional parameter.
Get or set the utils object.
Default: A object of type GraphViz2::Marpa::Utils.
FAQ
Why doesn't the lexer/parser handle my HTML-style labels?
Traps for young players:
- o The <br /> component must include the '/'. <br align='center'> is not accepted by Graphviz
- o The <br />'s attributes must use single quotes because output files use CSV with double quotes
See data/38.* for good examples.
How can I switch from Marpa::XS to Marpa::PP?
Install Marpa::PP manually. It is not mentioned in Build.PL or Makefile.PL.
Patch GraphViz2::Marpa::Parser (line 15) from Marpa::XS to Marpa:PP.
Then, run the tests which ship with this module. I've tried this, and the tests all worked. You don't need to install the code to test it. Just use:
shell> cd GraphViz2-Marpa-1.00/
shell> prove -Ilib -v t
Where are the scripts documented?
In "Scripts" in GraphViz2::Marpa.
How is the parsed graph stored in RAM?
Items are stored in an arrayref. This arrayref is available via the "items()" method.
These items have the same format as the arrayref of items returned by the items() method in GraphViz2::Marpa::Lexer, and the same as in GraphViz2::Marpa::Lexer::DFA.
However, the precise values in the 'type' field of the following hashref vary between the lexer and the parser.
Each element in the array is a hashref:
{
count => $integer, # 1 .. N.
name => '', # Unused.
type => $string, # The type of the token.
value => $value, # The value from the input stream.
}
$type => $value pairs used by the parser are listed here in alphabetical order by $type:
- o attribute_id => $id
- o attribute_value => $value
- o class_id => /^edge|graph|node$/
-
This represents 3 special tokens where the author of the dot file used one or more of the 3 words edge, graph, or node, to specify attributes which apply to all such cases. So:
node [shape = Msquare]
means all nodes after this point in the input stream default to having a square shape. Of course this can be overidden by another such line, or by any specific node having a shape as part of its list of attributes.
See data/51.* for sample code.
- o colon => ':'
-
This separates nodes from ports and ports from compass points.
- o compass_point => $id
- o digraph => $yes_no
-
'yes' => digraph and 'no' => graph.
- o edge_id => $id
-
$id is either '->' for a digraph or '--' for a graph.
- o end_attribute => ']'
-
This indicates the end of a set of attributes.
- o end_graph => $graph_count
-
This indicates the end of a graph or subgraph or any stand-alone {}, and - for subgraphs - preceeds the subgraph's 'end_subgraph'.
$graph_count increments by 1 each time 'graph_id' is detected in the input string, and decrements each time a matching 'end_graph' is detected.
- o end_subgraph => $subgraph_count
-
This indicates the end of a subgraph, and follows the subgraph's 'end_graph'.
$subgraph_count increments by 1 each time 'start_subgraph' is detected in the input string, and decrements each time a matching 'end_subgraph' is detected.
- o graph_id => $id
-
This indicates both the graph's $id and each subgraph's $id.
For graphs and subgraphs, the $id may be '' (the empty string).
- o node_id => $id
- o port_id => $id
- o start_attribute => '['
-
This indicates the start of a set of attributes.
- o start_graph => $graph_count
-
This indicates the start of a graph, or any stand-alone {}.
$graph_count increments by 1 each time 'graph_id' is detected in the input string, and decrements each time a matching 'end_graph' is detected.
- o start_subgraph => $subgraph_count
-
This indicates the start of a subgraph, and preceeds the subgraph's 'graph_id'.
$subgraph_count increments by 1 each time 'start_subgraph' is detected in the input string, and decrements each time a matching 'end_subgraph' is detected
- o strict => $yes_no
-
'yes' => strict and 'no' => not strict.
Consult data/*.lex and the corresponding data/*.parse for many examples.
How does the parser handle comments?
Comments are not expected in the input stream.
How does the parser interact with Marpa?
See http://savage.net.au/Perl-modules/html/graphviz2.marpa/Lexing.and.Parsing.with.Marpa.html.
Machine-Readable Change Log
The file CHANGES was converted into Changelog.ini by Module::Metadata::Changes.
Version Numbers
Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.
Support
Email the author, or log a bug on RT:
https://rt.cpan.org/Public/Dist/Display.html?Name=GraphViz2::Marpa.
Author
GraphViz2::Marpa was written by Ron Savage <ron@savage.net.au> in 2012.
Home page: http://savage.net.au/index.html.
Copyright
Australian copyright (c) 2012, Ron Savage.
All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html