README for testing lexers with lexilla/test.

The TestLexers application is run to test the lexing of a set of example files
and thus ensure that the lexers are working correctly.

Lexers are accessed through the Lexilla shared library which must be built first
in the lexilla/src directory.

TestLexers works on Windows, Linux, or macOS and requires a C++20 compiler.
MSVC 2019.4, GCC 9.0, Clang 9.0, and Apple Clang 11.0 are known to work.

MSVC is only available on Windows.

GCC and Clang work on Windows and Linux.

On macOS, only Apple Clang is available.

To use GCC run lexilla/test/makefile:
	make test

To use Clang run lexilla/test/makefile:
	make CLANG=1 test
On macOS, CLANG is set automatically so this can just be
	make test

To use MSVC:
	nmake -f testlexers.mak test
There is also a project file TestLexers.vcxproj that can be loaded into the Visual
C++ IDE.



Adding or Changing Tests

The lexilla/test/examples directory contains a set of tests located in a tree of
subdirectories.

Each directory contains example files along with control files called
SciTE.properties and expected result files with a .styled suffix.
If an unexpected result occurs then files with the suffix .new may be created.

Each file in the examples tree that does not have an extension of .properties, .styled, or
.new is an example file that will be lexed according to settings found in SciTE.properties.
The results of the lex will be compared to the corresponding .styled file and if different
the result will be saved to a .new file for checking.
So, if x.cxx is the example, its lexed form will be checked against x.cxx.styled and a
x.cxx.new file may be created. The .new and .styled files contain the text of the original
file along with style number changes in {} like:
	{5}function{0} {11}first{10}(){0}
After checking that the .new file is correct, it can be promoted to .styled and committed
to the repository.

The SciTE.properties file is similar to properties files used for SciTE but are simpler.
The lexer to be run is defined with a lexer.{filepattern} statement like:
	lexer.*.d=d

Keywords may be defined with keywords settings like:
	keywords.*.cxx=int char
	keywords2.*.cxx=open

Other settings are treated as lexer properties and forwarded to the lexer:
	lexer.cpp.track.preprocessor=1

If there is a need to test additional configurations of keywords or properties then
create another subdirectory with the different settings in a new SciTE.properties.