Guacamole - A parser toolkit for Standard Perl
version 0.008
use Guacamole; my ($ast) = Guacamole->parse($string);
Guacamole is a Perl parser toolkit.
It can:
Parse Standard Perl
This is explained in this document.
For Standard Perl, see the next clause.
Check a file is written in Standard Perl
This is done by standard, which is where Standard Perl is described.
Lint your code
See Guacamole::Linter.
Deparse your code
See Guacamole::Deparse.
Rewrite your code
There is a proof-of-concept for this and we hope to provide this as a framework.
Guacamole only works on Standard Perl. You can read about it here: standard.
my ($ast) = Guacamole->parse($string);
To parse a string, call Gaucamole's parse method. (This might turn to an object-oriented interface in the future.)
parse
It returns a list of results. If it ever returns more than one, this is a bug that means it couldn't ambiguously parse something. This will later be enforced in the interface. The current interface is not official.
Guacamole returns an AST with two types of nodes.
my ($ast) = Guacamole->parse('$foo = 1');
The above will generate a larger AST than you imagine (which might be pruned in the future). We'll focus on two types of nodes that will appear above.
Rules are the top level expressions. They include the definitions for rules. They include information on location in the file, length, line, and column.
$rule = { 'children' => [...], 'column' => 2, 'length' => 3, 'line' => 1, 'name' => 'VarIdentExpr', 'start_pos' => 1, 'type' => 'rule', },
This rule is a VarIdentExpr which is an expression for a variable identity.
VarIdentExpr
In the code above, it refers to the foo in $foo - which is the identity itself.
foo
$foo
It has one child, described below under Lexemes.
Lexemes
The child for the VarIdentExpr rule should be the value of the identity.
$lexeme = { 'name' => '', 'type' => 'lexeme', 'value' => 'foo', };
The name attribute for all lexemes is empty. This is to make it easy to write code that checks for the value of a rule without having to check whether it's a rule first.
name
Damian Conway
For helping understand what is feasible, what isn't, and why, and for having infinite patience in explaining these.
Jeffrey Kegler
For Marpa and helping understand how to use Marpa better.
Gonzalo Diethelm
For continuous feedback and support.
H. Merijn Brand (@Tux)
For providing the initial production-level test of Guacamole to help shake many of the bugs in the BNF.
standard
Gaucamole::Linter
Guacamole::Deparse
Sawyer X
Vickenty Fesunov
This software is Copyright (c) 2022 by Sawyer X.
This is free software, licensed under:
The MIT (X11) License
To install Guacamole, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Guacamole
CPAN shell
perl -MCPAN -e shell install Guacamole
For more information on module installation, please visit the detailed CPAN module installation guide.