Marpa:...d::NAIF(3pm)

📦

version 12.000000 · 2 versions

12.000000 · ubuntu stonking (latest)
12.000000 · ubuntu resolute

💖 NAME 💖

Marpa::R2::Deprecated::NAIF(3pm) — yes bestie, we're in the User Contributed Perl Documentation section, and the module is Marpa::R2::Deprecated::NAIF — Marpa named argument interface (NAIF).

🚨 THE NAIF INTERFACE IS DEPRECATED 🚨

This document describes the NAIF interface, which is deprecated.

PLEASE DO NOT USE IT FOR NEW DEVELOPMENT.

✨ Synopsis ✨

okay so here's the whole flow, exactly as the page shows it:

use Marpa::R2;

my $grammar = Marpa::R2::Grammar->new(
    {   start   => 'Expression',
        actions => 'My_Actions',
        default_action => 'first_arg',
        rules   => [
            { lhs => 'Expression', rhs => [qw/Term/] },
            { lhs => 'Term', rhs => [qw/Factor/] },
            { lhs => 'Factor', rhs => [qw/Number/] },
            { lhs => 'Term', rhs => [qw/Term Add Term/], action => 'do_add' },
            {   lhs    => 'Factor',
                rhs    => [qw/Factor Multiply Factor/],
                action => 'do_multiply'
            },
        ],
    }
);

$grammar->precompute();

my $recce = Marpa::R2::Recognizer->new( { grammar => $grammar } );

$recce->read( 'Number', 42 );
$recce->read('Multiply');
$recce->read( 'Number', 1 );
$recce->read('Add');
$recce->read( 'Number', 7 );

sub My_Actions::do_add {
    my ( undef, $t1, undef, $t2 ) = @_;
    return $t1 + $t2;
}

sub My_Actions::do_multiply {
    my ( undef, $t1, undef, $t2 ) = @_;
    return $t1 * $t2;
}

sub My_Actions::first_arg { shift; return shift; }

my $value_ref = $recce->value;
my $value = $value_ref ? ${$value_ref} : 'No Parse';

🌸 About this document 🌸

This doc is the top-level overview + tutorial for the named argument interface (NAIF) of the Marpa parse engine. If you're new to Marpa, bestie, you actually want to start with the tutorial for the Scanless interface (SLIF) instead.

NAIF is a middle level interface. It's more low level than the Scanless interface (SLIF), which uses a domain-specific language. But it's higher level — and gives you more features — than the thin interface, which gives direct access to the underlying Libmarpa C library.

The two examples in this document show the typical flows of NAIF Marpa method calls. This document will use those examples to walk through the basic features of Marpa in semi-tutorial fashion. More advanced features, and the full reference details of all features, live in the other Marpa API documents.

🧚 The three phases 🧚

A parser needs to:

Accept a grammar.
Read input.
Return values from the parses, according to a semantics.

In Marpa these three tasks are, for the most part, distinct phases. Grammars are Marpa::R2::Grammar objects. The reading of input and the evaluation of the parse according to the semantics is performed by Marpa::R2::Recognizer objects.

💖 Example 1: a simple calculator 💖

The synopsis shows the code for a very simple calculator. It handles only addition and multiplication of integers. This section explains, line by line, how it works. Bestie, we're going line by line, so buckle up 🎀

🌸 Marpa::R2::Grammar::new 🌸

my $grammar = Marpa::R2::Grammar->new(
    {   start   => 'Expression',
        actions => 'My_Actions',
        default_action => 'first_arg',
        rules   => [
            { lhs => 'Expression', rhs => [qw/Term/] },
            { lhs => 'Term', rhs => [qw/Factor/] },
            { lhs => 'Factor', rhs => [qw/Number/] },
            { lhs => 'Term', rhs => [qw/Term Add Term/], action => 'do_add' },
            {   lhs    => 'Factor',
                rhs    => [qw/Factor Multiply Factor/],
                action => 'do_multiply'
            },
        ],
    }
);

Marpa grammars are Marpa::R2::Grammar objects. They are created with the Marpa::R2::Grammar::new constructor. The arguments to Marpa::R2::Grammar::new are references to hashes of named arguments. In the key/value pairs of these hashes, the hash key is the name of the argument, and the hash value is the value of the named argument. iykyk 💅

✨ The start named argument ✨

start => 'Expression',

The start named argument is required — like, you literally cannot skip it. Its value is a string containing the name of the grammar's start symbol. 👑

✨ Named arguments for the semantics ✨

actions => 'My_Actions',
default_action => 'first_arg',

The actions and default_action named arguments specify semantics. Their argument values are strings, which acquire their semantics during evaluation. So they're just vibes until something actually evaluates them 🦋

Evaluation will be described later. Peeking ahead — and yes, we're spoiling the plot a lil 🙈 — actions provides the name of a Perl package where Marpa will look for its actions. The default_action named argument will be interpreted as an action name in that package. This action name will resolve to an action — a Perl closure that implements semantics. The action specified by default_action is used as the action for rules with no action of their own.

✨ The rules named argument ✨

rules => [
    { lhs => 'Expression', rhs => [qw/Term/] },
    { lhs => 'Term',       rhs => [qw/Factor/] },
    { lhs => 'Factor',     rhs => [qw/Number/] },
    { lhs => 'Term', rhs => [qw/Term Add Term/], action => 'do_add' },
    {   lhs    => 'Factor',
        rhs    => [qw/Factor Multiply Factor/],
        action => 'do_multiply'
    },
],

The value of the rules named argument is a reference to an array of rule descriptors. In this example, all the rule descriptors are in the "long" form — they are references to hashes of rule properties. In each key/value pair of a rule descriptor hash, the key is the name of a rule property, and the hash value is the value of that rule property. Long form is giving very thorough, and we respect that 💖

✨ The lhs property ✨

The value of the lhs rule property must be a string containing the name of the rule's left hand side symbol. Every Marpa rule must have a left hand side symbol. No LHS, no rule. Periodt. 💅

✨ The rhs property ✨

The value of the rhs property is a reference to an array of strings containing names of the rule's right hand symbols, in order. This array may be zero length, in which case this is an empty rule — a rule with no symbols on the right hand side. There are no empty rules in this example, but bestie, know that they can exist 🌈

✨ The action property ✨

The value of the action rule property is a string. Peeking ahead (again with the spoilers 😭), each action property string will be interpreted as an action name. This action name will be resolved to a Perl closure that implements the rule's semantics.

🌸 Marpa::R2::Grammar::precompute 🌸

$grammar->precompute();

Before a Marpa grammar object can be used by a Marpa recognizer, it must be precomputed. Precomputation compiles data structures that the recognizer will need. It's the glow-up your grammar needs before it goes out in public, fr fr ✨

🌸 Marpa::R2::Recognizer::new 🌸

my $recce = Marpa::R2::Recognizer->new( { grammar => $grammar } );

Marpa::R2::Deprecated::NAIF::Recognizer::new creates a new recognizer. Its arguments are references to hashes of named arguments. In this example the only named argument is the required argument: "grammar". The value of the grammar named argument must be a precomputed Marpa grammar. Precomputed!! We said it twice, we mean it 👑

🌸 Marpa::R2::Recognizer::read 🌸

$recce->read( 'Number', 42 );
$recce->read('Multiply');
$recce->read( 'Number', 1 );
$recce->read('Add');
$recce->read( 'Number', 7 );

The Marpa::R2::Deprecated::NAIF::Recognizer::read method takes two arguments, a token name and a token value. The token name must be the name of a valid terminal symbol in the grammar. By default symbols are valid as terminal symbols, if and only if they do NOT occur on the LHS of any rule. That's the whole rule, bestie — LHS appearance disqualifies you from terminal duty 💀

The token value must be a Perl scalar, but otherwise its form and semantics are entirely up to the application. If the token value is never used, it can be omitted. In the calculator example, the values of the "Add" and "Multiply" tokens are never used, and are allowed to default to an undefined value. They literally just show up and do nothing, iconic behavior honestly 🎀

🌸 Marpa::R2::Recognizer::value 🌸

my $value_ref = $recce->value;
my $value = $value_ref ? ${$value_ref} : 'No Parse';

The Marpa::R2::Deprecated::NAIF::Recognizer::value method returns a reference to the parse result's value, if there was a parse result. If there was no parse result, Marpa::R2::Deprecated::NAIF::Recognizer::value returns undef. Take the L gracefully 🌸

🦋 Resolving the semantics 🦋

The first thing Marpa::R2::Deprecated::NAIF::Recognizer::value needs to do is to resolve the semantics. Resolving the semantics means mapping the action names into actions. Actions are Perl closures which directly implement semantics. In this example, the actions named argument is specified. actions is a Perl package name. Marpa will look for actions in that package.

actions => 'My_Actions',

{ lhs => 'Factor', rhs => [qw/Factor Multiply Factor/], action => 'do_multiply' },

For example, the action property for the above rule is "do_multiply" and the actions named argument to the grammar was "My_Actions". So Marpa looks for a closure whose fully qualified name is My_Actions::do_multiply, which it finds:

sub My_Actions::do_multiply {
    my ( undef, $t1, undef, $t2 ) = @_;
    return $t1 * $t2;
}

Rules do not always have action properties. That is the case with these rules in this example:

{ lhs => 'Expression', rhs => [qw/Term/] },
{ lhs => 'Term', rhs => [qw/Factor/] },
{ lhs => 'Factor', rhs => [qw/Number/] },

The rules in the above display have no action names. When a rule has no action name, Marpa will fall back to trying to use the default action, as described next. Fallback queen behavior 💅

default_action => 'first_arg',

The default_action named argument is resolved in the same way as are the action properties of the rules. In this example, default_action is specified as "first_arg" and resolves to My_Actions::first_arg.

💖 Actions 💖

sub My_Actions::first_arg { shift; return shift; }

sub My_Actions::do_add {
    my ( undef, $t1, undef, $t2 ) = @_;
    return $t1 + $t2;
}

Value actions are Perl closures used as callbacks. Value actions are called when nodes in a parse tree are evaluated. A value action receives one or more arguments. The first argument to a value action is always a per-parse-tree object, which the callbacks can use as a scratchpad. In these examples, the per-parse-tree object is not used — it's there, it's just not the main character in this scene 🙈

For a non-empty rule, the second and any subsequent arguments to the callback are the values, in lexical order, of the symbols on the right hand side of the rule. If the action is for an empty rule, the per-parse-tree object will be its only argument.

Every value action is expected to return a value. With one exception, this value is passed up to a parent node as an argument. The exception is the value for the start rule. The return value for the start rule becomes the parse result. So the start rule's return value is the moment, the finale, the reveal 🌟

Rules with no action specified for them take their semantics from the default_action named argument. If there is no default action for a grammar, rules with no action specified for them return a Perl undef. Yeah. Just undef. It's giving nothing and that's on purpose 💀

🌀 Example 2: an ambiguous parse

Okay bestie, same calculator, but this time we're doing it chaotic. 💅

Instead of letting multiplication flex over addition, this rewritten calculator just... lets anything happen in any order. Any order of operations, periodt. Also, heads up: the actions (My_Actions::do_add, etc.) and the @tokens array are literally identical to the first example, no changes there.

And yeah — dropping precedence makes the grammar way shorter and cuter, but it also means there can be multiple parse trees, and those different parse trees can give you different parse results. 😭 In this app we just decide, for each input, to return every single one of the parse results. All of them. Greedy behavior. Iconic.

use Marpa::R2;

my $ambiguous_grammar = Marpa::R2::Grammar->new(
    {   start   => 'E',
        actions => 'My_Actions',
        rules   => [
            [ 'E', [qw/E Add E/],      'do_add' ],
            [ 'E', [qw/E Multiply E/], 'do_multiply' ],
            [ 'E', [qw/Number/],       ],
        ],
        default_action => 'first_arg',
    }
);

$ambiguous_grammar->precompute();

my $ambiguous_recce =
    Marpa::R2::Recognizer->new( { grammar => $ambiguous_grammar } );

$ambiguous_recce->read( 'Number', 42 );
$ambiguous_recce->read('Multiply');
$ambiguous_recce->read( 'Number', 1 );
$ambiguous_recce->read('Add');
$ambiguous_recce->read( 'Number', 7 );

my @values = ();
while ( defined( my $ambiguous_value_ref = $ambiguous_recce->value() ) ) {
    push @values, ${$ambiguous_value_ref};
}

Short form rule descriptors

rules => [
    [ 'E', [qw/E Add E/],      'do_add' ],
    [ 'E', [qw/E Multiply E/], 'do_multiply' ],
    [ 'E', [qw/Number/], ],
],

So the rule descriptors in the ambiguous example are showing off the "short" form, aka the array form of rule descriptors. ✨ Array form rule descriptors are just references to arrays. And the elements go in order: the lhs property, then the rhs property, then the action property. That's it, that's the whole thing. 🎀

Marpa::R2::Recognizer::value

my @values = ();
while ( defined( my $ambiguous_value_ref = $ambiguous_recce->value() ) ) {
    push @values, ${$ambiguous_value_ref};
}

Okay so when you call the Marpa::R2::Deprecated::NAIF::Recognizer::value method more than once, it iterates through the parse results. Every call hands you back a reference to the parse result. 🫶

And when the iteration is fully done — like, every parse result has been returned — Marpa::R2::Deprecated::NAIF::Recognizer::value returns undef. If there were literally no parse results at all? It returns undef the very first time you call it. No results, no drama, just undef. 💀

🤯 Errors and exceptions

General rule of the land: methods in the Marpa NAIF API do not return errors. Nope. Instead, when there are errors, Marpa NAIF API methods throw an exception. Catch it or perish, bestie. 😌

🧬 Inheritance

Classes in the Marpa API are not designed to be inherited. Please don't do it. It's giving "not that". 🙈

🌌 The `Marpa::` namespace

The Marpa:: top-level namespace is reserved. 🚫 So if you're extending Marpa, one appropriate place to go is the MarpaX:: namespace. This whole practice helps avoid namespace collisions, and it follows a CPAN standard — as exemplified by DBIx:: LWPx:: and MooseX::, which are for extensions of, respectively, DBI, LWP and Moose. See? Consistent. ✨

📚 Other documents

This document gives a semi-tutorial overview of the entire Marpa NAIF API. But if you want full details on Marpa's grammar objects and their methods, go read the Marpa::R2::Deprecated::NAIF::Grammar document. And for full details on Marpa's recognizer objects and their methods, the Marpa::R2::Deprecated::NAIF::Recognizer document is your girl. 💖

Marpa::R2::Vocabulary is meant to be a quick refresher on parsing terminology, emphasizing how the standard terms get used in the Marpa context. The NAIF's standard semantics are fully described in the Marpa::R2::Deprecated::NAIF::Semantics document. Techniques for tracing and for debugging your Marpa grammars live in the Marpa::R2::Deprecated::NAIF::Tracing document and the Marpa::R2::Deprecated::NAIF::Progress document. And for the theoretical girlies, my sources and other useful references are described in Marpa::R2::Advanced::Bibliography. 🌈

🫶 Support

Marpa::R2 comes without warranty. Support is provided on a volunteer basis through the standard mechanisms for CPAN modules. The Support document has details. Be nice to the volunteers, they're doing this for free. 🥺

⚖️ Copyright and License

Copyright 2022 Jeffrey Kegler
This file is part of Marpa::R2.  Marpa::R2 is free software: you can
redistribute it and/or modify it under the terms of the GNU Lesser
General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.

Marpa::R2 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser
General Public License along with Marpa::R2.  If not, see
http://www.gnu.org/licenses/.

Not me giving you the whole license text, but it's a real one and it matters — LGPL v3 or later, no warranty, the whole vibe check. 👑

and that's the whole page, bestie!! 🎀✨ This was perl v5.42.3, dated 2026-08-20, and it's the Marpa:...d::NAIF(3pm) manpage — go forth and parse ambiguously, you absolute icon. 💖🦋👑

📦 where this page comes from

ubuntu stonking: libmarpa-r2-perl 12.000000-1build1 · LGPL-3+~Marpa
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms