1/*
2 SPDX-FileCopyrightText: 2008 Paul Giannaros <paul@giannaros.org>
3 SPDX-FileCopyrightText: 2009-2018 Dominik Haumann <dhaumann@kde.org>
4 SPDX-FileCopyrightText: 2010 Joseph Wenninger <jowenn@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KATE_SCRIPT_H
10#define KATE_SCRIPT_H
11
12#include <QJSValue>
13#include <QMap>
14#include <QString>
15
16class QJSEngine;
17
18namespace KTextEditor
19{
20class ViewPrivate;
21}
22
23class KateScriptEditor;
24class KateScriptDocument;
25class KateScriptView;
26
27namespace Kate
28{
29enum class ScriptType {
30 /** The script is an indenter */
31 Indentation,
32 /** The script contains command line commands */
33 CommandLine,
34 /** Don't know what kind of script this is */
35 Unknown
36};
37}
38
39// BEGIN KateScriptHeader
40
41class KateScriptHeader
42{
43public:
44 KateScriptHeader() = default;
45 virtual ~KateScriptHeader() = default;
46
47 inline void setLicense(const QString &license)
48 {
49 m_license = license;
50 }
51 inline const QString &license() const
52 {
53 return m_license;
54 }
55
56 inline void setAuthor(const QString &author)
57 {
58 m_author = author;
59 }
60 inline const QString &author() const
61 {
62 return m_author;
63 }
64
65 inline void setRevision(int revision)
66 {
67 m_revision = revision;
68 }
69 inline int revision() const
70 {
71 return m_revision;
72 }
73
74 inline void setKateVersion(const QString &kateVersion)
75 {
76 m_kateVersion = kateVersion;
77 }
78 inline const QString &kateVersion() const
79 {
80 return m_kateVersion;
81 }
82
83 inline void setScriptType(Kate::ScriptType scriptType)
84 {
85 m_scriptType = scriptType;
86 }
87 inline Kate::ScriptType scriptType() const
88 {
89 return m_scriptType;
90 }
91
92private:
93 QString m_license; ///< the script's license, e.g. LGPL
94 QString m_author; ///< the script author, e.g. "John Smith <john@example.com>"
95 int m_revision = 0; ///< script revision, a simple number, e.g. 1, 2, 3, ...
96 QString m_kateVersion; ///< required katepart version
97 Kate::ScriptType m_scriptType = Kate::ScriptType::Unknown; ///< the script type
98};
99// END
100
101// BEGIN KateScript
102
103/**
104 * KateScript objects represent a script that can be executed and inspected.
105 */
106class KateScript
107{
108public:
109 enum InputType {
110 InputURL,
111 InputSCRIPT
112 };
113
114 typedef QMap<QString, QJSValue> FieldMap;
115
116 /**
117 * Create a new script representation, passing either a file or the script
118 * content @p urlOrScript to it.
119 * In case of a file, loading of the script will happen lazily.
120 */
121 explicit KateScript(const QString &urlOrScript, enum InputType inputType = InputURL);
122 virtual ~KateScript();
123
124 /** The script's URL */
125 const QString &url()
126 {
127 return m_url;
128 }
129
130 /**
131 * Load the script. If loading is successful, returns true. Otherwise, returns
132 * returns false and an error message will be set (see errorMessage()).
133 * Note that you don't have to call this -- it is called as necessary by the
134 * functions that require it.
135 * Subsequent calls to load will return the value it returned the first time.
136 */
137 bool load();
138
139 /**
140 * set view for this script for the execution
141 * will trigger load!
142 */
143 bool setView(KTextEditor::ViewPrivate *view);
144
145 /**
146 * Get a QJSValue for a global item in the script given its name, or an
147 * invalid QJSValue if no such global item exists.
148 */
149 QJSValue global(const QString &name);
150
151 /**
152 * Return a function in the script of the given name, or an invalid QJSValue
153 * if no such function exists.
154 */
155 QJSValue function(const QString &name);
156
157 /** Return a context-specific error message */
158 const QString &errorMessage()
159 {
160 return m_errorMessage;
161 }
162
163 /** Returns the backtrace when a script has errored out */
164 static QString backtrace(const QJSValue &error, const QString &header = QString());
165
166 /** Execute a piece of code **/
167 QJSValue evaluate(const QString &program, const FieldMap &env = FieldMap());
168
169 /** Displays the backtrace when a script has errored out */
170 void displayBacktrace(const QJSValue &error, const QString &header = QString());
171
172 /** Clears any uncaught exceptions in the script engine. */
173 void clearExceptions();
174
175 /** set the general header after construction of the script */
176 void setGeneralHeader(const KateScriptHeader &generalHeader);
177 /** Return the general header */
178 KateScriptHeader &generalHeader();
179
180protected:
181 /** Checks for exception and gives feedback on the console. */
182 bool hasException(const QJSValue &object, const QString &file);
183
184private:
185 /** Whether or not there has been a call to load */
186 bool m_loaded = false;
187
188 /** Whether or not the script loaded successfully into memory */
189 bool m_loadSuccessful = false;
190
191 /** The script's URL */
192 QString m_url;
193
194 /** An error message set when an error occurs */
195 QString m_errorMessage;
196
197protected:
198 /** The Qt interpreter for this script */
199 QJSEngine *m_engine = nullptr;
200
201private:
202 /** general header data */
203 KateScriptHeader m_generalHeader;
204
205 /** wrapper objects */
206 KateScriptEditor *m_editor = nullptr;
207 KateScriptDocument *m_document = nullptr;
208 KateScriptView *m_view = nullptr;
209
210private:
211 /** if input is script or url**/
212 enum InputType m_inputType;
213 QString m_script;
214};
215
216// END
217
218#endif
219

source code of ktexteditor/src/script/katescript.h