KTextEditor

katescript.h
1 /*
2  SPDX-FileCopyrightText: 2008 Paul Giannaros <[email protected]>
3  SPDX-FileCopyrightText: 2009-2018 Dominik Haumann <[email protected]>
4  SPDX-FileCopyrightText: 2010 Joseph Wenninger <[email protected]>
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 
16 class QJSEngine;
17 
18 namespace KTextEditor
19 {
20 class ViewPrivate;
21 }
22 
23 class KateScriptEditor;
24 class KateScriptDocument;
25 class KateScriptView;
26 
27 namespace Kate
28 {
29 enum 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 
41 class KateScriptHeader
42 {
43 public:
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 
92 private:
93  QString m_license; ///< the script's license, e.g. LGPL
94  QString m_author; ///< the script author, e.g. "John Smith <[email protected]>"
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 {
108 public:
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  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 
177 protected:
178  /** Checks for exception and gives feedback on the console. */
179  bool hasException(const QJSValue &object, const QString &file);
180 
181 private:
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 
194 protected:
195  /** The Qt interpreter for this script */
196  QJSEngine *m_engine = nullptr;
197 
198 private:
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 
207 private:
208  /** if input is script or url**/
209  enum InputType m_inputType;
210  QString m_script;
211 };
212 
213 // END
214 
215 #endif
KateScript objects represent a script that can be executed and inspected.
Definition: katescript.h:106
This class wraps the global editor instance KateGlobal, exposing some helper methods such as the clip...
qint64 revision() const override
Current revision.
Thinish wrapping around KTextEditor::DocumentPrivate, exposing the methods we want exposed and adding...
const QString & url()
The script&#39;s URL.
Definition: katescript.h:122
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:20
const QString & errorMessage()
Return a context-specific error message.
Definition: katescript.h:155
Thinish wrapping around KTextEditor::ViewPrivate, exposing the methods we want exposed and adding som...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Jun 17 2021 22:57:22 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.