The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MarpaX-Demo-StringParser-2.04
River stage zero No dependents
++
/ MarpaX::Demo::StringParser::Renderer

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.

The Marpa homepage.

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