result_handling_policies.h

Go to the documentation of this file.

#pragma once
 
namespace armarx::skills::client
{
 
    /**
     * @brief Result handling policies.
     *
     * These policies are meant to be used to handle common use-cases in handling outputs of skill
     * executions to avoid boilerplate.  Since the skill outputs should be std::expected and
     * expected is defined as [[nodiscard]], unhandled outputs will result in compiler warnings.
     * Thus, to get rid of the warnings, the output must be stored in a local variable and handled
     * as such:
     *
     * ```cpp
     * auto result = skill({.params = …});
     * if (result != Success)
     * {
     *     <handling the error or ignoring the error or printing it or ...>
     * }
     * ```
     *
     * The purpose of these policies is to allow skill business object authors to define operators
     * to handle common use-cases in a one liner.  Specifically, by overwriting operator||() and the
     * given policy as parameter as follows:
     *
     * ```cpp
     * void operator||(std::expected<Skill:Output, Skill::ErrorOutput> const& skillResult,
     *                 armarx::skills::client::result_handling_policies::Continue const& policy)
     * {
     *     // Silently ignore any outcome.
     * }
     * ```
     *
     * a fluent skill execution can be written that handles the outcome as follows:
     *
     * ```cpp
     * using namespace armarx::skills::client::result_handling_policies; // Pull the policies into
     * the current scope.
     *
     * skill({.params = …}) or Continue();  // This will handle the outcome and supress the warning.
     * ```
     *
     * The currently supported policies are defined in this namespace.  The skill business object
     * author is responsible for supplying these overloads if they want to support this feature.
     */
    namespace result_handling_policies
    {
        /**
         * @brief Ignore any skill outcome and just continue.
         */
        class Continue
        {
        };
 
        /**
         * @brief Print a warning on failure but continue in any case.
         */
        class WarnOnFailureAndContinue
        {
        };
 
        /**
         * @brief Escalate any failures by throwing an exception.
         */
        class Escalate
        {
        };
    } // namespace result_handling_policies
 
} // namespace armarx::skills::client