boost/parser
2
0
Fork 0
mirror of https://github.com/boostorg/parser.git synced 2026-01-19 04:22:13 +00:00
Code Issues Projects Releases Wiki Activity

Add Doxygen comments to all normalize_iterators() overloads, and indicate

Browse Source 
which error handling function apply this function to their inputs and which do
not.

See #202.
This commit is contained in:
Zach Laine
2024-12-07 18:56:18 -06:00
parent 5c036a778a
commit 0463ecb4f6
3 changed files with 33 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/tutorial.qbk
View File

@@ -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]

6
include/boost/parser/error_handling.hpp
View File

@@ -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<typename Iter>
line_position<Iter> 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<typename Iter, typename Sentinel>
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,

38
include/boost/parser/error_handling_fwd.hpp
View File

@@ -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<typename Iter, typename Sentinel>
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<typename Iter, typename Sentinel>
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<typename Iter, typename Sentinel, template<class> 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<typename Iter, typename Sentinel, template<class> 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<typename I, typename S>
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<typename I, typename S>
auto normalize_iterators(I first, parse_error<I> 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<typename I, typename S>
auto normalize_iterators(I first, lex_error<I> e, S last);