NAME

Graph::Easy::Marpa - A Marpa-based parser for Graph::Easy::Marpa-style Graphviz files

Synopsis

Sample Code

        #!/usr/bin/env perl

        use strict;
        use warnings;

        use Graph::Easy::Marpa;

        use Getopt::Long;

        use Pod::Usage;

        # -----------------------------------------------

        my($option_parser) = Getopt::Long::Parser -> new();

        my(%option);

        if ($option_parser -> getoptions
        (
                \%option,
                'description=s',
                'dot_input_file=s',
                'format=s',
                'help',
                'input_file=s',
                'logger=s',
                'maxlevel=s',
                'minlevel=s',
                'output_file=s',
                'rankdir=s',
                'report_tokens=i',
                'token_file=s',
        ) )
        {
                pod2usage(1) if ($option{'help'});

                # Return 0 for success and 1 for failure.

                exit Graph::Easy::Marpa -> new(%option) -> run;
        }
        else
        {
                pod2usage(2);
        }

This is shipped as scripts/parse.pl, although the shipped version has built-in help.

Run 'perl -Ilib scripts/parse.pl -h' for sample demos.

Sample output

Unpack the distro and copy html/*.html and html/*.svg to your web server's doc root directory.

Then, point your browser at 127.0.0.1/index.html.

Or, hit http://savage.net.au/Perl-modules/html/graph.easy.marpa/index.html.

Modules

o Graph::Easy::Marpa

The current module, which documents the set of modules.

It uses Graph::Easy::Marpa::Parser and Graph::Easy::Marpa::Renderer::GraphViz2, and 'dot', to render a Graph::Easy::Marpa-syntax file into a (by default) *.svg file.

See scripts/parse.pl and scripts/parse.sh.

o Graph::Easy::Marpa::Parser

See Graph::Easy::Marpa::Parser.

Accepts a graph definition in the Graph::Easy::Marpa language and builds a data structure representing the graph.

See scripts/parse.pl and scripts/parse.sh.

o Graph::Easy::Marpa::Renderer::GraphViz2

This is the default renderer, and can output a dot file, suitable for inputting to the dot program.

Also, it can use GraphViz2 to call dot and write dot's output to yet another file.

o Graph::Easy::Marpa::Actions

This is a file of methods called by Marpa::R2 as callbacks, during the parse.

End-users have no need to call any of its methods.

o Graph::Easy::Marpa::Config

This manages the config file, which contains a HTML template used by scripts/generate.index.pl.

End-users have no need to call any of its methods.

o Graph::Easy::Marpa::Filer

Methods to help with reading sets of files.

End-users have no need to call any of its methods.

o Graph::Easy::Marpa::Utils

Methods to help with testing and generating the demo page.

See http://savage.net.au/Perl-modules/html/graph.easy.marpa/index.html.

End-users have no need to call any of its methods.

Description

Graph::Easy::Marpa provides a Marpa-based parser for Graph::Easy::Marpa-style graph definitions.

Such graph definitions are wrappers around Graphviz's DOT language. Therefore this module is a pre-processor for DOT files.

The default renderer mentioned above, Graph::Easy::Marpa::Renderer::GraphViz2, can be used to convert the graph into a image.

See "Data Files and Scripts" for details.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

Install Graph::Easy::Marpa as you would for any Perl module:

Run:

        cpanm Graph::Easy::Marpa

or run:

        sudo cpan Graph::Easy::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) = Graph::Easy::Marpa -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type Graph::Easy::Marpa.

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

o description => $graph_description_string

Specify a string for the graph definition.

You are strongly encouraged to surround this string with '...' to protect it from your shell.

See also the input_file key to read the graph from a file.

The description key takes precedence over the input_file key.

The value for description is passed to Graph::Easy::Marpa::Parser.

Default: ''.

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.

If '', the file will not be created.

The value for dot_input_file is passed to Graph::Easy::Marpa::Renderer::GraphViz2.

Default: ''.

o format => $format_name

This is the format of the output file, to be created by the renderer.

The value for format is passed to Graph::Easy::Marpa::Renderer::GraphViz2.

Default: 'svg'.

o input_file => $graph_file_name

Read the graph definition from this file.

See also the description key to read the graph from the command line.

The whole file is slurped in as a single graph.

The first few lines of the file can start with /^\s*#/, and will be discarded as comments.

The description key takes precedence over the input_file key.

The value for input_file is passed to Graph::Easy::Marpa::Parser.

Default: ''.

o logger => $logger_object

Specify a logger object.

The default value triggers creation of an object of type Log::Handler which outputs to the screen.

To disable logging, just set logger to the empty string.

The value for logger is passed to Graph::Easy::Marpa::Parser and to Graph::Easy::Marpa::Renderer::GraphViz2.

Default: undef.

o maxlevel => $level

This option is only used if an object of type Log::Handler is created. See logger above.

Data Files and Scripts

Overview of the Data Flow

The parser works like this:

o You use the parser Graph::Easy::Marpa::Parser directly ...

Call Graph::Easy::Marpa::Parser -> new(%options).

o ... or, you use Graph::Easy::Marpa, which calls the parser and then the renderer

Call Graph::Easy::Marpa -> new(%options).

Of course, the renderer is only called if the parser exits without error.

Details:

o Input a graph definition

This comes from the description parameter to new(), or is read from a file with the input_file parameter.

See new(input_file => $graph_file_name) or new(description => $graph_string) above for details.

A definition looks like '[node.1]{a:b;c:d}->{e:f;}->{g:h}[node.2]{i:j}->[node.3]{k:l}'.

Here, node names are: node.1, node.2 and node.3.

Edge names are: '->' for directed graphs, or '--' for undirected graphs.

Nodes and edges can have attributes, very much like CSS. The attributes in this sample are meaningless, and are just to demonstrate the syntax.

And yes, unlike the original Graph::Easy syntax, you can use a series of edges between 2 nodes, with different attributes, as above.

See http://www.graphviz.org/content/attrs for a long list of the attributes available for Graphviz.

o Parse the graph

After the parser runs successfully, the parser object holds a Set::Array object of tokens representing the graph.

See "How is the parsed graph stored in RAM?" in Graph::Easy::Marpa::Parser for details.

o Output the parsed tokens

See new(token_file => $csv_file_name) above for details.

o Call the renderer

Data and Script Interaction

Sample input files for the parser are in data/*.ge. Sample output files are in data/*.tokens.

o scripts/parse.pl and scripts/parser.sh

These use Graph::Easy::Marpa::Parser.

They run the parser on one *.ge input file, and produce an arrayref of items.

Run scripts/parse.pl -h for samples of how to drive it.

Try:

        cat data/node.05.ge
        perl -Ilib scripts/parse.pl -i data/node.05.ge -t data/node.05.tokens -re 1

You can use scripts/parse.sh to simplify this process:

        scripts/parse.sh data/node.05.ge data/node.05.tokens -re 1
        scripts/parse.sh data/subgraph.12.ge data/subgraph.12.tokens -re 1

Methods