= HIGHLIGHT TESTCASES MANUAL
André Simon
v4.0, March 2021
:lang: en
:icons: font
:toc: left
:toc-title: Contents
:toclevels: 4
:sectnums:
:sectnumlevels: 1
:sectanchors:
// GitHub Settings to enable Admonitions Icons in preview:
ifdef::env-github[]
:caution-caption: :fire:
:important-caption: :heavy_exclamation_mark:
:note-caption: :information_source:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
== ABOUT
Input files whose filenames start with `syntax_test_` can contain column and state
indicators in comment sections to test the highlight syntax recognition of the
previous line. If such a test fails, highlight will print an error message and
exit with FAILURE return value.
See the feature discussion here: https://gitlab.com/saalen/highlight/issues/80
[NOTE]
================================================================================
For UTF-8 encoded input, you need to set `--encoding=utf-8`. Otherwise the
state indicator positions will not be calculated correctly.
================================================================================
[NOTE]
================================================================================
Only the last 100 states of each input line are being tracked.
================================================================================
== TEST CASE NOTATION
A test case is defined by two entities: column and expected state.
The column is defined by ``^`` ("here") or ``<`` ("comment start / first column").
The state is defined by one of the following identifiers:
[horizontal]
`def` :: standard / no recognition // SEE V4 migration note below
`sng` :: string // SEE V4 migration note below
`num` :: number
`slc` :: single line comment
`com` :: multiline comment
`esc` :: escape character
`ppc` :: preprocessor
`pps` :: preprocessor string
`opt` :: operator
`ipl` :: interpolation
`ws` :: whitespace
`kwX` :: keyword group X (X: a..z)
`stX` :: semantic token X (X: a..z)
The state identifiers match the corresponding HTML output CSS class names.
Since release 3.47, the whitespace indicator `ws` is no longer exclusive.
A test will succeed at a position with whitespace if the enclosing state is matched
or if `ws` is tested specifically.
V4 migration: For a smooth transition after the V4 release, `std` will be recognized
as `def`, and `str` is equivalent to `sng`.
Add a leading `~` to an indicator to match any other state as success.
=== Example
The following C file `syntax_test_1.c` contains various state indicators:
[source,C]
--------------------------------------------------------------------------------
#include <iostream>
#include "myheader"
// ^ ppc ^^^^^^^^^^ pps 1)
int main() {
// ^^^^ kwd 2)
/* comment comment comment
* < com ^ ws ^ com 3)
*/
int var = 0x1234;
/* ^^^ def ^ ^ num */
// ^ opt 4)
std::cout << "whatever: " << var << "\n";
// ^^^^^^^^^^^^ str ^^opt ^^ esc
return 0;
// < kwa 5)
}
--------------------------------------------------------------------------------
1) This line contains a test for preprocessor and a preprocessor string.
The `^` indicators point at the tested string sections of the previous line.
2) The keyword group `kwd` is checked (functions are highlighted as `kwd` in C syntax)
3) The `<` points to column 0 as the comment starts there.
`ws` tests for whitespace.
4) A source code line can be tested with various test comments.
Here the `opt` test looks for the operator two lines before.
5) `<` points at column 4, the beginning of the comment.
Running highlight with this file will not produce any additional output, as all
tests pass. The exit status will be 0.
If you change the `kwa` in 5 to `kwb` (or any other state), highlight will print
an error like this, and exit with status 1:
.........................................................
highlight: Could not validate file:
syntax_test_1.c line 17, column 4: got kwa instead of kwb
.........................................................
The highlight GUI will show error messages in an error summary prompt.