Alertable.hpp

Go to the documentation of this file.

/*
 * Copyright (C) Cross The Road Electronics.  All rights reserved.
 * License information can be found in CTRE_LICENSE.txt
 * For support and suggestions contact support@ctr-electronics.com or file
 * an issue tracker at https://github.com/CrossTheRoadElec/Phoenix-Releases
 */
#pragma once
 
#include "ctre/phoenix6/Alerts.hpp"
#include <functional>
#include <vector>
 
namespace ctre {
namespace phoenix6 {
 
    class AlertableCollection;
 
    /**
     * \brief Interface for all types that can report a Phoenix alert.
     */
    class PhoenixAlertable {
    public:
        /**
         * \brief Levels of urgency of a registered alert.
         */
        using AlertLevel = PhoenixAlert::Level;
 
        /**
         * \brief Registers all alerts for this type to the provided collection.
         *
         * When registering alerts, the provided alert IDs must be unique within the
         * AlertableCollection. As a result, the IDs should generally contain information
         * unique to this specific instance, such as device and signal name.
         *
         * \param collection Alertable collection into which the alerts are registered
         */
        virtual void RegisterAlerts(AlertableCollection &collection) = 0;
    };
 
    /**
     * \brief Information about an alert.
     */
    struct AlertInfo final {
        /** \brief Whether the alert is active. */
        bool isActive{};
        /** \brief The new text to report in the alert, or nullopt to leave the text unchanged. */
        std::optional<std::string> text{};
 
        /**
         * Creates new information for an inactive alert.
         *
         * \returns Information for an inactive alert
         */
        static AlertInfo Inactive() { return {}; }
 
        /**
         * Creates new information for an active alert.
         *
         * \tparam S Type of the text, convertible to std::optional<std::string>
         * \param text New text to report in the alert, or nullopt to leave the text unchanged
         * \return Information for an active alert
         */
        template <std::convertible_to<std::optional<std::string>> S = std::optional<std::string>>
        static AlertInfo Active(S &&text = std::nullopt)
        {
            return {true, std::forward<S>(text)};
        }
    };
 
    /**
     * \brief Information about a multi-level alert.
     */
    struct MultiAlertInfo final {
        /** \brief Whether the multi-level alert is active. */
        bool isActive{};
        /** \brief The new alert urgency level. */
        PhoenixMultiAlert::Level level{};
        /** \brief The new text to report in the alert, or nullopt to leave the text unchanged. */
        std::optional<std::string> text{};
 
        /**
         * Creates new information for an inactive multi-level alert.
         *
         * \returns Information for an inactive multi-level alert
         */
        static MultiAlertInfo Inactive() { return {}; }
 
        /**
         * Creates new information for an active multi-level alert.
         *
         * \tparam S Type of the text, convertible to std::optional<std::string>
         * \param level New alert urgency level
         * \param text New text to report in the alert, or nullopt to leave the text unchanged
         * \return Information for an active multi-level alert
         */
        template <std::convertible_to<std::optional<std::string>> S = std::optional<std::string>>
        static MultiAlertInfo Active(PhoenixMultiAlert::Level level, S &&text = std::nullopt)
        {
            return {true, level, std::forward<S>(text)};
        }
    };
 
    /**
     * \brief Collection of objects that can report alerts.
     *
     * This collection must outlive any PhoenixAlertable objects and lambda
     * captures registered to the collection.
     */
    class AlertableCollection {
        std::string group;
        std::vector<std::function<void()>> alerts;
        std::vector<std::function<void()>> beforeAlerts;
 
    public:
        /**
         * \brief Constructs a new collection of alertable objects.
         *
         * \param group Alert group identifier
         */
        AlertableCollection(std::string group) :
            group{group}
        {}
 
        AlertableCollection(AlertableCollection &&) = default;
        AlertableCollection &operator=(AlertableCollection &&) = default;
 
        /**
         * \brief Reports all alerts in this collection.
         */
        void Report() const
        {
            for (auto const &func : beforeAlerts) {
                func();
            }
            for (auto const &alert : alerts) {
                alert();
            }
        }
 
        /**
         * \brief Adds a PhoenixAlertable to this collection.
         *
         * \param alertable PhoenixAlertable to register
         * \returns This collection
         */
        AlertableCollection &WithAlertable(PhoenixAlertable &alertable) &
        {
            alertable.RegisterAlerts(*this);
            return *this;
        }
 
        /**
         * \brief Adds a PhoenixAlertable to this collection.
         *
         * \param alertable PhoenixAlertable to register
         * \returns This collection
         */
        AlertableCollection &&WithAlertable(PhoenixAlertable &alertable) &&
        {
            return std::move(WithAlertable(alertable));
        }
 
        /**
         * \brief Adds an alertable to this collection.
         *
         * \tparam F Type of the function registering the alerts
         * \param alertable Function that registers the alerts
         * \returns This collection
         */
        template <std::invocable<AlertableCollection &> F>
        AlertableCollection &WithAlertable(F const &alertable) &
        {
            alertable(*this);
            return *this;
        }
 
        /**
         * \brief Adds an alertable to this collection.
         *
         * \tparam F Type of the function registering the alerts
         * \param alertable Function that registers the alerts
         * \returns This collection
         */
        template <std::invocable<AlertableCollection &> F>
        AlertableCollection &&WithAlertable(F const &alertable) &&
        {
            return std::move(WithAlertable(alertable));
        }
 
        /**
         * \brief Adds a PhoenixAlert to this collection.
         *
         * \tparam F Type of the function returning live information to report in the alert
         * \param id Alert identifier, unique within the group
         * \param level Alert urgency level
         * \param infoGetter Function returning the #AlertInfo to report
         * \param text Default alert text to display when the alert is active
         * \param debounce Debounce time of the alert, or negative to use the default debounce time (1 second)
         * \returns This collection
         */
        template <std::invocable F>
            requires std::convertible_to<std::invoke_result_t<F>, std::optional<AlertInfo>>
        AlertableCollection &WithAlert(std::string id, PhoenixAlert::Level level, F &&infoGetter, std::string const &text = "", wpi::units::second_t debounce = -1_s) &
        {
            PhoenixAlert alert{group, std::move(id), level, text};
            if (debounce >= 0_s) {
                alert.WithDebounce(debounce);
            }
            alerts.emplace_back([alert=std::move(alert), infoGetter=std::forward<F>(infoGetter)]() mutable {
                std::optional<AlertInfo> const result = infoGetter();
                if (result) {
                    if (result->isActive) {
                        alert.SetActive(result->text);
                    } else {
                        alert.SetInactive();
                    }
                }
            });
            return *this;
        }
 
        /**
         * \brief Adds a PhoenixAlert to this collection.
         *
         * \tparam F Type of the function returning live information to report in the alert
         * \param id Alert identifier, unique within the group
         * \param level Alert urgency level
         * \param infoGetter Function returning the #AlertInfo to report
         * \param text Default alert text to display when the alert is active
         * \param debounce Debounce time of the alert, or negative to use the default debounce time (1 second)
         * \returns This collection
         */
        template <std::invocable F>
            requires std::convertible_to<std::invoke_result_t<F>, std::optional<AlertInfo>>
        AlertableCollection &&WithAlert(std::string id, PhoenixAlert::Level level, F &&infoGetter, std::string const &text = "", wpi::units::second_t debounce = -1_s) &&
        {
            return std::move(WithAlert(std::move(id), level, std::forward<F>(infoGetter), text, debounce));
        }
 
        /**
         * \brief Adds a PhoenixMultiAlert to this collection.
         *
         * \tparam F Type of the function returning live information to report in the alert
         * \param id Alert identifier, unique within the group
         * \param levelFlags Alert urgency levels to include
         * \param infoGetter Function returning the #MultiAlertInfo to report
         * \param text Default alert text to display when the alert is active
         * \param debounce Debounce time of the alert, or negative to use the default debounce time (1 second)
         * \returns This collection
         */
        template <std::invocable F>
            requires std::convertible_to<std::invoke_result_t<F>, std::optional<MultiAlertInfo>>
        AlertableCollection &WithMultiAlert(std::string id, uint32_t levelFlags, F &&infoGetter, std::string const &text = "", wpi::units::second_t debounce = -1_s) &
        {
            PhoenixMultiAlert alert{group, std::move(id), levelFlags, text};
            if (debounce >= 0_s) {
                alert.WithDebounce(debounce);
            }
            alerts.emplace_back([alert=std::move(alert), infoGetter=std::forward<F>(infoGetter)]() mutable {
                std::optional<MultiAlertInfo> const result = infoGetter();
                if (result) {
                    if (result->isActive) {
                        alert.SetActive(result->level, result->text);
                    } else {
                        alert.SetInactive();
                    }
                }
            });
            return *this;
        }
 
        /**
         * \brief Adds a PhoenixMultiAlert to this collection.
         *
         * \tparam F Type of the function returning live information to report in the alert
         * \param id Alert identifier, unique within the group
         * \param levelFlags Alert urgency levels to include
         * \param infoGetter Function returning the #MultiAlertInfo to report
         * \param text Default alert text to display when the alert is active
         * \param debounce Debounce time of the alert, or negative to use the default debounce time (1 second)
         * \returns This collection
         */
        template <std::invocable F>
            requires std::convertible_to<std::invoke_result_t<F>, std::optional<MultiAlertInfo>>
        AlertableCollection &&WithMultiAlert(std::string id, uint32_t levelFlags, F &&infoGetter, std::string const &text = "", wpi::units::second_t debounce = -1_s) &&
        {
            return std::move(WithMultiAlert(std::move(id), levelFlags, std::forward<F>(infoGetter), text, debounce));
        }
 
        /**
         * \brief Adds a function to run before updating any alerts. This can be
         * used to perform actions such as a bulk signal refresh so individual
         * alerts do not have to perform refreshes.
         *
         * \tparam F Type of the function to register
         * \param func Function to run before any alerts
         * \returns This collection
         */
        template <std::invocable F>
        AlertableCollection &WithBeforeAlerts(F &&func) &
        {
            beforeAlerts.emplace_back(std::forward<F>(func));
            return *this;
        }
 
        /**
         * \brief Adds a function to run before updating any alerts. This can be
         * used to perform actions such as a bulk signal refresh so individual
         * alerts do not have to perform refreshes.
         *
         * \tparam F Type of the function to register
         * \param func Function to run before any alerts
         * \returns This collection
         */
        template <std::invocable F>
        AlertableCollection &&WithBeforeAlerts(F &&func) &&
        {
            return std::move(WithBeforeAlerts(std::forward<F>(func)));
        }
    };
 
}
}