Marpa:...rammar(3pm)

📦

version 12.000000 · 2 versions

12.000000 · ubuntu stonking (latest)
12.000000 · ubuntu resolute

🌸 Marpa::R2::Deprecated::NAIF::Grammar — NAIF grammars 🌸

okay bestie, gather round. this is a User Contributed Perl Documentation page, section 3pm, for Marpa::R2::Deprecated::NAIF::Grammar — and yes, the vibes are immaculate but the news is not, so let's get the serious part out of the way first. 💖

🚨 THE NAIF INTERFACE IS DEPRECATED 🚨

This document describes the NAIF interface, which is deprecated. PLEASE DO NOT USE IT FOR NEW DEVELOPMENT.

for real. this is the "we still love her but she's retired" era. new projects, go find the SLIF docs, i'm begging 😭

✨ Synopsis ✨

here's the whole vibe in one code block, no cap:

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();

💅 Description 💅

This document describes grammars for Marpa's named argument interface (NAIF). So if you're a beginner, or you're not sure which interface you even want, or you straight up don't know what the NAIF interface is — bestie, you probably want the document on grammars for the SLIF interface instead. go read that one, i'll wait 🫶

To create a Marpa grammar object, use the new method. Rules and symbols may be specified when the grammar is created.

To change a Marpa grammar object, use the set method. New rules may be added until a grammar is precomputed.

A grammar cannot be used for parsing until it is precomputed. To precompute a Marpa grammar object, use the precompute method. After precomputation, no new rules may added and most other changes are forbidden. it's giving "locked in", literally 🔒

🔤 Symbol names 🔤

Marpa reserves, for its internal use, all symbol names ending with one of these four symbols:

the right square bracket (])
the right parenthesis ())
the right angle bracket (>)
the right curly bracket (})

Any other valid Perl string is an acceptable symbol name. that's it, that's the whole rule. slay ✨

🎟️ Terminal symbols 🎟️

Marpa defines a terminal as a symbol which is valid as an input token symbol. By default, the terminals are those symbols who do not appear on the LHS of any rule.

Marpa will allow any non-nulling symbol to be a terminal, even those which appear on the LHS of one or more rules. To allow (or disallow) use of a symbol as a terminal, the application can use the terminals named argument, and the terminal property. An attempt to use a nulling symbol as a terminal is a fatal error. 💀 so don't do that.

🔁 Sequence rules 🔁

It is very common in a grammar for one symbol to produce a repeating sequence. Marpa allows a shorthand for this: sequence rules. The RHS of a sequence rule will be repeated, as specified by the min rule property. In sequence rules the RHS must always be one symbol in length, and that symbol may not be a nullable symbol.

A rule is a sequence rule if the min rule property is defined. min can be 0 or 1, and specifies the minimum number of times that the sequence is allowed to repeat. As of this writing, the maximum number of repetitions is always infinite. periodt.

{ lhs => 'sequence', rhs => ['item'], min => 0, action => 'do_sequence' }

A min of zero indicates a sequence that repeats zero or more times. This is the equivalent of using the star quantifier (*) in the standard regular expression notation.

{ lhs => 'sequence', rhs => ['item'], min => 1, action => 'do_sequence' }

A min of one indicates a sequence that repeats one or more times. This is the equivalent of using the plus quantifier (+) in the standard regular expression notation.

Sequences can have a separator, specified with the separator rule property. By default, separation is Perl-style: trailing separators are allowed. In "proper" separation, a separator must actually separate two sequence items and therefore is not allowed after the last item of a sequence. If you prefer "proper" separation, you can set the proper rule property.

👑 Advantages of sequence rules 👑

You are never forced to use sequence rules, but it's usually better if you do. When a sequence is written as a sequence rule, Marpa optimizes it. she's efficient like that 💅

When a sequence is written using non-sequence rules, the semantics typically wind up being spread over two or three Perl closures. The semantic action for a sequence rule is a single Perl closure. Putting the semantics into a single Perl closure often results in simpler and more natural code. See the section on sequences in the semantics document. iykyk 📖

🙈 Caveats 🙈

Marpa throws an exception if you try to use a nullable symbol as the right hand side of a sequence rule, or as the separator for a sequence rule. The ban on nullables in sequences only applies to sequences when they are written using sequence rules. Nothing prevents you from specifying a sequence of nullables using non-sequence rules. But usually there is no good reason to do this, and sequences of nullables can be highly ambiguous which, for efficiency reasons, makes them a good thing to avoid. like, bestie, just don't. 😭

To keep things simple, the right hand side of a sequence rule must be a single symbol. Of course, applications will often want to repeat sequences of multiple symbols. That is easy to do indirectly:

{ lhs => 'sequence', rhs => [qw(item)], min => 0, action => 'do_sequence' },
{ lhs => 'item', rhs => [qw(part1 part2)], action => 'do_item' },

🛠️ Constructor 🛠️

🌟 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::R2::Deprecated::NAIF::Grammar::new returns a new Marpa grammar object or throws an exception. The arguments to Marpa::R2::Deprecated::NAIF::Grammar::new are references to hashes of named arguments. In each key/value pair of this hash, the hash key is the argument name and the hash value is the value of the named argument. The available named arguments are described below. (stay tuned, bestie, there's a whole list coming 🍓)

🔧 Mutators 🔧

🌟 precompute() 🌟

$grammar->precompute();

The precompute method compiles data structures that the recognizer will need. It returns the grammar object or throws an exception.

🌟 set() 🌟

$grammar->set( { trace_file_handle => $trace_fh } );

The arguments to the set method are references to hashes of named arguments. The available named arguments are described below. set either returns true or throws an exception.

👀 Accessors 👀

🌟 check_terminal() 🌟

Returns a Perl true when its argument is the name of a terminal symbol. Otherwise, returns a Perl false. Not often needed, but a lexer may find this the most convenient way to determine if a symbol is a terminal. handy! ✨

🌟 rule() 🌟

my ( $lhs, @rhs ) = $grammar->rule($rule_id);

Given a rule ID as its argument, returns an array containing the symbols of the rule. The rule() method returns a Perl false if no rule with that rule ID exists. If the rule ID exists, the rule's LHS symbol is the first symbol in the array, and rest of the array contains the rule's RHS symbols in order. Situations where Rule ID's are encountered include callbacks and use of the progress method.

🌟 rule_ids() 🌟

my @rule_ids = $grammar->rule_ids();

Returns an array containing the valid rule IDs. Situations where Rule ID's are encountered include callbacks and use of the progress method.

🔍 Trace accessors 🔍

🌟 show_problems() 🌟

print $grammar->show_problems()
    or die "print failed: $ERRNO";

Usually the application does not call this method directly. Returns a string describing any serious but non-fatal problems a grammar had in the precomputation phase. A serious problem is one that will prevent parsing. Warnings are not serious problems in this sense. If there were no serious problems, returns a string saying so. This method is not useful before precomputation.

In Marpa, most serious grammar problems are not immediately thrown as exceptions. This is because there can be a number of serious problems in a grammar, particularly one that is large or in an early draft. If each serious problem caused an immediate exception, the user would have to fix them one at a time — very tedious. 💀 we do not do tedious here.

The recognizer throws an exception when the user attempts to create a parse from a grammar with serious problems. When that happens, the string returned by show_problems is part of the error message.

🌟 show_rules() 🌟

print $grammar->show_rules()
    or die "print failed: $ERRNO";

Returns a string listing the rules. Each rule is shown with comments which indicate rule properties. show_rules is useful in debugging grammars.

Marpa does extensive rewriting of its grammars, and both the original rules and the rewritten rules appear in the show_rules list. When a rule is rewritten, the original rule is often not used. In that case, "!used" will be one of the comments for the original rule. The "!used" comment also marks rules not used for reasons other than rewrites. For example, inaccessible and unproductive rules are also marked "!used".

The "discard_sep" comment indicates that the rule discards separators This is only relevant in sequence rules. Other comments indicate whether rules were nullable, unproductive, inaccessible, or empty.

🌟 show_symbols() 🌟

print $grammar->show_symbols()
    or die "print failed: $ERRNO";

Returns a string listing the symbols, along with comments indicating whether they were terminal, nulling, nullable, unproductive or inaccessible. Useful for debugging grammars. 🦋

okay that's part one bestie, don't go anywhere — there's more coming, and it's lowkey juicy 🌈

✨ Named arguments ✨

okay bestie, these are the named arguments you can hand over to the constructor. each one is a little control knob, and they all matter 💅

💖 `action_object`

The action_object named argument gives a Perl class name that Marpa uses when it's resolving action names into Perl closures. There has to be a new constructor defined in that action_object package. That constructor gets used to create the per-parse-tree variables. The per-parse-tree variable is passed to rule evaluation closures as their first argument. More deets live in the document on semantics.

💖 `actions`

actions => 'My_Actions',

The actions named argument gives the Perl package Marpa uses when resolving action names to Perl closures. If you specify both an actions named argument and an action_object named argument, then the package from actions is the only one used to resolve action names. The actions package is treated only as a package, and not as a class. Any new constructor in the actions package is ignored. Details are in the document on semantics.

💖 `default_action`

default_action => 'first_arg',

The default_action named argument sets the value action name for rules that don't have an action property. Details are in the document on semantics.

💖 `default_empty_action`

The default_empty_action named argument sets the action for empty (zero length) rules that have no action specified explicitly. Details are in the document on semantics.

💖 `inaccessible_ok`

The value has to be a reference to an array of symbol names. By default, Marpa warns if a symbol is inaccessible, but the warning gets suppressed for any symbol named in the array. Setting the inaccessible_ok named argument after grammar precomputation is useless, and it itself results in a warning.

⚠️ so yeah, set this one before precomputation or don't bother, bestie.

Inaccessible symbols are symbols which cannot be derived from the start symbol, and which therefore can never be part of a successful parse. Inaccessible symbols often indicate errors in grammar design. But a user may have plans for these symbols, may wish to keep them as notes, or may simply wish to deal with them later.

💖 `infinite_action`

Takes as its value a string specifying what Marpa should do if it discovers that its grammar is infinitely ambiguous. The value must be one of "fatal", "warn" or "quiet". A grammar is infinitely ambiguous if there is some input for which it produces an endless number of parses.

If the value is "fatal", Marpa throws an exception when it encounters an infinitely ambiguous grammar. This is the default and will usually be what the user wants. In most cases, an infinitely ambiguous grammar is simply a mistake.

"quiet" indicates that the user wants to allow infinitely ambiguous grammars. "warn" indicates that the user wants to allow infinitely ambiguous grammars, but wants a warning message to be printed to the trace file handle.

💖 `rules`

The value of the rules named argument is a reference to an array of rule descriptors. The rules named argument may be specified multiple times, adding new rules to the grammar each time. New rules may be added until the grammar is precomputed. The format of rule descriptors is explained below.

💖 `source`

The value of the source named argument is a reference to string that contains a description of the grammar in BNF format. The format of this string is described in the document on the BNF format. The source named argument may only be specified once, and it cannot be used together with the rules named argument.

💖 `start`

start => 'Expression',

The value of the start named argument must be a symbol name. It will be used as the start symbol for the grammar. The start named argument is required.

💖 `symbols`

The value of the symbols named arguments must be a reference to a hash. In each key/value pair of this hash, the hash key is the symbol property name and the hash value is the symbol descriptor. Symbol descriptors are described below.

Note that the value of symbols named argument is a hash, but the value of the rules named argument is an array. This is because symbol names make convenient hash keys. For rules, there is no equally natural choice for a hash key.

💖 `terminals`

The value of the terminals named argument must be a reference to an array of symbol names. All the symbols in the array will be allowed as terminals. See the discussion of terminals above.

💖 `trace_file_handle`

The value is a file handle. Trace output and warning messages go to the trace file handle. By default the trace file handle is STDERR.

💖 `unproductive_ok`

The value must be a reference to an array of symbol names. By default, Marpa warns if a symbol is unproductive, but the warning is suppressed for any symbol named in the array. Setting the unproductive_ok named argument after grammar precomputation is useless, and itself results in a warning.

⚠️ same energy as inaccessible_ok: precomputation first? too late, girl.

Unproductive symbols are symbols which can never derive a sentence. (A sentence is a string of zero or more terminals.) That means that unproductive symbols can never be part of a successful parse. Unproductive symbols often indicate errors in grammar design. But a user may have plans for these symbols, may wish to keep them as notes, or may simply wish to deal with them later.

💖 `warnings`

The value is a boolean. Warnings are written to the trace file handle. By default, warnings are on. Usually, an application will want to leave them on. If warnings are turned off, turning them back on after grammar precomputation is useless, and itself results in a warning.

✨ Rule descriptors ✨

           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'
               },
           ],

💖 Rule descriptors as hashes 💖

okay so the long form of a rule descriptor? it's literally just a hash ref, bestie. every key is a property name, every value is that property's value. iconic.

✨ action ✨

The action property is a string that tells Marpa what the semantics for that rule are. (Peep the semantics doc for the tea ☕.) But heads up: nulling symbols are handled per-symbol, not per-rule. So if you try to put an action on an empty rule? Marpa will throw an exception. Not cute. Don't do it.

🎀 keep 🎀

Separators in sequence rules? Usually they don't matter. By default Marpa yeets them during parse tree traversal and before node evaluation, so your semantic actions never even see them. But if you set keep to a Perl true, Marpa keeps them so your actions can peek. The catch? You now have to figure out which is a separator and which is an item. That's on you, bestie. (Details in the semantics doc.)

🦋 lhs 🦋

lhs has to be a string with the name of the rule's left-hand side symbol. Every Marpa rule needs one. No LHS, no rule. periodt.

🌸 min 🌸

min can only be 0, 1, or undefined. If it's 0 or 1, your rule is a sequence rule. If it's undefined, it's a regular BNF rule. Sequence rules can only have ONE symbol on the right side, called the sequence item. And that item can't be nullable. The input has to match that item at least min times, and it can match it infinitely many more times. slay.

💅 null_ranking 💅

null_ranking? It's ignored unless you changed the recognizer's ranking_method from its default. It lets your app control the order that rules with nullable symbols come back from the value method. Those rules can match the same input in different ways depending on which symbols get nulled. Those different ways are called null variants. If you leave null_ranking undefined, the order is arbitrary (that's the default, and most apps are fine with it). Want the full tea? Check the parse order doc.

🫶 proper 🫶

By default, sequence rules with separators allow trailing separators (very Perl of them). If you set proper to a Perl true, you enforce "proper" separation. That means separators have to actually separate stuff, and trailing separators? Not allowed. no cap.

😭 rank 😭

rank is ignored unless you changed ranking_method from default. The allowed range is implementation-defined, but anything from -134,217,727 to 134,217,727 is always valid. Default is 0. Want the deets? Parse order doc.

🔥 rhs 🔥

rhs is an array ref of strings -- the names of the right-hand symbols, in order. It can be zero length, which makes it an empty rule (no symbols on the right). Also, if you just don't include rhs in the descriptor? That rule is empty too. iykyk.

👑 separator 👑

Any sequence rule can have a separator. The value has to be a symbol name. Marpa allows trailing separators by default (Perl vibes ✨). And the separator itself? Can't be a nullable symbol. nope.

🌈 Rule descriptors as arrays 🌈

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

You can also write rule descriptors in "short form" -- just an array ref. The elements, in order, are lhs, rhs, and action. The last two are optional. If you skip one, it's the same as skipping it in the long form. easy.

⭐ Duplicate rules ⭐

Marpa throws an exception if you try to add a duplicate rule. Two BNF rules are duplicates if:

Both rules have the same left hand symbol.
Both rules have the same right hand symbols in the same order.

Sequence rules are even stricter: a sequence rule's LHS can't be the LHS of another sequence rule, and it can't be the LHS of any BNF rule either. This makes duplicate rules intuitive and easy to detect. But don't worry, it doesn't limit what you can express with Marpa grammars -- it's super easy to work around. For example, make an intermediate rule of length one whose RHS is the sequence LHS symbol. Then you can use that intermediate LHS anywhere, no restrictions. chef's kiss.

💜 Symbol descriptors 💜

           symbols => {
               MinusMinus => { terminal => 1 },
               Minus      => { terminal => 1 },
               Number     => { terminal => 1 },
           },

A symbol descriptor is a hash. Keys are property names, values are the values. The properties you can use are:

🍓 terminal 🍓

terminal is a boolean. True means the symbol can be a terminal. False means it can't. (See the terminals section for more.)

🧚 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/.

this page was served fresh on 2026-08-20 with perl v5.42.3 💖 stay slaying, bestie!

📦 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