1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <[email protected]>
3 SPDX-FileCopyrightText: 2020 Jonathan Poelen <[email protected]>
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 *
30 * \since 5.50
31 * \sa Definition::singleLineCommentPosition()
32 *
33 * \value StartOfLine
34 * \value AfterWhitespace
35 */
36enum class CommentPosition {
37 StartOfLine = 0,
38 AfterWhitespace
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 */
81class 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)
114public:
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 singleLineCommentMarker() 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 singleLineCommentPosition() 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> multiLineCommentMarker() 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
421private:
422 friend class DefinitionData;
423 KSYNTAXHIGHLIGHTING_NO_EXPORT explicit Definition(const DefinitionData &defData);
424 std::shared_ptr<DefinitionData> d;
425};
426
427}
428
429QT_BEGIN_NAMESPACE
430Q_DECLARE_TYPEINFO(KSyntaxHighlighting::Definition, Q_RELOCATABLE_TYPE);
431QT_END_NAMESPACE
432
433#endif
434

source code of syntax-highlighting/src/lib/definition.h