From ed3683a8cea2f61e759a8a85aaa98114506d077f Mon Sep 17 00:00:00 2001 From: Emil Dotchevski Date: Sun, 6 Dec 2020 23:42:50 -0800 Subject: [PATCH] Uniform wrapping for multi-line comments --- examples/asio_beast_leaf_rpc.cpp | 100 ++++++++++-------- examples/capture_in_exception.cpp | 19 ++-- examples/capture_in_result.cpp | 19 ++-- examples/error_log.cpp | 31 +++--- examples/error_trace.cpp | 30 +++--- examples/exception_to_result.cpp | 34 +++--- examples/lua_callback_eh.cpp | 28 ++--- examples/lua_callback_result.cpp | 30 +++--- examples/print_file/print_file_eh.cpp | 32 +++--- .../print_file/print_file_eh_error_tags.cpp | 32 +++--- .../print_file/print_file_outcome_result.cpp | 38 ++++--- examples/print_file/print_file_result.cpp | 35 +++--- .../print_file_result_error_tags.cpp | 32 +++--- examples/print_half.cpp | 8 +- include/boost/leaf.hpp | 6 +- include/boost/leaf/result.hpp | 6 +- 16 files changed, 277 insertions(+), 203 deletions(-) diff --git a/examples/asio_beast_leaf_rpc.cpp b/examples/asio_beast_leaf_rpc.cpp index 6586a19..999dddc 100644 --- a/examples/asio_beast_leaf_rpc.cpp +++ b/examples/asio_beast_leaf_rpc.cpp @@ -3,10 +3,11 @@ // 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) -// PLEASE NOTE: This example requires the Boost 1.70 version of Asio and Beast, which at the time of this -// writing is in beta. +// PLEASE NOTE: This example requires the Boost 1.70 version of Asio and Beast, +// which at the time of this writing is in beta. -// Example of a composed asynchronous operation which uses the LEAF library for error handling and reporting. +// Example of a composed asynchronous operation which uses the LEAF library for +// error handling and reporting. // // Examples of running: // - in one terminal (re)run: ./asio_beast_leaf_rpc_v3 0.0.0.0 8080 @@ -62,24 +63,24 @@ using response_t = http::response; response_t handle_request(request_t &&request); -// A composed asynchronous operation that implements a basic remote calculator over HTTP. -// It receives from the remote side commands such as: +// A composed asynchronous operation that implements a basic remote calculator +// over HTTP. It receives from the remote side commands such as: // sum 1 2 3 // div 3 2 // mod 1 0 // in the body of POST requests and sends back the result. // // Besides the calculator related commands, it also offer a special command: -// - `error_quit` that asks the server to simulate a server side error that leads to the connection being dropped -// . +// - `error_quit` that asks the server to simulate a server side error that +// leads to the connection being dropped. // // From the error handling perspective there are three parts of the implementation: // - the handling of an HTTP request and creating the response to send back // (see handle_request) -// - the parsing and execution of the remote command we received as the body of an an HTTP POST request +// - the parsing and execution of the remote command we received as the body of +// an an HTTP POST request // (see execute_command()) -// - this composed asynchronous operation which calls them -// . +// - this composed asynchronous operation which calls them, // // This example operation is based on: // - https://github.com/boostorg/beast/blob/b02f59ff9126c5a17f816852efbbd0ed20305930/example/echo-op/echo_op.cpp @@ -137,28 +138,35 @@ auto async_demo_rpc(AsyncStream &stream, ErrorContext &error_context, Completion // If getting here, we completed a write operation. m_data.response.reset(); - // And start reading a new message if not quitting - // (i.e. the message semantics of the last response we sent required an end of file) + // And start reading a new message if not quitting (i.e. + // the message semantics of the last response we sent + // required an end of file) if (!m_write_and_quit) { start_read_request(); return true; } - // We didn't initiate any new async operation above, so we will not continue the execution. + // We didn't initiate any new async operation above, so + // we will not continue the execution. return false; }); } - // The activation object and load_last_operation need to be reset before calling the completion handler - // This is because, in general, the completion handler may be called directly or posted and if posted, - // it could execute in another thread. This means that regardless of how the handler gets to be actually - // called we must ensure that it is not called with the error context active. - // Note: An error context cannot be activated twice + // The activation object and load_last_operation need to be + // reset before calling the completion handler This is because, + // in general, the completion handler may be called directly or + // posted and if posted, it could execute in another thread. + // This means that regardless of how the handler gets to be + // actually called we must ensure that it is not called with the + // error context active. Note: An error context cannot be + // activated twice } if (!result_continue_execution) { - // We don't continue the execution due to an error, calling the completion handler + // We don't continue the execution due to an error, calling the + // completion handler this->complete_now(result_continue_execution.error()); } else if( !*result_continue_execution ) { - // We don't continue the execution due to the flag not being set, calling the completion handler + // We don't continue the execution due to the flag not being + // set, calling the completion handler this->complete_now(leaf::result{}); } } @@ -179,8 +187,8 @@ auto async_demo_rpc(AsyncStream &stream, ErrorContext &error_context, Completion return net::async_initiate)>(initiation, token, &stream, &error_context); } -// The location of a int64 parse error. -// It refers the range of characters from which the parsing was done. +// The location of a int64 parse error. It refers the range of characters from +// which the parsing was done. struct e_parse_int64_error { using location_base = std::pair; struct location : public location_base { @@ -216,14 +224,15 @@ leaf::result parse_int64(std::string_view word) { return value; } -// The command being executed while we get an error. -// It refers the range of characters from which the command was extracted. +// The command being executed while we get an error. It refers the range of +// characters from which the command was extracted. struct e_command { std::string_view value; }; -// The details about an incorrect number of arguments error -// Some commands may accept a variable number of arguments (e.g. greater than 1 would mean [2, SIZE_MAX]). +// The details about an incorrect number of arguments error Some commands may +// accept a variable number of arguments (e.g. greater than 1 would mean [2, +// SIZE_MAX]). struct e_unexpected_arg_count { struct arg_info { std::size_t count; @@ -349,7 +358,8 @@ leaf::result execute_command(std::string_view line) { for (auto const &w : words) { BOOST_LEAF_AUTO(i, parse_int64(w)); if (i == 0) { - // In some cases this command execution function might throw, not just return an error. + // In some cases this command execution function might throw, + // not just return an error. throw std::runtime_error{"division by zero"}; } div /= i; @@ -364,7 +374,8 @@ leaf::result execute_command(std::string_view line) { BOOST_LEAF_AUTO(i2, parse_int64(words.front())); words.pop_front(); if (i2 == 0) { - // In some cases this command execution function might throw, not just return an error. + // In some cases this command execution function might throw, not + // just return an error. throw leaf::exception(std::runtime_error{"division by zero"}); } response = std::to_string(i1 % i2); @@ -396,8 +407,9 @@ response_t handle_request(request_t &&request) { std::move(response)); }; - // In this variant of the RPC example we execute the remote command and handle any errors coming from it - // in one place (using `leaf::try_handle_all`). + // In this variant of the RPC example we execute the remote command and + // handle any errors coming from it in one place (using + // `leaf::try_handle_all`). auto pair_status_response = leaf::try_handle_all( [&]() -> leaf::result> { if (request.method() != http::verb::post) { @@ -407,14 +419,16 @@ response_t handle_request(request_t &&request) { BOOST_LEAF_AUTO(response, execute_command(request.body())); return std::make_pair(http::status::ok, std::move(response)); }, - // For the `error_quit` command and associated error condition we have the error handler itself fail - // (by throwing). This means that the server will not send any response to the client, it will just - // shutdown the connection. - // This implementation showcases two aspects: + // For the `error_quit` command and associated error condition we have + // the error handler itself fail (by throwing). This means that the + // server will not send any response to the client, it will just + // shutdown the connection. This implementation showcases two aspects: // - that the implementation of error handling can fail, too - // - how the asynchronous operation calling this error handling function reacts to this failure. + // - how the asynchronous operation calling this error handling function + // reacts to this failure. [](e_error_quit const &) -> std::pair { throw std::runtime_error("error_quit"); }, - // For the rest of error conditions we just build a message to be sent to the remote client. + // For the rest of error conditions we just build a message to be sent + // to the remote client. [&](e_parse_int64_error const &e, e_http_status const *status, e_command const *cmd, leaf::verbose_diagnostic_info const &diag) { return make_sr(status, boost::str(boost::format("%1% int64 parse error: %2%") % msg_prefix(cmd) % e.value) + @@ -459,7 +473,8 @@ int main(int argc, char **argv) { return std::string("Error: "); }; - // Error handler for internal server internal errors (not communicated to the remote client). + // Error handler for internal server internal errors (not communicated to + // the remote client). auto error_handlers = std::make_tuple( [&](std::exception_ptr const &ep, e_last_operation const *op) { return leaf::try_handle_all( @@ -487,9 +502,9 @@ int main(int argc, char **argv) { return -23; }); - // Top level try block and error handler. - // It will handle errors from starting the server for example failure to bind to a given port - // (e.g. ports less than 1024 if not running as root) + // Top level try block and error handler. It will handle errors from + // starting the server for example failure to bind to a given port (e.g. + // ports less than 1024 if not running as root) return leaf::try_handle_all( [&]() -> leaf::result { auto load = leaf::on_error(e_last_operation{"main"}); @@ -526,8 +541,9 @@ int main(int argc, char **argv) { auto error_context = leaf::make_context(error_handlers); int rv = 0; async_demo_rpc(socket, error_context, [&](leaf::result result) { - // Note: In case we wanted to add some additional information to the error associated with the result - // we would need to activate the error-context + // Note: In case we wanted to add some additional information to + // the error associated with the result we would need to + // activate the error-context auto active_context = activate_context(error_context); if (result) { std::cout << "Server: Client work completed successfully" << std::endl; diff --git a/examples/capture_in_exception.cpp b/examples/capture_in_exception.cpp index 1c6e3ae..b15b5df 100644 --- a/examples/capture_in_exception.cpp +++ b/examples/capture_in_exception.cpp @@ -27,7 +27,8 @@ struct e_failure_info2 { int value; }; // A type that represents a successfully returned result from a task. struct task_result { }; - // This is our task function. It produces objects of type task_result, but it may fail... + // This is our task function. It produces objects of type task_result, but it + // may fail. task_result task() { bool succeed = (rand()%4) != 0; //...at random. @@ -44,9 +45,9 @@ int main() { int const task_count = 42; - // The error_handlers are used in this thread (see leaf::try_catch below). The - // arguments passed to individual lambdas are transported from the worker thread - // to the main thread automatically. + // The error_handlers are used in this thread (see leaf::try_catch below). + // The arguments passed to individual lambdas are transported from the + // worker thread to the main thread automatically. auto error_handlers = std::make_tuple( []( e_failure_info1 const & v1, e_failure_info2 const & v2, e_thread_id const & tid ) { @@ -63,11 +64,11 @@ int main() // Container to collect the generated std::future objects. std::vector> fut; - // Launch the tasks, but rather than launching the task function directly, we launch a - // wrapper function which calls leaf::capture, passing a context object that will hold - // the error objects reported from the task in case it throws. The error types the - // context is able to hold statically are automatically deduced from the type of the - // error_handlers tuple. + // Launch the tasks, but rather than launching the task function directly, + // we launch a wrapper function which calls leaf::capture, passing a context + // object that will hold the error objects reported from the task in case it + // throws. The error types the context is able to hold statically are + // automatically deduced from the type of the error_handlers tuple. std::generate_n( std::back_inserter(fut), task_count, [&] { diff --git a/examples/capture_in_result.cpp b/examples/capture_in_result.cpp index 906fe43..0947685 100644 --- a/examples/capture_in_result.cpp +++ b/examples/capture_in_result.cpp @@ -27,7 +27,8 @@ struct e_failure_info2 { int value; }; // A type that represents a successfully returned result from a task. struct task_result { }; - // This is our task function. It produces objects of type task_result, but it may fail... + // This is our task function. It produces objects of type task_result, but it + // may fail. leaf::result task() { bool succeed = (rand()%4) != 0; //...at random. @@ -44,9 +45,9 @@ int main() { int const task_count = 42; - // The error_handlers are used in this thread (see leaf::try_handle_all below). The - // arguments passed to individual lambdas are transported from the worker thread - // to the main thread automatically. + // The error_handlers are used in this thread (see leaf::try_handle_all + // below). The arguments passed to individual lambdas are transported from + // the worker thread to the main thread automatically. auto error_handlers = std::make_tuple( []( e_failure_info1 const & v1, e_failure_info2 const & v2, e_thread_id const & tid ) { @@ -63,11 +64,11 @@ int main() // Container to collect the generated std::future objects. std::vector>> fut; - // Launch the tasks, but rather than launching the task function directly, we launch a - // wrapper function which calls leaf::capture, passing a context object that will hold - // the error objects reported from the task in case of an error. The error types the - // context is able to hold statically are automatically deduced from the type of the - // error_handlers tuple. + // Launch the tasks, but rather than launching the task function directly, + // we launch a wrapper function which calls leaf::capture, passing a context + // object that will hold the error objects reported from the task in case of + // an error. The error types the context is able to hold statically are + // automatically deduced from the type of the error_handlers tuple. std::generate_n( std::back_inserter(fut), task_count, [&] { diff --git a/examples/error_log.cpp b/examples/error_log.cpp index b3f72a1..412f61d 100644 --- a/examples/error_log.cpp +++ b/examples/error_log.cpp @@ -3,14 +3,14 @@ // 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) -// This program demonstrates the use of leaf::on_error to print the path an error takes -// as it bubbles up the call stack. The printing code only runs if: +// This program demonstrates the use of leaf::on_error to print the path an +// error takes as it bubbles up the call stack. The printing code only runs if: // - An error occurs, and -// - A handler that takes e_error_log argument is present. -// Otherwise none of the error log machinery will be invoked by LEAF. +// - A handler that takes e_error_log argument is present. Otherwise none of the +// error log machinery will be invoked by LEAF. -// This example is similar to error_trace, except the path the error takes is not captured, -// only printed. +// This example is similar to error_trace, except the path the error takes is +// not captured, only printed. #include #include @@ -22,7 +22,8 @@ namespace leaf = boost::leaf; -// The error log is activated only if an error-handling scope provides a handler for e_error_log. +// The error log is activated only if an error-handling scope provides a handler +// for e_error_log. struct e_error_log { struct rec @@ -40,7 +41,8 @@ struct e_error_log std::cerr << "Error! Log:" << std::endl; } - // Our e_error_log instance is stateless, used only as a target to operator<<. + // Our e_error_log instance is stateless, used only as a target to + // operator<<. template friend std::ostream & operator<<( e_error_log const &, T const & x ) { @@ -48,14 +50,15 @@ struct e_error_log } }; -// The ERROR_LOG macro is designed for use in functions that detect or forward errors -// up the call stack. If an error occurs, and if an error-handling scope provides a handler -// for e_error_log, the supplied lambda is executed as the error bubbles up. +// The ERROR_LOG macro is designed for use in functions that detect or forward +// errors up the call stack. If an error occurs, and if an error-handling scope +// provides a handler for e_error_log, the supplied lambda is executed as the +// error bubbles up. #define ERROR_LOG auto _log = leaf::on_error( []( e_error_log & log ) { log << e_error_log::rec{__FILE__, __LINE__}; } ) -// Each function in the sequence below calls the previous function, and each function has -// failure_percent chance of failing. If a failure occurs, the ERROR_LOG macro will cause -// the path the error takes to be printed. +// Each function in the sequence below calls the previous function, and each +// function has failure_percent chance of failing. If a failure occurs, the +// ERROR_LOG macro will cause the path the error takes to be printed. int const failure_percent = 25; leaf::result f1() diff --git a/examples/error_trace.cpp b/examples/error_trace.cpp index ae6b96c..9eed432 100644 --- a/examples/error_trace.cpp +++ b/examples/error_trace.cpp @@ -3,14 +3,15 @@ // 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) -// This program demonstrates the use of leaf::on_error to capture the path an error takes -// as is bubbles up the call stack. The error path-capturing code only runs if: +// This program demonstrates the use of leaf::on_error to capture the path an +// error takes as is bubbles up the call stack. The error path-capturing code +// only runs if: // - An error occurs, and -// - A handler that takes e_error_trace argument is present. -// Otherwise none of the error trace machinery will be invoked by LEAF. +// - A handler that takes e_error_trace argument is present. Otherwise none of +// the error trace machinery will be invoked by LEAF. -// This example is similar to error_log, except the path the error takes is recorded in -// a std::deque, rather than just printed in-place. +// This example is similar to error_log, except the path the error takes is +// recorded in a std::deque, rather than just printed in-place. #include #include @@ -23,7 +24,8 @@ namespace leaf = boost::leaf; -// The error trace is activated only if an error-handling scope provides a handler for e_error_trace. +// The error trace is activated only if an error-handling scope provides a +// handler for e_error_trace. struct e_error_trace { struct rec @@ -46,14 +48,16 @@ struct e_error_trace } }; -// The ERROR_TRACE macro is designed for use in functions that detect or forward errors -// up the call stack. If an error occurs, and if an error-handling scope provides a handler -// for e_error_trace, the supplied lambda is executed as the error bubbles up. +// The ERROR_TRACE macro is designed for use in functions that detect or forward +// errors up the call stack. If an error occurs, and if an error-handling scope +// provides a handler for e_error_trace, the supplied lambda is executed as the +// error bubbles up. #define ERROR_TRACE auto _trace = leaf::on_error( []( e_error_trace & tr ) { tr.value.emplace_front(e_error_trace::rec{__FILE__, __LINE__}); } ) -// Each function in the sequence below calls the previous function, and each function has -// failure_percent chance of failing. If a failure occurs, the ERROR_TRACE macro will cause -// the path the error takes to be captured in an e_error_trace. +// Each function in the sequence below calls the previous function, and each +// function has failure_percent chance of failing. If a failure occurs, the +// ERROR_TRACE macro will cause the path the error takes to be captured in an +// e_error_trace. int const failure_percent = 25; leaf::result f1() diff --git a/examples/exception_to_result.cpp b/examples/exception_to_result.cpp index d565a44..031e200 100644 --- a/examples/exception_to_result.cpp +++ b/examples/exception_to_result.cpp @@ -3,9 +3,9 @@ // 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) -// This example demonstrates how to transport exceptions thrown by a low level function -// through an intermediate scopes that are not exception-safe, to be handled in a high -// level function which may or may not be exception-safe. +// This example demonstrates how to transport exceptions thrown by a low level +// function through an intermediate scopes that are not exception-safe, to be +// handled in a high level function which may or may not be exception-safe. #include #include @@ -37,8 +37,9 @@ int compute_answer_throws() // Call compute_answer_throws, switch to result for error handling. leaf::result compute_answer() noexcept { - // Convert exceptions of types error_a and error_b to be communicated by leaf::result. - // Any other exception will be communicated as a std::exception_ptr. + // Convert exceptions of types error_a and error_b to be communicated by + // leaf::result. Any other exception will be communicated as a + // std::exception_ptr. return leaf::exception_to_result( [] { @@ -58,9 +59,9 @@ leaf::result print_answer() noexcept int main() { - // Exercise print_answer a few times and handle errors. Note that the exception objects - // that compute_answer_throws throws are not handled as exceptions, but as regular - // LEAF error error objects... + // Exercise print_answer a few times and handle errors. Note that the + // exception objects that compute_answer_throws throws are not handled as + // exceptions, but as regular LEAF error error objects... for( int i=0; i!=42; ++i ) { leaf::try_handle_all( @@ -80,18 +81,21 @@ int main() std::cerr << "Error B!" << std::endl; }, - //...except for error_c errors, which (for demonstration) are captured as exceptions - // into std::exception_ptr as "unknown" exceptions. Presumably this should not - // happen, therefore at this point we treat this situation as a logic error: we print + // ...except for error_c errors, which (for demonstration) are + // captured as exceptions into std::exception_ptr as "unknown" + // exceptions. Presumably this should not happen, therefore at this + // point we treat this situation as a logic error: we print // diagnostic information and bail out. []( std::exception_ptr const * ep ) { std::cerr << "Got unknown error!" << std::endl; - // Above, why do we take ep as a pointer? Because handle_all requires that the last - // handler matches any error and, taken as a pointer, if there isn't a std::exception_ptr - // associated with the error, the handler will still be matched (with 0 passed for ep). - // Had we taken it by value or by const &, the program would not have compiled. + // Above, why do we take ep as a pointer? Because handle_all + // requires that the last handler matches any error and, taken + // as a pointer, if there isn't a std::exception_ptr associated + // with the error, the handler will still be matched (with 0 + // passed for ep). Had we taken it by value or by const &, the + // program would not have compiled. if( ep ) leaf::try_catch( [&] diff --git a/examples/lua_callback_eh.cpp b/examples/lua_callback_eh.cpp index b4cd607..f6ad354 100644 --- a/examples/lua_callback_eh.cpp +++ b/examples/lua_callback_eh.cpp @@ -28,10 +28,11 @@ struct e_lua_pcall_error { int value; }; struct e_lua_error_message { std::string value; }; -// This is a C callback with a specific signature, callable from programs written in Lua. -// If it succeeds, it returns an int answer, by pushing it onto the Lua stack. But "sometimes" -// it fails, in which case it throws an exception. This causes the Lua interpreter to abort and -// pop back into the C++ code which called it (see call_lua below). +// This is a C callback with a specific signature, callable from programs +// written in Lua. If it succeeds, it returns an int answer, by pushing it onto +// the Lua stack. But "sometimes" it fails, in which case it throws an +// exception. This causes the Lua interpreter to abort and pop back into the C++ +// code which called it (see call_lua below). int do_work( lua_State * L ) { bool success = rand()%2; // "Sometimes" do_work fails. @@ -53,12 +54,13 @@ std::shared_ptr init_lua_state() std::shared_ptr L(lua_open(), &lua_close); // Register the do_work function (above) as a C callback, under the global - // Lua name "do_work". With this, calls from Lua programs to do_work - // will land in the do_work C function we've registered. + // Lua name "do_work". With this, calls from Lua programs to do_work will + // land in the do_work C function we've registered. lua_register( &*L, "do_work", &do_work ); - // Pass some Lua code as a C string literal to Lua. This creates a global Lua - // function called "call_do_work", which we will later ask Lua to execute. + // Pass some Lua code as a C string literal to Lua. This creates a global + // Lua function called "call_do_work", which we will later ask Lua to + // execute. luaL_dostring( &*L, "\ \n function call_do_work()\ \n return do_work()\ @@ -72,8 +74,8 @@ std::shared_ptr init_lua_state() // in Lua, and returns the value from do_work, which is written in C++ and // registered with the Lua interpreter as a C callback. -// If do_work succeeds, we return the resulting int answer. -// If it fails, we'll communicate that failure to our caller. +// If do_work succeeds, we return the resulting int answer. If it fails, we'll +// communicate that failure to our caller. int call_lua( lua_State * L ) { // Ask the Lua interpreter to call the global Lua function call_do_work. @@ -83,9 +85,9 @@ int call_lua( lua_State * L ) auto load = leaf::on_error(e_lua_error_message{lua_tostring(L, 1)}); lua_pop(L,1); - // We got a Lua error that is definitely not the error we're throwing in do_work. - // (if it did throw an exception, we won't be here). - // Throw a new exception to indicate that lua_pcall returned an error. + // We got a Lua error that is definitely not the error we're throwing in + // do_work. (if it did throw an exception, we won't be here). Throw a + // new exception to indicate that lua_pcall returned an error. throw leaf::exception(e_lua_pcall_error{err}); } else diff --git a/examples/lua_callback_result.cpp b/examples/lua_callback_result.cpp index 0de1c7e..e31fce3 100644 --- a/examples/lua_callback_result.cpp +++ b/examples/lua_callback_result.cpp @@ -28,10 +28,11 @@ struct e_lua_pcall_error { int value; }; struct e_lua_error_message { std::string value; }; -// This is a C callback with a specific signature, callable from programs written in Lua. -// If it succeeds, it returns an int answer, by pushing it onto the Lua stack. But "sometimes" -// it fails, in which case it calls luaL_error. This causes the Lua interpreter to abort and -// pop back into the C++ code which called it (see call_lua below). +// This is a C callback with a specific signature, callable from programs +// written in Lua. If it succeeds, it returns an int answer, by pushing it onto +// the Lua stack. But "sometimes" it fails, in which case it calls luaL_error. +// This causes the Lua interpreter to abort and pop back into the C++ code which +// called it (see call_lua below). int do_work( lua_State * L ) { bool success = rand()%2; // "Sometimes" do_work fails. @@ -53,12 +54,13 @@ std::shared_ptr init_lua_state() std::shared_ptr L(lua_open(), &lua_close); // Register the do_work function (above) as a C callback, under the global - // Lua name "do_work". With this, calls from Lua programs to do_work - // will land in the do_work C function we've registered. + // Lua name "do_work". With this, calls from Lua programs to do_work will + // land in the do_work C function we've registered. lua_register( &*L, "do_work", &do_work ); - // Pass some Lua code as a C string literal to Lua. This creates a global Lua - // function called "call_do_work", which we will later ask Lua to execute. + // Pass some Lua code as a C string literal to Lua. This creates a global + // Lua function called "call_do_work", which we will later ask Lua to + // execute. luaL_dostring( &*L, "\ \n function call_do_work()\ \n return do_work()\ @@ -72,8 +74,8 @@ std::shared_ptr init_lua_state() // in Lua, and returns the value from do_work, which is written in C++ and // registered with the Lua interpreter as a C callback. -// If do_work succeeds, we return the resulting int answer. -// If it fails, we'll communicate that failure to our caller. +// If do_work succeeds, we return the resulting int answer. If it fails, we'll +// communicate that failure to our caller. leaf::result call_lua( lua_State * L ) { leaf::error_monitor cur_err; @@ -85,9 +87,11 @@ leaf::result call_lua( lua_State * L ) auto load = leaf::on_error(e_lua_error_message{lua_tostring(L, 1)}); lua_pop(L,1); - // We got a Lua error which may be the error we're reporting from do_work, or some other error. - // If it is another error, cur_err.assigned_error_id() will return a new leaf::error_id, - // otherwise we'll be working with the original value returned by leaf::new_error in do_work. + // We got a Lua error which may be the error we're reporting from + // do_work, or some other error. If it is another error, + // cur_err.assigned_error_id() will return a new leaf::error_id, + // otherwise we'll be working with the original value returned by + // leaf::new_error in do_work. return cur_err.assigned_error_id().load(e_lua_pcall_error{err}); } else diff --git a/examples/print_file/print_file_eh.cpp b/examples/print_file/print_file_eh.cpp index 9665c31..c2c0d53 100644 --- a/examples/print_file/print_file_eh.cpp +++ b/examples/print_file/print_file_eh.cpp @@ -3,11 +3,12 @@ // 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) -// This is the program presented in https://boostorg.github.io/leaf/#introduction-eh. +// This is the program presented in +// https://boostorg.github.io/leaf/#introduction-eh. -// It reads a text file in a buffer and prints it to std::cout, using LEAF to handle errors. -// This version uses exception handling. The version that does not use exception -// handling is in print_file_result.cpp. +// It reads a text file in a buffer and prints it to std::cout, using LEAF to +// handle errors. This version uses exception handling. The version that does +// not use exception handling is in print_file_result.cpp. #include #include @@ -31,8 +32,9 @@ struct eof_error: input_error { }; struct output_error: std::exception { }; -// We will handle all failures in our main function, but first, here are the declarations of the functions it calls, each -// communicating failures by throwing exceptions +// We will handle all failures in our main function, but first, here are the +// declarations of the functions it calls, each communicating failures by +// throwing exceptions // Parse the command line, return the file name. char const * parse_command_line( int argc, char const * argv[] ); @@ -73,12 +75,14 @@ int main( int argc, char const * argv[] ) return 0; }, - // Each of the lambdas below is an error handler. LEAF will consider them, in order, and call the first one that matches - // the available error objects. + // Each of the lambdas below is an error handler. LEAF will consider + // them, in order, and call the first one that matches the available + // error objects. // This handler will be called if the error includes: // - a caught exception of type open_error, and - // - an object of type leaf::e_errno that has .value equal to ENOENT, and + // - an object of type leaf::e_errno that has .value equal to ENOENT, + // and // - an object of type leaf::e_file_name. []( open_error &, leaf::match_value, leaf::e_file_name const & fn ) { @@ -98,7 +102,8 @@ int main( int argc, char const * argv[] ) // This handler will be called if the error includes: // - a caught exception of type input_error, and - // - an optional object of type leaf::e_errno (regardless of its .value), and + // - an optional object of type leaf::e_errno (regardless of its + // .value), and // - an object of type leaf::e_file_name. []( input_error &, leaf::e_errno const * errn, leaf::e_file_name const & fn ) { @@ -125,9 +130,10 @@ int main( int argc, char const * argv[] ) return 5; }, - // This last handler matches any error: it prints diagnostic information to help debug logic errors in the program, since it - // failed to match an appropriate error handler to the error condition it encountered. In this program this handler will - // never be called. + // This last handler matches any error: it prints diagnostic information + // to help debug logic errors in the program, since it failed to match + // an appropriate error handler to the error condition it encountered. + // In this program this handler will never be called. []( leaf::error_info const & unmatched ) { std::cerr << diff --git a/examples/print_file/print_file_eh_error_tags.cpp b/examples/print_file/print_file_eh_error_tags.cpp index 648796e..2f088af 100644 --- a/examples/print_file/print_file_eh_error_tags.cpp +++ b/examples/print_file/print_file_eh_error_tags.cpp @@ -3,11 +3,12 @@ // 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) -// This is the program presented in https://boostorg.github.io/leaf/#introduction-eh. +// This is the program presented in +// https://boostorg.github.io/leaf/#introduction-eh. -// It reads a text file in a buffer and prints it to std::cout, using LEAF to handle errors. -// This version uses exception handling. The version that does not use exception -// handling is in print_file_result.cpp. +// It reads a text file in a buffer and prints it to std::cout, using LEAF to +// handle errors. This version uses exception handling. The version that does +// not use exception handling is in print_file_result.cpp. #include #include @@ -31,8 +32,9 @@ struct eof_error { }; struct output_error { }; -// We will handle all failures in our main function, but first, here are the declarations of the functions it calls, each -// communicating failures by throwing exceptions +// We will handle all failures in our main function, but first, here are the +// declarations of the functions it calls, each communicating failures by +// throwing exceptions // Parse the command line, return the file name. char const * parse_command_line( int argc, char const * argv[] ); @@ -73,12 +75,14 @@ int main( int argc, char const * argv[] ) return 0; }, - // Each of the lambdas below is an error handler. LEAF will consider them, in order, and call the first one that matches - // the available error objects. + // Each of the lambdas below is an error handler. LEAF will consider + // them, in order, and call the first one that matches the available + // error objects. // This handler will be called if the error includes: // - an object of type open_error, and - // - an object of type leaf::e_errno that has .value equal to ENOENT, and + // - an object of type leaf::e_errno that has .value equal to ENOENT, + // and // - an object of type leaf::e_file_name. []( open_error &, leaf::match_value, leaf::e_file_name const & fn ) { @@ -98,7 +102,8 @@ int main( int argc, char const * argv[] ) // This handler will be called if the error includes: // - an object of type input_error, and - // - an optional object of type leaf::e_errno (regardless of its .value), and + // - an optional object of type leaf::e_errno (regardless of its + // .value), and // - an object of type leaf::e_file_name. []( input_error &, leaf::e_errno const * errn, leaf::e_file_name const & fn ) { @@ -125,9 +130,10 @@ int main( int argc, char const * argv[] ) return 5; }, - // This last handler matches any error: it prints diagnostic information to help debug logic errors in the program, since it - // failed to match an appropriate error handler to the error condition it encountered. In this program this handler will - // never be called. + // This last handler matches any error: it prints diagnostic information + // to help debug logic errors in the program, since it failed to match + // an appropriate error handler to the error condition it encountered. + // In this program this handler will never be called. []( leaf::error_info const & unmatched ) { std::cerr << diff --git a/examples/print_file/print_file_outcome_result.cpp b/examples/print_file/print_file_outcome_result.cpp index c474b84..b96e450 100644 --- a/examples/print_file/print_file_outcome_result.cpp +++ b/examples/print_file/print_file_outcome_result.cpp @@ -3,11 +3,12 @@ // 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) -// This is the program presented in https://boostorg.github.io/leaf/#introduction-result, -// converted to use outcome::result instead of leaf::result. +// This is the program presented in +// https://boostorg.github.io/leaf/#introduction-result, converted to use +// outcome::result instead of leaf::result. -// It reads a text file in a buffer and prints it to std::cout, using LEAF to handle errors. -// This version does not use exception handling. +// It reads a text file in a buffer and prints it to std::cout, using LEAF to +// handle errors. This version does not use exception handling. #include #include @@ -37,14 +38,16 @@ enum error_code template using result = outcome::std_result; -// To enable LEAF to work with outcome::result, we need to specialize the is_result_type template: +// To enable LEAF to work with outcome::result, we need to specialize the +// is_result_type template: namespace boost { namespace leaf { template struct is_result_type>: std::true_type { }; } } -// We will handle all failures in our main function, but first, here are the declarations of the functions it calls, each -// communicating failures using result: +// We will handle all failures in our main function, but first, here are the +// declarations of the functions it calls, each communicating failures using +// result: // Parse the command line, return the file name. result parse_command_line( int argc, char const * argv[] ); @@ -85,12 +88,14 @@ int main( int argc, char const * argv[] ) return 0; }, - // Each of the lambdas below is an error handler. LEAF will consider them, in order, and call the first one that matches - // the available error objects. + // Each of the lambdas below is an error handler. LEAF will consider + // them, in order, and call the first one that matches the available + // error objects. // This handler will be called if the error includes: // - an object of type error_code equal to open_error, and - // - an object of type leaf::e_errno that has .value equal to ENOENT, and + // - an object of type leaf::e_errno that has .value equal to ENOENT, + // and // - an object of type leaf::e_file_name. []( leaf::match, leaf::match_value, leaf::e_file_name const & fn ) { @@ -109,8 +114,10 @@ int main( int argc, char const * argv[] ) }, // This handler will be called if the error includes: - // - an object of type error_code equal to any of size_error, read_error, eof_error, and - // - an optional object of type leaf::e_errno (regardless of its .value), and + // - an object of type error_code equal to any of size_error, + // read_error, eof_error, and + // - an optional object of type leaf::e_errno (regardless of its + // .value), and // - an object of type leaf::e_file_name. []( leaf::match, leaf::e_errno const * errn, leaf::e_file_name const & fn ) { @@ -137,9 +144,10 @@ int main( int argc, char const * argv[] ) return 5; }, - // This last handler matches any error: it prints diagnostic information to help debug logic errors in the program, since it - // failed to match an appropriate error handler to the error condition it encountered. In this program this handler will - // never be called. + // This last handler matches any error: it prints diagnostic information + // to help debug logic errors in the program, since it failed to match + // an appropriate error handler to the error condition it encountered. + // In this program this handler will never be called. []( leaf::error_info const & unmatched ) { std::cerr << diff --git a/examples/print_file/print_file_result.cpp b/examples/print_file/print_file_result.cpp index 50c5359..2843033 100644 --- a/examples/print_file/print_file_result.cpp +++ b/examples/print_file/print_file_result.cpp @@ -3,11 +3,12 @@ // 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) -// This is the program presented in https://boostorg.github.io/leaf/#introduction-result. +// This is the program presented in +// https://boostorg.github.io/leaf/#introduction-result. -// It reads a text file in a buffer and prints it to std::cout, using LEAF to handle errors. -// This version does not use exception handling. The version that does use exception -// handling is in print_file_eh.cpp. +// It reads a text file in a buffer and prints it to std::cout, using LEAF to +// handle errors. This version does not use exception handling. The version that +// does use exception handling is in print_file_eh.cpp. #include #include @@ -37,8 +38,9 @@ template using result = leaf::result; -// We will handle all failures in our main function, but first, here are the declarations of the functions it calls, each -// communicating failures using result: +// We will handle all failures in our main function, but first, here are the +// declarations of the functions it calls, each communicating failures using +// result: // Parse the command line, return the file name. result parse_command_line( int argc, char const * argv[] ); @@ -79,12 +81,14 @@ int main( int argc, char const * argv[] ) return 0; }, - // Each of the lambdas below is an error handler. LEAF will consider them, in order, and call the first one that matches - // the available error objects. + // Each of the lambdas below is an error handler. LEAF will consider + // them, in order, and call the first one that matches the available + // error objects. // This handler will be called if the error includes: // - an object of type error_code equal to open_error, and - // - an object of type leaf::e_errno that has .value equal to ENOENT, and + // - an object of type leaf::e_errno that has .value equal to ENOENT, + // and // - an object of type leaf::e_file_name. []( leaf::match, leaf::match_value, leaf::e_file_name const & fn ) { @@ -103,8 +107,10 @@ int main( int argc, char const * argv[] ) }, // This handler will be called if the error includes: - // - an object of type error_code equal to any of size_error, read_error, eof_error, and - // - an optional object of type leaf::e_errno (regardless of its .value), and + // - an object of type error_code equal to any of size_error, + // read_error, eof_error, and + // - an optional object of type leaf::e_errno (regardless of its + // .value), and // - an object of type leaf::e_file_name. []( leaf::match, leaf::e_errno const * errn, leaf::e_file_name const & fn ) { @@ -131,9 +137,10 @@ int main( int argc, char const * argv[] ) return 5; }, - // This last handler matches any error: it prints diagnostic information to help debug logic errors in the program, since it - // failed to match an appropriate error handler to the error condition it encountered. In this program this handler will - // never be called. + // This last handler matches any error: it prints diagnostic information + // to help debug logic errors in the program, since it failed to match + // an appropriate error handler to the error condition it encountered. + // In this program this handler will never be called. []( leaf::error_info const & unmatched ) { std::cerr << diff --git a/examples/print_file/print_file_result_error_tags.cpp b/examples/print_file/print_file_result_error_tags.cpp index 5549a83..a1f8f04 100644 --- a/examples/print_file/print_file_result_error_tags.cpp +++ b/examples/print_file/print_file_result_error_tags.cpp @@ -3,11 +3,12 @@ // 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) -// This is the program presented in https://boostorg.github.io/leaf/#introduction-eh. +// This is the program presented in +// https://boostorg.github.io/leaf/#introduction-eh. -// It reads a text file in a buffer and prints it to std::cout, using LEAF to handle errors. -// This version does not use exception handling. The version that does use exception -// handling is in print_file_eh.cpp. +// It reads a text file in a buffer and prints it to std::cout, using LEAF to +// handle errors. This version does not use exception handling. The version that +// does use exception handling is in print_file_eh.cpp. #include #include @@ -36,8 +37,9 @@ template using result = leaf::result; -// We will handle all failures in our main function, but first, here are the declarations of the functions it calls, each -// communicating failures using result: +// We will handle all failures in our main function, but first, here are the +// declarations of the functions it calls, each communicating failures using +// result: // Parse the command line, return the file name. result parse_command_line( int argc, char const * argv[] ); @@ -78,12 +80,14 @@ int main( int argc, char const * argv[] ) return 0; }, - // Each of the lambdas below is an error handler. LEAF will consider them, in order, and call the first one that matches - // the available error objects. + // Each of the lambdas below is an error handler. LEAF will consider + // them, in order, and call the first one that matches the available + // error objects. // This handler will be called if the error includes: // - an object of type open_error, and - // - an object of type leaf::e_errno that has .value equal to ENOENT, and + // - an object of type leaf::e_errno that has .value equal to ENOENT, + // and // - an object of type leaf::e_file_name. []( open_error &, leaf::match_value, leaf::e_file_name const & fn ) { @@ -103,7 +107,8 @@ int main( int argc, char const * argv[] ) // This handler will be called if the error includes: // - an object of type input_error, and - // - an optional object of type leaf::e_errno (regardless of its .value), and + // - an optional object of type leaf::e_errno (regardless of its + // .value), and // - an object of type leaf::e_file_name. []( input_error &, leaf::e_errno const * errn, leaf::e_file_name const & fn ) { @@ -130,9 +135,10 @@ int main( int argc, char const * argv[] ) return 5; }, - // This last handler matches any error: it prints diagnostic information to help debug logic errors in the program, since it - // failed to match an appropriate error handler to the error condition it encountered. In this program this handler will - // never be called. + // This last handler matches any error: it prints diagnostic information + // to help debug logic errors in the program, since it failed to match + // an appropriate error handler to the error condition it encountered. + // In this program this handler will never be called. []( leaf::error_info const & unmatched ) { std::cerr << diff --git a/examples/print_half.cpp b/examples/print_half.cpp index 0e0ec36..badb4c2 100644 --- a/examples/print_half.cpp +++ b/examples/print_half.cpp @@ -46,7 +46,8 @@ struct BigInt friend std::ostream& operator<<(std::ostream& o, const BigInt&) { return o << "big int half"; } }; -// This function handles ConversionErrc::TooLong errors, forwards any other error to the caller. +// This function handles ConversionErrc::TooLong errors, forwards any other +// error to the caller. leaf::result print_half(const std::string& text) { return leaf::try_handle_some( @@ -88,8 +89,9 @@ int main( int argc, char const * argv[] ) []( leaf::error_info const & unmatched ) { - // This will never execute in this program, but it would detect logic errors where an unknown error reaches main. - // In this case, we print diagnostic information. + // This will never execute in this program, but it would detect + // logic errors where an unknown error reaches main. In this case, + // we print diagnostic information. std::cerr << "Unknown failure detected" << std::endl << "Cryptic diagnostic information follows" << std::endl << diff --git a/include/boost/leaf.hpp b/include/boost/leaf.hpp index 057582c..939f210 100644 --- a/include/boost/leaf.hpp +++ b/include/boost/leaf.hpp @@ -4600,8 +4600,10 @@ namespace boost { namespace leaf { { } - // SFINAE: T can be initialized with a U, e.g. result("literal"). - // Not using is_constructible on purpose, bug with COMPILER=/usr/bin/clang++ CXXSTD=11 clang 3.3. + // SFINAE: + // T can be initialized with a U, e.g. result("literal"). + // Not using is_constructible on purpose, bug with + // COMPILER=/usr/bin/clang++ CXXSTD=11 clang 3.3. template result( U && u, decltype(init_T_with_U(std::forward(u))) * = 0 ): stored_(std::forward(u)), diff --git a/include/boost/leaf/result.hpp b/include/boost/leaf/result.hpp index adc7546..57d9eff 100644 --- a/include/boost/leaf/result.hpp +++ b/include/boost/leaf/result.hpp @@ -275,8 +275,10 @@ namespace boost { namespace leaf { { } - // SFINAE: T can be initialized with a U, e.g. result("literal"). - // Not using is_constructible on purpose, bug with COMPILER=/usr/bin/clang++ CXXSTD=11 clang 3.3. + // SFINAE: + // T can be initialized with a U, e.g. result("literal"). + // Not using is_constructible on purpose, bug with + // COMPILER=/usr/bin/clang++ CXXSTD=11 clang 3.3. template result( U && u, decltype(init_T_with_U(std::forward(u))) * = 0 ): stored_(std::forward(u)),