tbx/include/utils/sequencer.h

/*!
 * \file utils/sequencer.h
 * \brief
 *      A terminal-like device communication automation tool
 *
 * \copyright Copyright (C) 2021 Christos Choutouridis <christos@choutouridis.net>
 *
 * <dl class=\"section copyright\"><dt>License</dt><dd>
 * The MIT License (MIT)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 * </dd></dl>
 */

#ifndef TBX_UTILS_SEQUENCER_H_
#define TBX_UTILS_SEQUENCER_H_


#include <core/core.h>
#include <core/crtp.h>
#include <cont/range.h>

#include <ctime>
#include <array>
#include <string_view>
#include <limits>
#include <type_traits>
#include <functional>

namespace tbx {

/*!
 * \class sequencer
 * \brief
 *      A CRTP base class to provide the sequencer functionality.
 *
 * Sequencer can automate communication with a terminal-like device such as AT-command modems etc...
 * It can operate based on a script array and handle the outgoing commands and incoming responses.
 * The user can create matching rules on received data and hook handlers and actions on them.
 *
 * The derived class (implementation) has to provide:
 *  1) size_t get(Data_t* data);
 *     This function return 0 or a number of Data_t items. The data points to buffer for the input data.
 *  2) size_t put(const Data_t* data, size_t n);
 *     This function sends to implementation the data pointed by \c data witch have size \c n.
 *  3) clock_t clock();
 *     This function return a number to be used as time. The units of this function may be arbitrary but they
 *     match the units in \c record_t::timeout field.
 *
 * \tparam Impl_t   The type of derived class
 * \tparam Cont_t   The container type holding the data of type \c Data_t for the derived class.
 * \tparam Data_t   The char-like stream item type. Usually \c char
 * \tparam N        The size of the sequence buffer to temporary store each line from get().
 *
 * \note
 *      We need access to derived class container to sneaky get a range of the data beside
 *      the normal data flow, in order to implement the \see control_t::DETECT operation.
 */
template <typename Impl_t, typename Cont_t, typename Data_t, size_t N>
class sequencer {
    _CRTP_IMPL(Impl_t);

    static_assert(
        std::is_same_v<typename Cont_t::value_type, Data_t>,
        "Cont_t must be a container of type Data_t"
    );

    // local type dispatch
    using str_view_t    = std::basic_string_view<Data_t>;
    using range_t       = typename Cont_t::range_t;

    //! \name Public types
    //! @{
    public:
        //! \enum status_t
        //! \brief The sequencer run status
        enum class status_t {
            OK, ERROR
        };


        //! \enum action_t
        //! \brief Possible response actions for the sequencer
        enum class action_t {
            NO, NEXT, GOTO, EXIT_OK, EXIT_ERROR
        };

        //! \enum control_t
        //! \brief The control type of the script entry.
        enum class control_t {
            NOP,    //!< No command, dont send or expect anything, used for delays
            SEND,   //!< Send data to implementation through put()
            EXPECT, //!< Expects data from implementation via get()
            DETECT  //!< Detects data into rx buffer without receiving them via contents()

            //! \note
            //! The \c DETECT extra incoming channel serve the purpose of sneak into receive
            //! buffer and check for data without getting them. This is useful when the receive driver
            //! is buffered with a delimiter and we seek for data that don't follow the delimiter pattern.
            //!
            //! For example:
            //! A modem sends reponses with '\n' termination but for some "special" command it opens a cursor
            //! lets say ">$ " without '\n' at the end.
        };

        //! \enum match_t
        //! \brief Token match types
        enum class match_t {
            NO, STARTS_WITH, ENDS_WITH, CONTAINS, nSTARTS_WITH, nENDS_WITH, nCONTAINS
        };

        /*!
         *  Match handler function pointer type.
         *  Expects a pointer to buffer and a size and returns status
         */
        using handler_ft = void (*) (const Data_t*, size_t);

        /*!
         * \struct handle_t
         * \brief
         *      The script record handle block.
         *
         * Each script record contains some blocks for matching functionality. Each block
         * has a token and a matching type. If the response matches the token, the sequencer calls
         * the handler and perform the action.
         */
        struct handle_t {
            std::basic_string_view<Data_t>
                                token;          //!< The token for the match
            match_t             match_type;     //!< The matching type functionality
            handler_ft          handler;        //!< The handler to called if the match is successful.
            action_t            action;         //!< The action to be performer if the match is successful
            size_t              idx;            //!< The index for the action_t::GOTO action. Otherwise can be left 0.
        };

        /*!
         * \struct record_t
         * \brief
         *      Describes the sequencer's script record entry (line).
         *
         * Each line consist from a control, 2 blocks and a timeout. The control says if we send or receive data.
         * The blocks contain the data and the matching information. And the timeout guards the entire line.
         */
        template<size_t Nhandles =2>
        struct record_t {
            control_t   control;    //!< The type of the entry
            std::array<handle_t, Nhandles>
                        block;      //!< The matching blocks
            clock_t     timeout;    //!< Timeout in CPU time
        };

        /*!
         * \struct script_t
         * \brief
         *      Describes the sequencer's script.
         *
         * The user can create arrays as the example bellow to act as a script.
         * \code
         *  const std::array<Seq::record_t, 8> script = {{
         *  / * 0 * / {Seq::control_t::NOP,  {"",         Seq::match_t::NO, nullptr, Seq::action_t::GOTO, 1}, 1000},  //delay 1000 clocks
         *  / * 1 * / {Seq::control_t::SEND, {"ATE0\r\n", Seq::match_t::NO, nullptr, Seq::action_t::NEXT, 0}, 1000},
         *  / * 2 * / {Seq::control_t::EXPECT, {{
         *                {"OK\r\n", Seq::match_t::ENDS_WITH,   nullptr, Seq::action_t::NEXT, 0},
         *                {"ERROR",  Seq::match_t::CONTAINS,    nullptr, Seq::action_t::EXIT_ERROR, 0} }},
         *                1000
         *            },
         *            // ...
         *  }};
         * \endcode
         */
        template <size_t Nrecords, size_t Nhandles =2>
        using script_t = std::array<record_t<Nhandles>, Nrecords>;
    //! @}



    //! \name Constructor / Destructor
    //!@{
    protected:
       ~sequencer () = default;                               //!< \brief Allow destructor from derived only
       sequencer () = default;                                //!< \brief A default constructor from derived only
       sequencer(const sequencer&) = delete;                //!< No copies
       sequencer& operator= (const sequencer&) = delete;    //!< No copy assignments
    //!@}

    //! \name Sequencer interface requirements for implementer
    //! @{
    private:
       size_t get_ (Data_t* data) { return impl().get (data); }
       size_t put_ (const Data_t* data, size_t n) { return impl().put (data, n); }
       const range_t contents_ () const { return impl().contents(); }
       clock_t clock_ () { return impl().clock(); }
    //! @}

    //! \name Private functionality
    //! @{
    private:
       /*!
        * \brief
        *       Check if the \c stream starts with the \c prefix
        * \param stream     The stream in witch we search
        * \param prefix     What we search
        * \return           True on success, false otherwise
        */
       static bool starts_with_ (const str_view_t stream, const str_view_t prefix) {
           return (stream.rfind(prefix, 0) != str_view_t::npos);
       }

       /*!
        * \brief
        *       Check if the \c stream ends with the \c postfix
        * \param stream     The stream in witch we search
        * \param postfix    What we search
        * \return           True on success, false otherwise
        */
       static bool ends_with_ (const str_view_t stream, const str_view_t postfix) {
           if (stream.size() < postfix.size())
               return false;
           return (
               stream.compare(
                   stream.size() - postfix.size(),
                   postfix.size(),
                   postfix) == 0
               );
       }

       /*!
        * \brief
        *       Check if the \c haystack contains the \c needle
        * \param haystack   The stream in witch we search
        * \param needle     What we search
        * \return           True on success, false otherwise
        */
       static bool contains_ (const str_view_t haystack, const str_view_t needle) {
           return (haystack.find(needle) != str_view_t::npos);
       }
       /*!
        * \brief
        *   Return the new sequencer's step value.
        *
        * Step is index to the sequencer's script array.
        *
        * \param current_idx    The current step value
        * \param action         The advancing type
        * \param go_idx         The new value of the step in the case of GOTO type
        * \return               The new sequencer's step value
        */
       static size_t step_ (size_t current_idx, action_t action, size_t go_idx =0) {
           switch (action) {
               default:
               case action_t::NO:   return current_idx;
               case action_t::NEXT: return ++current_idx;
               case action_t::GOTO: return go_idx;
               case action_t::EXIT_OK:
               case action_t::EXIT_ERROR:
                                    return 0;
           }
       }
       static status_t action_ (size_t& step, const handle_t& block, const str_view_t buffer = str_view_t{}) {
           if (block.handler != nullptr)
               block.handler(buffer.begin(), buffer.size());
           switch (block.action) {
               case action_t::EXIT_OK:
                   step = std::numeric_limits<size_t>::max();
                   return status_t::OK;
               case action_t::EXIT_ERROR:
                   step = std::numeric_limits<size_t>::max();
                   return status_t::ERROR;
               default:
                   step = step_(step, block.action, block.idx);
                   return status_t::OK;
           }

       }

    //! @}


    public:
       /*!
        * \brief
        *   Checks if the \c needle matches the \c haystack.
        *
        * \param type       The type of matching functionality
        * \param haystack   The stream in witch we search
        * \param needle     The stream we search
        * \return           True on match
        */
       static bool match (const str_view_t haystack, const str_view_t needle, match_t type) {
           switch (type) {
               default:
               case match_t::NO:            return true;
               case match_t::STARTS_WITH:   return starts_with_(haystack, needle);
               case match_t::ENDS_WITH:     return ends_with_(haystack, needle);
               case match_t::CONTAINS:      return contains_(haystack, needle);
               case match_t::nSTARTS_WITH:  return !starts_with_(haystack, needle);
               case match_t::nENDS_WITH:    return !ends_with_(haystack, needle);
               case match_t::nCONTAINS:     return !contains_(haystack, needle);
           }
       }

       /*!
        * \brief
        *       A static functionality to provide access to sequencer's inner matching mechanism.
        *       Checks the \c buffer against \c handle and calls its action if needed.
        *
        * \param handle     Reference to handle
        * \param buffer     The buffer to check
        * \return           True on match, false otherwise
        */
       static bool check_handle (const handle_t& handle, const str_view_t buffer) {
           size_t tmp{};
           if (match(buffer, handle.token, handle.match_type)) {
               action_ (tmp, handle, buffer);
               return true;
           }
           return false;
       }

       /*!
        * \brief
        *   Run the script array
        *
        * The main sequencer functionality. It starts with the first entry of the array.
        * - If the entry is \c NOP it executes the action after the timeout.
        *   \c token and \c handler are discarded.
        * - If the entry is \c SEND it uses the first handle block's token to send and executes the action after that.
        *   \c timeout is discarded.
        * - If the entry is \c EXCEPTS it continuously try to receive data using implementation's get until one
        *   of the handle blocks match.
        *   On match:
        *     - Calls the handler if there is one
        *     - Executes the action
        *     - Skips the next handle blocks if there is any.
        *   If there is no match on timeout it return status_t::EXIT_ERROR
        * - If the entry is \c DETECT it continuously try to detect data using implementation's contents until one
        *   of the handle blocks match.
        *   On match:
        *     - Calls the handler if there is one
        *     - Executes the action
        *     - Skips the next handle blocks if there is any.
        *   If there is no match on timeout it return status_t::EXIT_ERROR
        *
        * \tparam Steps     The number of steps of the script
        * \tparam Nhandles  The number of handle blocks in the each script record.
        *
        * \param script     Reference to script to run
        * \return           The status of entire operation as described above
        */
       template <size_t Steps, size_t Nhandles>
       bool run (const script_t<Steps, Nhandles>& script) {
           Data_t buffer[N];
           size_t resp_size{};
           status_t status{};

           clock_t mark = clock_();
           for (size_t step =0, p_step =0 ; step < Steps ; ) {
               const record_t<Nhandles>& it = script[step];

               if (step != p_step) {
                   p_step = step;
                   mark = clock_();
               }
               switch (it.control) {
                   default:
                   case control_t::NOP:
                       if ((clock_() - mark) >= it.timeout)
                           status = action_ (step, it.block[0]);
                       break;

                   case control_t::SEND:
                	   if (put_(it.block[0].token.data(), it.block[0].token.size()) != it.block[0].token.size())
                	       return false;
                       status = action_ (step, it.block[0]);
                       break;

                   case control_t::EXPECT:
                       resp_size = get_(buffer);
                       if (resp_size) {
                           for (auto& block : it.block) {
                               if (match(
                                       {buffer, resp_size},
                                       block.token,
                                       block.match_type)) {
                                   status = action_ (step, block, {buffer, resp_size});
                                   break;
                               }
                           }
                       }
                       if (it.timeout && (clock_() - mark) >= it.timeout)
                           return false;
                       break;
                   case control_t::DETECT:
                       auto data = contents_();
                       if (data.begin() != data.end()) {
                           for (auto& block : it.block) {
                               if (match(
                                       {data.begin(), static_cast<size_t>(data.end() - data.begin())},
                                       block.token,
                                       block.match_type)) {
                                   status = action_ (step, block, {buffer, resp_size});
                                   break;
                               }
                           }
                       }
                       if (it.timeout && (clock_() - mark) >= it.timeout)
                           return false;
                       break;
               } // switch (it.control)
           }
           return (status == status_t::OK);
       }
};

/*!
 * An "empty" block for convenience.
 */
template <typename Impl_t, typename Cont_t, typename Data_t, size_t N>
constexpr typename sequencer<Impl_t, Cont_t, Data_t, N>::handle_t Sequencer_null_block = {
    "",
    sequencer<Impl_t, Cont_t, Data_t, N>::match_t::NO,
    nullptr,
    sequencer<Impl_t, Cont_t, Data_t, N>::action_t::NO,
    0
};

}
#endif /* TBX_UTILS_SEQUENCER_H_ */