KTextEditor

katescript.h
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
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 */
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 */
107{
108public:
109 enum InputType { InputURL, InputSCRIPT };
110
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 */
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
Thinish wrapping around KTextEditor::DocumentPrivate, exposing the methods we want exposed and adding...
This class wraps the global editor instance KateGlobal, exposing some helper methods such as the clip...
Thinish wrapping around KTextEditor::ViewPrivate, exposing the methods we want exposed and adding som...
KateScript objects represent a script that can be executed and inspected.
Definition katescript.h:107
QJSValue global(const QString &name)
Get a QJSValue for a global item in the script given its name, or an invalid QJSValue if no such glob...
QJSEngine * m_engine
The Qt interpreter for this script.
Definition katescript.h:196
KateScriptHeader & generalHeader()
Return the general header.
void displayBacktrace(const QJSValue &error, const QString &header=QString())
Displays the backtrace when a script has errored out.
bool setView(KTextEditor::ViewPrivate *view)
set view for this script for the execution will trigger load!
void clearExceptions()
Clears any uncaught exceptions in the script engine.
const QString & url()
The script's URL.
Definition katescript.h:122
QJSValue evaluate(const QString &program, const FieldMap &env=FieldMap())
Execute a piece of code.
static QString backtrace(const QJSValue &error, const QString &header=QString())
Returns the backtrace when a script has errored out.
bool load()
Load the script.
void setGeneralHeader(const KateScriptHeader &generalHeader)
set the general header after construction of the script
const QString & errorMessage()
Return a context-specific error message.
Definition katescript.h:155
QJSValue function(const QString &name)
Return a function in the script of the given name, or an invalid QJSValue if no such function exists.
bool hasException(const QJSValue &object, const QString &file)
Checks for exception and gives feedback on the console.
KateScript(const QString &urlOrScript, enum InputType inputType=InputURL)
Create a new script representation, passing either a file or the script content urlOrScript to it.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:15:44 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.