Add documentation for non-throwing expectations

doc/x3/spirit_x3.qbk

@@ -1,6 +1,7 @@
 [/==============================================================================
     Copyright (C) 2001-2015 Joel de Guzman
     Copyright (C) 2001-2011 Hartmut Kaiser
+    Copyright (C) 2024 Nana Sakisaka
 
     Distributed under the Boost Software License, Version 1.0. (See accompanying
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -237,6 +238,7 @@ Supported compilers will be:
 [include        tutorial/annotation.qbk]
 [include        tutorial/rexpr.qbk]
 [include        tutorial/error_handling.qbk]
+[include        tutorial/non_throwing_expectations.qbk]
 [endsect]
 
 [section    Quick Reference]

doc/x3/tutorial/error_handling.qbk

@@ -1,5 +1,6 @@
 [/==============================================================================
     Copyright (C) 2001-2018 Joel de Guzman
+    Copyright (C) 2024 Nana Sakisaka
 
     Distributed under the Boost Software License, Version 1.0. (See accompanying
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -94,6 +95,10 @@ matches the input or an exception is emitted. Using on_error(), that
 exception can be handled by calling a handler with the context at which the
 parsing failed can be reported.
 
+[tip    Check the [link spirit_x3.tutorials.non_throwing_expectations Non-throwing Expectations Tutorial]
+        for information on switching to more efficient error handling without using C++ exceptions.
+]
+
 [heading on_error]
 
 `on_error` is the counterpart of `on_success`, as discussed in the
@@ -104,6 +109,7 @@ that are executed by the parser when an __x3_expectation_failure__ is thrown
 via the expect operator or directive. `on_error` handlers have access to the
 iterators, the context and the exception that was thrown.
 
+[#__tutorial_error_handling__]
 [heading Error Handling]
 
 Before we proceed, let me introduce a helper class, the
@@ -129,8 +135,8 @@ Here's our `on_error` handler:
           , Exception const& x, Context const& context)
         {
             auto& error_handler = x3::get<x3::error_handler_tag>(context).get();
-            std::string message = "Error! Expecting: " + x.which() + " here:";
-            error_handler(x.where(), message);
+            std::string message = "Error! Expecting: " + x3::which(x) + " here:";
+            error_handler(x3::where(x), message);
             return x3::error_handler_result::fail;
         }
     };
@@ -146,7 +152,7 @@ determining the line number and actual column position, and formatting the
 error message printed. All we have to do is provide the actual error string
 which we extract from the __x3_expectation_failure__ exception:
 
-   std::string message = "Error! Expecting: " + x.which() + " here:";
+   std::string message = "Error! Expecting: " + x3::which(x) + " here:";
 
 Then, we return `x3::error_handler_result::fail` to tell X3 that we want to
 fail the parse when such an event is caught. You can return one of:

doc/x3/tutorial/non_throwing_expectations.qbk

@@ -0,0 +1,97 @@
+[/==============================================================================
+    Copyright (C) 2024 Nana Sakisaka
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+===============================================================================/]
+
+[section:non_throwing_expectations Non-throwing Expectations]
+
+By default, X3 throws __x3_expectation_failure__ when an expectation failure occurs.
+While C++ exceptions are straightforward, they come with significant overhead
+that can drastically impact your application's processing speed, especially if
+your parser is called within a performance-critical loop.
+
+In short, even the simplest grammar, like the one below, would throw exceptions
+100,000 times if invoked 100,000 times with mismatched input.
+
+    x3::lit('a') > 'b'
+
+You can change this behavior to store the error in a user-provided variable
+instead of throwing an exception.
+
+Non-throwing mode can be up to *1-90 times faster* than the traditional mode,
+depending on the complexity of your grammar.
+
+[tip    The performance improvement is capped by the overhead of C++ exceptions,
+        meaning the reduction in parse time is limited by the overhead that
+        exceptions would have introduced.
+]
+
+[heading Migration Guide]
+
+To switch to non-throwing mode, define the macro `BOOST_SPIRIT_X3_THROW_EXPECTATION_FAILURE`
+as `0` before including X3 headers, and then make a few modifications to your
+parser's entry point.
+
+Here's an example of a parser in its default (throwing) mode:
+
+    #include <boost/spirit/home/x3.hpp>
+
+    void do_parse()
+    {
+        // ... setup your variables here...
+
+        try
+        {
+            bool const ok = x3::parse(first, last, parser);
+            if (!ok)
+            {
+                // error handling
+            }
+        }
+        catch (x3::expectation_failure<Iterator> const& failure)
+        {
+            // error handling
+        }
+    }
+
+Next, adjust your code as follows to switch to non-throwing mode:
+
+    #define BOOST_SPIRIT_X3_THROW_EXPECTATION_FAILURE 0
+    #include <boost/spirit/home/x3.hpp>
+
+    void do_parse()
+    {
+        // ... setup your variables here...
+
+        // convenient helper, defaults to `boost::optional<x3::expectation_failure<Iterator>>`
+        x3::expectation_failure_optional<Iterator> failure;
+
+        bool const ok = x3::parse(
+            first, last, x3::with<x3::expectation_failure_tag>(failure)[parser]);
+
+        if (!ok)
+        {
+            if (failure.has_value())
+            {
+                // error handling
+            }
+        }
+    }
+
+[tip    You can also inspect the variable within [link __tutorial_error_handling__ `on_error` handler].
+]
+
+That's it! All X3 parsers will behave semantically the same as before,
+except that expectation failures will be stored in the variable instead of
+being thrown as C++ exceptions.
+
+The following types are supported for the context value:
+
+* `bool`
+* `std::optional<x3::expectation_failure<Iterator>>`
+* `boost::optional<x3::expectation_failure<Iterator>>`
+* `std::reference_wrapper` of optional types
+
+[endsect]