When using expectation points, a parsing failure results in an exception that generically indicates the failure, but probably doesn’t explain the problem in the most meaningful way. It is possible to attach an error handler to react to the failed match in a more specialized way:<\/p>\n
<\/p>\n
\r\nrule = alpha > '!';\r\non_error<fail>(rule,\r\n std::cerr << val("Expected '!' at offset ") << (_3 - _1)\r\n << " in \\" << std::string(_1, _2) << '"'\r\n << std::endl);\r\n<\/pre>\nThat will produce a message like the following on stderr:<\/p>\n
Expected '!' at offset 7 in \"Some input\"<\/code><\/p>\nHowever, if there’s more than one expectation point in a rule, then the diagnostic may be unhelpfully generic. To do otherwise, one must distinguish which expectation point failed. While it is certainly possible to factor the grammar into additional rules in order to have at most one expectation point per rule, that’s not necessary and can make the grammar less readable than otherwise. Instead, the what<\/em> parameter (_4<\/code>) of the error handler can be used:<\/p>\n\r\nrule = alpha > '!';\r\non_error<fail>(rule,\r\n std::cerr << val("Expected " << _4 << " at offset ")\r\n << (_3 - _1) << " in \\" << std::string(_1, _2) << '"'\r\n << std::endl);\r\n<\/pre>\nThe what<\/em> parameter describes the failure. In the case of an expectation point match failure, it is the name of the parser that failed to match or, if the parser is to match literal text, like '!'<\/code> in the preceding example, the what<\/em> parameter will be \"literal-char\"<\/code> or similar. In this case, _4<\/code> will be \"literal-char\"<\/code> (in the form of a boost::spirit::utf8_string which is a specialization of std::basic_string), and thus not terribly useful in a diagnostic.<\/p>\nTo make the error message more helpful, and especially in rules with more than one literal parser to distinguish, create distinct, named rules:<\/p>\n
\r\nexclamation = lit('!');\r\nexclamation.name("!");\r\nrule = alpha > exclamation;\r\non_error<fail>(rule,\r\n std::cerr << val("Expected ") << _4 << " at offset "\r\n << (_3 - _1) << " in \\" << std::string(_1, _2) << '"'\r\n << std::endl);\r\n<\/pre>\nThis will report Expected ! at offset...<\/code> when the exclamation rule fails to match.<\/p>\nSince an expectation point failure is distinguished by the what<\/em> parameter, it follows that the what<\/em> parameter can be used to dispatch to different behavior in the error handler based upon which expectation point failed to match. Doing so can be as simple as passing the what<\/em> parameter to an error handling function which can use normal C++ techniques for dispatch such as cascading if-else’s or a map lookup, using the what<\/em> string as the key to find a function to call. However, Phoenix offers power to do that work within the context of the on_error()<\/code> call:<\/p>\n\r\nsemicolon = lit(';');\r\nsemicolon.name(";");\r\nrule = alpha > semicolon > alpha;\r\non_error<fail>(rule,\r\n let(_a = bind(&boost::spirit::info::tag, _4))\r\n [\r\n if_(";" == _a)\r\n [\r\n report_missing(_4, _1, _2, _3)\r\n ]\r\n .else_\r\n [\r\n if_("alpha" == _a)\r\n [\r\n report_missing("second word", _1, _2, _3)\r\n ]\r\n .else_\r\n [\r\n report_error(_4, _1, _2, _3)\r\n ]\r\n ]\r\n ]);\r\n<\/pre>\nFor the last example to compile, a number of include and using directives are necessary beyond the basics you are probably accustomed to seeing:<\/p>\n
\r\n#include <boost\/spirit\/home\/phoenix\/bind\/bind_member_variable.hpp>\r\n#include <boost\/spirit\/home\/phoenix\/scope\/let.hpp>\r\n#include <boost\/spirit\/home\/phoenix\/scope\/local_variable.hpp>\r\n#include <boost\/spirit\/home\/phoenix\/statement\/if.hpp>\r\nusing boost::phoenix::local_names;\r\n<\/pre>\nIt would seem, at first blush, that comparing to _4<\/code> directly should work, but it doesn’t because _4<\/code> is a Phoenix actor. Instead, a string type is needed to support the comparisons against the string literals for dispatching. In this example, a local Phoenix variable, _a<\/code> is declared and assigned the result of binding _4<\/code> to boost::spirit::info::tag, the field of the boost::spirit::info struct that contains the what<\/em> string. Thus, _a<\/code> is a variable local to the error handler that is bound to the boost::spirit::utf8_string that describes the error and supports comparisons. Note the use of Phoenix’s let<\/code> construct to declare a local variable scope. (This _a<\/code>, which is boost::phoenix::local_names::_a<\/code>, can be ambiguous with boost::spirit::qi::_a<\/code>, depending upon using directives and declarations.)<\/p>\nThe two functions, report_missing()<\/code> and report_error()<\/code> are not defined here, but presumably would report on stderr or raise an exception to indicate that a parsing error occurred, and would report the error context from the input range [_1,_2)<\/code> and would note the error location, within that range, as given by _3<\/code>.<\/p>\nWhen dispatching in this manner, there can be other parsing errors besides expectation point match failures, hence the final .else_<\/code> branch in the example error handler. For lack of a better response, the example just reports a generic error message that includes the what<\/em> parameter’s text to give some sort of explanation. A real world rule would possibly provide a more context-specific diagnostic.<\/p>\nA final caution regarding this technique: the compile time, maintenance burden, and code size increases with each additional expectation point to be handled. Using a map-based dispatch may well be better when the number of expectation points grows. However, the diagnostic text generation may get out of synchronization with the point in the grammar triggering it because of their being located in different parts of the code.<\/p>\n
There is another way to keep the diagnostic text near the rule triggering an error, while avoiding a great deal of code within the grammar. It involves collecting the rule name and corresponding diagnostic in a structure stored in an array that is then passed to an error handler that uses the what<\/em> parameter to select a diagnostic from the array. If that was as clear as mud, don’t worry. The code should make it clear. Let’s start with the rule name to diagnostic mapping which combines the structure and array within a class template:<\/p>\n\r\ntemplate <size_t N>\r\nclass diagnostics\r\n{\r\npublic:\r\n diagnostics();\r\n\r\n \/\/ Adds a tag and diagnostic message pair to self.\r\n void\r\n add(char const * _tag, char const * _diagnostic);\r\n\r\n \/\/ Returns the diagnostic, if any, for _tag.\r\n char const *\r\n operator [](char const * _tag) const;\r\n\r\nprivate:\r\n struct entry\r\n {\r\n char const * tag;\r\n char const * diagnostic;\r\n };\r\n\r\n entry entries_[N];\r\n size_t size_;\r\n};\r\n<\/pre>\ndiagnostics, as written, simply saves pointers to string literals. For more flexibility, it could store real strings (std::basic_string<>s, for instance), but this design is useful and simpler for exposition. To use diagnostics, one must create a grammar data member for each rule that will use it, and then populate it as needed by the rule:<\/p>\n
\r\nsemicolon = lit(';');\r\nsemicolon.name(";");\r\nrule = alpha > semicolon > alpha;\r\ndiags.add(";", "Missing semicolon after first word");\r\ndiags.add("alpha", "Missing second word");\r\non_error<fail>(rule,\r\n error_handler(ref(diags), _1, _2, _3, _4));\r\n<\/pre>\nNotice how the first expectation point is identified by a named rule for the required semicolon, which will produce an error message or exception containing the diagnostic text \"Missing semicolon after first word\"<\/code>. Similarly, if there is no word after a semicolon, then the diagnostic \"Missing second word\"<\/code> will be used because the second alpha will fail to match. In each case, the expectation is that the error handler will use _4<\/code> to indicate which rule fail to satisfy an expectation point.<\/p>\nTo round out this example, here’s how error_handler()<\/code> might look:<\/p>\n\r\nstruct error_handler_impl\r\n{\r\n template <class, class, class, class, class>\r\n struct result { typedef void type; };\r\n\r\n template <class D, class B, class E, class W, class I>\r\n void\r\n operator ()(D const & _diagnostics, B _begin, E _end,\r\n W _where, I const & _info) const\r\n {\r\n utf8_string const & tag(_info.tag);\r\n char const * const what(tag.c_str());\r\n char const * diagnostic(_diagnostics[what]);\r\n std::string scratch;\r\n if (!diagnostic)\r\n {\r\n scratch.reserve(25 + tag.length());\r\n scratch = "Invalid syntax: expected ";\r\n scratch += tag;\r\n diagnostic = scratch.c_str();\r\n }\r\n raise_parsing_error(diagnostic, _begin, _end,\r\n _where);\r\n }\r\n};\r\nphx::function<error_handler_impl> error_handler;\r\n<\/pre>\nYou’re probably wondering where the implementation of diagnostics’ member functions are to be found. Here they are:<\/p>\n
\r\ntemplate <size_t N>\r\ninline\r\ndiagnostics<N>::diagnostics()\r\n : size_(0)\r\n{\r\n}\r\n\r\ntemplate <size_t N>\r\nvoid\r\ndiagnostics<N>::add(char const * const _tag,\r\n char const * const _diagnostic)\r\n{\r\n assert(size_ < N);\r\n entry & e(entries_[size_++]);\r\n e.tag = _tag;\r\n e.diagnostic = _diagnostic;\r\n}\r\n\r\ntemplate <size_t N>\r\nchar const *\r\ndiagnostics<N>::operator [](char const * const _tag) const\r\n{\r\n for (size_t i(0); i < size_; ++i)\r\n {\r\n entry const & e(entries_[i]);\r\n if (0 == std::strcmp(e.tag, _tag))\r\n {\r\n return e.diagnostic;\r\n }\r\n }\r\n return 0;\r\n}\r\n<\/pre>\nIt should now be apparent that there are numerous ways to dispatch error handling when using expectation points, but all revolve around decoding the what<\/em> parameter. In the end, factor your grammar to be functional and readable and then consider which expectation point failure dispatching technique fits best without sacrificing readability or performance.<\/p>\nShare this:<\/h3>