1/*
2 SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>
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 * Built-in default theme types.
219 * \sa defaultTheme()
220 *
221 * \value LightTheme
222 * \value DarkTheme
223 */
224 enum DefaultTheme {
225 LightTheme,
226 DarkTheme
227 };
228 Q_ENUM(DefaultTheme)
229
230 /*!
231 * Returns a default theme instance of the given type.
232 * The returned Theme is guaranteed to be a valid theme.
233 * \since 5.79
234 */
235 Q_INVOKABLE KSyntaxHighlighting::Theme defaultTheme(KSyntaxHighlighting::Repository::DefaultTheme t = KSyntaxHighlighting::Repository::LightTheme) const;
236
237 /*!
238 * Returns the best matching theme for the given palette
239 * \since 5.79
240 **/
241 Theme themeForPalette(const QPalette &palette) const;
242
243 /*!
244 * Reloads the repository.
245 * This is a moderately expensive operations and should thus only be
246 * triggered when the installed syntax definition files changed.
247 */
248 void reload();
249
250 /*!
251 * Add a custom search path to the repository.
252 * This path will be searched in addition to the usual locations for syntax
253 * and theme definition files. Both locations on disk as well as Qt
254 * resource paths are supported.
255 *
256 * \note Internally, the two sub-folders \a path/syntax as well as
257 * \a path/themes are searched for additional Definition%s and
258 * Theme%s. Do not append syntax or themes to \a path
259 * yourself.
260 *
261 * \note Calling this triggers a reload() of the repository.
262 *
263 * \since 5.39
264 */
265 void addCustomSearchPath(const QString &path);
266
267 /*!
268 * Returns the list of custom search paths added to the repository.
269 * By default, this list is empty.
270 *
271 * \sa addCustomSearchPath()
272 * \since 5.39
273 */
274 QList<QString> customSearchPaths() const;
275
276Q_SIGNALS:
277 /*!
278 * This signal is emitted before the reload is started.
279 * \since 6.0
280 */
281 void aboutToReload();
282
283 /*!
284 * This signal is emitted when the reload is finished.
285 * \since 6.0
286 */
287 void reloaded();
288
289private:
290 Q_DISABLE_COPY(Repository)
291 friend class RepositoryPrivate;
292 std::unique_ptr<RepositoryPrivate> d;
293};
294
295}
296
297#endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H
298

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