console.h

/*
 * uuid-console - Microcontroller console shell
 * Copyright 2019,2021-2022  Simon Arlott
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef UUID_CONSOLE_H_
#define UUID_CONSOLE_H_
 
#include <Arduino.h>
 
#include <cstdarg>
#include <cstdint>
#include <deque>
#include <functional>
#include <iterator>
#include <limits>
#include <list>
#include <memory>
#include <map>
#include <set>
#include <string>
#include <vector>
 
#include <uuid/common.h>
#include <uuid/log.h>
 
#ifndef UUID_LOG_THREAD_SAFE
# define UUID_LOG_THREAD_SAFE 0
#endif
 
#ifndef UUID_COMMON_STD_MUTEX_AVAILABLE
# define UUID_COMMON_STD_MUTEX_AVAILABLE 0
#endif
 
#if defined(DOXYGEN) || UUID_COMMON_STD_MUTEX_AVAILABLE
# define UUID_CONSOLE_THREAD_SAFE 1
#else
# define UUID_CONSOLE_THREAD_SAFE 0
#endif
 
#if UUID_CONSOLE_THREAD_SAFE
# include <mutex>
#endif
 
namespace uuid {
 
namespace console {
 
#if UUID_COMMON_THREAD_SAFE && UUID_LOG_THREAD_SAFE && UUID_CONSOLE_THREAD_SAFE
static constexpr bool thread_safe = true;
#else
static constexpr bool thread_safe = false;
#endif
 
class Commands;
class CommandLine;
class Shell;
 
class Commands {
private:
    class Command;
 
public:
    struct Completion;
 
    struct Execution {
        const __FlashStringHelper *error; 
    };
 
    using command_function = std::function<void(Shell &shell, std::vector<std::string> &arguments)>;
    using argument_completion_function = std::function<const std::vector<std::string>(
        Shell &shell, const std::vector<std::string> &current_arguments, const std::string &next_argument)>;
 
    class AvailableCommand {
    public:
        AvailableCommand(const Command &command);
 
        inline const std::vector<std::string> &name() const { return name_; }
 
        inline const std::vector<std::string> &arguments() const { return arguments_; }
 
        inline const command_function &function() const { return command_.function_; };
 
        inline const argument_completion_function &arg_function() const { return command_.arg_function_; };
 
        inline int flags() const { return command_.flags_; }
 
        inline int not_flags() const { return command_.not_flags_; }
 
    private:
        const Commands::Command &command_; 
        std::vector<std::string> name_; 
        std::vector<std::string> arguments_; 
    };
 
    class AvailableCommands {
    public:
        using command_iterator = std::multimap<unsigned int,Command>::const_iterator; 
        class const_iterator {
        public:
            using iterator_category = std::bidirectional_iterator_tag; 
            using difference_type = std::size_t; 
            using value_type = AvailableCommand; 
            using pointer = const value_type*; 
            using reference = const value_type&; 
            const_iterator(const Shell &shell, const command_iterator &begin,
                    const command_iterator &command, const command_iterator &end);
 
            inline reference operator*() const { return *available_command_; }
            inline pointer operator->() const { return available_command_.get(); }
 
            const_iterator& operator++();
            inline const_iterator operator++(int) { auto tmp = *this; ++(*this); return tmp; }
 
            const_iterator& operator--();
            inline const_iterator operator--(int) { auto tmp = *this; --(*this); return tmp; }
 
            friend inline bool operator==(const const_iterator& lhs, const const_iterator& rhs) { return lhs.command_ == rhs.command_; }
            friend inline bool operator!=(const const_iterator& lhs, const const_iterator& rhs) { return lhs.command_ != rhs.command_; }
 
        private:
            void update();
 
            const Shell &shell_; 
            const command_iterator begin_; 
            command_iterator command_; 
            const command_iterator end_; 
            std::shared_ptr<AvailableCommand> available_command_; 
        };
 
        AvailableCommands(const Shell &shell, const command_iterator &begin, const command_iterator &end);
 
        inline const_iterator begin() const { return cbegin(); }
        const_iterator cbegin() const;
        inline const_iterator end() const { return cend(); }
        const_iterator cend() const;
 
    private:
        const Shell &shell_; 
        command_iterator begin_; 
        command_iterator end_; 
    };
 
    Commands() = default;
    ~Commands() = default;
 
    void add_command(const flash_string_vector &name, command_function function);
    void add_command(const flash_string_vector &name, const flash_string_vector &arguments,
            command_function function);
    void add_command(const flash_string_vector &name, const flash_string_vector &arguments,
            command_function function, argument_completion_function arg_function);
 
    void add_command(unsigned int context, const flash_string_vector &name,
            command_function function);
    void add_command(unsigned int context, const flash_string_vector &name,
            const flash_string_vector &arguments, command_function function);
    void add_command(unsigned int context, const flash_string_vector &name,
            const flash_string_vector &arguments, command_function function,
            argument_completion_function arg_function);
    void add_command(unsigned int context, unsigned int flags,
            const flash_string_vector &name, command_function function);
    void add_command(unsigned int context, unsigned int flags,
            const flash_string_vector &name, const flash_string_vector &arguments,
            command_function function);
    void add_command(unsigned int context, unsigned int flags,
            const flash_string_vector &name, const flash_string_vector &arguments,
            command_function function, argument_completion_function arg_function);
    void add_command(unsigned int context, unsigned int flags, unsigned int not_flags,
            const flash_string_vector &name, command_function function);
    void add_command(unsigned int context, unsigned int flags, unsigned int not_flags,
            const flash_string_vector &name, const flash_string_vector &arguments,
            command_function function);
    void add_command(unsigned int context, unsigned int flags, unsigned int not_flags,
            const flash_string_vector &name, const flash_string_vector &arguments,
            command_function function, argument_completion_function arg_function);
 
    Execution execute_command(Shell &shell, CommandLine &&command_line);
 
    Completion complete_command(Shell &shell, const CommandLine &command_line);
 
    AvailableCommands available_commands(const Shell &shell) const;
 
private:
    class Command {
    public:
        Command(unsigned int flags, unsigned int not_flags,
                const flash_string_vector name, const flash_string_vector arguments,
                command_function function, argument_completion_function arg_function);
        ~Command();
 
        size_t minimum_arguments() const;
        inline size_t maximum_arguments() const { return arguments_.size(); }
 
        unsigned int flags_; 
        unsigned int not_flags_; 
        const flash_string_vector name_; 
        const flash_string_vector arguments_; 
        command_function function_; 
        argument_completion_function arg_function_; 
    private:
        Command(const Command&) = delete;
        Command& operator=(const Command&) = delete;
    };
 
    struct Match {
        std::multimap<size_t,const Command*> exact; 
        std::multimap<size_t,const Command*> partial; 
        std::vector<const Command*> all; 
    };
 
    Match find_command(Shell &shell, const CommandLine &command_line);
 
    static bool find_longest_common_prefix(const std::multimap<size_t,const Command*> &commands, std::vector<std::string> &longest_name);
 
    static std::string find_longest_common_prefix(const std::vector<std::string> &arguments);
 
    std::multimap<unsigned int,Command> commands_; 
};
 
class Shell: public std::enable_shared_from_this<Shell>, public uuid::log::Handler, public ::Stream {
public:
    static constexpr size_t MAX_COMMAND_LINE_LENGTH = 80; 
    static constexpr size_t MAX_LOG_MESSAGES = 20; 
    using password_function = std::function<void(Shell &shell, bool completed, const std::string &password)>;
    using delay_function = std::function<void(Shell &shell)>;
    using blocking_function = std::function<bool(Shell &shell, bool stop)>;
 
    Shell(Stream &stream, std::shared_ptr<Commands> commands, unsigned int context = 0, unsigned int flags = 0);
 
    ~Shell() = default;
 
    static void loop_all();
 
    void start();
    void loop_one();
    bool running() const;
    void stop();
 
    static const uuid::log::Logger& logger();
    virtual void operator<<(std::shared_ptr<uuid::log::Message> message);
    uuid::log::Level log_level() const;
    void log_level(uuid::log::Level level);
 
    size_t maximum_command_line_length() const;
    void maximum_command_line_length(size_t length);
    size_t maximum_log_messages() const;
    void maximum_log_messages(size_t count);
    unsigned long idle_timeout() const;
    void idle_timeout(unsigned long timeout);
 
    inline unsigned int context() const {
        if (!context_.empty()) {
            return context_.back();
        } else {
            return 0;
        }
    }
    inline void enter_context(unsigned int context) {
        context_.emplace_back(context);
    }
    virtual bool exit_context();
 
    inline void add_flags(unsigned int flags) { flags_ |= flags; }
    inline bool has_flags(unsigned int flags, unsigned int not_flags = 0) const {
        return has_all_flags(flags) && !has_any_flags(not_flags);
    }
    inline bool has_all_flags(unsigned int flags) const { return (flags_ & flags) == flags; }
    inline bool has_any_flags(unsigned int flags) const { return (flags_ & flags) != 0; }
    inline void remove_flags(unsigned int flags) { flags_ &= ~flags; }
 
    void enter_password(const __FlashStringHelper *prompt, password_function function);
 
    void delay_for(unsigned long ms, delay_function function);
 
    void delay_until(uint64_t ms, delay_function function);
 
    void block_with(blocking_function function);
 
    int available() final override;
    int read() final override;
    int peek() final override;
 
    size_t write(uint8_t data) final override;
    size_t write(const uint8_t *buffer, size_t size) final override;
    void flush() final override;
 
    using ::Print::print; 
    size_t print(const std::string &data);
    using ::Print::println; 
    size_t println(const std::string &data);
    size_t printf(const char *format, ...) /* __attribute__((format(printf, 2, 3))) */;
    size_t printf(const __FlashStringHelper *format, ...) /* __attribute__((format(printf, 2, 3))) */;
    size_t printfln(const char *format, ...) /* __attribute__((format (printf, 2, 3))) */;
    size_t printfln(const __FlashStringHelper *format, ...) /* __attribute__((format(printf, 2, 3))) */;
 
    Commands::AvailableCommands available_commands() const;
    void print_all_available_commands();
 
protected:
    virtual void erase_current_line();
    virtual void erase_characters(size_t count);
 
    virtual void started();
    virtual void display_banner();
    virtual std::string hostname_text();
    virtual std::string context_text();
    virtual std::string prompt_prefix();
    virtual std::string prompt_suffix();
    virtual void end_of_transmission();
    virtual void stopped();
 
    void invoke_command(const std::string &line);
 
private:
    enum class Mode : uint8_t {
        NORMAL, 
        PASSWORD, 
        DELAY, 
        BLOCKING, 
    };
 
    class ModeData {
    public:
        virtual ~ModeData() = default;
 
    protected:
        ModeData() = default;
    };
 
    class PasswordData: public ModeData {
    public:
        PasswordData(const __FlashStringHelper *password_prompt, password_function &&password_function);
        ~PasswordData() override = default;
 
        const __FlashStringHelper *password_prompt_; 
        password_function password_function_; 
    };
 
    class DelayData: public ModeData {
    public:
        DelayData(uint64_t delay_time, delay_function &&delay_function);
        ~DelayData() override = default;
 
        uint64_t delay_time_; 
        delay_function delay_function_; 
    };
 
    class BlockingData: public ModeData {
    public:
        explicit BlockingData(blocking_function &&blocking_function);
        ~BlockingData() override = default;
 
        blocking_function blocking_function_; 
        bool consume_line_feed_ = true; 
        bool stop_ = false; 
    };
 
    class QueuedLogMessage {
    public:
        QueuedLogMessage(unsigned long id, std::shared_ptr<uuid::log::Message> &&content);
        ~QueuedLogMessage() = default;
 
        unsigned long id_; 
        std::shared_ptr<const uuid::log::Message> content_; 
    };
 
    Shell(const Shell&) = delete;
    Shell& operator=(const Shell&) = delete;
 
    static std::set<std::shared_ptr<Shell>>& registered_shells();
 
    void loop_normal();
    void loop_password();
    void loop_delay();
    void loop_blocking();
 
    void display_prompt();
    void output_logs();
    void process_command();
    void process_completion();
    void process_password(bool completed);
 
    void check_idle_timeout();
 
    void delete_buffer_word(bool display);
 
    size_t vprintf(const char *format, va_list ap);
    size_t vprintf(const __FlashStringHelper *format, va_list ap);
 
    Stream &stream_; 
    std::shared_ptr<Commands> commands_; 
    std::deque<unsigned int> context_; 
    unsigned int flags_ = 0; 
#if UUID_CONSOLE_THREAD_SAFE
    mutable std::mutex mutex_; 
#endif
    unsigned long log_message_id_ = 0; 
    std::list<QueuedLogMessage> log_messages_; 
    size_t maximum_log_messages_ = MAX_LOG_MESSAGES; 
    std::string line_buffer_; 
    size_t maximum_command_line_length_ = MAX_COMMAND_LINE_LENGTH; 
    unsigned char previous_ = 0; 
    Mode mode_ = Mode::NORMAL; 
    std::unique_ptr<ModeData> mode_data_ = nullptr; 
    bool stopped_ = false; 
    bool prompt_displayed_ = false; 
    uint64_t idle_time_ = 0; 
    uint64_t idle_timeout_ = 0; 
};
 
class CommandLine {
public:
    CommandLine() = default;
 
    explicit CommandLine(const std::string &line);
 
    explicit CommandLine(std::initializer_list<const std::vector<std::string>> arguments);
 
    ~CommandLine() = default;
 
#ifdef UNIT_TEST
    CommandLine(CommandLine&&) = default;
    CommandLine& operator=(CommandLine&&) = default;
    CommandLine(const CommandLine&) __attribute__((deprecated)) = default;
    CommandLine& operator=(const CommandLine&) __attribute__((deprecated)) = default;
#endif
 
    std::string to_string(size_t reserve = Shell::MAX_COMMAND_LINE_LENGTH) const;
 
    inline size_t total_size() const { return parameters_.size() + (trailing_space ? 1 : 0); }
    void reset();
 
    inline void escape_all_parameters() { escape_parameters_ = std::numeric_limits<size_t>::max(); }
    inline void escape_initial_parameters() { escape_parameters_ = parameters_.size(); }
    inline void escape_initial_parameters(size_t count) { escape_parameters_ = count; }
 
    inline std::vector<std::string>& operator*() { return parameters_; }
    inline const std::vector<std::string>& operator*() const { return parameters_; }
    inline std::vector<std::string>* operator->() { return &parameters_; }
    inline const std::vector<std::string>* operator->() const { return &parameters_; }
 
    friend inline bool operator==(const CommandLine& lhs, const CommandLine& rhs) {
        return (lhs.trailing_space == rhs.trailing_space) && (lhs.parameters_ == rhs.parameters_);
    }
    friend inline bool operator!=(const CommandLine& lhs, const CommandLine& rhs) {
        return !(lhs == rhs);
    }
 
    bool trailing_space = false; 
private:
    std::vector<std::string> parameters_; 
    size_t escape_parameters_ = std::numeric_limits<size_t>::max(); 
};
 
struct Commands::Completion {
    std::list<CommandLine> help; 
    CommandLine replacement; 
};
 
} // namespace console
 
} // namespace uuid
 
#endif