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