utl/include/utl/dev/sequencer.h

/*!
 * \file dev/sequencer.h
 * \brief
 *      A script based automation tool for send/receive communications
 *
 * \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 utl_dev_dequencer_h__
#define utl_dev_dequencer_h__

#include <utl/core/impl.h>
#include <utl/container/range.h>

#include <ctime>
#include <array>
#include <string_view>
#include <type_traits>
#include <utility>
#include <tuple>

namespace utl {

/*!
 * \class sequencer
 * \brief
 *      A CRTP base class to provide the sequencer functionality.
 *
 * Sequencer is a script engine with receive/transmit functionalities based on predicates. It has:
 *  - A program counter like variable named \c step.
 *  - \c step actions like NEXT, GOTO exit with status etc...
 *  - Input data match predicates to trigger those actions.
 *  - Input data handlers to trigger external functionality on predicate match
 *  - Output data handlers to "edit" data before transmiting them
 *  - A small predicate set provided to the user. (starts_with, ends_with, contains).
 *
 * Sequencer can automate communication with a terminal-like device such as AT-command modems, can
 * be used to implement communication protocols, or even small http servers.
 *
 * 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.
 *
 *  3) size_t contents_ (Data_t* data);
 *     This function return 0 or a number of Data_t items without removing them from the implementer's container
 *     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.
 *
 *  4) 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 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 Data_t, size_t N>
class sequencer {
    _CRTP_IMPL(Impl_t);

    //! \name Public types
    //! @{
    public:
        using value_type    = Data_t;
        using pointer_type  = Data_t*;
        using size_type     = size_t;
        using string_view   = std::basic_string_view<Data_t>;

        /*!
         * The sequencer engine status. A variable of this type is returned by
         * \see action_().
         */
        enum class seq_status_t {
            CONTINUE,   //!< Means we keep looping
            EXIT        //!< Means, we exit with status the one indicated by \c action_t of the \c record_t
        };

        //! \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()
            OR_EXPECT,  //!< Expects data from implementation via get() in conjunction with previous EXPECT
            DETECT,     //!< Detects data into rx buffer without receiving them via contents()
            OR_DETECT   //!< Detects data into rx buffer without receiving them via contents() in conjunction with
                        //!< previous DETECT

            //! \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 responses with '\n' termination but for some "special" command it opens a cursor
            //! lets say ">$ " without '\n' at the end.
        };

        //! \enum action_t
        //! \brief
        //!     Possible response actions for the sequencer. This is the
        //!     equivalent of changing the program counter of the sequencer
        //!     and is composed by a type and a value.
        //!
        struct action_t {
            enum {
                NO =0,      //!< Do not change sequencer's step
                NEXT,       //!< Go to next sequencer step. In case of EXPECT/DETECT block of records
                            //!< skip the entire block of EXPECT[, OR_EXPECT[, OR_EXPECT ...]] and go
                            //!< to the next (non OR_*) control record.
                GOTO,       //!< Manually sets the step counter to the number of the \c step member.
                EXIT,       //!< Instruct for an exit returning the action.value as status
            } type;
            size_t value;   //!< Used by \c GOTO to indicate the next sequencer's step.
        };

        //! A no_action action_t
        static constexpr action_t no_action  = {action_t::NO, 0};
        //! A next action_t
        static constexpr action_t next       = {action_t::NEXT, 0};
        //! A goto action_t template
        template <size_t GOTO>
        static constexpr action_t go_to      = {action_t::GOTO, static_cast<size_t>(GOTO)};

        //! An exit ok action_t
        static constexpr action_t exit_ok    = {action_t::EXIT, 0};
        //! An exit error action_t
        static constexpr action_t exit_error = {action_t::EXIT, static_cast<size_t>(-1)};
        //! A generic exit action_t template
        template <size_t Status>
        static constexpr action_t exit       = {action_t::EXIT, static_cast<size_t>(Status)};

        /*!
         * Match binary predicate function pointer type.
         * Expects two string views and return a boolean.
         * It is used by EXPECT/DETECT blocks to trigger their {handler, action} pair.
         */
        using match_ft   = bool (*) (const string_view haystack, const string_view needle);

        /*!
         *  Send/Receive handler function pointer type.
         *  Expects a pointer to buffer and a size and returns status.
         *  It is used on predicate match on EXPECT/DETECT blocks, or as data wrapper on SEND blocks.
         */
        using handler_ft = void (*) (const Data_t*, size_t);

        /*!
         * \struct record_t
         * \brief
         *      Describes the sequencer's script record entry (line).
         */
        struct record_t {
            control_t   control;    //!< The control type of the entry
            string_view token;      //!< String view to token data. [MUST BE null terminated].
                                    //!< This is passed as 2nd argument to match predicate on EXPECT/DETECT, or as
                                    //! {data, size} pair to SEND handler and put_().
                                    //!< If unused set it to ""
            match_ft    match;      //!< Match predicate to used in EXPECT/DETECT blocks
                                    //!< If unused set it to nullptr
            handler_ft  handler;    //!< The handler to called if the match is successful, or before put_()
                                    //!< If unused set it to nullptr
            action_t    action;     //!< Indicates the step manipulation if the match is successful or after NOP and put_()
            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
         * Seq s;
         * const Seq::script_t<4> script = {{
         *     {Seq::control_t::NOP,       "",         Seq::nil,       Seq::nil, {Seq::action_t::GOTO, 1},       1000},
         *
         *     {Seq::control_t::SEND,      "ATE0\r\n", Seq::nil,       Seq::nil, {Seq::action_t::NEXT, 0},       0},
         *     {Seq::control_t::EXPECT,    "OK\r\n",   Seq::ends_with, Seq::nil, {Seq::action_t::EXIT_OK, 0},    1000},
         *     {Seq::control_t::OR_EXPECT, "ERROR",    Seq::contains,  Seq::nil, {Seq::action_t::EXIT_ERROR, 0}, 0}
         * }};
         * s.run(script);
         * \endcode
         */
        template <size_t Nrecords>
        using script_t = std::array<record_t, Nrecords>;


        /*!
         * \brief
         *       Check if the \c stream1 is equal to \c stream2
         * \param stream1    The stream in witch we search [The input buffer]
         * \param stream2    What we search [The record's token]
         * \return           True on success, false otherwise
         */
        static constexpr auto equals = [](const string_view stream1, const string_view stream2) noexcept -> bool {
            return (stream1 == stream2);
        };

        /*!
         * \brief
         *       Check if the \c stream starts with the \c prefix
         * \param stream     The stream in witch we search [The input buffer]
         * \param prefix     What we search [The record's token]
         * \return           True on success, false otherwise
         */
        static constexpr auto starts_with = [](const string_view stream, const string_view prefix) noexcept -> bool {
            return (stream.rfind(prefix, 0) != string_view::npos);
        };

        /*!
         * \brief
         *       Check if the \c stream ends with the \c postfix
         * \param stream     The stream in witch we search [The input buffer]
         * \param postfix    What we search [The record's token]
         * \return           True on success, false otherwise
         */
        static constexpr auto ends_with = [](const string_view stream, const string_view postfix) -> bool {
            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 [The input buffer]
         * \param needle     What we search [The record's token]
         * \return           True on success, false otherwise
         */
        static constexpr auto contains = [](const string_view haystack, const string_view needle) noexcept -> bool {
            return (haystack.find(needle) != string_view::npos);
        };

        //! Always false predicate
        static constexpr auto always_true = [](const string_view s1, const string_view s2) noexcept -> bool {
            (void)s1; (void)s2;
            return true;
        };

        //! Always false predicate
        static constexpr auto always_false = [](const string_view s1, const string_view s2) noexcept -> bool {
            (void)s1; (void)s2;
            return false;
        };

        //! Empty predicate or handler
        static constexpr auto nil = nullptr;
    //! @}



    //! \name Object lifetime
    //!@{
    protected:
       ~sequencer () = default;                             //!< \brief Allow destructor from derived only
       constexpr sequencer () noexcept = 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 contents_ (Data_t* data) { return impl().contents(data); }
       size_t put_ (const Data_t* data, size_t n) { return impl().put (data, n); }
       clock_t clock_ () noexcept { return impl().clock(); }
    //! @}

    //! \name Private functionality
    //! @{
    private:

       /*!
        * Check if there is a handler and call it
        * \param handler    The handler to check
        * \param buffer     String view to buffer to pass to handler
        * \return           True if handler is called
        */
       constexpr bool handle_ (handler_ft handler, const string_view buffer = string_view{}) {
           if (handler != nullptr) {
               handler (buffer.begin(), buffer.size());
               return true;
           }
           return false;
       }

       /*!
        * \brief
        *   Return the new sequencer's step value and the sequencer's loop status as pair.
        *
        * \param script         Reference to entire script.
        * \param step           The current step
        * \return               new step - status pair
        */
       template <size_t Steps>
       constexpr std::pair<size_t, seq_status_t> action_ (const script_t<Steps>& script, size_t step) {
           control_t skip_while{};
           size_t s;

           switch (script[step].action.type) {
               default:
               case action_t::NO:                   return std::make_pair(step, seq_status_t::CONTINUE);
               case action_t::NEXT:
                   switch (script[step].control) {
                       case control_t::NOP:         return std::make_pair(++step, seq_status_t::CONTINUE);
                       case control_t::SEND:        return std::make_pair(++step, seq_status_t::CONTINUE);
                       case control_t::EXPECT:
                       case control_t::OR_EXPECT:   skip_while = control_t::OR_EXPECT; break;
                       case control_t::DETECT:
                       case control_t::OR_DETECT:   skip_while = control_t::OR_DETECT; break;
                   }
                   s = step;
                   while (script[++s].control == skip_while)
                       ;
                                                    return std::make_pair(s, seq_status_t::CONTINUE);
               case action_t::GOTO:                 return std::make_pair(script[step].action.value, seq_status_t::CONTINUE);
               case action_t::EXIT:                 return std::make_pair(script[step].action.value, seq_status_t::EXIT);

           }
       }

    //! @}


    public:

       //! \return   The buffer size of the sequencer
       constexpr size_t size() const noexcept { return N; }

       /*!
        * \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 buffer     The buffer to check (1st parameter to match)
        * \param token      String view to check against buffer (2nd parameter to match)
        * \param handler    Function pointer to match predicate to use
        * \param handle     Reference to handle to call on match
        *
        * \return           True on match, false otherwise
        */
       constexpr bool check_handle (const string_view buffer, const string_view token, match_ft match, handler_ft handle) {
           if (match != nullptr && match(buffer, token))
               return handle_ (handle, buffer);
           return false;
       }

       /*!
        * \brief
        *   Run the script array
        *
        * The main sequencer functionality. It starts with the first entry of the array.
        *
        * - If the record is \c NOP it executes the action after the timeout.
        *   \c NOP uses {\c action_t, \c timeout}.
        * - If the record is \c SEND passes the token to handler (if any), then to put_() and executes the action after that.
        *   \c SEND uses {\c token, \c handler, \c action_t}
        * - If the record is \c EXCEPT it continuously try to receive data using \see get_()
        *     * If no data until timeout, exit with failure
        *     * On data reception for this record AND for each OR_EXPECT that follows, calls the match predicate
        *       by passing the received data and token.
        *       On predicate match
        *         - Calls the handler if there is one
        *         - Executes the action. No farther EXPECT, OR_EXPECT, ... checks are made.
        * - If the record is \c DETECT it continuously try to receive data using \see contents_()
        *     * If no data until timeout, exit with failure
        *     * On data reception for this record AND for each OR_DETECT that follows, calls the match predicate
        *       by passing the received data and token.
        *       On predicate match
        *         - Calls the handler if there is one
        *         - Executes the action. No farther DETECT, OR_DETECT, ... checks are made.
        *
        * \tparam Steps     The number of records of the script
        *
        * \param script     Reference to script to run
        * \return           The status of entire operation as described above
        *   \arg            0       Success
        *   \arg   (size_t)-1       Failure
        *   \arg        other       Arbitrary return status
        */
       template <size_t Steps>
       size_t run (const script_t<Steps>& script) {
           Data_t buffer[N];
           size_t resp_size;

           size_t step =0, p_step =0;
           clock_t mark = clock_();

           seq_status_t status{seq_status_t::CONTINUE}; do {
               if (step >= Steps)
                   return exit_error.value;
               const record_t& record = script[step];   // get reference ot current line

               if (step != p_step) {                    // renew time marker in each step
                   p_step = step;
                   mark = clock_();
               }
               switch (record.control) {
                   default:
                   case control_t::NOP:
                       if ((clock_() - mark) >= record.timeout)
                           std::tie(step, status) = action_ (script, step);
                       break;

                   case control_t::SEND:
                       if (record.handler != nullptr)
                           record.handler(record.token.data(), record.token.size());
                       if (put_(record.token.data(), record.token.size()) != record.token.size())
                	       return exit_error.value;
                	   std::tie(step, status) = action_ (script, step);
                       break;

                   case control_t::EXPECT:
                   case control_t::OR_EXPECT:
                       resp_size = get_(buffer);
                       if (resp_size) {
                           size_t s = step ; do{
                               if (script[s].match != nullptr && script[s].match({buffer, resp_size}, script[s].token)) {
                                   handle_ (script[s].handler, {buffer, resp_size});
                                   std::tie(step, status) = action_ (script, s);
                                   break;
                               }
                           } while ((++s < Steps) && (script[s].control == control_t::OR_EXPECT));
                       }
                       if (record.timeout && (clock_() - mark) >= record.timeout)
                           return exit_error.value;
                       break;

                   case control_t::DETECT:
                   case control_t::OR_DETECT:
                       resp_size = contents_(buffer);
                       if (resp_size) {
                           size_t s = step ; do {
                               if (script[s].match != nullptr && script[s].match({buffer, resp_size}, script[s].token)) {
                                   handle_ (script[s].handler, {buffer, resp_size});
                                   std::tie(step, status) = action_ (script, s);
                                   break;
                               }
                           } while ((++s < Steps) && (script[s].control == control_t::OR_DETECT));
                       }
                       if (record.timeout && (clock_() - mark) >= record.timeout)
                           return exit_error.value;
                       break;

               } // switch (record.control)

           } while ( status == seq_status_t::CONTINUE);

           return step; // step here is set by action_ as the return status
       }
};


} //namespace utl;
#endif /* utl_dev_dequencer_h__ */