Skip to content

Commit ec54970

Browse files
RPG-18Dmitry Mukhitov
RPG-18
and
Dmitry Mukhitov
authored
Syntax highlighting (#46)
* append syntax-highlighting * formatters * fix: build MS VC * syntax highlighting in produce window Co-authored-by: Dmitry Mukhitov <damukhitov@mts.ru>
1 parent 70568d2 commit ec54970

File tree

107 files changed

+17055
-5
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

107 files changed

+17055
-5
lines changed

‎3rdparty/syntax-highlighting/CMakeLists.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
add_subdirectory(data)
2+
add_subdirectory(src)

‎3rdparty/syntax-highlighting/README.md

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
# Syntax Highlighting
2+
3+
Syntax highlighting engine for Kate syntax definitions
4+
5+
## Table of contents
6+
7+
1. [Introduction](#introduction)
8+
2. [Out of scope](#out-of-scope)
9+
3. [Syntax definition files](#syntax-definition-files)
10+
4. [Color theme files](#color-theme-files)
11+
5. [Build it](#build-it)
12+
6. [How to contribute](#how-to-contribute)
13+
* [Licensing](#licensing)
14+
* [Tips for contributing to syntax definition files](#tips-for-contributing-to-syntax-definition-files)
15+
* [Adding unit tests for a syntax definition](#adding-unit-tests-for-a-syntax-definition)
16+
7. [Report bug or help to fix them](#report-bug-or-help-to-fix-them)
17+
8. [Updating the syntax & themes pages of the kate-editor.org website](#updating-the-kate-editororgsyntax-website)
18+
19+
## Introduction
20+
21+
This is a stand-alone implementation of the Kate syntax highlighting engine.
22+
It's meant as a building block for text editors as well as for simple highlighted
23+
text rendering (e.g. as HTML), supporting both integration with a custom editor
24+
as well as a ready-to-use QSyntaxHighlighter sub-class.
25+
26+
Besides a C++ API, a [QML API](@ref qml_api) is also provided.
27+
28+
## Out of scope
29+
30+
To not turn this into yet another text editor, the following things are considered
31+
out of scope:
32+
33+
* code folding, beyond providing folding range information
34+
* auto completion
35+
* spell checking
36+
* user interface for configuration
37+
* management of text buffers or documents
38+
39+
If you need any of this, check out [KTextEditor](https://api.kde.org/frameworks/ktexteditor/html/).
40+
41+
## Syntax definition files
42+
43+
This library uses Kate syntax definition files for the actual highlighting,
44+
the file format is documented [here](https://docs.kde.org/?application=katepart&branch=trunk5&path=highlight.html).
45+
46+
More than 300 syntax definition files are included, that are located
47+
in **data/syntax/** and have the **.xml** extension. Additional ones are
48+
picked up from the file system if present, so you can easily extend this
49+
by application-specific syntax definitions for example.
50+
51+
To install or test a syntax definition file locally, place it in
52+
**org.kde.syntax-highlighting/syntax/**, which is located in your user directory.
53+
Usually it is:
54+
55+
<table>
56+
<tr>
57+
<td>For local user</td>
58+
<td>$HOME/.local/share/org.kde.syntax-highlighting/syntax/</td>
59+
</tr>
60+
<tr>
61+
<td>For Flatpak packages</td>
62+
<td>$HOME/.var/app/<em>package-name</em>/data/org.kde.syntax-highlighting/syntax/</td>
63+
</tr>
64+
<tr>
65+
<td>For Snap packages</a></td>
66+
<td>$HOME/snap/<em>package-name</em>/current/.local/share/org.kde.syntax-highlighting/syntax/</td>
67+
</tr>
68+
<tr>
69+
<td>On Windows®</td>
70+
<td>&#37;USERPROFILE&#37;&#92;AppData&#92;Local&#92;org.kde.syntax-highlighting&#92;syntax&#92;</td>
71+
</tr>
72+
<tr>
73+
<td>On macOS®</td>
74+
<td>$HOME/Library/Application Support/org.kde.syntax-highlighting/syntax/</td>
75+
</tr>
76+
</table>
77+
78+
For more details, see ["The Highlight Definition XML Format" (Working with Syntax Highlighting, KDE Documentation)](https://docs.kde.org/?application=katepart&branch=trunk5&path=highlight.html#katehighlight-xml-format).
79+
80+
Also, in **data/schema/** there is a script to validate the syntax definition XML
81+
files. Use the command `validatehl.sh mySyntax.xml`.
82+
83+
## Color theme files
84+
85+
This library includes the color themes, which are documented
86+
[here](https://docs.kde.org/?application=katepart&branch=trunk5&path=color-themes.html).
87+
88+
The color theme files use the JSON format and are located in **data/themes/**
89+
with the **.theme** extension.
90+
Additional ones are also picked up from the file system if present,
91+
in the **org.kde.syntax-highlighting/themes/** folder of your user directory,
92+
allowing you to easily add custom color theme files. This location is the same
93+
as shown in the table of the [previous section](#syntax-definition-files),
94+
replacing the **syntax** folder with **themes**.
95+
For more details, see ["The Color Themes JSON Format" (Working with Color Themes, KDE Documentation)](https://docs.kde.org/?application=katepart&branch=trunk5&path=color-themes.html#color-themes-json).
96+
97+
The [KTextEditor](https://api.kde.org/frameworks/ktexteditor/html/) library
98+
(used by Kate, Kile and KDevelop, for example) provides a
99+
[user interface](https://docs.kde.org/?application=katepart&branch=trunk5&path=color-themes.html#color-themes-gui)
100+
for editing and creating KSyntaxHighlighting color themes, including
101+
a tool for exporting and importing the JSON theme files.
102+
103+
Note that in KDE text editors, the KSyntaxHighlighting color themes are used
104+
[since KDE Frameworks 5.75](https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/),
105+
released on October 10, 2020. Previously, Kate's color schemes
106+
(KConfig based schema config) were used and are now deprecated.
107+
The tool **utils/schema-converter/** and the script **utils/kateschema_to_theme_converter.py**
108+
convert the old Kate schemas to KSyntaxHighlighting themes.
109+
110+
Also see ["Submit a KSyntaxHighlighting Color Theme" (Kate Editor Website)](https://kate-editor.org/post/2020/2020-09-18-submit-a-ksyntaxhighlighting-color-theme/).
111+
112+
## Build it
113+
114+
1. Create and change into a build directory. Usually, a folder called **build**
115+
is created inside the **syntax-highlighting** source directory.
116+
117+
```bash
118+
mkdir <build-directory>
119+
cd <build-directory>
120+
```
121+
122+
2. Run the configure process with *cmake* and compile:
123+
124+
```bash
125+
cmake <source-directory>
126+
make
127+
```
128+
129+
For example:
130+
131+
```bash
132+
git clone git@invent.kde.org:frameworks/syntax-highlighting.git
133+
mkdir ./syntax-highlighting/build
134+
cd ./syntax-highlighting/build
135+
cmake ../
136+
make
137+
```
138+
139+
For more details see ["Building Kate from Sources on Linux" (Kate Editor Website)](https://kate-editor.org/build-it/).
140+
141+
**NOTE:** If running *cmake* shows an error related to your version of KDE
142+
Frameworks, you edit the **CMakeLists.txt** file in the line
143+
`find_package(ECM 5.XX.X ...)`.
144+
145+
3. To run tests:
146+
147+
```bash
148+
make test
149+
```
150+
151+
The tests are located in the **autotests** directory.
152+
This command can be used to check changes to units test after modifying some
153+
syntax definition file. To add a unit test or update the references, see the
154+
section ["Adding unit tests for a syntax definition"](#adding-unit-tests-for-a-syntax-definition).
155+
156+
## How to contribute
157+
158+
KDE uses a GitLab instance at **invent.kde.org** for code review. The official
159+
repository of the KSyntaxHighlighting framework is [here](https://invent.kde.org/frameworks/syntax-highlighting).
160+
161+
All the necessary information to send contributions is [here](https://community.kde.org/Infrastructure/GitLab).
162+
163+
### Licensing
164+
165+
Contributions to KSyntaxHighlighting shall be licensed under [MIT](LICENSES/MIT.txt).
166+
167+
All files shall contain a proper "SPDX-License-Identifier: MIT" identifier inside a header like:
168+
169+
```cpp
170+
/*
171+
SPDX-FileCopyrightText: 2020 Christoph Cullmann <cullmann@kde.org>
172+
173+
SPDX-License-Identifier: MIT
174+
*/
175+
```
176+
177+
### Tips for contributing to syntax definition files
178+
179+
* If you are modifying an existing syntax definition XML file, you must increase
180+
the version number of the language.
181+
182+
* Do not use hard-coded colors, as they may not look good or be illegible in some color
183+
themes. Prefer to use the default color styles.
184+
185+
For more information, see:
186+
187+
* [Available Default Styles (Working with Syntax Highlighting, KDE Documentation)](https://docs.kde.org/?application=katepart&branch=trunk5&path=highlight.html#kate-highlight-default-styles)
188+
* [Kate Part (KF5): New Default Styles for better Color Schemes (Kate Editor Website)](https://kate-editor.org/2014/03/07/kate-part-kf5-new-default-styles-for-better-color-schemes/)
189+
190+
* Add test files, these are found in **autotests/input/**.
191+
If you are going to add a new syntax XML file, create a new test file; if you
192+
are going to modify a XML file, adds examples to existing test files.
193+
194+
Then, it is necessary to generate and update the files in **autotests/folding/**,
195+
**autotests/html/** and **autotests/reference/**, which must be included in the
196+
patches. Instructions are [below](#adding-unit-tests-for-a-syntax-definition).
197+
198+
### Adding unit tests for a syntax definition
199+
200+
1. Add an input file into the **autotests/input/** folder, lets call it
201+
**test.&lt;language-extension&gt;**.
202+
203+
2. If the file extension is not sufficient to trigger the right syntax definition, you can add an
204+
second file **testname.&lt;language-extension&gt;.syntax** that contains the syntax definition name
205+
to enforce the use of the right extension.
206+
207+
3. Do `make && make test`.
208+
209+
Note that after adding or modifying something in
210+
**&lt;source-directory&gt;/autotests/input/**, an error will be showed when
211+
running `make test`, because the references in the source directory do not
212+
match the ones now generated.
213+
214+
4. Inspect the outputs found in your binary directory **autotests/folding.out/**,
215+
**autotests/html.output/** and **autotests/output/**.
216+
217+
5. If OK, run in the binary folder `./autotests/update-reference-data.sh`
218+
to copy the results to the right location.
219+
That script updates the references in the source directory in
220+
**autotest/folding/**, **autotest/html/** and **autotest/reference/**.
221+
222+
6. Add the result references after the copying to the git.
223+
224+
## Report bug or help to fix them
225+
226+
KDE uses Bugzilla to management of bugs at **bugs.kde.org**. You can see the bugs
227+
reported of **frameworks-syntax-highlighting** [here](https://bugs.kde.org/describecomponents.cgi?product=frameworks-syntax-highlighting).
228+
229+
Also, you can report a bug [here](https://bugs.kde.org/enter_bug.cgi?product=frameworks-syntax-highlighting).
230+
231+
However, some users often report bugs related to syntax highlighting in
232+
[kate/syntax](https://bugs.kde.org/buglist.cgi?component=syntax&product=kate&resolution=---)
233+
and [kile/editor](https://bugs.kde.org/buglist.cgi?component=editor&product=kile&resolution=---).
234+
235+
## Updating the syntax & themes pages of the kate-editor.org website
236+
237+
To update the [kate-editor.org/syntax](https://kate-editor.org/syntax/) and
238+
[kate-editor.org/themes](https://kate-editor.org/themes/) websites
239+
including the update site & all linked examples/files,
240+
please run after successful **build** & **test** the following make target:
241+
242+
```bash
243+
make update_kate_editor_org
244+
```
245+
246+
This will clone the [kate-editor.org git](https://invent.kde.org/websites/kate-editor-org)
247+
from *invent.kde.org* into **kate-editor-org** inside the build directory and update the needed things.
248+
249+
You can afterwards step into **kate-editor-org** and commit & push the change after review.
250+
251+
The [kate-editor.org](https://kate-editor.org) webserver will update itself periodically from the repository on *invent.kde.org*.

‎3rdparty/syntax-highlighting/data/CMakeLists.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
add_library(SyntaxHighlightingData OBJECT)
2+
target_sources(SyntaxHighlightingData PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/syntax_data.qrc)
3+
target_sources(SyntaxHighlightingData PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/themes/theme_data.qrc)
4+
set_property(TARGET SyntaxHighlightingData PROPERTY POSITION_INDEPENDENT_CODE 1)
5+
target_link_libraries(SyntaxHighlightingData PRIVATE Qt6::Core)

‎3rdparty/syntax-highlighting/data/index.katesyntax

1.51 KB
Binary file not shown.

‎3rdparty/syntax-highlighting/data/syntax/alert.xml

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE language SYSTEM "language.dtd">
3+
<language version="6" kateversion="3.1" name="Alerts" section="Other" extensions="" mimetype="" author="Dominik Haumann (dhaumann@kde.org)" license="MIT" hidden="true">
4+
<highlighting>
5+
<list name="alerts_hi">
6+
<item>ALERT</item>
7+
<item>ATTENTION</item>
8+
<item>DANGER</item>
9+
<item>HACK</item>
10+
<item>SECURITY</item>
11+
</list>
12+
<list name="alerts_mid">
13+
<item>BUG</item>
14+
<item>FIXME</item>
15+
<item>DEPRECATED</item>
16+
<item>TASK</item>
17+
<item>TODO</item>
18+
<item>TBD</item>
19+
<item>WARNING</item>
20+
<item>CAUTION</item>
21+
<item>NOLINT</item>
22+
<item>NOQA</item>
23+
</list>
24+
<list name="alerts_lo">
25+
<item>###</item>
26+
<item>NOTE</item>
27+
<item>NOTICE</item>
28+
<item>TEST</item>
29+
<item>TESTING</item>
30+
</list>
31+
<contexts>
32+
<context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
33+
<StringDetect attribute="Region Marker" context="#stay" String="{{{" beginRegion="AlertRegion1" />
34+
<StringDetect attribute="Region Marker" context="#stay" String="}}}" endRegion="AlertRegion1" />
35+
<WordDetect attribute="Region Marker" context="#stay" String="BEGIN" beginRegion="AlertRegion2" />
36+
<WordDetect attribute="Region Marker" context="#stay" String="END" endRegion="AlertRegion2" />
37+
<keyword attribute="Alert Level 1" context="#stay" String="alerts_hi" />
38+
<keyword attribute="Alert Level 2" context="#stay" String="alerts_mid" />
39+
<keyword attribute="Alert Level 3" context="#stay" String="alerts_lo" />
40+
</context>
41+
</contexts>
42+
<itemDatas>
43+
<itemData name="Normal Text" defStyleNum="dsNormal"/>
44+
<itemData name="Alert Level 1" defStyleNum="dsAlert" color="#e85848" selColor="#e85848" backgroundColor="#451e1a" />
45+
<itemData name="Alert Level 2" defStyleNum="dsAlert" color="#ca9219" selColor="#ca9219" backgroundColor="#451e1a" />
46+
<itemData name="Alert Level 3" defStyleNum="dsAlert" color="#81ca2d" selColor="#81ca2d" />
47+
<itemData name="Region Marker" defStyleNum="dsRegionMarker"/>
48+
</itemDatas>
49+
</highlighting>
50+
<general>
51+
<keywords casesensitive="1"/>
52+
</general>
53+
</language>
54+
<!-- kate: indent-width 2; -->

‎3rdparty/syntax-highlighting/data/syntax/comments.xml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE language SYSTEM "language.dtd">
3+
<language
4+
version="1"
5+
kateversion="5.0"
6+
name="Comments"
7+
section="Other"
8+
extensions=""
9+
mimetype=""
10+
author="Alex Turbov (i.zaufi@gmail.com)"
11+
license="MIT"
12+
hidden="true"
13+
>
14+
<highlighting>
15+
<contexts>
16+
<context name="Normal" attribute="Comment" lineEndContext="#pop">
17+
<IncludeRules context="##Alerts" />
18+
<IncludeRules context="##Modelines" />
19+
<IncludeRules context="##SPDX-Comments" />
20+
</context>
21+
</contexts>
22+
<itemDatas>
23+
<itemData name="Comment" defStyleNum="dsComment" />
24+
</itemDatas>
25+
</highlighting>
26+
</language>
27+
<!-- kate: indent-width 2; -->

0 commit comments

Comments
 (0)