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 * -# Then, all files compiled into the library through resources are loaded.
81 * The internal resource path is ":/org.kde.syntax-highlighting/syntax".
82 * This path should never be touched by other applications.
83 *
84 * -# Then, all custom files compiled into resources are loaded.
85 * The resource path is ":/org.kde.syntax-highlighting/syntax-addons".
86 * This path can be used by other libraries/applications to bundle specialized definitions.
87 * Per default this path isn't used by the framework itself.
88 *
89 * -# Finally, the search path can be extended by calling addCustomSearchPath().
90 * A custom search path can either be a path on disk or again a path to
91 * a Qt resource.
92 *
93 * Similarly, loading Theme files works as follows:
94 *
95 * -# First, all Theme files are loaded that are located in
96 * QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("org.kde.syntax-highlighting/themes"), QStandardPaths::LocateDirectory);
97 * Under Unix, this uses $XDG_DATA_HOME and $XDG_DATA_DIRS, which could
98 * map to $HOME/.local5/share/org.kde.syntax-highlighting/themes and
99 * /usr/share/org.kde.syntax-highlighting/themes.
100 *
101 * -# Then, all files compiled into the library through resources are loaded.
102 * The internal resource path is ":/org.kde.syntax-highlighting/themes".
103 * This path should never be touched by other applications.
104 *
105 * -# Then, all custom files compiled into resources are loaded.
106 * The resource path is ":/org.kde.syntax-highlighting/themes-addons".
107 * This path can be used by other libraries/applications to bundle specialized themes.
108 * Per default this path isn't used by the framework itself.
109 *
110 * -# Finally, all Theme%s located in the paths added addCustomSearchPath()
111 * are loaded.
112 *
113 * @note Whenever a Definition or a Theme exists twice, the variant with
114 * higher version is used.
115 *
116 * @note The QStandardPaths lookup can be disabled by compiling the framework with the -DNO_STANDARD_PATHS define.
117 *
118 * @see Definition, Theme, AbstractHighlighter
119 * @since 5.28
120 */
121class KSYNTAXHIGHLIGHTING_EXPORT Repository : public QObject
122{
123 Q_OBJECT
124 Q_PROPERTY(QList<KSyntaxHighlighting::Definition> definitions READ definitions NOTIFY reloaded)
125 Q_PROPERTY(QList<KSyntaxHighlighting::Theme> themes READ themes NOTIFY reloaded)
126
127public:
128 /**
129 * Create a new syntax definition repository.
130 * This will read the meta data information of all available syntax
131 * definition, which is a moderately expensive operation, it's therefore
132 * recommended to keep a single instance of Repository around as long
133 * as you need highlighting in your application.
134 */
135 Repository();
136 ~Repository();
137
138 /**
139 * Returns the Definition named @p defName.
140 *
141 * If no Definition is found, Definition::isValid() of the returned instance
142 * returns false.
143 *
144 * @note The search is @e Qt::CaseInsensitive using untranslated names or
145 * alternative names. For instance, the cpp.xml definition file sets
146 * its name to @e C++ with an alternative name of @e CPP. Therefore, the
147 * strings "C++", "c++", "CPP" and "cpp" will all return a valid
148 * Definition file.
149 */
150 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForName(const QString &defName) const;
151
152 /**
153 * Returns the best matching Definition for the file named @p fileName.
154 * The match is performed based on the \e extensions and @e mimetype of
155 * the definition files. If multiple matches are found, the one with the
156 * highest priority is returned.
157 *
158 * If no match is found, Definition::isValid() of the returned instance
159 * returns false.
160 */
161 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForFileName(const QString &fileName) const;
162
163 /**
164 * Returns all Definition%s for the file named @p fileName sorted by priority.
165 * The match is performed based on the \e extensions and @e mimetype of
166 * the definition files.
167 *
168 * @since 5.56
169 */
170 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForFileName(const QString &fileName) const;
171
172 /**
173 * Returns the best matching Definition to the type named @p mimeType
174 *
175 * If no match is found, Definition::isValid() of the returned instance
176 * returns false.
177 *
178 * @since 5.50
179 */
180 Q_INVOKABLE KSyntaxHighlighting::Definition definitionForMimeType(const QString &mimeType) const;
181
182 /**
183 * Returns all Definition%s to the type named @p mimeType sorted by priority
184 *
185 * @since 5.56
186 */
187 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitionsForMimeType(const QString &mimeType) const;
188
189 /**
190 * Returns all available Definition%s.
191 * Definition%ss are ordered by translated section and translated names,
192 * for consistent displaying.
193 */
194 Q_INVOKABLE QList<KSyntaxHighlighting::Definition> definitions() const;
195
196 /**
197 * Returns all available color themes.
198 * The returned list should never be empty.
199 */
200 Q_INVOKABLE QList<KSyntaxHighlighting::Theme> themes() const;
201
202 /**
203 * Returns the theme called @p themeName.
204 * If the requested theme cannot be found, the retunred Theme is invalid,
205 * see Theme::isValid().
206 */
207 Q_INVOKABLE KSyntaxHighlighting::Theme theme(const QString &themeName) const;
208
209 /**
210 * Built-in default theme types.
211 * @see defaultTheme()
212 */
213 enum DefaultTheme {
214 //! Theme with a light background color.
215 LightTheme,
216 //! Theme with a dark background color.
217 DarkTheme
218 };
219 Q_ENUM(DefaultTheme)
220
221 /**
222 * Returns a default theme instance of the given type.
223 * The returned Theme is guaranteed to be a valid theme.
224 * @since 5.79
225 */
226 Q_INVOKABLE KSyntaxHighlighting::Theme defaultTheme(DefaultTheme t = LightTheme) const;
227
228 /**
229 * Returns the best matching theme for the given palette
230 * @since 5.79
231 **/
232 Theme themeForPalette(const QPalette &palette) const;
233
234 /**
235 * Reloads the repository.
236 * This is a moderately expensive operations and should thus only be
237 * triggered when the installed syntax definition files changed.
238 */
239 void reload();
240
241 /**
242 * Add a custom search path to the repository.
243 * This path will be searched in addition to the usual locations for syntax
244 * and theme definition files. Both locations on disk as well as Qt
245 * resource paths are supported.
246 *
247 * @note Internally, the two sub-folders @p path/syntax as well as
248 * @p path/themes are searched for additional Definition%s and
249 * Theme%s. Do not append @e syntax or @e themes to @p path
250 * yourself.
251 *
252 * @note Calling this triggers a reload() of the repository.
253 *
254 * @since 5.39
255 */
256 void addCustomSearchPath(const QString &path);
257
258 /**
259 * Returns the list of custom search paths added to the repository.
260 * By default, this list is empty.
261 *
262 * @see addCustomSearchPath()
263 * @since 5.39
264 */
265 QList<QString> customSearchPaths() const;
266
267Q_SIGNALS:
268 /**
269 * This signal is emitted before the reload is started.
270 * @since 6.0
271 */
272 void aboutToReload();
273
274 /**
275 * This signal is emitted when the reload is finished.
276 * @since 6.0
277 */
278 void reloaded();
279
280private:
281 Q_DISABLE_COPY(Repository)
282 friend class RepositoryPrivate;
283 std::unique_ptr<RepositoryPrivate> d;
284};
285
286}
287
288#endif // KSYNTAXHIGHLIGHTING_REPOSITORY_H
289

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