The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
GraphViz2-Marpa-1.13
River stage one • 1 direct dependent • 1 total dependent
++
/ GraphViz2::Marpa::Renderer::GraphViz2

NAME

GraphViz2::Marpa::Renderer::GraphViz2 - A renderer for lexed and parsed Graphviz dot files

Synopsis

See "Synopsis" in GraphViz2::Marpa.

Description

GraphViz2::Marpa::Renderer provides a renderer for Graphviz (dot) graph definitions lexed by GraphViz2::Marpa::Lexer and parsed by GraphViz2::Marpa::Parser.

It outputs a string to the output file, which (ideally) exactly matches the graph definition input to the lexer, although there might be small differences in the line-by-line formatting.

This module is the default rendering engine for GraphViz2::Marpa.

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($renderer) = GraphViz2::Marpa::Renderer::GraphViz2 -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type GraphViz2::Marpa::Renderer::GraphViz2.

Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. maxlevel()]):

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.

To disable logging, just set 'logger' to the empty string (not undef).

o maxlevel => $level

This option is only used if this module creates an object of type Log::Handler. See Log::Handler::Levels.

Default: 'notice'.

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. This will contain the text string of the rendered graph.

Default: ''.

The default means the output file is not written. Use the "output_string()" method to retrieve the string.

o parsed_file => aParsedOutputFileName

Specify the name of a CSV file of parsed tokens to read.

Default: ''.

This file is read only if the token option (next) does not contain an arrayref of tokens to process.

o tokens => $arrayref

Specify the arrayref of tokens output by the parser.

The format of this array is documented in "How is the parsed graph stored in RAM?" in GraphViz2::Marpa::Parser.

Default: [].

Methods

format_attributes($attributes)

$attributes is an arrayref of interleaved attribute ids and values.

Called by "run()".

format_output()

Called by "run()".

Sets "output_string()".

items()

Returns an arrayref of items output by the renderer.

log($level, $s)

Calls $self -> logger -> $level($s) if ($self -> logger).

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 (not undef), in the call 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 GraphViz2::Marpa:::Lexer or GraphViz2::Marpa::Parser create 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 GraphViz2::Marpa:::Lexer or GraphViz2::Marpa::Parser create an object of type Log::Handler. See Log::Handler::Levels.

'minlevel' is a parameter to "new()". See "Constructor and Initialization" for details.

new()

See "Constructor and Initialization" for details on the parameters accepted by "new()".

output_file([$file_name])

Here, the [] indicate an optional parameter.

Get or set the name of the output file. This will contain the text string of the rendered graph.

If the output file name is not set, use the "output_string()" method to retrieve the string.

'output_file' is a parameter to "new()". See "Constructor and Initialization" for details.

output_string()

Returns the text string of the rendered graph.

To save the output in a file, use the 'output_file' parameter to "new()".

parsed_file([$file_name])

Here, the [] indicate an optional parameter.

Get or set the name of the file of parsed tokens to read.

run()

'parsed_file' is a parameter to "new()". See "Constructor and Initialization" for details.

Renders the arrayref of items as a string and, optionally, writes that string to the output file.

Calls "format_output()".

See "output_string()".

Returns 0 for success and 1 for failure.

tokens([$arrayref])

Here, the [] indicate an optional parameter.

Gets or sets the arrayref of tokens to be rendered.

'tokens' is a parameter to "new()". See "Constructor and Initialization" for details.

utils([$aUtilsObject])

Here, the [] indicate an optional parameter.

Get or set the utils object.

Default: A object of type GraphViz2::Marpa::Utils.

FAQ

If I input x.gv and output x.rend, should these 2 files be identical?

Yes - at least in the sense that running dot with them as input will produce the same output files. This is using the default renderer, of course.

Since comments in *.gv files are discarded, they can never be in the output files (*.lex, *.parse and *.rend).

So, if x.gv is formatted as I do, then x.rend will be formatted identically.

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