NAME
MarpaX::Demo::StringParser::Renderer - The default rendering engine for MarpaX::Demo::StringParser
Synopsis
See "Synopsis" in MarpaX::Demo::StringParser.
In particular, "DASH" in MarpaX::Demo::StringParser describes DASH, the Graphviz-like graph definition language supported by these modules.
See also scripts/render.pl and scripts/render.sh.
Description
This module is the default rendering engine for MarpaX::Demo::StringParser.
It provides a GraphViz2-based renderer for DASH, as parsed by MarpaX::Demo::StringParser.
For more details, see "Description" in MarpaX::Demo::StringParser.
Installation
Install MarpaX::Demo::StringParser as you would for any Perl
module:
Run:
cpanm MarpaX::Demo::StringParser
or run:
sudo cpan MarpaX::Demo::StringParser
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) = MarpaX::Demo::StringParser::Renderer -> new(k1 => v1, k2 => v2, ...)
.
It returns a new object of type MarpaX::Demo::StringParser::Renderer
.
Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. maxlevel()]):
- o dot_input_file => $file_name
-
Specify the name of a file that the rendering engine can write to, which will contain the input to dot (or whatever). This is good for debugging.
Default: ''.
If '', the file will not be created.
- o format => $format
-
This is the format of the output file.
You can also pass this value into "run(%arg)".
The value passed in to run() takes precedence over the value passed in to new().
Default: 'svg'.
- o graphviz_tree => $Boolean
-
Specify whether (1) or not (0) to display the tree of nodes after this module has inserted any anonymous nodes necessary to keep Graphviz happy.
Default: 0.
- o logger => $logger_object
-
Specify a logger object.
To disable logging, just set logger to the empty string.
Default: An object of type Log::Handler.
- o maxlevel => $level
-
This option is only used if this module creates an object of type Log::Handler.
See Log::Handler::Levels.
Default: 'notice'. A typical choice is 'info' or 'debug'.
- o minlevel => $level
-
This option is only used if this module creates an object of type Log::Handler.
See Log::Handler::Levels.
Default: 'error'.
No lower levels are used.
- o output_file => $file_name
-
Specify the name of the output file to write.
You can also pass this value into "run(%arg)".
The value passed in to run() takes precedence over the value passed in to new().
Default: ''.
- o rankdir => $direction
-
$direction must be one of: LR or RL or TB or BT.
Specify the rankdir of the graph as a whole.
The value for rankdir is passed to MarpaX::Demo::StringParser::Renderer.
Default: 'TB'.
Methods
dot_input_file([$file_name])
Here, the [] indicate an optional parameter.
Get or set the name of the file into which the rendering engine will write to input to dot (or whatever).
You can pass 'dot_input_file' as a key into new() and run().
The value passed in to run() takes precedence over the value passed in to new().
'dot_input_file' is a parameter to "new()". See "Constructor and Initialization" for details.
format([$format])
Here, the [] indicate an optional parameter.
Get or set the format of the output file.
You can pass 'format' as a key into new() and run().
The value passed in to run() takes precedence over the value passed in to new().
'format' is a parameter to "new()". See "Constructor and Initialization" for details.
graphviz_tree([$Boolean])
Here, the [] indicate an optional parameter.
Get or set whether or not to display the tree of nodes after this module has inserted any anonymous nodes necessary to keep Graphviz happy.
You can pass 'graphviz_tree' as a key into new() and run().
The value passed in to run() takes precedence over the value passed in to new().
'graphviz_tree' is a parameter to "new()". See "Constructor and Initialization" for details.
log($level, $s)
If a logger is defined, this logs the message $s at level $level.
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.
You can pass 'logger' as a key into new() and run().
The value passed in to run() takes precedence over the value passed in to new().
'logger' is a parameter to "new()". See "Constructor and Initialization" for details.
maxlevel([$string])
Here, the [] indicate an optional parameter.
Get or set the value used by the logger object.
This option is only used if this module creates an object of type Log::Handler.
See Log::Handler::Levels.
'maxlevel' is a parameter to "new()". See "Constructor and Initialization" for details.
minlevel([$string])
Here, the [] indicate an optional parameter.
Get or set the value used by the logger object.
This option is only used if this module creates an object of type Log::Handler.
See Log::Handler::Levels.
'minlevel' is a parameter to "new()". See "Constructor and Initialization" for details.
output_all_edges($graph_subtree)
Walk the tree and output, via "output_node($node)", all edges and the nodes on either side of it.
output_all_nodes($graph_subtree)
Walk the tree and output, via "output_node($node)", all nodes.
output_node($node)
Convert, via GraphViz2, the node into DOT format.
This is a tree node, not a DOT node.
output_file([$file_name])
Here, the [] indicate an optional parameter.
Get or set the name of the output file.
You can pass 'output_file' as a key into new() and run().
The value passed in to run() takes precedence over the value passed in to new().
'output_file' is a parameter to "new()". See "Constructor and Initialization" for details.
rankdir([$direction])
Here, the [] indicate an optional parameter.
Get or set the rankdir of the graph as a whole.
You can pass 'rankdir' as a key into new() and run().
The value passed in to run() takes precedence over the value passed in to new().
'rankdir' is a parameter to "new()". See "Constructor and Initialization" for details.
run(%arg)
Renders a set of items as an image, using GraphViz2.
Keys and values in %arg are (see for "Constructor and Initialization" details):
- o dot_output_file => $file_name
- o format => $format
- o graphtree_viz => $Boolean
- o output_file => $file_name
- o rankdir => $string
FAQ
What is DASH?
See "DASH" in MarpaX::Demo::StringParser.
This module does not use DASH. Rather, it interprets the tree of parsed nodes output by MarpaX::Demo::StringParser.
How is the parsed graph stored in RAM?
See "How is the parsed graph stored in RAM?" in MarpaX::Demo::StringParser.
What are the defaults for GraphViz2?
GraphViz2 -> new
(
edge => {color => 'grey'},
global => {directed => $self -> _determine_digraph_status},
graph => {rankdir => $self -> rankdir},
logger => $self -> logger,
node => {shape => 'oval'},
verbose => 0,
)
Why is _determine_digraph_status() undocumented?
It would never be overridden by a sub-class.
It determines if the output DOT file contains 'graph' or 'digraph', by examining the first edge in the tree. '--' means 'graph' and '->' means 'digraph'.
Yes, I know I just documented it! It's an Easter Egg.
See also
Marpa::R2, GraphViz2 and GraphViz2::Marpa.
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=MarpaX::Demo::StringParser.
Author
MarpaX::Demo::StringParser was written by Ron Savage <ron@savage.net.au> in 2013.
Home page: http://savage.net.au/index.html.
Copyright
Australian copyright (c) 2013, 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