1= HIGHLIGHT TESTCASES MANUAL
2André Simon
3v4.0, March 2021
4:lang: en
5:icons: font
6:toc: left
7:toc-title: Contents
8:toclevels: 4
9:sectnums:
10:sectnumlevels: 1
11:sectanchors:
12// GitHub Settings to enable Admonitions Icons in preview:
13ifdef::env-github[]
14:caution-caption: :fire:
15:important-caption: :heavy_exclamation_mark:
16:note-caption: :information_source:
17:tip-caption: :bulb:
18:warning-caption: :warning:
19endif::[]
20
21== ABOUT
22
23Input files whose filenames start with `syntax_test_` can contain column and state
24indicators in comment sections to test the highlight syntax recognition of the
25previous line. If such a test fails, highlight will print an error message and
26exit with FAILURE return value.
27
28See the feature discussion here: https://gitlab.com/saalen/highlight/issues/80
29
30
31[NOTE]
32================================================================================
33For UTF-8 encoded input, you need to set `--encoding=utf-8`. Otherwise the
34state indicator positions will not be calculated correctly.
35================================================================================
36
37
38[NOTE]
39================================================================================
40Only the last 100 states of each input line are being tracked.
41================================================================================
42
43
44== TEST CASE NOTATION
45
46A test case is defined by two entities: column and expected state.
47
48The column is defined by ``^`` ("here") or ``<`` ("comment start / first column").
49
50The state is defined by one of the following identifiers:
51
52[horizontal]
53`def` :: standard / no recognition // SEE V4 migration note below
54`sng` :: string                    // SEE V4 migration note below
55`num` :: number
56`slc` :: single line comment
57`com` :: multiline comment
58`esc` :: escape character
59`ppc` :: preprocessor
60`pps` :: preprocessor string
61`opt` :: operator
62`ipl` :: interpolation
63`ws`  :: whitespace
64`kwX`  :: keyword group X (X: a..z)
65`stX`  :: semantic token X (X: a..z)
66
67The state identifiers match the corresponding HTML output CSS class names.
68
69Since release 3.47, the whitespace indicator `ws` is no longer exclusive.
70A test will succeed at a position with whitespace if the enclosing state is matched
71or if `ws` is tested specifically.
72
73V4 migration: For a smooth transition after the V4 release, `std` will be recognized
74as `def`, and `str` is equivalent to `sng`.
75
76Add a leading `~` to an indicator to match any other state as success.
77
78
79=== Example
80
81The following C file `syntax_test_1.c` contains various state indicators:
82
83[source,C]
84--------------------------------------------------------------------------------
85#include <iostream>
86#include "myheader"
87// ^ ppc ^^^^^^^^^^ pps       1)
88
89int main() {
90//  ^^^^ kwd                  2)
91/* comment comment comment
92 * <  com ^ ws     ^ com      3)
93 */
94
95    int var =   0x1234;
96/*      ^^^ def ^    ^ num */
97//          ^ opt             4)
98    std::cout << "whatever: " << var <<   "\n";
99//               ^^^^^^^^^^^^ str    ^^opt ^^ esc
100    return 0;
101    //  <   kwa               5)
102}
103--------------------------------------------------------------------------------
104
1051) This line contains a test for preprocessor and a preprocessor string.
106   The `^` indicators point at the tested string sections of the previous line.
107
1082) The keyword group `kwd` is checked (functions are highlighted as `kwd` in C syntax)
109
1103) The `<` points to column 0 as the comment starts there.
111   `ws` tests for whitespace.
112
1134) A source code line can be tested with various test comments.
114   Here the `opt` test looks for the operator two lines before.
115
1165) `<` points at column 4, the beginning of the comment.
117
118
119Running highlight with this file will not produce any additional output, as all
120tests pass. The exit status will be 0.
121
122If you change the `kwa` in 5 to `kwb` (or any other state), highlight will print
123an error like this, and exit with status 1:
124
125.........................................................
126highlight: Could not validate file:
127syntax_test_1.c line 17, column 4: got kwa instead of kwb
128.........................................................
129
130
131The highlight GUI will show error messages in an error summary prompt.
132
133