The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Graph-Easy-Marpa-1.00
++
/ Graph::Easy::Marpa::Parser

NAME

Graph::Easy::Marpa::Parser - A Marpa-based parser for Graph::Easy

Synopsis

See "Data and Script Interaction" in Graph::Easy::Marpa.

Description

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

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::Parser -> new(k1 => v1, k2 => v2, ...).

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

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_name

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

Default is 'svg'.

o input_file => $csv_file_name

This is the name of the file to read containing the tokens (items) output from Graph::Easy::Marpa::Lexer.

o logger => $logger_object

Specify a logger object.

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

The default value is an object of type Log::Handler.

This logger is passed to Graph::Easy::Marpa::Renderer::GraphViz2.

o maxlevel => $level

This option is only used if Graph::Easy::Marpa:::Lexer or Graph::Easy::Marpa::Parser create an object of type Log::Handler. See Log::Handler::Levels.

The default 'maxlevel' is 'info'. A typical value is 'debug'.

o minlevel => $level

This option is only used if Graph::Easy::Marpa:::Lexer or Graph::Easy::Marpa::Parser create an object of type Log::Handler. See Log::Handler::Levels.

The default 'minlevel' is 'error'.

No lower levels are used.

o output_file => $output_file_name

If an output file name is supplied, and a rendering object is also supplied, then this call is made:

        $self -> renderer -> run
        (
        format      => $self -> format,
        items       => [$self -> items -> print],
        logger      => $self -> logger,
        output_file => $file_name,
        );

This is how the plotted graph is actually created.

o parsed_tokens_file => $token_file_name

This is the name of the file to write containing the tokens (items) output from Graph::Easy::Marpa::Parser.

The default value is '', meaning the file is not written.

See also the input_file, above.

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 default value is: 'TB' (top to bottom).

o renderer => $renderer_object

This is the object whose run() method will be called to render the result of parsing the cooked file received from Graph::Easy::Marpa::Lexer.

The format of the parameters passed to the renderer are documented in "run(%arg)" in Graph::Easy::Marpa::Renderer::GraphViz2, which is the default value for this object.

o report_items => $Boolean

Calls "report()" to report, via the log, the items recognized in the cooked file.

o tokens => $arrayref

This is an arrayref of tokens normally output by Graph::Easy::Marpa::Lexer.

In some test files, this arrayref is constructed manually, and the 'input_file' is not used.

See "tokens()" in Graph::Easy::Marpa::Lexer for a detailed explanation.

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).

format([$format])

Here, the [] indicate an optional parameter.

Get or set the format of the output file.

grammar()

Initializes and returns a data structure of type Marpa::Grammar. This defines the acceptable syntax of the precise subset of Graph::Easy definitions which this module is able to parse.

Note that the method grammar() calls (via Marpa) various helper functions (i.e. not methods), including edge_id(). The latter applies a restriction to the definition of edges in the grammar.

Specifically, edges must currently match this regexp: /^<?(-|=|\.|~|- |= |\.-|\.\.-){1,}>?$/, which I've gleaned from the Graph::Easy docs at Edges.

Later, the allowable syntax will be exanded to accept special arrow heads, etc.

Also, since edges can have attributes, such attributes are another method of describing the desired edge's characteristics. That is, besides using a string matching that regexp to specify what the edge looks like when plotted.

input_file([$cooked_file_name])

The [] indicate an optional parameter.

Get or set the name of the cooked file to read containing the tokens which has been output by Graph::Easy::Marpa::Lexer.

items()

Returns a object of type Set::Array, which is an arrayref of items output by the parser.

See the "FAQ" for details.

See also run(), below.

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.

This logger is passed to Graph::Easy::Marpa::Renderer::GraphViz2.

maxlevel([$string])

Here, the [] indicate an optional parameter.

Get or set the value used by the logger object.

This option is only used if Graph::Easy::Marpa:::Lexer or Graph::Easy::Marpa::Parser create an object of type Log::Handler. See Log::Handler::Levels.

minlevel([$string])

Here, the [] indicate an optional parameter.

Get or set the value used by the logger object.

This option is only used if Graph::Easy::Marpa:::Lexer or Graph::Easy::Marpa::Parser create an object of type Log::Handler. See Log::Handler::Levels.

output_file([$output_file_name])

Here, the [] indicate an optional parameter.

Get or set the name of the file to which the renderer will write to resultant graph.

This is how the plotted graph is actually created.

If no renderer is supplied, or no output file is supplied, nothing is written.

parsed_tokens_file([$token_file_name])

Here, the [] indicate an optional parameter.

Get or set the name of the file to write containing the tokens (items) output from Graph::Easy::Marpa::Parser.

rankdir([$direction])

Here, the [] indicate an optional parameter.

Get or set the rankdir of the graph as a whole.

read_csv_file($file_name)

Read the named CSV file into ann arrayref of hashrefs.

renderer([$renderer_object])

Here, the [] indicate an optional parameter.

Get or set the value of the object which will do the rendering.

If an output file name is supplied, and a rendering object is also supplied, then this call is made:

        $self -> renderer -> run
        (
        format      => $self -> format,
        items       => [$self -> items -> print],
        logger      => $self -> logger,
        output_file => $file_name,
        );

This is how the plotted graph is actually created.

report()

Report, via the log, the list of items recognized in the cooked file.

report_items([$Boolean])

Here, the [] indicate an optional parameter.

Get or set the value which determines whether or not "report()" is called.

run()

Runs the Marpa-based parser on the input_file.

Returns 0 for success and 1 for failure, or dies with an error message.

See t/attr.t, scripts/parse.pl and scripts/parse.sh.

The end result is an arrayref, accessible with the items() method, of hashrefs representing items in the input stream.

The structure of this arrayref of hashrefs is discussed in the "FAQ".

tokens([$arrayref])

Here, the [] indicate an optional parameter.

Get or set an arrayref of tokens normally output by Graph::Easy::Marpa::Lexer.

In some test files, this arrayref is constructed manually, and the 'input_file' is not used.

FAQ

How is the parsed graph stored in RAM?

See "FAQ" in Graph::Easy::Marpa::Lexer.

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=Graph::Easy::Marpa.

Author

Graph::Easy::Marpa was written by Ron Savage <ron@savage.net.au> in 2011.

Home page: http://savage.net.au/index.html.

Copyright

Australian copyright (c) 2011, 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