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 { InputURL, InputSCRIPT };
110
111 typedef QMap<QString, QJSValue> FieldMap;
112
113 /**
114 * Create a new script representation, passing either a file or the script
115 * content @p urlOrScript to it.
116 * In case of a file, loading of the script will happen lazily.
117 */
118 explicit KateScript(const QString &urlOrScript, enum InputType inputType = InputURL);
119 virtual ~KateScript();
120
121 /** The script's URL */
122 const QString &url()
123 {
124 return m_url;
125 }
126
127 /**
128 * Load the script. If loading is successful, returns true. Otherwise, returns
129 * returns false and an error message will be set (see errorMessage()).
130 * Note that you don't have to call this -- it is called as necessary by the
131 * functions that require it.
132 * Subsequent calls to load will return the value it returned the first time.
133 */
134 bool load();
135
136 /**
137 * set view for this script for the execution
138 * will trigger load!
139 */
140 bool setView(KTextEditor::ViewPrivate *view);
141
142 /**
143 * Get a QJSValue for a global item in the script given its name, or an
144 * invalid QJSValue if no such global item exists.
145 */
146 QJSValue global(const QString &name);
147
148 /**
149 * Return a function in the script of the given name, or an invalid QJSValue
150 * if no such function exists.
151 */
152 QJSValue function(const QString &name);
153
154 /** Return a context-specific error message */
155 const QString &errorMessage()
156 {
157 return m_errorMessage;
158 }
159
160 /** Returns the backtrace when a script has errored out */
161 static QString backtrace(const QJSValue &error, const QString &header = QString());
162
163 /** Execute a piece of code **/
164 QJSValue evaluate(const QString &program, const FieldMap &env = FieldMap());
165
166 /** Displays the backtrace when a script has errored out */
167 void displayBacktrace(const QJSValue &error, const QString &header = QString());
168
169 /** Clears any uncaught exceptions in the script engine. */
170 void clearExceptions();
171
172 /** set the general header after construction of the script */
173 void setGeneralHeader(const KateScriptHeader &generalHeader);
174 /** Return the general header */
175 KateScriptHeader &generalHeader();
176
177protected:
178 /** Checks for exception and gives feedback on the console. */
179 bool hasException(const QJSValue &object, const QString &file);
180
181private:
182 /** Whether or not there has been a call to load */
183 bool m_loaded = false;
184
185 /** Whether or not the script loaded successfully into memory */
186 bool m_loadSuccessful = false;
187
188 /** The script's URL */
189 QString m_url;
190
191 /** An error message set when an error occurs */
192 QString m_errorMessage;
193
194protected:
195 /** The Qt interpreter for this script */
196 QJSEngine *m_engine = nullptr;
197
198private:
199 /** general header data */
200 KateScriptHeader m_generalHeader;
201
202 /** wrapper objects */
203 KateScriptEditor *m_editor = nullptr;
204 KateScriptDocument *m_document = nullptr;
205 KateScriptView *m_view = nullptr;
206
207private:
208 /** if input is script or url**/
209 enum InputType m_inputType;
210 QString m_script;
211};
212
213// END
214
215#endif
216

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