Unicode palette

For a compact list of all the non-ASCII characters used in CQL, see palette . CQL is distributed with a text version of this file, palette.cql.

Unicode characters in CQL

CQL 6.2 supports certain special characters that are not available on standard computer keyboards, such as ♔, ✵, and ⊢. We call these unicode characters.

What's Unicode?

Unicode is a system that assigns a single nonnegative integer, called a codepoint, to each character. The familiar ASCII characters have codepoints between 0 and 127. Other characters, which sometimes call "Unicode characters" have higher codepoints.

Any CQL file is a sequence of 8-bit bytes. Each ASCII character is encoded within that file as a single byte. Unicode characters that are not ASCII are encoded using between two and four consecutive bytes using a standard convention called UTF-8.

Each non-ASCII Unicode character or sequence of characters in a CQL file can be replaced with a series of 1 or more ASCII characters to generate an equivalent CQL program.

A Unicode character with codepoint n is customarily written U+x , where x is the hexadecimal representation of the integer n.

For example, the white king, ♔ , has codepoint with decimal value 9812, corresponding to a hexadecimal value of x2654, and would be therefore be notated as U+2654.

CQL Chess font

Most of the CQL characters are legible by default in most operating systems and standard applications (other than Windows), but they are easier to read using the CQL's custom chess font.

Table of Unicode characters with ASCII equivalents

The basic piece designators

	KQRBNP
	kqrbnp

may be replaced by the corresponding figurine chess characters

	♔♕♖♗♘♙
	♚♛♜♝♞♟

Moreover, the following special symbols may be used:

UTF8	Codepoint	ASCII
⊢	U+22A2	path
――	U+2015 U+2015	--
×	U+D7	[x]
◎	U+25CE	focus
△	U+25B3	A
▲	U+25B3	a
◭	U+25ED	[Aa]
□	U+25A1	_
✵	U+2735	flip
⬓	U+2B13	flipcolor
→	U+2190	<-
←	U+2192	->
∙	U+2219	currentposition
▦	U+25A6	a-h1-8
≤	U+2264	<=
≥	U+2265	>=
≠	U+2260	!=
∊	U+220A	[element]
∪	U+222A	|
∩	U+2229	&
∀	U+2200	[forall]
≺	U+227A	[<]
≻	U+227B	[>]
≼	U+227C	[<=]
≽	U+227D	[>=]

You can get the ASCII equivalent of most of the symbols in this documentation by hovering over the symbol with the mouse.

Using Unicode symbols on Windows

For most Windows users, we recommend using Emil Vlasák's VisualCQL. VisualCQL supports Unicode in a native and easy-to-use way.

Inputting unicode symbols on non-Windows systems

If you do not want to use Unicode symbols, just use the ASCII. Everything in CQL will work fine with ASCII.

But if you want to see the symbols in your files, there are several ways to input unicode symbols:

Copying and pasting

You can copy and past the symbols from any documentation page of or from the palette of symbols.

Using -u

You can convert a CQL file into one using unicode by using the following invocation

	cql -u a.cql

This will convert all characters in the file a.cql into their unicode equivalents.

Using -a

You can convert a CQL file into ASCII by using the following invocation

	cql -a u.cql

This will convert all unicode characters in the file u.cql into their ASCII equivalents. This function sometimes adds spaces between output tokens.

Debugging unicode issues

Please contact CQL CQL support if you run into Unicode issues, since at this point we want to know what sorts of issues arise.

CQL ships with a simple debugging tool

	cql -echo filename.cql

which outputs a human-readable version of the Unicode symbols used in the file filename.cql.

Sending a CQL file to others

If you have a CQL file that uses Unicode characters, you can send it to people who do not have the ability to view the Unicode characters by first converting the file to html and sending that:

	cql -html filename.cql

This will create a file named filename-cql.html which is cross-platform html file that displays the contents of filename.cql. This html file can be sent as an attachment in gmail or other email clients. If you send the CQL file directly, the recipients might not be able to view the file clearly if they lack the correct font.

Use of unicode in piece designators

You do not need to use brackets to include sequences of simple piece designators:

	[RB]a4 //A rook or a bishop on a4
	♖♗a4 //same thing

History of special symbols in chess notation

Like CQL, others have similarly found the need to resort to non-ASCII chess symbols when annotating and discussing chess games.

Such symbols have been used for decades in chess notation, most famously by the Informant. (See e.g. Diana Mihajlova's The universal chess language of the Informant). Note that some of our symbols, notably △ and □ have different meanings in CQL than they did in the old Informants, but we doubt that this particular issue is one likely to cause confusion nowadays.

In a similar vein, Mark Lowery has described some other examples of non-ASCII chess notation used by the United States Chess Federation and others: Mark Lowery blog.