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

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