These notes on the ChaiScript language may help when using it in <script> sections in CartoType import rules. Here are some external links to some other useful resources:

ChaiScript Overview and Tutorial

ChaiScript Tutorial: the link is to the first of a series of articles.

ChaiScript Keyword Reference

ChaiScript built-in types and functions

General nature of the language

ChaiScript is a strongly typed declarative language with syntax similar to C++. Important differences from C++ are:

  • All statements are legal at file scope, outside any function.
  • Variables have no type until they are first given a value, either at the time of declaration or later.
  • Flow-of-control constructs like if, for and while take blocks enclosed in { … }; they cannot take single statements.
  • There are no postincrement or postdecrement operators (++ and -- after the variable name).

Character set

ChaiScript uses only 7-bit ASCII characters in keywords, identifiers and other syntax elements like operators. ChaiScript program code is a series of 8-bit bytes. The ChaiScript parser assumes the ASCII encoding (i.e., the first 127 codepoints of Unicode). Byte values greater than 127 can be used but their interpretation is the choice of the programmer. (CartoType-specific note: strings passed from or to CartoType, e.g., by getting an input field or setting a map object attribute, are encoded as UTF-8).


Identifiers are case-sensitive sequences of characters starting with a letter (a…z, A…Z) or an underscore (_), and continuing with zero or more letters, underscores and digits (0…9). The format is identical to that of C++ and C. The following keywords are recognised:

attr auto break case catch class continue def default else finally for global if return switch try var while

There are some special identifiers which are not strictly keywords but have reserved meanings:

_ __CLASS__ Infinity false __FILE__ __FUNC__ __LINE__ Nan true

The following punctuation tokens are recognised:

:: ( ) : { } [ ] . ,

The following operator tokens are recognised:

? || && | ^ & == != < <= > >= << >> + - * / % ++ -- ! ~

Line breaks are marked by either a single linefeed or a carriage return followed by a linefeed.

Integer literals are as in C++. Decimal binary, octal and hexadecimal integer literals are all supported.

Floating-point number literals are as in C++, but C++17 hexadecimal floating-point literals are not supported.

String literals are sequences of characters enclosed in double quotes. Double quotes can be put in a string using the sequence \”. String literals may contain interpolations, which are enclosed in ${ … } and may contain unescaped double quotes. Interpolations may be nested. They are used as code literals and interpreted as ChaiScript code by the built-in print function.

Operator literals are operators enclosed in back ticks, like `+`. They are function objects referring to operators.

Comments are as in C++. That is, a comment lasting to the end of the current line starts with //, and a multi-line comment is of the form /* … */.

Annotations are special single-line comments starting with #. A function’s annotation can be retrieved programmatically.

Statements and declarations

Statements and declarations are terminated either by the end of a line or by a semicolon. Multi-line statements are parsed greedily; if the parser has not encountered a semicolon or other delimiter indicating the end of a statement when it reaches the end of a line, it moves on to the next line. Unlike in C++, semicolons are not mandatory.


A ChaiScript program is a sequence of statements and declarations. Unlike in C++, statements may exist outside any function. A program to print ‘Hello World’ can therefore be expressed as the one-line program

puts(“Hello World”)

Built-in types

The following types are built in, and have constructors (e.g., uint32_t(), int(45), etc.) with the same name:

Boolean types


integer types

int long unsigned_int unsigned_long long_long unsigned_long_long size_t int8_t int16_t int32_t int64_t uint8_t uint16_t uint32_t uint64_t

floating point types

double long_double float

character types

char wchar_t char16_t char32_t

Standard library types

These types are provided by the standard library, which is automatically loaded by ChaiScript.

string types

string: very similar to C++’s std::string

aggregate types




other types


Creating variables: auto and var

Variables are declared using auto, or var, which is a synonym of auto. The syntax is:

auto <name>


auto <name> = <expression>

and the type of the variable is deduced from that of the expression if any. If no expression is given, the type is determined the first time the variable is assigned.


auto n = 3
var f = 56.78
auto s = “abc”
auto u = unsigned_int() // sets u to 0