KSyntaxHighlighting

definition.h
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 <QPair>
14 #include <QVector>
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 CommentPosition {
37  //! The comment marker is inserted at the beginning of a line at column 0
38  StartOfLine = 0,
39  //! The comment marker is inserted after leading whitespaces right befire
40  //! the first non-whitespace character.
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  QVector<QString> mimeTypes() const;
189 
190  /**
191  * File extensions associated with this syntax definition.
192  * The returned list contains wildcards.
193  */
194  QVector<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  QVector<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  QVector<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 singleLineCommentMarker() 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 singleLineCommentPosition() 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> multiLineCommentMarker() 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  QVector<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
@ StartOfLine
The comment marker is inserted at the beginning of a line at column 0.
CommentPosition
Defines the insert position when commenting code.
Definition: definition.h:36
@ AfterWhitespace
The comment marker is inserted after leading whitespaces right befire the first non-whitespace charac...
unsigned int version()
Represents a syntax definition.
Definition: definition.h:86
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Mar 26 2023 04:09:17 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.