boost/parser/error_handling_fwd.hpp

0001 #ifndef BOOST_PARSER_ERROR_HANDLING_FWD_HPP
0002 #define BOOST_PARSER_ERROR_HANDLING_FWD_HPP
0003
0004 #include <boost/parser/config.hpp>
0005
0006 #include <boost/parser/detail/text/transcode_view.hpp>
0007
0008 #include <iostream>
0009 #include <string_view>
0010
0011
0012 namespace boost { namespace parser {
0013
0014     /** The possible actions to take when a parse error is handled by an error
0015         handler. */
0016     enum class error_handler_result {
0017         fail,   /// Fail the top-level parse.
0018         rethrow /// Re-throw the parse error exception.
0019     };
0020
0021     /** The exception thrown when a parse error is encountered, consisting of
0022         an iterator to the point of failure, and the name of the failed parser
0023         or rule in `what()`. */
0024     template<typename Iter>
0025     struct parse_error : std::runtime_error
0026     {
0027         parse_error(Iter it, std::string const & msg) :
0028             runtime_error(msg), iter(it)
0029         {}
0030
0031         Iter iter;
0032     };
0033
0034     /** A position within a line, consisting of an iterator to the start of
0035         the line, the line number, and the column number. */
0036     template<typename Iter>
0037     struct line_position
0038     {
0039         Iter line_start;
0040         int64_t line_number;
0041         int64_t column_number;
0042     };
0043
0044     /** Writes a formatted message (meaning prefixed with the file name, line,
0045         and column number) to `os`. */
0046     template<typename Iter, typename Sentinel>
0047     std::ostream & write_formatted_message(
0048         std::ostream & os,
0049         std::string_view filename,
0050         Iter first,
0051         Iter it,
0052         Sentinel last,
0053         std::string_view message,
0054         int64_t preferred_max_line_length = 80,
0055         int64_t max_after_caret = 40);
0056
0057 #if defined(_MSC_VER) || defined(BOOST_PARSER_DOXYGEN)
0058     /** Writes a formatted message (meaning prefixed with the file name, line,
0059         and column number) to `os`.  This overload is Windows-only. */
0060     template<typename Iter, typename Sentinel>
0061     std::ostream & write_formatted_message(
0062         std::ostream & os,
0063         std::wstring_view filename,
0064         Iter first,
0065         Iter it,
0066         Sentinel last,
0067         std::string_view message,
0068         int64_t preferred_max_line_length = 80,
0069         int64_t max_after_caret = 40);
0070 #endif
0071
0072     /** Writes a formatted parse-expectation failure (meaning prefixed with
0073         the file name, line, and column number) to `os`. */
0074     template<typename Iter, typename Sentinel>
0075     std::ostream & write_formatted_expectation_failure_error_message(
0076         std::ostream & os,
0077         std::string_view filename,
0078         Iter first,
0079         Sentinel last,
0080         parse_error<Iter> const & e,
0081         int64_t preferred_max_line_length = 80,
0082         int64_t max_after_caret = 40);
0083
0084 #if defined(_MSC_VER) || defined(BOOST_PARSER_DOXYGEN)
0085     /** Writes a formatted parse-expectation failure (meaning prefixed with
0086         the file name, line, and column number) to `os`.  This overload is
0087         Windows-only. */
0088     template<typename Iter, typename Sentinel>
0089     std::ostream & write_formatted_expectation_failure_error_message(
0090         std::ostream & os,
0091         std::wstring_view filename,
0092         Iter first,
0093         Sentinel last,
0094         parse_error<Iter> const & e,
0095         int64_t preferred_max_line_length = 80,
0096         int64_t max_after_caret = 40);
0097 #endif
0098
0099     /** The kinds of diagnostics that can be handled by an error handler. */
0100     enum class diagnostic_kind {
0101         error,  /// An error diagnostic.
0102         warning /// A warning diagnostic.
0103     };
0104
0105     /** The error handler used when the user does not specify a custom one.
0106         This error handler prints warnings and errors to `std::cerr`, and does
0107         not have an associcated filename. */
0108     struct default_error_handler
0109     {
0110         constexpr default_error_handler() = default;
0111
0112         /** Handles a `parse_error` exception thrown during parsing.  A
0113             formatted parse-expectation failure is printed to `std::cerr`.
0114             Always returns `error_handler_result::fail`. */
0115         template<typename Iter, typename Sentinel>
0116         error_handler_result operator()(
0117             Iter first, Sentinel last, parse_error<Iter> const & e) const;
0118
0119         /** Prints `message` to `std::cerr`.  The diagnostic is printed with
0120             the given `kind`, indicating the location as being at `it`.  This
0121             must be called within a parser semantic action, providing the
0122             parse context. */
0123         //[ error_handler_api_1
0124         template<typename Context, typename Iter>
0125         void diagnose(
0126             diagnostic_kind kind,
0127             std::string_view message,
0128             Context const & context,
0129             Iter it) const;
0130         //]
0131
0132         /** Prints `message` to `std::cerr`.  The diagnostic is printed with
0133             the given `kind`, at no particular location.  This must be called
0134             within a parser semantic action, providing the parse context. */
0135         //[ error_handler_api_2
0136         template<typename Context>
0137         void diagnose(
0138             diagnostic_kind kind,
0139             std::string_view message,
0140             Context const & context) const;
0141         //]
0142     };
0143
0144     /** Prints warnings and errors to the `std::ostream`s provided by the
0145         user, or `std::cerr` if neither stream is specified.  If a filename is
0146         provided, that is used to print all diagnostics. */
0147     struct stream_error_handler
0148     {
0149         stream_error_handler() : err_os_(&std::cerr), warn_os_(err_os_) {}
0150         stream_error_handler(std::string_view filename) :
0151             filename_(filename), err_os_(&std::cerr), warn_os_(err_os_)
0152         {}
0153         stream_error_handler(std::string_view filename, std::ostream & errors) :
0154             filename_(filename), err_os_(&errors), warn_os_(&errors)
0155         {}
0156         stream_error_handler(
0157             std::string_view filename,
0158             std::ostream & errors,
0159             std::ostream & warnings) :
0160             filename_(filename), err_os_(&errors), warn_os_(&warnings)
0161         {}
0162 #if defined(_MSC_VER) || defined(BOOST_PARSER_DOXYGEN)
0163         /** This overload is Windows-only. */
0164         stream_error_handler(std::wstring_view filename) :
0165             err_os_(&std::cerr), warn_os_(err_os_)
0166         {
0167             auto const r = filename | detail::text::as_utf8;
0168             filename_.assign(r.begin(), r.end());
0169         }
0170         /** This overload is Windows-only. */
0171         stream_error_handler(
0172             std::wstring_view filename, std::ostream & errors) :
0173             err_os_(&errors), warn_os_(&errors)
0174         {
0175             auto const r = filename | detail::text::as_utf8;
0176             filename_.assign(r.begin(), r.end());
0177         }
0178         /** This overload is Windows-only. */
0179         stream_error_handler(
0180             std::wstring_view filename,
0181             std::ostream & errors,
0182             std::ostream & warnings) :
0183             err_os_(&errors), warn_os_(&warnings)
0184         {
0185             auto const r = filename | detail::text::as_utf8;
0186             filename_.assign(r.begin(), r.end());
0187         }
0188 #endif
0189
0190         /** Handles a `parse_error` exception thrown during parsing.  A
0191             formatted parse-expectation failure is printed to `*err_os_` when
0192             `err_os_` is non-null, or `std::cerr` otherwise.  Always returns
0193             `error_handler_result::fail`. */
0194         template<typename Iter, typename Sentinel>
0195         error_handler_result
0196         operator()(Iter first, Sentinel last, parse_error<Iter> const & e) const;
0197
0198         /** Let `std::ostream * s = kind == diagnostic_kind::error : err_os_ :
0199             warn_os_`; prints `message` to `*s` when `s` is non-null, or
0200             `std::cerr` otherwise.  The diagnostic is printed with the given
0201             `kind`, indicating the location as being at `it`.  This must be
0202             called within a parser semantic action, providing the parse
0203             context. */
0204         template<typename Context, typename Iter>
0205         void diagnose(
0206             diagnostic_kind kind,
0207             std::string_view message,
0208             Context const & context,
0209             Iter it) const;
0210
0211         /** Let `std::ostream * s = kind == diagnostic_kind::error : err_os_ :
0212             warn_os_`; prints `message` to `*s` when `s` is non-null, or
0213             `std::cerr` otherwise.  The diagnostic is printed with the given
0214             `kind`, at no particular location.  This must be called within a
0215             parser semantic action, providing the parse context. */
0216         template<typename Context>
0217         void diagnose(
0218             diagnostic_kind kind,
0219             std::string_view message,
0220             Context const & context) const;
0221
0222     private:
0223         std::string filename_;
0224         std::ostream * err_os_;
0225         std::ostream * warn_os_;
0226     };
0227
0228 }}
0229
0230 #endif