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

NAME

Graph::Easy::Marpa::Lexer - A Set::FA::Element-based lexer for Graph::Easy

Synopsis

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

Description

Graph::Easy::Marpa::Lexer provides a Set:FA::Element-based lexer 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::Lexer -> new(k1 => v1, k2 => v2, ...).

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

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

o cooked_file => $csv_file_name

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

This file can be input to Graph::Easy::Marpa::Parser.

o description => '[node.1]<->[node.2]'

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.

o input_file => $graph_file_name

Read the graph definition from this file.

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

The whole file is slurped in as 1 graph.

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

The 'description' key takes precedence over the 'input_file' key.

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::Lexer::DFA.

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 report_items => $Boolean

Calls "report()" to report, via the log, the items recognized by the state machine.

o report_stt => $Boolean

Calls Set::FA::Element.report(). Set min and max log levels to 'info' for this.

o stt_file => $stt_file_name

Specify which file contains the state transition table.

Default: ''.

The default value means the STT is read from the source code of Graph::Easy::Marpa::Lexer.

Candidate files are '', 'data/default.stt.csv' and 'data/default.stt.ods'.

The type of this file must be specified by the 'type' key.

Note: If you use stt_file => your.stt.ods and type => 'ods', Module::Load's load() will be used to load OpenOffice::OODoc. This module is no longer listed in Build.PL and Makefile.PL as a pre-req, so you will need to install it manually.

o type => $stt_file_type

Specify the type of the stt_file: '' for internal, csv for CSV, or ods for Open Office Calc spreadsheet.

Default is ''.

The default value means the STT is read from the source code of Graph::Easy::Marpa::Lexer.

This option must be used with the 'stt_file' key.

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

Methods

cooked_file([$csv_file_name])

The [] indicate an optional parameter.

Get or set the name of the CSV file to write containing the tokens which can be parsed by Graph::Easy::Marpa::Parser.

file([$file_name])

The [] indicate an optional parameter.

Get or set the name of the file the graph will be read from.

See "get_graph_from_file()".

get_graph_from_command_line()

If the caller has requested a graph be parsed from the command line, with the graph option to new(), get it now.

Called as appropriate by run().

get_graph_from_file()

If the caller has requested a graph be parsed from a file, with the file option to new(), get it now.

Called as appropriate by run().

graph([$graph])

The [] indicate an optional parameter.

Get or set the value of the Graph::Easy graph definition string.

input_file([$graph_file_name])

Here, the [] indicate an optional parameter.

Get or set the name of the file to read the graph definition from.

See also the description() method.

The whole file is slurped in as 1 graph.

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

The value supplied to the description() method takes precedence over the value read from the input file.

items()

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

See the "FAQ" for details.

log($level, $s)

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

log($level, $s)

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

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::Lexer::DFA.

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.

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 by the state machine.

report_items([0 or 1])

The [] indicate an optional parameter.

Get or set the value which determines whether or not to report the items recognised by the state machine.

report_stt([0 or 1])

The [] indicate an optional parameter.

Get or set the value which determines whether or not to report the parsed state transition table (STT).

run()

This is the only method the caller needs to call. All parameters are supplied to new().

Returns 0 for success and 1 for failure.

stt_file([$stt_file_name])

The [] indicate an optional parameter.

Get or set the name of the file containing the state transition table.

This option is used in conjunction with the type() option.

timeout($seconds)

The [] indicate an optional parameter.

Get or set the timeout for how long to run the DFA.

tokens()

Returns an arrayref of cooked tokens. Each element of this arrayref is an arrayref of 2 elements:

o The type of the token
o The value of the token

If you provide an output file by using the cooked_file option to new(), or the cooked_file() method, the tokens written to that file are exactly the same as the tokens returned by tokens().

E.g.: If the cooked file looks like:

        "key","value"
        left_bracket       , [
        node_name_id       , 'Murrumbeena'
        right_bracket      , ]
        left_brace         , {
        attribute_name_id  , 'color'
        colon              , :
        attribute_value_id , 'blue'
        semi_colon         , ;
        right_brace        , }
        ...

then the arrayref will contain:

        ['left_bracket',       '[']
        ['node_name_id',       'Murrumbeena']
        ['right_bracket',      ']']
        ['left_brace',         '{']
        ['attribute_name_id',  'color']
        ['colon',              ':']
        ['attribute_value_id', 'blue']
        ['semi_colon',         ';']
        ['right_brace',        '}']
        ...

If you look at the source code for the run() method in Graph::Easy::Marpa, you'll see this arrayref can be passed directly as the value of the tokens key in the call to Graph::Easy::Marpa::Parser's new().

type([$type])

The [] indicate an optional parameter.

Get or set the value which determines what type of stt_file is read.

FAQ

Where are the functions named in the STT?

In Graph::Easy::Marpa::Lexer::DFA.

How is the lexed or parsed graph stored in RAM?

Items are stored in an arrayref. This arrayref is available via the "items()" method.

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

Each element in the array is a hashref, listed here in alphabetical order by type.

Note: Items are numbered from 1 up.

o Attributes

The attribute name must match /^[a-z][a-z0-9_]*$/.

The attribute value is everything up to the next ';' or '}'.

The name and value are separated by a ':'.

An attribute can belong to a graph, node or an edge. An attribute definition of '{color: red;}' would produce a hashref of:

        {
        count => $n,
        name  => 'color',
        type  => 'attribute',
        value => 'red',
        }

An attribute definition of '{color: red; shape: circle;}' will produce 2 hashrefs, i.e. 2 sequential elements in the arrayref:

        {
        count => $n,
        name  => 'color',
        type  => 'attribute',
        value => 'red',
        }

        {
        count => $n,
        name  => 'shape',
        type  => 'attribute',
        value => 'circle',
        }

Attribute hashrefs appear in the arrayref immediately after the item (edge, group, node) to which they belong. For groups, this means they appear straight after the hashref whose type is 'pop_subgraph'.

o Classes and class attributes

These notes apply to the 4 class names, /^(?:edge|graph|group|node)$/, and all their subclasses.

Note: It does not make sense for a class of 'graph' to have any subclasses.

A class definition of 'edge {color: white}' would produce 2 hashrefs:

        {
        count => $n,
        name  => 'edge',
        type  => 'class_name',
        value => '',
        }

        {
        count => $n,
        name  => 'color',
        type  => 'attribute',
        value => 'white',
        }

A class definition of 'node.green {color: green; shape: square}' would produce 3 hashrefs:

        {
        count => $n,
        name  => 'node.green',
        type  => 'class_name',
        value => '',
        }

        {
        count => $n,
        name  => 'color',
        type  => 'attribute',
        value => 'green',
        }

        {
        count => $n,
        name  => 'shape',
        type  => 'attribute',
        value => 'square',
        }

Class and class attribute hashrefs always appear at the start of the arrayref of items.

o Edges

An edge definition of '->' would produce a hashref of:

        {
        count => $n,
        name  => '->',
        type  => 'edge',
        value => '',
        }
o Nodes

A node definition of '[Name]' would produce a hashref of:

        {
        count => $n,
        name  => 'Name',
        type  => 'node',
        value => '',
        }

A node can have a definition of '[]', which means it has no name. Such node are called anonymous (or invisible) because while they take up space in the output stream, they have no printable or visible characters in the output stream. See Graph::Easy for details.

Each anonymous node will have at least these 2 attributes:

        {
        count => $n,
        name  => 'color',
        type  => 'attribute',
        value => 'invis',
        }

        {
        count => $n,
        name  => 'label',
        type  => 'attribute',
        value => '',
        }

You can of course give your anonymous nodes any attributes, but they will be forced to have these 2 attributes.

Node names are case-sensitive.

o Subgraphs

A group produces 2 hashrefs, one at the start of the group, and one at the end.

A group defnition of '(Solar system: [Mercury] -> [Neptune])' would produce a hashref like this at the start, i.e. when the '(' - just before 'Solar' - is detected in the input stream:

        {
        count => $n,
        name  => 'Solar system',
        type  => 'push_subgraph',
        value => '',
        }

and a hashref like this at the end, i.e. when the ')' - just after '[Neptune]' - is detected:

        {
        count => $n,
        name  => 'Solar system',
        type  => 'pop_subgraph',
        value => '',
        }

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