26 Tracing and diagnosing parses

Libmarpa is very low-level, and does not use strings to identify its objects. Libmarpa is expected to come with a upper level which uses strings to name and/or identify the objects used in parsing, in the process deciding issues like naming conventions, ASCII-7 versus UTF-8, etc. Based on those decisions, the upper layer is expected to offer facilities for tracking and displaying symbol names, displaying rules, tracking and displaying tokens, and displaying progress items.

It is possible to trace and diagnose parses without an upper layer – a few programs in Libmarpa’s test suite do this. Instead of using symbol names and expanding rules into their LHS and RHS, the user can keep track of symbol IDs and rule IDs. But most people who have tried this would agree that this is something that the user should go to great pains to avoid.

As a rule, every application of Libmarpa should have an upper layer with diagnostics. If a pre-existing diagnostics layer is not used, it should be one of the first things written — it is very likely to be one of the first things needed.

The rest of this chapter describes facilities that should be offered in the layer handling grammar diagnostics. Applications may want to allow these facilities at various levels of verbosity. Implementation suggestions are made, focusing on what information the facilities should display at the highest verbosity level.