/ 
Parse-Marpa-0.001_068
/ Parse::Marpa::DIAGNOSTICS

NAME

Parse::Marpa::DIAGNOSTICS - Marpa's Diagnostics

THIS DOCUMENT IS UNDER CONSTRUCTION AND INCOMPLETE

THIS DOCUMENT IS UNDER CONSTRUCTION AND INCOMPLETE

OVERVIEW

This document covers Marpa methods and method options primarily useful for debugging grammars and parses.

DIAGNOSTIC OPTIONS

These are options to the Parse::Marpa::new(), Parse::Marpa::set(), and Parse::Marpa::Parse::new() methods.

academic

The academic option is only useful for testing the early stages of Marpa, up to the creation of NFA's in the precomputation phase. For this, CHAF rewriting must be turned off, which means the Marpa parse engine cannot actually go on to parse these.

trace_actions
trace_completions
trace_evaluation_choices
trace_iteration_changes
trace_iteration_searches
trace_iterations
trace_lex
trace_lex_matches
trace_lex_tries
trace_predefineds
trace_priorities
trace_rules
trace_strings
trace_values

DIAGNOSTIC METHODS FOR GRAMMAR OBJECTS

Parse::Marpa::inaccessible_symbols
Parse::Marpa::show_NFA
Parse::Marpa::show_SDFA
Parse::Marpa::show_accessible_symbols
Parse::Marpa::show_location(message, text, offset)

message must be a string, text a reference to a string, and offset, a character offset within that string. show_location() returns a multi-line string with a header line containing message, the line from text containing offset, and a "pointer" line. The pointer line uses the ASCII "caret" symbol to point to the exact offset.

Parse::Marpa::show_nullable_symbols
Parse::Marpa::show_nulling_symbols
Parse::Marpa::show_problems
Parse::Marpa::show_productive_symbols
Parse::Marpa::show_rules
Parse::Marpa::show_source_grammar_status
Parse::Marpa::show_symbols
Parse::Marpa::unproductive_symbols

DIAGNOSTIC METHODS FOR PARSE OBJECTS

Parse::Marpa::Parse::show
Parse::Marpa::Parse::show_status
Parse::Marpa::Parse::find_complete_rule(parse, start_earleme, _symbol, end_earleme

The Parse::Marpa::Parse::find_complete_rule() method takes a parse object as its one required argument. Arguments which specify a start_earleme, symbol and end_earleme are optional. If the start earleme is not specified, it defaults to earleme 0. If the end earleme is not specified, it defaults to "default parse end earleme", that is, whatever would be the default earleme for the end of a parse. If an end earleme argument after the default parse end earleme is specified, it is ignored and the default parse end earleme is used. The symbol argument, if specified, must be the name of the symbol to the raw interface.

find_complete_rule() looks for parses of complete rules. Only parses which start at the start earleme are considered. It looks first for any which end at the end earleme, then iterates back, looking for shorter and shorter parses, until it reaches the start earleme and is looking for null parses. The parses are always for complete rules, but can be subparses in the sense that they are parses from symbols other than the grammar's start symbol. Complete parses for rules with any symbol on the left hand side are considered, unless a start symbol was specified as an argument, in which case only parses of that symbol are considered.

The return value is an array. The first element of the array is the earleme at which the complete parse ends. The second element is a pointer to an array of the names of the symbols which could be left hand sides of the complete rule. Symbol names will be raw interface names. If you are using a high-level grammar interface, these names may differ from the ones in your source.

There may be more than one because, unlike a conventional Earley parser, Marpa works in terms of LR(0) states, and not directly with the rules of the grammar. A single LR(0) state, may contain several different complete rules, some in turn having different left hand sides. If a symbol argument was specified, it will be in the list of symbols in the return value.

(Note on what might seem like a contradiction to experts: if there is more than one LHS for a complete parse in an LR(0) state. that of course means that the grammar is not LR(0). Marpa does not do LR(0) parsing. Marpa uses LR(0) states to guide Earley parsing, and Earley parsing is not restricted to LR(0) grammars.)

find_complete_rule() is an experimental start on interfaces for online mode, error recovery, and advanced wizardry with grammars. The infrastructure to use the information it provides is not yet in place. It is even more especially subject to change than the rest of this alpha release.