fflua_luascriptitem.h

/*
* File: fflua_luascriptitem.h
*
*  Created by Robert Patterson 2022-07-30
*
* ******* IMPORTANT!!! ******
* Although this file is available in the PDK Framework folder, it should NOT be used in
* the PDK Framework umbrella. This file is placed in the framework folder purely ONLY to
* provide online documentation for the FCLuaScriptItem and FCLuaScriptItems classes!
*
* (The file will ONLY make sense in the context of the specific
* LuaBridge connection implementation.)
*
* The following class implementations are for the special FCLuaScriptItem and FCLuaScriptItems classes
* in RGP Lua. Since a limitation of LuaBridge is that the include file can only be included at one place,
* this work-around is used.
*/
 
#ifndef jwlua_fflua_luascriptitem_h
#define jwlua_fflua_luascriptitem_h
 
#include <string>
#include <functional>
#include <unordered_map>
 
#include "ff_base.h"
 
class FCLuaScriptItem : public __FCBase
{
private:
    std::string _filepath;
    std::string _filename;
    std::optional<std::string> _scripttext;
    std::string _menutext;
    std::string _undotext;
    std::string _description;
    std::string _prefix;
    std::unordered_map<std::string, std::string> _fields;
    bool _debug;
    bool _loadasstring;
    int _executableindex;
    bool _versionCompatible;
    bool _autoReportErrors;
    bool _trusted;
    __FCUserWindow* _controllingwindow;
    EVERSION _minFinaleYear;
    EVERSION _maxFinaleYear;
    EVERSION _minFinaleVersion;
    EVERSION _maxFinaleVersion;
    EVERSION _minLuaVersion;
    EVERSION _maxLuaVersion;
    
    // The cleanup function is called in the destructor function.
    // This is needed because the Lua connector (RGP Lua) is tightly coupled to this
    // class and needs to be notified when it is destroyed.
    std::function<void (FCLuaScriptItem *)> _cleanupFunction;
    // The isexecuting function is called to determine if there is a script executing
    std::function<bool (const FCLuaScriptItem *)> _isExecuting;
    void* _userData; // opaque to FCLuaScriptItem
    
    luabridge::LuaRef _printCallBack;
    luabridge::LuaRef _handleExecutionStarted;
    luabridge::LuaRef _handleExecutionStopped;
    luabridge::LuaRef _handleModalWindowOpened;
    luabridge::LuaRef _handleModalWindowClosed;
    
    void _init()
    {
        _debug = false;
        _loadasstring = false;
        _versionCompatible = false;
        _autoReportErrors = true;
        _trusted = false;
        _minFinaleYear = 0;
        _maxFinaleYear = UINT32_MAX;
        _minFinaleVersion = 0;
        _maxFinaleVersion = UINT32_MAX;
        _minLuaVersion = 0;
        _maxLuaVersion = UINT32_MAX;
        _userData = nullptr;
        _controllingwindow = nullptr;
    }
    
    template<typename... Args>
    void ExecuteCallbackFunction(luabridge::LuaRef& functionLuaRef, Args... args)
    {
        if (functionLuaRef.isFunction())
            functionLuaRef(this, args...);
    }
   
public:
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
    FCLuaScriptItem(std::function<void (FCLuaScriptItem *)> cleanupFunc, std::function<bool (const FCLuaScriptItem *)> isExecutingFunc, const char *filePath, const char *fileName, const char *scriptText, lua_State* L)
                : _cleanupFunction(cleanupFunc), _isExecuting(isExecutingFunc), _executableindex(-1),
                    _printCallBack(L),
                    _handleExecutionStarted(L),
                    _handleExecutionStopped(L),
                    _handleModalWindowOpened(L),
                    _handleModalWindowClosed(L)
    {
        _init();
        if (filePath)
            _filepath = filePath;
        if (fileName)
            _filename = fileName;
        assert(!_filepath.size() || _filename.size());
        if (scriptText)
            _scripttext = scriptText;
    }
    
    FCLuaScriptItem(std::function<bool (const FCLuaScriptItem *)> isExecuting, int index, const char *fileName, lua_State* L)
                : _cleanupFunction(nullptr), _isExecuting(isExecuting), _executableindex(index),
                    _printCallBack(L),
                    _handleExecutionStarted(L),
                    _handleExecutionStopped(L),
                    _handleModalWindowOpened(L),
                    _handleModalWindowClosed(L)
    {
        _init();
        if (fileName)
            _filename = fileName;
    }
    
    ~FCLuaScriptItem()
    {
        // Nop-out the callbacks, because if they throw an error when we are trying to be destroyed,
        // there may not be anything to catch the exception. Consider the following scenario:
        //
        // Both handlers run the same code that contains a runtime error.
        // The supervising script executes the script item, which error aborts in the start handler.
        // When the supervisor tries to call lua_close on itself, all its open script items are destroyed.
        // Including this one that (if we didn't nop these out) would call the stopped
        // handler and trigger another exception, crashing the system.
        //
        // If there is ever a need to report execution stopped from a dying FCLuaScriptItem, we'll
        // revisit this. As of now, there is not.
        _handleExecutionStarted = luabridge::LuaRef(_handleExecutionStarted.state());
        _handleExecutionStopped = luabridge::LuaRef(_handleExecutionStopped.state());
        if (_cleanupFunction) _cleanupFunction(this);
    }
#endif // DOXYGEN_SHOULD_IGNORE_THIS
 
    const char* ClassName() const override { return "FCLuaScriptItem"; }
 
    enum LUASCRIPT_REQVERSION_TYPES {
 
        REQVERSIONTYPE_MINIMUM_FINALE = 0,
 
        REQVERSIONTYPE_MAXIMUM_FINALE,
 
        REQVERSIONTYPE_MINIMUM_FINALE_MAJOR,
 
        REQVERSIONTYPE_MAXIMUM_FINALE_MAJOR,
 
        REQVERSIONTYPE_MINIMUM_LUAX1000,
 
        REQVERSIONTYPE_MAXIMUM_LUAX1000
 
    };
 
    bool IsExecuting() const { return _isExecuting(this); }
    
    void StopExecuting() { if (_cleanupFunction) _cleanupFunction(this); }
 
    //
    // Getters
    //
    
    const char * GetFilePath() const { return _filepath.c_str(); }
    
    const char * GetFileName() const { return _filename.c_str(); }
 
    const char * GetOptionalScriptText() const
    {
        if (_scripttext.has_value())
            return _scripttext->c_str();
        return nullptr;
    }
    
    const char * GetMenuItemText() const { return _menutext.c_str(); }
    
    const char * GetUndoText() const { return _undotext.c_str(); }
    
    const char * GetDescription() const { return _description.c_str(); }
    
    const char * GetPrefix() const { return _prefix.c_str(); }
    
    bool GetDebug() const { return _debug; }
    
    bool GetLoadAsString() const { return _loadasstring; }
    
    int GetExecutableIndex() const { return _executableindex; }
    
    bool GetVersionCompatible() const { return _versionCompatible; }
    
    EVERSION GetRequiredVersion(int versiontype) const
    {
        switch(versiontype)
        {
            case REQVERSIONTYPE_MINIMUM_FINALE: return _minFinaleVersion;
            case REQVERSIONTYPE_MAXIMUM_FINALE: return _maxFinaleVersion;
            case REQVERSIONTYPE_MINIMUM_FINALE_MAJOR: return _minFinaleYear;
            case REQVERSIONTYPE_MAXIMUM_FINALE_MAJOR: return _maxFinaleYear;
            case REQVERSIONTYPE_MINIMUM_LUAX1000: return _minLuaVersion;
            case REQVERSIONTYPE_MAXIMUM_LUAX1000: return _maxLuaVersion;
        }
        throw std::runtime_error("Invalid value passed to FCLuaScriptItem::GetRequiredVersion");
    }
    
    bool GetAutomaticallyReportErrors() const { return _autoReportErrors; }
    
    bool GetTrusted() const { return _trusted; }
    
    __FCUserWindow* GetControllingWindow() const { return _controllingwindow; }
 
    FCString * CreateFinalePluginValue(const char *fieldname)
    {
        auto it = _fields.find(fieldname);
        if (it == _fields.end())
            return nullptr;
        return new FCString(it->second.c_str());
    }
    
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
    luabridge::RefCountedPtr<FCString> CreateFinalePluginValue_GC(const char *fieldname)
    { return makeLuaSharedPtr(CreateFinalePluginValue(fieldname)); }
#endif // DOXYGEN_SHOULD_IGNORE_THIS
    
    //
    // Setters
    //
    
    void SetOptionalScriptText(const char* value)
    {
        if (value)
            _scripttext = value;
        else
            _scripttext = std::nullopt;
    }
 
    void SetMenuItemText(const char * value) { _menutext = value; }
 
    void SetUndoText(const char * value) { _undotext = value; }
 
    void SetDescription(const char * value) { _description = value; }
 
    void SetPrefix(const char * value) { _prefix = value; }
 
    void SetDebug(bool state) { _debug = state; }
    
    void SetLoadAsString(bool state) { _loadasstring = state; }
    
    void SetAutomaticallyReportErrors(bool state) { _autoReportErrors = state; }
    
    void SetTrusted(bool state) { _trusted = state; }
    
    void SetControllingWindow(__FCUserWindow* value) { _controllingwindow = value; }
 
    bool RegisterPrintFunction(luabridge::LuaRef lua_callback_function)
    {
        if (!lua_callback_function.isFunction()) return false;
        _printCallBack = lua_callback_function;
        return true;
    }
 
    bool RegisterOnExecutionWillStart(luabridge::LuaRef lua_callback_function)
    {
        if (!lua_callback_function.isFunction()) return false;
        _handleExecutionStarted = lua_callback_function;
        return true;
    }
 
    bool RegisterOnExecutionDidStop(luabridge::LuaRef lua_callback_function)
    {
        if (!lua_callback_function.isFunction()) return false;
        _handleExecutionStopped = lua_callback_function;
        return true;
    }
 
    bool RegisterOnModalWindowWillOpen(luabridge::LuaRef lua_callback_function)
    {
        if (!lua_callback_function.isFunction()) return false;
        _handleModalWindowOpened = lua_callback_function;
        return true;
    }
 
    bool RegisterOnModalWindowDidClose(luabridge::LuaRef lua_callback_function)
    {
        if (!lua_callback_function.isFunction()) return false;
        _handleModalWindowClosed = lua_callback_function;
        return true;
    }
 
    void OnExecutionWillStart()
    {
        ExecuteCallbackFunction(_handleExecutionStarted);
    }
    
    void OnExecutionDidStop(bool success, const char* msg, int msgtype, int linenumber, const char* source)
    {
        ExecuteCallbackFunction(_handleExecutionStopped, success, msg, msgtype, linenumber, source);
    }
 
    void OnModalWindowWillOpen()
    {
        ExecuteCallbackFunction(_handleModalWindowOpened);
    }
 
    void OnModalWindowDidClose()
    {
        ExecuteCallbackFunction(_handleModalWindowClosed);
    }
 
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
    const luabridge::LuaRef& GetPrintFunction() const { return _printCallBack; }
    
    void SetVersionCompatible(const bool state) { _versionCompatible = state; }
    
    void SetFinalePluginFields(const std::unordered_map<std::string, std::string>& fields)
    { _fields = fields; }
    
    void SetRequiredVersion(LUASCRIPT_REQVERSION_TYPES versiontype, EVERSION requiredversion)
    {
        switch(versiontype)
        {
            case REQVERSIONTYPE_MINIMUM_FINALE:
                _minFinaleVersion = requiredversion;
                break;
                
            case REQVERSIONTYPE_MAXIMUM_FINALE:
                _maxFinaleVersion = requiredversion;
                break;
                
            case REQVERSIONTYPE_MINIMUM_FINALE_MAJOR:
                _minFinaleYear = requiredversion;
                break;
                
            case REQVERSIONTYPE_MAXIMUM_FINALE_MAJOR:
                _maxFinaleYear = requiredversion;
                break;
                
            case REQVERSIONTYPE_MINIMUM_LUAX1000:
                _minLuaVersion = requiredversion;
                break;
                
            case REQVERSIONTYPE_MAXIMUM_LUAX1000:
                _maxLuaVersion = requiredversion;
                break;
                
            default:
                throw std::runtime_error("Invalid value passed to FCLuaScriptItem::SetRequiredVersion");
        }
    }
    
    void* GetUserData() const { return _userData; }
 
    void SetUserData(void* ptr) { _userData = ptr; }
#endif // DOXYGEN_SHOULD_IGNORE_THIS
};
 
class FCLuaScriptItems : public __FCCollection
{
public:
    const char* ClassName() const override { return "FCLuaScriptItems"; }
 
    FCLuaScriptItems() : __FCCollection()
    {}
 
    void Add(FCLuaScriptItem *pNewItem) { __FCCollection::Add(pNewItem); }
 
    void InsertItemAt(FCLuaScriptItem *pNewItem, int index)  { __FCCollection::InsertItemAt(pNewItem, index); }
 
    FCLuaScriptItem* GetItemAt(int index) const { return (FCLuaScriptItem*) __FCCollection::GetItemAt(index); }
};
 
 
#endif // jwlua_fflua_luascriptitem_h