1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <[email protected]>
3
4 SPDX-License-Identifier: MIT
5*/
6
7#ifndef KSYNTAXHIGHLIGHTING_REPOSITORY_H
8#define KSYNTAXHIGHLIGHTING_REPOSITORY_H
9
10#include "ksyntaxhighlighting_export.h"
11
12#include <QList>
13#include <QObject>
14#include <QtGlobal>
15
16#include <memory>
17
18QT_BEGIN_NAMESPACE
19class QString;
20class QPalette;
21QT_END_NAMESPACE
22
23/*!
24 * \namespace KSyntaxHighlighting
25 *
26 * \brief Syntax highlighting engine for Kate syntax definitions.
27 *
28 * In order to access the syntax highlighting Definition files, use the
29 * class Repository.
30 */
31namespace KSyntaxHighlighting
32{
33class Definition;
34class RepositoryPrivate;
35class Theme;
36
37/*!
38 * \class KSyntaxHighlighting::Repository
39 * \inheaderfile KSyntaxHighlighting/Repository
40 * \inmodule KSyntaxHighlighting
41 *
42 * \brief Syntax highlighting repository.
43 *
44 * The Repository gives access to all syntax Definitions available on the
45 * system, typically described in *.xml files. The Definition files are read
46 * from the resource that is compiled into the executable, and from the file
47 * system. If a Definition exists in the resource and on the file system,
48 * then the one from the file system is chosen.
49 *
50 * Typically, only one instance of the Repository is needed. This single
51 * instance can be thought of as a singleton you keep alive throughout the
52 * lifetime of your application. Then, either call definitionForName() with the
53 * given language name (e.g. "QML" or "Java"), or definitionForFileName() to
54 * obtain a Definition based on the filename/mimetype of the file. The
55 * function definitions() returns a list of all available syntax Definition%s.
56 *
57 * In addition to Definitions, the Repository also provides a list of Themes.
58 * A Theme is defined by a set of default text style colors as well as editor
59 * colors. These colors together provide all required colros for drawing all
60 * primitives of a text editor. All available Theme%s can be queried through
61 * themes(), and a Theme with a specific name is obtained through theme().
62 * Additionally, defaultTheme() provides a way to obtain a default theme for
63 * either a light or a black color theme.
64 *
65 * All highlighting Definition and Theme files are compiled into the shared
66 * KSyntaxHighlighting library by using the Qt resource system. Loading
67 * additional files from disk is supported as well.
68 *
69 * Loading syntax Definition files works as follows:
70 * \list
71 * \li First, all syntax highlighting files are loaded that are located in
72 * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/syntax"), QStandardPaths::LocateDirectory);
73 * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could
74 * map to $HOME/.local5/share/org.kde.syntax-highlighting/syntax and
75 * /usr/share/org.kde.syntax-highlighting/syntax.
76 *
77 * \li Then, all files compiled into the library through resources are loaded.
78 * The internal resource path is ":/org.kde.syntax-highlighting/syntax".
79 * This path should never be touched by other applications.
80 *
81 * \li Then, all custom files compiled into resources are loaded.
82 * The resource path is ":/org.kde.syntax-highlighting/syntax-addons".
83 * This path can be used by other libraries/applications to bundle specialized definitions.
84 * Per default this path isn't used by the framework itself.
85 *
86 * \li Finally, the search path can be extended by calling addCustomSearchPath().
87 * A custom search path can either be a path on disk or again a path to
88 * a Qt resource.
89 * \endlist
90 *
91 * Similarly, loading Theme files works as follows:
92 * \list
93 * \li First, all Theme files are loaded that are located in
94 * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory);
95 * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could
96 * map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and
97 * /usr/share/org.kde.syntax-highlighting/themes.
98 *
99 * \li Then, all files compiled into the library through resources are loaded.
100 * The internal resource path is ":/org.kde.syntax-highlighting/themes".
101 * This path should never be touched by other applications.
102 *
103 * \li Then, all custom files compiled into resources are loaded.
104 * The resource path is ":/org.kde.syntax-highlighting/themes-addons".
105 * This path can be used by other libraries/applications to bundle specialized themes.
106 * Per default this path isn't used by the framework itself.
107 *
108 * \li Finally, all Theme%s located in the paths added addCustomSearchPath()
109 * are loaded.
110 * \endlist
111 *
112 * \note Whenever a Definition or a Theme exists twice, the variant with
113 * higher version is used.
114 *
115 * \note The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define.
116 *
117 * \sa Definition, Theme, AbstractHighlighter
118 * \since 5.28
119 */
120class KSYNTAXHIGHLIGHTING_EXPORT Repository : public QObject
121{
122 Q_OBJECT
123
124 /*!
125 * \property KSyntaxHighlighting::Repository::definitions
126 */
127 Q_PROPERTY(QList<KSyntaxHighlighting::Definition> definitions READ definitions NOTIFY reloaded)
128
129 /*!
130 * \property KSyntaxHighlighting::Repository::themes
131 */
132 Q_PROPERTY(QList<KSyntaxHighlighting::Theme> themes READ themes NOTIFY reloaded)
133
134public:
135 /*!
136 * Create a new syntax definition repository.
137 * This will read the meta data information of all available syntax
138 * definition, which is a moderately expensive operation, it's therefore
139 * recommended to keep a single instance of Repository around as long
140 * as you need highlighting in your application.
141 */
142 Repository();
143
144 ~Repository();
145
146 /*!
147 * Returns the Definition named \a defName.
148 *
149 * If no Definition is found, Definition::isValid() of the returned instance
150 * returns false.
151 *
152 * \note The search is Qt::CaseInsensitive using untranslated names or
153 * alternative names. For instance, the cpp.xml definition file sets
154 * its name to C++ with an alternative name of CPP. Therefore, the
155 * strings "C++", "c++", "CPP" and "cpp" will all return a valid
156 * Definition file.
157 */
158 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForName(const QString &defName) const;
159
160 /*!
161 * Returns the best matching Definition for the file named \a fileName.
162 * The match is performed based on the \e extensions and mimetype of
163 * the definition files. If multiple matches are found, the one with the
164 * highest priority is returned.
165 *
166 * If no match is found, Definition::isValid() of the returned instance
167 * returns false.
168 */
169 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForFileName(const QString &fileName) const;
170
171 /*!
172 * Returns all Definition%s for the file named \a fileName sorted by priority.
173 * The match is performed based on the \e extensions and mimetype of
174 * the definition files.
175 *
176 * \since 5.56
177 */
178 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForFileName(const QString &fileName) const;
179
180 /*!
181 * Returns the best matching Definition to the type named \a mimeType
182 *
183 * If no match is found, Definition::isValid() of the returned instance
184 * returns false.
185 *
186 * \since 5.50
187 */
188 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForMimeType(const QString &mimeType) const;
189
190 /*!
191 * Returns all Definition%s to the type named \a mimeType sorted by priority
192 *
193 * \since 5.56
194 */
195 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForMimeType(const QString &mimeType) const;
196
197 /*!
198 * Returns all available Definition%s.
199 * Definition%ss are ordered by translated section and translated names,
200 * for consistent displaying.
201 */
202 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitions() const;
203
204 /*!
205 * Returns all available color themes.
206 * The returned list should never be empty.
207 */
208 Q_INVOKABLE QList<KSyntaxHighlighting::Theme> themes() const;
209
210 /*!
211 * Returns the theme called \a themeName.
212 * If the requested theme cannot be found, the retunred Theme is invalid,
213 * see Theme::isValid().
214 */
215 Q_INVOKABLE KSyntaxHighlighting::Theme theme(const QString &themeName) const;
216
217 /*!
218 * \enum ResolveState
219 *
220 * Built-in default theme types.
221 * \sa defaultTheme()
222 *
223 * \value LightTheme
224 * \value DarkTheme
225 */
226 enum DefaultTheme {
227 LightTheme,
228 DarkTheme
229 };
230 Q_ENUM(DefaultTheme)
231
232 /*!
233 * Returns a default theme instance of the given type.
234 * The returned Theme is guaranteed to be a valid theme.
235 * \since 5.79
236 */
237 Q_INVOKABLE KSyntaxHighlighting::Theme defaultTheme(DefaultTheme t = LightTheme) const;
238
239 /*!
240 * Returns the best matching theme for the given palette
241 * \since 5.79
242 **/
243 Theme themeForPalette(const QPalette &palette) const;
244
245 /*!
246 * Reloads the repository.
247 * This is a moderately expensive operations and should thus only be
248 * triggered when the installed syntax definition files changed.
249 */
250 void reload();
251
252 /*!
253 * Add a custom search path to the repository.
254 * This path will be searched in addition to the usual locations for syntax
255 * and theme definition files. Both locations on disk as well as Qt
256 * resource paths are supported.
257 *
258 * \note Internally, the two sub-folders \a path/syntax as well as
259 * \a path/themes are searched for additional Definition%s and
260 * Theme%s. Do not append syntax or themes to \a path
261 * yourself.
262 *
263 * \note Calling this triggers a reload() of the repository.
264 *
265 * \since 5.39
266 */
267 void addCustomSearchPath(const QString &path);
268
269 /*!
270 * Returns the list of custom search paths added to the repository.
271 * By default, this list is empty.
272 *
273 * \sa addCustomSearchPath()
274 * \since 5.39
275 */
276 QList<QString> customSearchPaths() const;
277
278Q_SIGNALS:
279 /*!
280 * This signal is emitted before the reload is started.
281 * \since 6.0
282 */
283 void aboutToReload();
284
285 /*!
286 * This signal is emitted when the reload is finished.
287 * \since 6.0
288 */
289 void reloaded();
290
291private:
292 Q_DISABLE_COPY(Repository)
293 friend class RepositoryPrivate;
294 std::unique_ptr<RepositoryPrivate> d;
295};
296
297}
298
299#endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H
300

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