QoreProgram.h

/* -*- mode: c++; indent-tabs-mode: nil -*- */
/*
    QoreProgram.h
 
    Program Object Definition
 
    Qore Programming Language
 
    Copyright (C) 2003 - 2023 Qore Technologies, s.r.o.
 
    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.
 
    Note that the Qore library is released under a choice of three open-source
    licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
    information.
*/
 
#ifndef _QORE_QOREPROGRAM_H
 
#define _QORE_QOREPROGRAM_H
 
#include <qore/AbstractPrivateData.h>
#include <qore/Restrictions.h>
#include <qore/OutputStream.h>
#include <qore/InputStream.h>
 
// warnings - must correspond with the string order in QoreProgram.cpp
// new warnings must also be added as constants
#define QP_WARN_NONE                     0
#define QP_WARN_WARNING_MASK_UNCHANGED   (1 << 0)   
#define QP_WARN_DUPLICATE_LOCAL_VARS     (1 << 1)   
#define QP_WARN_UNKNOWN_WARNING          (1 << 2)   
#define QP_WARN_UNDECLARED_VAR           (1 << 3)   
#define QP_WARN_DUPLICATE_GLOBAL_VARS    (1 << 4)   
#define QP_WARN_UNREACHABLE_CODE         (1 << 5)   
#define QP_WARN_NONEXISTENT_METHOD_CALL  (1 << 6)   
#define QP_WARN_INVALID_OPERATION        (1 << 7)   
#define QP_WARN_CALL_WITH_TYPE_ERRORS    (1 << 8)   
#define QP_WARN_RETURN_VALUE_IGNORED     (1 << 9)   
#define QP_WARN_DEPRECATED               (1 << 10)  
#define QP_WARN_EXCESS_ARGS              (1 << 11)  
#define QP_WARN_DUPLICATE_HASH_KEY       (1 << 12)  
#define QP_WARN_UNREFERENCED_VARIABLE    (1 << 13)  
#define QP_WARN_DUPLICATE_BLOCK_VARS     (1 << 14)  
#define QP_WARN_MODULE_ONLY              (1 << 15)  
#define QP_WARN_BROKEN_LOGIC_PRECEDENCE  (1 << 16)  
#define QP_WARN_INVALID_CATCH            (1 << 17)  
#define QP_WARN_ALL                      -1         
 
#define QP_WARN_MODULES (QP_WARN_UNREACHABLE_CODE|QP_WARN_NONEXISTENT_METHOD_CALL|QP_WARN_INVALID_OPERATION|QP_WARN_CALL_WITH_TYPE_ERRORS|QP_WARN_RETURN_VALUE_IGNORED|QP_WARN_DUPLICATE_HASH_KEY|QP_WARN_DUPLICATE_BLOCK_VARS|QP_WARN_BROKEN_LOGIC_PRECEDENCE|QP_WARN_INVALID_CATCH)
 
#define QP_WARN_DEFAULT (QP_WARN_UNKNOWN_WARNING|QP_WARN_MODULES|QP_WARN_DEPRECATED)
 
enum BreakpointPolicy : unsigned char {
   BKP_PO_NONE = 0,
   BKP_PO_ACCEPT = 1,
   BKP_PO_REJECT = 2,
};
 
DLLEXPORT extern const char** qore_warnings;
 
DLLEXPORT extern unsigned qore_num_warnings;
 
DLLEXPORT int get_warning_code(const char* str);
 
// forward references
class AbstractCallReferenceNode;
class LocalVar;
class ExceptionSink;
class QoreListNode;
class QoreNamespace;
class RootQoreNamespace;
class QoreStringNode;
class QoreHashNode;
class FunctionCallNode;
class AbstractStatement;
class UnresolvedProgramCallReferenceNode;
class Var;
class LVList;
class UserFunctionVariant;
class QoreParseTypeInfo;
class ParamList;
class AbstractQoreZoneInfo;
class qore_program_private;
class AbstractQoreProgramExternalData;
class QoreBreakpoint;
class AbstractQoreFunctionVariant;
class QoreRWLock;
class QoreExternalFunction;
class QoreExternalGlobalVar;
class QoreExternalConstant;
 
typedef std::list<QoreBreakpoint*> bkp_list_t;
 
hashdecl QoreBreakpointList_t : public bkp_list_t {
    DLLEXPORT QoreBreakpointList_t();
    // dereferences all breakpoints and clears the list
    DLLEXPORT ~QoreBreakpointList_t();
};
 
 
class QoreProgram : public AbstractPrivateData {
    friend class qore_program_private_base;
    friend class qore_program_private;
    friend class qore_debug_program_private;
    friend hashdecl ThreadLocalProgramData;
 
public:
    DLLEXPORT QoreProgram();
 
 
    DLLEXPORT QoreProgram(int64 parse_options);
 
 
    DLLEXPORT QoreValue callFunction(const char* name, const QoreListNode* args, ExceptionSink* xsink);
 
 
    DLLEXPORT QoreValue run(ExceptionSink* xsink);
 
 
    DLLEXPORT QoreValue runTopLevel(ExceptionSink* xsink);
 
 
    DLLEXPORT void parseFileAndRun(const char* filename);
 
 
    DLLEXPORT void parseAndRun(FILE *fp, const char* name);
 
 
    DLLEXPORT void parseAndRun(const char* str, const char* name);
 
 
    DLLEXPORT void runClass(const char* classname, ExceptionSink* xsink);
 
 
    DLLEXPORT void parseFileAndRunClass(const char* filename, const char* classname);
 
 
    DLLEXPORT void parseAndRunClass(FILE *fp, const char* name, const char* classname);
 
 
    DLLEXPORT void parseAndRunClass(const char* str, const char* name, const char* classname);
 
 
    DLLEXPORT void parse(FILE *fp, const char* name, ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL);
 
 
    DLLEXPORT void parse(const QoreString* str, const QoreString* lstr, ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL);
 
 
    DLLEXPORT void parse(const QoreString* str, const QoreString* lstr, ExceptionSink* xsink, ExceptionSink* warn_sink, int warn_mask, const QoreString* source, int offset);
 
 
    DLLEXPORT void parse(const char* str, const char* lstr, ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL);
 
 
    DLLEXPORT void parse(const char* str, const char* lstr, ExceptionSink* xsink, ExceptionSink* warn_sink, int warn_mask, const char* source, int offset);
 
 
    DLLEXPORT void parseFile(const char* filename, ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL, bool only_first_except = false);
 
 
    DLLEXPORT void parsePending(const char* code, const char* label, ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL);
 
 
    DLLEXPORT void parsePending(const char* code, const char* label, ExceptionSink* xsink, ExceptionSink* warn_sink, int warn_mask, const char* source, int offset);
 
 
    DLLEXPORT void parsePending(const QoreString* str, const QoreString* lstr, ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL);
 
 
    DLLEXPORT void parsePending(const QoreString* str, const QoreString* lstr, ExceptionSink* xsink, ExceptionSink* warn_sink, int warn_mask, const QoreString* source, int offset);
 
 
    DLLEXPORT void parseCommit(ExceptionSink* xsink, ExceptionSink* warn_sink = 0, int warn_mask = QP_WARN_ALL);
 
 
    DLLEXPORT int parseRollback(ExceptionSink* xsink);
 
    DLLEXPORT bool existsFunction(const char* name);
 
 
    using AbstractPrivateData::deref;
    DLLEXPORT virtual void deref(ExceptionSink* xsink);
 
    DLLEXPORT QoreProgram* programRefSelf() const;
 
    DLLEXPORT void lockOptions();
 
 
    DLLEXPORT void setExecClass(const char* ecn = 0);
 
    DLLEXPORT void parseSetParseOptions(int64 po);
 
    DLLEXPORT void parseDisableParseOptions(int64 po);
 
    DLLEXPORT void waitForTermination();
 
 
    DLLEXPORT void waitForTerminationAndDeref(ExceptionSink* xsink);
 
    DLLEXPORT QoreNamespace* getQoreNS() const;
 
    DLLEXPORT RootQoreNamespace* getRootNS() const;
 
 
    DLLEXPORT int setWarningMask(int wm);
 
 
    DLLEXPORT int enableWarning(int code);
 
 
    DLLEXPORT int disableWarning(int code);
 
    DLLEXPORT int getParseOptions() const;
 
    DLLEXPORT int64 getParseOptions64() const;
 
 
    DLLEXPORT void setParseOptions(int64 po, ExceptionSink* xsink);
 
 
    DLLEXPORT void disableParseOptions(int64 po, ExceptionSink* xsink);
 
 
    DLLEXPORT void replaceParseOptions(int64 po, ExceptionSink* xsink);
 
 
    DLLEXPORT QoreListNode* getUserFunctionList();
 
    DLLEXPORT bool checkWarning(int code) const;
 
    DLLEXPORT int getWarningMask() const;
 
    DLLEXPORT bool checkFeature(const char* f) const;
 
    DLLEXPORT QoreListNode* getFeatureList() const;
 
 
    DLLEXPORT QoreStringNode* getScriptName() const;
 
 
    DLLEXPORT QoreStringNode* getScriptPath() const;
 
 
    DLLEXPORT QoreStringNode* getScriptDir() const;
 
 
    DLLEXPORT void setScriptPath(const char* path);
 
 
    DLLEXPORT QoreValue getGlobalVariableValue(const char* var, bool &found) const;
 
 
    DLLEXPORT QoreValue getGlobalVariableVal(const char* var, bool &found) const;
 
    // retrieves the time zone setting for the program
    DLLEXPORT const AbstractQoreZoneInfo *currentTZ() const;
 
    // sets the program's time zone
    DLLEXPORT void setTZ(const AbstractQoreZoneInfo *n_TZ);
 
 
    DLLEXPORT void addFeature(const char* name);
 
 
    DLLEXPORT void parseSetTimeZone(const char* zone);
 
 
    DLLEXPORT void parseDefine(const char* str, QoreValue val);
 
 
    DLLEXPORT void parseDefine(const char* str, const char* val);
 
    // @deprecated use parseCmdLineDefines(ExceptionSink& xs, ExceptionSink& ws, int w, const std::map<std::string, std::string>& defmap) instead
    DLLEXPORT void parseCmdLineDefines(const std::map<std::string, std::string> defmap, ExceptionSink& xs, ExceptionSink& ws, int w);
 
 
    DLLEXPORT void parseCmdLineDefines(ExceptionSink& xs, ExceptionSink& ws, int w, const std::map<std::string, std::string>& defmap);
 
 
    DLLEXPORT void setExternalData(const char* owner, AbstractQoreProgramExternalData* pud);
 
 
    DLLEXPORT AbstractQoreProgramExternalData* getExternalData(const char* owner) const;
 
 
    DLLEXPORT AbstractQoreProgramExternalData* removeExternalData(const char* owner);
 
 
    DLLEXPORT QoreHashNode* getGlobalVars() const;
 
 
    DLLEXPORT int setGlobalVarValue(const char* name, QoreValue val, ExceptionSink* xsink);
 
    // finds a function or class method variant if possible
    DLLEXPORT const AbstractQoreFunctionVariant* runtimeFindCall(const char* name, const QoreListNode* params, ExceptionSink* xsink) const;
 
    // finds all variants of a function or class method and returns a list of the results
    DLLEXPORT QoreListNode* runtimeFindCallVariants(const char* name, ExceptionSink* xsink) const;
 
 
    DLLEXPORT QoreListNode* getThreadList() const;
 
 
    DLLEXPORT const QoreClass* findClass(const char* path, ExceptionSink* xsink) const;
 
 
    DLLEXPORT class_vec_t findAllClassesRegex(const QoreString& pattern, int re_opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT hashdecl_vec_t findAllHashDeclsRegex(const QoreString& pattern, int re_opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT func_vec_t findAllFunctionsRegex(const QoreString& pattern, int re_opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT ns_vec_t findAllNamespacesRegex(const QoreString& pattern, int re_opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT gvar_vec_t findAllGlobalVarsRegex(const QoreString& pattern, int re_opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT const_vec_t findAllNamespaceConstantsRegex(const QoreString& pattern, int re_opts, ExceptionSink* xsink) const;
 
 
    DLLEXPORT const QoreExternalFunction* findFunction(const char* path) const;
 
 
    DLLEXPORT const TypedHashDecl* findHashDecl(const char* path, const QoreNamespace*& pns) const;
 
 
    DLLEXPORT QoreNamespace* findNamespace(const QoreString& path);
 
 
    DLLEXPORT const QoreNamespace* findNamespace(const QoreString& path) const;
 
 
    DLLEXPORT const QoreExternalGlobalVar* findGlobalVar(const char* path, const QoreNamespace*& pns) const;
 
 
    DLLEXPORT const QoreExternalConstant* findNamespaceConstant(const char* path, const QoreNamespace*& pns) const;
 
 
    DLLEXPORT void depRef();
 
 
    DLLEXPORT void depDeref();
 
 
    DLLEXPORT QoreHashNode* getThreadData();
 
 
    DLLEXPORT int issueModuleCmd(const char* module, const char* cmd, ExceptionSink* xsink);
 
    DLLLOCAL QoreProgram(QoreProgram* pgm, int64 po, bool ec = false, const char* ecn = nullptr);
 
    DLLLOCAL LocalVar *createLocalVar(const char* name, const QoreTypeInfo *typeInfo);
 
    // returns 0 if a "requires" exception has already occurred
    DLLLOCAL ExceptionSink* getParseExceptionSink();
 
    DLLLOCAL void addFile(char* f);
    DLLLOCAL QoreListNode* getVarList();
    DLLLOCAL void parseSetIncludePath(const char* path);
    DLLLOCAL const char* parseGetIncludePath() const;
 
    /* for run-time module loading; the parse lock must be grabbed
        before loading new modules - note this should only be assigned
        to an AutoLock or SafeLocker object!
    */
    DLLLOCAL QoreThreadLock *getParseLock();
    DLLLOCAL const LVList* getTopLevelLVList() const;
 
 
    DLLLOCAL const char* parseGetScriptDir() const;
 
    // can only be called while parsing from the same thread doing the parsing
    DLLLOCAL bool parseExceptionRaised() const;
 
    // TODO: implement !
    DLLEXPORT QoreValue getLocalVariableVal(const char* var, bool &found) const;
 
    DLLEXPORT void assignBreakpoint(QoreBreakpoint *bkpt, ExceptionSink *xsink);
 
    DLLEXPORT void deleteAllBreakpoints();
 
    DLLEXPORT void getBreakpoints(QoreBreakpointList_t &bkptList);
 
    DLLEXPORT void getStatementBreakpoints(const AbstractStatement* statement, QoreBreakpointList_t &bkptList);
 
    DLLEXPORT AbstractStatement* findStatement(const char* fileName, int line) const;
 
    DLLEXPORT AbstractStatement* findFunctionStatement(const char* functionName, const QoreListNode* params, ExceptionSink* xsink) const;
 
 
    DLLEXPORT unsigned long getStatementId(const AbstractStatement* statement) const;
 
 
    DLLEXPORT AbstractStatement* resolveStatementId(unsigned long statementId) const;
 
 
    DLLEXPORT QoreHashNode* getSourceFileNames(ExceptionSink* xsink) const;
 
    DLLEXPORT QoreHashNode* getSourceLabels(ExceptionSink* xsink) const;
 
 
    DLLEXPORT unsigned getProgramId() const;
 
 
    DLLEXPORT static QoreProgram* resolveProgramId(unsigned programId);
 
    DLLEXPORT void registerQoreObject(QoreObject *o, ExceptionSink* xsink) const;
 
    DLLEXPORT void unregisterQoreObject(QoreObject *o, ExceptionSink* xsink) const;
 
    DLLEXPORT QoreObject* findQoreObject() const;
 
    DLLEXPORT static QoreObject* getQoreObject(QoreProgram* pgm);
 
    DLLEXPORT static QoreListNode* getAllQoreObjects(ExceptionSink* xsink);
 
    DLLEXPORT bool checkAllowDebugging(ExceptionSink* xsink);
 
protected:
 
    DLLLOCAL virtual ~QoreProgram();
 
private:
    qore_program_private* priv;
 
    DLLLOCAL QoreProgram(const QoreProgram&);
 
    DLLLOCAL QoreProgram& operator=(const QoreProgram&);
};
 
 
class QoreProgramHelper {
private:
   QoreProgram* pgm;
   ExceptionSink& xsink;
 
public:
   DLLEXPORT QoreProgramHelper(ExceptionSink& xs);
 
   DLLEXPORT QoreProgramHelper(int64 parse_options, ExceptionSink& xs);
 
 
   DLLEXPORT ~QoreProgramHelper();
 
   DLLEXPORT QoreProgram* operator->();
 
   DLLEXPORT QoreProgram* operator*();
};
 
 
class CurrentProgramRuntimeExternalParseContextHelper {
public:
    DLLEXPORT CurrentProgramRuntimeExternalParseContextHelper();
 
    DLLEXPORT ~CurrentProgramRuntimeExternalParseContextHelper();
 
    DLLEXPORT operator bool() const;
 
private:
    bool valid = true;
 
    // not implemented
    CurrentProgramRuntimeExternalParseContextHelper(const CurrentProgramRuntimeExternalParseContextHelper&) = delete;
    void* operator new(size_t) = delete;
};
 
 
class ProgramRuntimeExternalParseContextHelper {
public:
    DLLEXPORT ProgramRuntimeExternalParseContextHelper(QoreProgram* pgm);
 
    DLLEXPORT ~ProgramRuntimeExternalParseContextHelper();
 
    DLLEXPORT operator bool() const;
 
private:
    QoreProgram* pgm;
 
    // not implemented
    ProgramRuntimeExternalParseContextHelper(const ProgramRuntimeExternalParseContextHelper&) = delete;
    void* operator new(size_t) = delete;
};
 
 
class QoreProgramContextHelper {
public:
    DLLEXPORT QoreProgramContextHelper(QoreProgram* pgm);
    DLLEXPORT ~QoreProgramContextHelper();
 
private:
    QoreProgram* old_pgm;
 
    // not implemented
    QoreProgramContextHelper(const QoreProgramContextHelper&) = delete;
    void* operator new(size_t) = delete;
};
 
 
class AbstractQoreProgramExternalData {
public:
 
    DLLEXPORT virtual ~AbstractQoreProgramExternalData();
 
 
    virtual AbstractQoreProgramExternalData* copy(QoreProgram* pgm) const = 0;
 
 
    virtual void init();
 
    virtual void doDeref() = 0;
};
 
typedef std::list<AbstractStatement*> AbstractStatementList_t;
typedef std::list<int> TidList_t;
 
 
class QoreBreakpoint : public AbstractPrivateData {
private:
    qore_program_private* pgm;
    AbstractStatementList_t statementList;
    typedef std::map<int/*tid*/, int/*count*/> TidMap_t;
    TidMap_t tidMap;
    QoreObject* qo; // reference to Qore script object, it's private object but we cannot
    static QoreRWLock lck_breakpoint; // to protect breakpoint manipulation
    static QoreBreakpointList_t breakpointList;
    static volatile unsigned breakpointIdCounter;   // to generate breakpointId
    unsigned breakpointId;
 
    DLLLOCAL void unassignAllStatements();
    DLLLOCAL bool isStatementAssigned(const AbstractStatement *statement) const;
    DLLLOCAL bool checkPgm(ExceptionSink* xsink) const;
 
    friend class qore_program_private;
    friend class AbstractStatement;
 
protected:
    DLLLOCAL virtual ~QoreBreakpoint();
    DLLLOCAL virtual bool checkBreak() const;
 
public:
    bool enabled;
    BreakpointPolicy policy;
 
    DLLEXPORT QoreBreakpoint();
    DLLEXPORT QoreBreakpoint& operator=(const QoreBreakpoint& other);
    DLLEXPORT void assignProgram(QoreProgram *new_pgm, ExceptionSink* xsink);
    /* Get assigned program to breakpoint
    */
    DLLEXPORT QoreProgram* getProgram() const;
    DLLEXPORT void assignStatement(AbstractStatement* statement, ExceptionSink* xsink);
    DLLEXPORT void unassignStatement(AbstractStatement* statement, ExceptionSink* xsink);
    DLLEXPORT void getStatements(AbstractStatementList_t &statList, ExceptionSink* xsink);
    DLLEXPORT QoreListNode* getStatementIds(ExceptionSink* xsink);
    DLLEXPORT AbstractStatement* resolveStatementId(unsigned long statementId, ExceptionSink* xsink) const;
    DLLEXPORT void getThreadIds(TidList_t &tidList, ExceptionSink* xsink);
    DLLEXPORT void setThreadIds(TidList_t tidList, ExceptionSink* xsink);
    DLLEXPORT void addThreadId(int tid, ExceptionSink* xsink);
    DLLEXPORT void removeThreadId(int tid, ExceptionSink* xsink);
    DLLEXPORT bool isThreadId(int tid, ExceptionSink* xsink);
    DLLEXPORT void clearThreadIds(ExceptionSink* xsink);
 
 
    DLLEXPORT unsigned getBreakpointId() const;
 
 
    DLLEXPORT static QoreBreakpoint* resolveBreakpointId(unsigned breakpointId);
 
    DLLEXPORT void setQoreObject(QoreObject* n_qo);
 
    DLLEXPORT QoreObject* getQoreObject();
};
 
 
class QoreExternalProgramContextHelper {
public:
    DLLEXPORT QoreExternalProgramContextHelper(ExceptionSink* xsink, QoreProgram* pgm);
 
    DLLEXPORT ~QoreExternalProgramContextHelper();
 
private:
    class ProgramThreadCountContextHelper* priv;
};
 
 
class QoreExternalProgramCallContextHelper {
public:
    DLLEXPORT QoreExternalProgramCallContextHelper(QoreProgram* pgm);
 
    DLLEXPORT ~QoreExternalProgramCallContextHelper();
 
private:
    class QoreExternalProgramCallContextHelperPriv* priv;
};
 
#endif  // _QORE_QOREPROGRAM_H