1 | /* |
2 | SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org> |
3 | SPDX-FileCopyrightText: 2020 Jonathan Poelen <jonathan.poelen@gmail.com> |
4 | |
5 | SPDX-License-Identifier: MIT |
6 | */ |
7 | |
8 | #ifndef KSYNTAXHIGHLIGHTING_DEFINITION_H |
9 | #define KSYNTAXHIGHLIGHTING_DEFINITION_H |
10 | |
11 | #include "ksyntaxhighlighting_export.h" |
12 | |
13 | #include <QList> |
14 | #include <QPair> |
15 | #include <QString> |
16 | #include <memory> |
17 | #include <qobjectdefs.h> |
18 | |
19 | namespace KSyntaxHighlighting |
20 | { |
21 | class Context; |
22 | class Format; |
23 | class KeywordList; |
24 | |
25 | class DefinitionData; |
26 | |
27 | /*! |
28 | * Defines the insert position when commenting code. |
29 | * |
30 | * \since 5.50 |
31 | * \sa Definition::singleLineCommentPosition() |
32 | * |
33 | * \value StartOfLine |
34 | * \value AfterWhitespace |
35 | */ |
36 | enum class { |
37 | = 0, |
38 | |
39 | }; |
40 | |
41 | /*! |
42 | * \class KSyntaxHighlighting::Definition |
43 | * \inheaderfile KSyntaxHighlighting/Definition |
44 | * \inmodule KSyntaxHighlighting |
45 | * |
46 | * Represents a syntax definition. |
47 | * |
48 | * A Definition is the short term for a syntax highlighting definition. It |
49 | * typically is defined in terms of an XML syntax highlighting file, containing |
50 | * all information about a particular syntax highlighting. This includes the |
51 | * highlighting of keywords, information about code folding regions, and |
52 | * indentation preferences. |
53 | * |
54 | * Each Definition contains a non-translated unique name() and a section(). |
55 | * In addition, for putting this information e.g. into menus, the functions |
56 | * translatedName() and translatedSection() are provided. However, if isHidden() |
57 | * returns \c true, the Definition should not be visible in the UI. The location |
58 | * of the Definition can be obtained through filePath(), which either is the |
59 | * location on disk or a path to a compiled-in Qt resource. |
60 | * |
61 | * The supported files of a Definition are defined by the list of extensions(), |
62 | * and additionally by the list of mimeTypes(). Note, that extensions() returns |
63 | * wildcards that need to be matched against the filename of the file that |
64 | * requires highlighting. If multiple Definition%s match the file, then the one |
65 | * with higher priority() wins. |
66 | * |
67 | * Advanced text editors such as Kate require additional information from a |
68 | * Definition. For instance, foldingEnabled() defines whether a Definition has |
69 | * code folding regions that can be shown in a code folding pane. Or |
70 | * singleLineCommentMarker() and multiLineCommentMarker() provide comment |
71 | * markers that can be used for commenting/uncommenting code. Similarly, |
72 | * formats() returns a list of Format items defined by this Definition (which |
73 | * equal the itemDatas of a highlighting definition file). includedDefinitions() |
74 | * returns a list of all included Definition%s referenced by this Definition via |
75 | * the rule IncludeRules, which is useful for displaying all Format items for |
76 | * color configuration in the user interface. |
77 | * |
78 | * \sa Repository |
79 | * \since 5.28 |
80 | */ |
81 | class KSYNTAXHIGHLIGHTING_EXPORT Definition |
82 | { |
83 | Q_GADGET |
84 | |
85 | /*! |
86 | * \property KSyntaxHighlighting::Definition::name |
87 | */ |
88 | Q_PROPERTY(QString name READ name) |
89 | |
90 | /*! |
91 | * \property KSyntaxHighlighting::Definition::translatedName |
92 | */ |
93 | Q_PROPERTY(QString translatedName READ translatedName) |
94 | |
95 | /*! |
96 | * \property KSyntaxHighlighting::Definition::section |
97 | */ |
98 | Q_PROPERTY(QString section READ section) |
99 | |
100 | /*! |
101 | * \property KSyntaxHighlighting::Definition::translatedSection |
102 | */ |
103 | Q_PROPERTY(QString translatedSection READ translatedSection) |
104 | |
105 | /*! |
106 | * \property KSyntaxHighlighting::Definition::author |
107 | */ |
108 | Q_PROPERTY(QString author READ author) |
109 | |
110 | /*! |
111 | * \property KSyntaxHighlighting::Definition::license |
112 | */ |
113 | Q_PROPERTY(QString license READ license) |
114 | public: |
115 | /*! |
116 | * Default constructor, creating an empty (invalid) Definition instance. |
117 | * isValid() for this instance returns \c false. |
118 | * |
119 | * Use the Repository instead to obtain valid instances. |
120 | */ |
121 | Definition(); |
122 | |
123 | /*! |
124 | * Move constructor. |
125 | * This definition takes the Definition data from \a other. |
126 | * |
127 | * \note \a other may only be assigned to or destroyed afterwards. |
128 | * \since 5.86 |
129 | */ |
130 | Definition(Definition &&other) noexcept; |
131 | |
132 | /*! |
133 | * Copy constructor. |
134 | * |
135 | * Both this definition as well as \a other share the Definition data. |
136 | */ |
137 | Definition(const Definition &other); |
138 | |
139 | ~Definition(); |
140 | |
141 | /*! |
142 | * Move assignment operator. |
143 | * |
144 | * This definition takes the Definition data from \a other. |
145 | * |
146 | * \note \a other may only be assigned to or destroyed afterwards. |
147 | * \since 5.86 |
148 | */ |
149 | Definition &operator=(Definition &&other) noexcept; |
150 | |
151 | /*! |
152 | * Copy assignment operator. |
153 | * |
154 | * Both this definition as well as \a rhs share the Definition data. |
155 | */ |
156 | Definition &operator=(const Definition &rhs); |
157 | |
158 | /*! |
159 | * Checks two definitions for equality. |
160 | */ |
161 | bool operator==(const Definition &other) const; |
162 | |
163 | /*! |
164 | * Checks two definitions for inequality. |
165 | */ |
166 | bool operator!=(const Definition &other) const; |
167 | |
168 | /*! |
169 | * Checks whether this object refers to a valid syntax definition. |
170 | */ |
171 | bool isValid() const; |
172 | |
173 | /*! |
174 | * Returns the full path to the definition XML file containing |
175 | * the syntax definition. Note that this can be a path to QRC content. |
176 | */ |
177 | QString filePath() const; |
178 | |
179 | /*! Name of the syntax. |
180 | * Used for internal references, prefer translatedName() for display. |
181 | */ |
182 | QString name() const; |
183 | |
184 | /*! |
185 | * Alternate names the syntax can be referred to by. |
186 | * |
187 | * \since 6.1 |
188 | */ |
189 | QStringList alternativeNames() const; |
190 | |
191 | /*! |
192 | * Translated name for display. |
193 | */ |
194 | QString translatedName() const; |
195 | |
196 | /*! |
197 | * The group this syntax definition belongs to. |
198 | * For display, consider translatedSection(). |
199 | */ |
200 | QString section() const; |
201 | |
202 | /*! |
203 | * Translated group name for display. |
204 | */ |
205 | QString translatedSection() const; |
206 | |
207 | /*! |
208 | * Mime types associated with this syntax definition. |
209 | */ |
210 | QList<QString> mimeTypes() const; |
211 | |
212 | /*! |
213 | * File extensions associated with this syntax definition. |
214 | * The returned list contains wildcards. |
215 | */ |
216 | QList<QString> extensions() const; |
217 | |
218 | /*! |
219 | * Returns the definition version. |
220 | */ |
221 | int version() const; |
222 | |
223 | /*! |
224 | * Returns the definition priority. |
225 | * A Definition with higher priority wins over Definitions with lower priorities. |
226 | */ |
227 | int priority() const; |
228 | |
229 | /*! |
230 | * Returns \c true if this is an internal definition that should not be |
231 | * displayed to the user. |
232 | */ |
233 | bool isHidden() const; |
234 | |
235 | /*! |
236 | * Generalized language style, used for indentation. |
237 | */ |
238 | QString style() const; |
239 | |
240 | /*! |
241 | * Indentation style to be used for this syntax. |
242 | */ |
243 | QString indenter() const; |
244 | |
245 | /*! |
246 | * Name and email of the author of this syntax definition. |
247 | */ |
248 | QString author() const; |
249 | |
250 | /*! |
251 | * License of this syntax definition. |
252 | */ |
253 | QString license() const; |
254 | |
255 | /*! |
256 | * Returns whether the character \a c is a word delimiter. |
257 | * A delimiter defines whether a characters is a word boundary. Internally, |
258 | * delimiters are used for matching keyword lists. As example, typically the |
259 | * dot '.' is a word delimiter. However, if you have a keyword in a keyword |
260 | * list that contains a dot, you have to add the dot to the |
261 | * weakDeliminator attribute of the general section in your |
262 | * highlighting definition. Similarly, sometimes additional delimiters are |
263 | * required, which can be specified in additionalDeliminator. |
264 | * |
265 | * Checking whether a character is a delimiter is useful for instance if |
266 | * text is selected with double click. Typically, the whole word should be |
267 | * selected in this case. Similarly to the example above, the dot '.' |
268 | * usually acts as word delimiter. However, using this function you can |
269 | * implement text selection in such a way that keyword lists are correctly |
270 | * selected. |
271 | * |
272 | * \note By default, the list of delimiters contains the following |
273 | * characters: \\t !%&()*+,-./:;<=>?[\\]^{|}~ |
274 | * |
275 | * \since 5.50 |
276 | * \sa isWordWrapDelimiter() |
277 | */ |
278 | bool isWordDelimiter(QChar c) const; |
279 | |
280 | /*! |
281 | * Returns whether it is safe to break a line at before the character \c. |
282 | * This is useful when wrapping a line e.g. by applying static word wrap. |
283 | * |
284 | * As example, consider the LaTeX code |
285 | * \code |
286 | * \command1\command2 |
287 | * \endcode |
288 | * Applying static word wrap could lead to the following code: |
289 | * \code |
290 | * \command1\ |
291 | * command2 |
292 | * \endcode |
293 | * command2 without a leading backslash is invalid in LaTeX. If '\\' is set |
294 | * as word wrap delimiter, isWordWrapDelimiter('\\') then returns true, |
295 | * meaning that it is safe to break the line before \c. The resulting code |
296 | * then would be |
297 | * \code |
298 | * \command1 |
299 | * \command2 |
300 | * \endcode |
301 | * |
302 | * \note By default, the word wrap delimiters are equal to the word |
303 | * delimiters in isWordDelimiter(). |
304 | * |
305 | * \since 5.50 |
306 | * \sa isWordDelimiter() |
307 | */ |
308 | bool isWordWrapDelimiter(QChar c) const; |
309 | |
310 | /*! |
311 | * Returns whether the highlighting supports code folding. |
312 | * Code folding is supported either if the highlighting defines code folding |
313 | * regions or if indentationBasedFoldingEnabled() returns \c true. |
314 | * \since 5.50 |
315 | * \sa indentationBasedFoldingEnabled() |
316 | */ |
317 | bool foldingEnabled() const; |
318 | |
319 | /*! |
320 | * Returns whether indentation-based folding is enabled. |
321 | * An example for indentation-based folding is Python. |
322 | * When indentation-based folding is enabled, make sure to also check |
323 | * foldingIgnoreList() for lines that should be treated as empty. |
324 | * |
325 | * \sa foldingIgnoreList(), State::indentationBasedFoldingEnabled() |
326 | */ |
327 | bool indentationBasedFoldingEnabled() const; |
328 | |
329 | /*! |
330 | * If indentationBasedFoldingEnabled() returns \c true, this function returns |
331 | * a list of regular expressions that represent empty lines. That is, all |
332 | * lines matching entirely one of the regular expressions should be treated |
333 | * as empty lines when calculating the indentation-based folding ranges. |
334 | * |
335 | * \note This list is only of relevance, if indentationBasedFoldingEnabled() |
336 | * returns \c true. |
337 | * |
338 | * \sa indentationBasedFoldingEnabled() |
339 | */ |
340 | QStringList foldingIgnoreList() const; |
341 | |
342 | /*! |
343 | * Returns the section names of keywords. |
344 | * \since 5.49 |
345 | * \sa keywordList() |
346 | */ |
347 | QStringList keywordLists() const; |
348 | |
349 | /*! |
350 | * Returns the list of keywords for the keyword list \a name. |
351 | * \since 5.49 |
352 | * \sa keywordLists(), setKeywordList() |
353 | */ |
354 | QStringList keywordList(const QString &name) const; |
355 | |
356 | /*! |
357 | * Set the contents of the keyword list \a name to \a content. |
358 | * Only existing keywordLists() can be changed. For non-existent keyword lists, |
359 | * false is returned. |
360 | * |
361 | * Whenever you change a keyword list, make sure to trigger a rehighlight of |
362 | * your documents. In case you are using QSyntaxHighlighter via SyntaxHighlighter, |
363 | * this can be done by calling SyntaxHighlighter::rehighlight(). |
364 | * |
365 | * \note In general, changing keyword lists via setKeywordList() is discouraged, |
366 | * since if a keyword list name in the syntax highlighting definition |
367 | * file changes, the call setKeywordList() may suddenly fail. |
368 | * |
369 | * \sa keywordList(), keywordLists() |
370 | * \since 5.62 |
371 | */ |
372 | bool setKeywordList(const QString &name, const QStringList &content); |
373 | |
374 | /*! |
375 | * Returns a list of all Format items used by this definition. |
376 | * The order of the Format items equals the order of the itemDatas in the xml file. |
377 | * \since 5.49 |
378 | */ |
379 | QList<Format> formats() const; |
380 | |
381 | /*! |
382 | * Returns a list of Definitions that are referenced with the IncludeRules rule. |
383 | * The returned list does not include this Definition. In case no other |
384 | * Definitions are referenced via IncludeRules, the returned list is empty. |
385 | * |
386 | * \since 5.49 |
387 | */ |
388 | QList<Definition> includedDefinitions() const; |
389 | |
390 | /*! |
391 | * Returns the marker that starts a single line comment. |
392 | * For instance, in C++ the single line comment marker is "//". |
393 | * \since 5.50 |
394 | * \sa singleLineCommentPosition(); |
395 | */ |
396 | QString () const; |
397 | |
398 | /*! |
399 | * Returns the insert position of the comment marker for sinle line |
400 | * comments. |
401 | * \since 5.50 |
402 | * \sa singleLineCommentMarker(); |
403 | */ |
404 | CommentPosition () const; |
405 | |
406 | /*! |
407 | * Returns the markers that start and end multiline comments. |
408 | * For instance, in XML this is defined as "<!--" and "-->". |
409 | * \since 5.50 |
410 | */ |
411 | QPair<QString, QString> () const; |
412 | |
413 | /*! |
414 | * Returns a list of character/string mapping that can be used for spell |
415 | * checking. This is useful for instance when spell checking LaTeX, where |
416 | * the string \"{A} represents the character Ä. |
417 | * \since 5.50 |
418 | */ |
419 | QList<QPair<QChar, QString>> characterEncodings() const; |
420 | |
421 | private: |
422 | friend class DefinitionData; |
423 | KSYNTAXHIGHLIGHTING_NO_EXPORT explicit Definition(const DefinitionData &defData); |
424 | std::shared_ptr<DefinitionData> d; |
425 | }; |
426 | |
427 | } |
428 | |
429 | QT_BEGIN_NAMESPACE |
430 | Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Definition, Q_RELOCATABLE_TYPE); |
431 | QT_END_NAMESPACE |
432 | |
433 | #endif |
434 | |