NAME
Marpa::Grammar - Marpa Grammar Objects
DESCRIPTION
Grammar objects are created with the new constructor. Rules and options may be specified when the grammar is created, or later using the set method. Rules are most conveniently added with the mdl_source named argument, which takes a reference to a string containing an MDL grammar description as its value. MDL (the Marpa Description Language) is detailed in another document.
MDL indirectly uses another interface, the plumbing interface. The plumbing is described in a document of its own. Users who want the last word in control can use the plumbing directly, but they will lose a lot of convenience and maintainability. Those who need the ultimate in efficiency can get the best of both worlds by using MDL to create a grammar, then stringifying it, as described below. The MDL parser itself uses a stringified MDL file.
Precomputation
Marpa needs to do extensive precomputation on grammars before they can be passed on to a recognizer or an evaluator. The user usually does not need to perform this precomputation explicitly. By default, in any method call that adds rules or terminal to a grammar, precomputation is done automatically.
Once a grammar has been precomputed, it is frozen against many kinds of changes. For example, you cannot add rules to a precomputed grammar. When the user wishes to build a grammar over several method calls, the default behavior of automatic precomputation is undesirable. Automatic precomputation can be turned off with the precompute method option. There is also a precompute method, which explicitly precomputes a grammar. With the precompute method option and the precompute method, the user can dictate exactly when precomputation takes place.
Cloning
By default, Marpa recognizers make a clone of the the grammar used to create them. This allows several recognizers to be created from the same grammar, without risk of one recognizer modifying the data in a way that interferes with another. Cloning can be overriden by using the clone option to the new and set methods.
Stringifying
Marpa can turn the grammar into a string with Marpa's stringify method. A stringified grammar is a string in every sense and can, for instance, be written to a file.
Marpa's unstringify static method takes a stringified grammar, eval's it, then tweaks it a bit to create a properly set-up grammar object. A subsequent Marpa process can read this file, unstringify the string, and continue the parse. Using a stringified grammar eliminates the overhead both of parsing MDL and of precomputation. As mentioned, where efficiency is a major consideration, this will usually be better than using the plumbing interface.
METHODS
new
my $grammar = Marpa::Grammar->new(); my $grammar = Marpa::Grammar->new(
{ max_parses => 10, mdl_source => \$source, } );Marpa::Recognizer::new has one, optional, argument -- a reference to a hash of named arguments. It returns a new grammar object or throws an exception.
Named arguments can be Marpa options. For these see Marpa::Doc::Options. In addition to the Marpa options, the mdl_source named argument, the precompute named argument, and the named arguments of the plumbing interface are also allowed. For details of the plumbing and its named arguments, see Marpa::Doc::Plumbing.
The value of the mdl_source named argument should be a reference to a string containing a description of the grammar in the Marpa Demonstration Language. Either the mdl_source named argument or the plumbing arguments may be used to build a grammar, but both cannot be used to build the same grammar object.
The value of the precompute named argument is interpreted as a Boolean. If true, and if any rules or terminals were added to the grammar in the method call, then the grammar is precomputed. This is the default behavior. If, in a new or set method call, the precompute named argument is set to a false value, precomputation will not be done by that method call.
In the new and set methods, a Marpa option can be specified both directly, as a named argument to the method, and indirectly, in the MDL grammar description supplied as the value of an mdl_source argument. When that happens, the value in the MDL description is applied first, and value supplied with the method's named argument is applied after the MDL is processed. This fits the usual intent, which is for named arguments to override MDL settings. However, this also means that trace settings won't be in effect until after the grammar description is processed, and that can be too late for some of the traces. For a way around this, see the set method.
set
$grammar->set( { mdl_source => \$source } );The set method takes as its one, required, argument a reference to a hash of named arguments. It allows Marpa options, the precompute named argument, the mdl_source named argument, and the plumbing arguments to be specified for an already existing grammar object. The effect of these arguments is as described above for the new method call. set either returns true or throws an exception.
The set method call can be used to control the order in which named arguments are applied. In particular, some tracing options need to be turned on prior to specifying the grammar. To do this, a new grammar object can be created with the trace options set, but without a grammar specification. Once the constructor returns, tracing will be in effect, and the set method can be used to specify the grammar, using either the mdl_source named argument or the plumbing arguments.
precompute
$grammar->precompute();The precompute method performs Marpa's precomputations on a grammar. It returns the grammar object or throws an exception.
It is usually not necessary for the user to call precompute explicitly. Precomputation is done automatically by the new and set methods when any rule or terminal is added to a grammar. The precompute method, along with the precompute option to the new and set methods is used to override the default behavior. For more details, see above.
stringify
my $stringified_grammar = $grammar->stringify();The stringify method takes as its single argument a grammar object and converts it into a string. It returns a reference to the string. The string is created using Data::Dumper. On failure, stringify throws an exception.
unstringify
$grammar = Marpa::Grammar::unstringify( $stringified_grammar, $trace_fh );
$grammar = Marpa::Grammar::unstringify($stringified_grammar);The unstringify static method takes a reference to a stringified grammar as its first argument. Its second, optional, argument is a file handle. The file handle argument will be used both as the unstringified grammar's trace file handle, and for any trace messages produced by unstringify itself. unstringify returns the unstringified grammar object unless it throws an exception.
If the trace file handle argument is omitted, it defaults to STDERR and the unstringified grammar's trace file handle reverts to the default for a new grammar, which is also STDERR. The trace file handle argument is necessary because in the course of compilation, the grammar's original trace file handle may have been lost. For example, a stringified grammar can be written to a file and emailed. Marpa cannot rely on finding the original trace file handle available and open when a stringified grammar is unstringified.
When Marpa deep copies grammars internally, it uses the stringify and unstringify methods. To preserve the trace file handle of the original grammar, Marpa first copies the handle to a temporary, then restores the handle using the trace_file_handle argument of unstringify.
clone
my $cloned_grammar = $grammar->clone();The clone method creates a useable copy of a grammar object. It returns a successfully cloned grammar object, or throws an exception.
SUPPORT
See the support section in the main module.
AUTHOR
Jeffrey Kegler
LICENSE AND COPYRIGHT
Copyright 2007 - 2009 Jeffrey Kegler
This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0.