NAME

MarpaX::Languages::Lua::Parser - A Lua source code parser

Synopsis

#!/usr/bin/env perl

use strict;
use warnings;

use MarpaX::Languages::Lua::Parser;

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

my($input_file_name) = shift || die "Usage: $0 a_lua_source_file_name\n";
my($parser)          = MarpaX::Languages::Lua::Parser -> new(input_file_name => $input_file_name);

$parser -> run;

print map{"$_\n"} @{$parser -> output_tokens};

This script ships as scripts/synopsis.pl. Run it as:

shell> perl -Ilib scripts/synopsis.pl lua.sources/echo.lua

See also scripts/parse.file.pl for code which takes command line parameters. For help, run:

shell> perl -Ilib scripts/parse.file.pl -h

Description

MarpaX::Languages::Lua::Parser parses Lua source code files.

The result is stored in a tree managed by Tree::DAG_Node.

A list of scalar tokens from this tree is stored in an arrayref.

See the FAQ question "How do I get output from this module?" for details.

Installation

Install MarpaX::Languages::Lua::Parser as you would for any Perl module:

Run:

cpanm MarpaX::Languages::Lua::Parser

or run:

sudo cpan MarpaX::Languages::Lua::Parser

or unpack the distro, and then:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

Constructor and Initialization

new() is called as my($parser) = MarpaX::Languages::Lua::Parser -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type MarpaX::Languages::Lua::Parser.

Key-value pairs accepted in the parameter list (see also the corresponding methods [e.g. "input_file_name([$string])"]):

o attributes => $Boolean

When set to 1, metadata attached to each tree node is included in the output.

If you set the "maxlevel()" to 'debug', this tree is printed to the log.

Default: 0.

o input_file_name => $string

The name the input file to be parsed.

This option is mandatory.

Default: ''.

o logger => aLog::HandlerObject

By default, an object of type Log::Handler is created which prints to STDOUT, but given the default setting (maxlevel => 'notice'), nothing is actually printed.

See maxlevel and minlevel below.

Set logger to '' (the empty string) to stop a logger being created.

Default: undef.

o maxlevel => logOption1

This option affects Log::Handler objects.

See the Log::Handler::Levels docs.

Typical values: 'info', 'debug'.

See the FAQ question "How do I get output from this module?" for details.

See also the help output by scripts/parse.file.pl -h.

Default: 'notice'.

o minlevel => logOption2

This option affects Log::Handler object.

See the Log::Handler::Levels docs.

Default: 'error'.

No lower levels are used.

o output_file_name => $string

The name of the text file to be written.

If not set, nothing is written.

The items written, one per line, are as returned by "output_tokens".

Default: ''.

Methods

attributes([$Boolean])

Here, the [] indicate an optional parameter.

Gets or sets the attributes option.

Note: The value passed to Tree::DAG_Node's tree2string() method is (1 - $Boolean).

See the FAQ question "How do I get output from this module?" for details.

attributes is a parameter to "new()".

input_file_name([$string])

Here, the [] indicate an optional parameter.

Get or set the name of the file to parse.

See lua.sources/*.lua for sample input.

Note: input_file_name is a parameter to new().

log($level, $s)

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

logger([$log_object])

Here, the [] indicate an optional parameter.

Get or set the log object.

$log_object must be a Log::Handler-compatible object.

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

Note: logger is a parameter to new().

maxlevel([$string])

Here, the [] indicate an optional parameter.

Get or set the value used by the logger object.

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

Typical values: 'info', 'debug'.

See the FAQ question "How do I get output from this module?" for details.

Note: maxlevel is a parameter to new().

minlevel([$string])

Here, the [] indicate an optional parameter.

Get or set the value used by the logger object.

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

Note: minlevel is a parameter to new().

new()

This method is auto-generated by Moo.

output_file_name([$string])

Here, the [] indicate an optional parameter.

Get or set the name of the file to write.

The tokens written are as returned from "output_tokens".

Note: output_file_name is a parameter to new().

output_tokens()

Returns an arrayref of tokens output by the parse, one per line. These tokens are pushed onto the stack by walking the tree returned by the renderer, which is an object of type Data::RenderAsTree. The renderer is run by passing it the output from the call to Marpa's value() method. See "renderer()".

If you set the "maxlevel()" to 'info', these tokens are printed to the log.

See scripts/synopsis.pl for accessing this arrayref.

See lua.output/*.txt for sample output.

renderer()

Returns the object of type Data::RenderAsTree, which takes the output from the call to Marpa's value() method and converts it into an object of type "Tree::DAG_Node".

If you set the "maxlevel()" to 'debug', this tree is printed to the log.

run([%args])

The method which does all the work.

%args is a hash with this optional (key => value) pair:

o input_file_name => $in_file_name
o output_file_name => $out_file_name

File names specified in the call to run() take precedence over file names specified to "new()".

Returns 0 for a successful parse and 1 for failure.

The code dies if Marpa::R2 itself can't parse the given input file.

Note: input_file_name and output_file_name are parameters to "new()".

FAQ

Why did you store Lua's BNF in a DATA section?

This avoids problems with single- and double-quotes in the BNF, and the allegedly unknown escape sequences \v etc too.

How do I get output from this module?

In various ways:

o Call the "output_tokens()" method

Then, process the arrayref returned.

o Call the "renderer()" method

This will return an object of type Data::RenderAsTree, and from there you can call that object's root() method, to get access to the tree itself. See this module's render() method for sample code.

o Set maxlevel to 'info'.

This writes the output tokens to the log, one per line.

See the render() method for sample code.

o Set maxlevel to 'debug'.

This writes the output tokens to the log, one per line, and also writes to the log the tree returned by passing the return value of Marpa's value() method to the renderer. The renderer is an object of type Data::RenderAsTree, and outputs a tree managed by Tree::DAG_Node.

See the "run([%args])" method for sample code.

o Set the output_file_name to a non-empty string

In this case the code will walk the tree just mentioned, and output the scalar items, one per line, to this file.

o All of the above

How do I interpret the output?

For help with this, try the IRC channel irc.freenode.net#marpa.

What that really means is that neither Jeffrey no anyone else imposes any kind of restriction on what you may do with the output, or with how you may interpret it.

Where is Marpa's home page?

http://savage.net.au/Marpa.html.

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.

Repository

https://github.com/ronsavage/MarpaX-Languages-Lua-Parser

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=MarpaX::Languages::Lua::Parser.

Credits

Jeffrey Kegler wrote the code, and posted a link on the IRC chat channel mentioned above.

See http://irclog.perlgeek.de/marpa/2015-06-13.

Author

MarpaX::Languages::Lua::Parser was packaged by Ron Savage <ron@savage.net.au> in 2015.

Homepage: http://savage.net.au/.

Copyright

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 2.0, a copy of which is available at:
http://www.opensource.org/licenses/index.html

To install MarpaX::Languages::Lua::Parser, copy and paste the appropriate command in to your terminal.

cpanm

cpanm MarpaX::Languages::Lua::Parser

CPAN shell

perl -MCPAN -e shell
install MarpaX::Languages::Lua::Parser

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

Synopsis

Description

Installation

Constructor and Initialization

Methods

attributes([$Boolean])

input_file_name([$string])

log($level, $s)

logger([$log_object])

maxlevel([$string])

minlevel([$string])

new()

output_file_name([$string])

output_tokens()

renderer()

run([%args])

FAQ

Why did you store Lua's BNF in a __DATA__ section?

How do I get output from this module?

How do I interpret the output?

Where is Marpa's home page?

Machine-Readable Change Log

Version Numbers

Repository

Support

Credits

Author

Copyright

Module Install Instructions

Why did you store Lua's BNF in a DATA section?