KSyntaxHighlighting

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

KDE's Doxygen guidelines are available online.