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