diff --git a/doc/tutorial.qbk b/doc/tutorial.qbk index 7ad3166f..ae87c5e7 100644 --- a/doc/tutorial.qbk +++ b/doc/tutorial.qbk @@ -4045,6 +4045,10 @@ reporting API you need to know which functions require token iterators and which do not, and how to get from token iterators down to the underlying input iterators. +TODO: Note on the error handling-specific page that some error handling +functions require normalize_iterators, and some apply it themselves. Also +note that all the error handlers appply it. + [endsect] [section Memory Allocation] diff --git a/include/boost/parser/error_handling.hpp b/include/boost/parser/error_handling.hpp index 8645c02f..86ffea80 100644 --- a/include/boost/parser/error_handling.hpp +++ b/include/boost/parser/error_handling.hpp @@ -31,7 +31,7 @@ namespace boost { namespace parser { } /** Returns the `line_position` for `it`, counting lines from the - beginning of the input `first`. */ + beginning of the input `first`. Requires non-token iterators. */ template line_position find_line_position(Iter first, Iter it) { @@ -57,7 +57,7 @@ namespace boost { namespace parser { } /** Returns the iterator to the end of the line in which `it` is - found. */ + found. Requires non-token iterators. */ template Iter find_line_end(Iter it, Sentinel last) { @@ -156,8 +156,6 @@ namespace boost { namespace parser { { std::string message = "error: Expected "; message += e.what(); - // TODO: Document that this gracefully handles token iterators, and - // document the other parts of the API that do or do not. auto [first, it, last] = parser::normalize_iterators(first_, e, last_); return parser::write_formatted_message( os, diff --git a/include/boost/parser/error_handling_fwd.hpp b/include/boost/parser/error_handling_fwd.hpp index 2676c52e..de367f08 100644 --- a/include/boost/parser/error_handling_fwd.hpp +++ b/include/boost/parser/error_handling_fwd.hpp @@ -61,7 +61,7 @@ namespace boost { namespace parser { }; /** Writes a formatted message (meaning prefixed with the file name, line, - and column number) to `os`. */ + and column number) to `os`. Normalizes token iterators as needed. */ template std::ostream & write_formatted_message( std::ostream & os, @@ -75,7 +75,8 @@ namespace boost { namespace parser { #if defined(_MSC_VER) || defined(BOOST_PARSER_DOXYGEN) /** Writes a formatted message (meaning prefixed with the file name, line, - and column number) to `os`. This overload is Windows-only. */ + and column number) to `os`. Normalizes token iterators as needed. + This overload is Windows-only. */ template std::ostream & write_formatted_message( std::ostream & os, @@ -89,7 +90,8 @@ namespace boost { namespace parser { #endif /** Writes a formatted parse-expectation failure (meaning prefixed with - the file name, line, and column number) to `os`. */ + the file name, line, and column number) to `os`. Normalizes token + iterators as needed. */ template class Exception> std::ostream & write_formatted_expectation_failure_error_message( std::ostream & os, @@ -102,8 +104,8 @@ namespace boost { namespace parser { #if defined(_MSC_VER) || defined(BOOST_PARSER_DOXYGEN) /** Writes a formatted parse-expectation failure (meaning prefixed with - the file name, line, and column number) to `os`. This overload is - Windows-only. */ + the file name, line, and column number) to `os`. Normalizes token + iterators as needed. This overload is Windows-only. */ template class Exception> std::ostream & write_formatted_expectation_failure_error_message( std::ostream & os, @@ -115,18 +117,32 @@ namespace boost { namespace parser { int64_t max_after_caret = 40); #endif - /** TODO: Document that users may need to use this if they make their own - error handlers and do token parsing. */ + // TODO: Document that users may need to use this if they make their own + // error handlers and do token parsing. + + /** Returns a tuple of three iterators (corresponding to `first`, `curr`, + and `last`) that are suitable for use in the other error handling + functions, many of which require iterators into the undelying sequence + being parsed. For non-token parsing cases, this is effectively a + no-op; the given iterators are simply returned as-is. */ template auto normalize_iterators(I first, I curr, S last); - /** TODO: Document that users may need to use this if they make their own - error handlers and do token parsing. */ + /** Returns a tuple of three iterators (corresponding to `first`, the + iterator captured in `e`, and `last`) that are suitable for use in the + other error handling functions, many of which require iterators into + the undelying sequence being parsed. For non-token parsing cases, + this is effectively a no-op; the given iterators are simply returned + as-is. */ template auto normalize_iterators(I first, parse_error e, S last); - /** TODO: Document that users may need to use this if they make their own - error handlers and do token parsing. */ + /** Returns a tuple of three iterators (corresponding to `first`, the + iterator captured in `e`, and `last`) that are suitable for use in the + other error handling functions, many of which require iterators into + the undelying sequence being parsed. For non-token parsing cases, + this is effectively a no-op; the given iterators are simply returned + as-is. */ template auto normalize_iterators(I first, lex_error e, S last);