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 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 maxlevel => $level

This option affects Log::Handler. See Log::Handler::Levels.

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

o minlevel => $level

This option affects 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], output_file => $file_name);

This is how the plotted graph is actually created.

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 token_file => $token_file_name

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

See also the input_file, above.

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.

Methods

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.

items()

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

See the "FAQ" in Graph::Easy::Marpa for details.

These items are not the same as the arrayref of items returned by the items() methods in Graph::Easy::Marpa::DFA and Graph::Easy::Marpa::Lexer.

See also run(), below.

log($level, $s)

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

logger()

Returns a object of type Log::Handler.

maxlevel([$level])

The [] indicate an optional parameter.

Get or set the value of the logger's maxlevel option.

minlevel([$level])

The [] indicate an optional parameter.

Get or set the value of the logger's minlevel option.

read_csv_file($file_name)

Read the named CSV file into ann arrayref of hashrefs.

report()

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

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" in Graph::Easy::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=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

cpanm Graph::Easy::Marpa

perl -MCPAN -e shell
install Graph::Easy::Marpa