File indexing completed on 2024-03-24 04:00:26
0001 /* 0002 SPDX-FileCopyrightText: 2008 Paul Giannaros <paul@giannaros.org> 0003 SPDX-FileCopyrightText: 2009-2018 Dominik Haumann <dhaumann@kde.org> 0004 SPDX-FileCopyrightText: 2010 Joseph Wenninger <jowenn@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef KATE_SCRIPT_H 0010 #define KATE_SCRIPT_H 0011 0012 #include <QJSValue> 0013 #include <QMap> 0014 #include <QString> 0015 0016 class QJSEngine; 0017 0018 namespace KTextEditor 0019 { 0020 class ViewPrivate; 0021 } 0022 0023 class KateScriptEditor; 0024 class KateScriptDocument; 0025 class KateScriptView; 0026 0027 namespace Kate 0028 { 0029 enum class ScriptType { 0030 /** The script is an indenter */ 0031 Indentation, 0032 /** The script contains command line commands */ 0033 CommandLine, 0034 /** Don't know what kind of script this is */ 0035 Unknown 0036 }; 0037 } 0038 0039 // BEGIN KateScriptHeader 0040 0041 class KateScriptHeader 0042 { 0043 public: 0044 KateScriptHeader() = default; 0045 virtual ~KateScriptHeader() = default; 0046 0047 inline void setLicense(const QString &license) 0048 { 0049 m_license = license; 0050 } 0051 inline const QString &license() const 0052 { 0053 return m_license; 0054 } 0055 0056 inline void setAuthor(const QString &author) 0057 { 0058 m_author = author; 0059 } 0060 inline const QString &author() const 0061 { 0062 return m_author; 0063 } 0064 0065 inline void setRevision(int revision) 0066 { 0067 m_revision = revision; 0068 } 0069 inline int revision() const 0070 { 0071 return m_revision; 0072 } 0073 0074 inline void setKateVersion(const QString &kateVersion) 0075 { 0076 m_kateVersion = kateVersion; 0077 } 0078 inline const QString &kateVersion() const 0079 { 0080 return m_kateVersion; 0081 } 0082 0083 inline void setScriptType(Kate::ScriptType scriptType) 0084 { 0085 m_scriptType = scriptType; 0086 } 0087 inline Kate::ScriptType scriptType() const 0088 { 0089 return m_scriptType; 0090 } 0091 0092 private: 0093 QString m_license; ///< the script's license, e.g. LGPL 0094 QString m_author; ///< the script author, e.g. "John Smith <john@example.com>" 0095 int m_revision = 0; ///< script revision, a simple number, e.g. 1, 2, 3, ... 0096 QString m_kateVersion; ///< required katepart version 0097 Kate::ScriptType m_scriptType = Kate::ScriptType::Unknown; ///< the script type 0098 }; 0099 // END 0100 0101 // BEGIN KateScript 0102 0103 /** 0104 * KateScript objects represent a script that can be executed and inspected. 0105 */ 0106 class KateScript 0107 { 0108 public: 0109 enum InputType { InputURL, InputSCRIPT }; 0110 0111 typedef QMap<QString, QJSValue> FieldMap; 0112 0113 /** 0114 * Create a new script representation, passing either a file or the script 0115 * content @p urlOrScript to it. 0116 * In case of a file, loading of the script will happen lazily. 0117 */ 0118 explicit KateScript(const QString &urlOrScript, enum InputType inputType = InputURL); 0119 virtual ~KateScript(); 0120 0121 /** The script's URL */ 0122 const QString &url() 0123 { 0124 return m_url; 0125 } 0126 0127 /** 0128 * Load the script. If loading is successful, returns true. Otherwise, returns 0129 * returns false and an error message will be set (see errorMessage()). 0130 * Note that you don't have to call this -- it is called as necessary by the 0131 * functions that require it. 0132 * Subsequent calls to load will return the value it returned the first time. 0133 */ 0134 bool load(); 0135 0136 /** 0137 * set view for this script for the execution 0138 * will trigger load! 0139 */ 0140 bool setView(KTextEditor::ViewPrivate *view); 0141 0142 /** 0143 * Get a QJSValue for a global item in the script given its name, or an 0144 * invalid QJSValue if no such global item exists. 0145 */ 0146 QJSValue global(const QString &name); 0147 0148 /** 0149 * Return a function in the script of the given name, or an invalid QJSValue 0150 * if no such function exists. 0151 */ 0152 QJSValue function(const QString &name); 0153 0154 /** Return a context-specific error message */ 0155 const QString &errorMessage() 0156 { 0157 return m_errorMessage; 0158 } 0159 0160 /** Returns the backtrace when a script has errored out */ 0161 static QString backtrace(const QJSValue &error, const QString &header = QString()); 0162 0163 /** Execute a piece of code **/ 0164 QJSValue evaluate(const QString &program, const FieldMap &env = FieldMap()); 0165 0166 /** Displays the backtrace when a script has errored out */ 0167 void displayBacktrace(const QJSValue &error, const QString &header = QString()); 0168 0169 /** Clears any uncaught exceptions in the script engine. */ 0170 void clearExceptions(); 0171 0172 /** set the general header after construction of the script */ 0173 void setGeneralHeader(const KateScriptHeader &generalHeader); 0174 /** Return the general header */ 0175 KateScriptHeader &generalHeader(); 0176 0177 protected: 0178 /** Checks for exception and gives feedback on the console. */ 0179 bool hasException(const QJSValue &object, const QString &file); 0180 0181 private: 0182 /** Whether or not there has been a call to load */ 0183 bool m_loaded = false; 0184 0185 /** Whether or not the script loaded successfully into memory */ 0186 bool m_loadSuccessful = false; 0187 0188 /** The script's URL */ 0189 QString m_url; 0190 0191 /** An error message set when an error occurs */ 0192 QString m_errorMessage; 0193 0194 protected: 0195 /** The Qt interpreter for this script */ 0196 QJSEngine *m_engine = nullptr; 0197 0198 private: 0199 /** general header data */ 0200 KateScriptHeader m_generalHeader; 0201 0202 /** wrapper objects */ 0203 KateScriptEditor *m_editor = nullptr; 0204 KateScriptDocument *m_document = nullptr; 0205 KateScriptView *m_view = nullptr; 0206 0207 private: 0208 /** if input is script or url**/ 0209 enum InputType m_inputType; 0210 QString m_script; 0211 }; 0212 0213 // END 0214 0215 #endif