Frequently Asked Questions

How to translate code?

To translate a Citrine program from one language into another:

ctr -t en2nl.dict myprogram.ctr

Dictionaries have the following format:


Use t for tokens and s for strings. There are 2 special translation pairs: the decimal separator (d) and the thousands separator (x). To generate a dictionary from 2 versions of Citrine in different languages:

ctr -g /nl/dictionary.h /en/dictionary.h

How to use the icons?

Install 'Citrine.ttf' and configure your editor (I use Geany and Geany Macros, a macro package for Geany is included ):

cp ~/.config/geany/plugins/Geany_Macros/settings.conf ~/.config/geany/plugins/Geany_Macros/settings_backup.conf

cp macros.ini ~/.config/geany/plugins/Geany_Macros/settings.conf


Use macros_single_quotes.ini for single quotes, and macros_double_quotes for double quotes. You can download the font and macro package from the Download Page (always select the latest version). The fonts and macros are also included in the source.

List of symbols:

icon code keys
2009ALT; (thin space)
↵ 21B5ALTn
‘’ 2018+2019ALT "
“” 201C+201DALT "
«» 00AB+00BBALT "


The Citrine code base is tested using the Test-o-Mat framework which ships with Citrine. The Test-o-Mat system is very simple to understand and work with and can also be used to test other software. The basic idea is that you have test definitions and expectation files (.exp). After loading the test framework, override the next-message to generate a new test specification object and override the process-message of the Test Suite to describe how the test should be processed. For a detailed example you can look at test no. 365 in the test folder (tests/test0365.ctr). The Test-o-Mat framework is only available in the English language at the moment. In the example below (based on that test) we simply compare the contents of the test file with itself using a the UNIX cat-command:

Program use: Path Test-o-Mat Package.
☞ number of tests ≔ 1.

Tests path: ‘’.
☞ test suite ≔ Tests new.

test suite on: ‘next’ do: {
	☞ test ≔ Nil.
	(⚿ counter < number of tests) true: {
		test ≔ Test new
			number: ⚿ counter copy,
			name: ‘test0365.ctr’,
			file: ‘test0365.ctr’.
	⚿ counter add: 1.
	↲ test.

test suite on: ‘process:’ do: { :test
	☞ actions ≔ Tests actions.
	☞ action ≔ 
			Tests action
			command: Path cat,
			target: ‘../test0365.ctr’,
			output: Path tmp result,
			log: Path tmp log.
		append: action,
		expect: ‘../test0365.ctr’,
		run or fail: ‘OK↵’.
test suite run.

How to write webapps?

Citrine ships with a CCGILIB-based HTTP plugin (mods/request/libctrrequest.so) that allows you to deal with GET and POST requests. you can use the Request object like this:

get  ≔ Request get: ‘ search’ .
list ≔ Request getArray: ‘ orders[]’ .
post ≔ Request post: ‘ message’ .
list ≔ Request postArray: ‘ orders[]’ .
file ≔ Request file: ‘ avatar’ .

Storm Server is a CCGILib based SCGI server for Citrine for hi-traffic web applications, to start an instance of Storm we put the following code in storm.ctr:

host: ‘ localhost’  
listen: 4000
pid: ‘/var/run/storm.pid’  callback: {
	✎ write: ‘Content-type: text/html\n\n’ .
	☞ fname ≔ Program setting: ‘ DOCUMENT_URI’ .
	☞ script ≔ File new: ‘ /var/www/htdocs’  + fname.
	Program use: script.

NGINX example configuration /etc/nginx/nginx.conf:

location ~ \.ctr$ {
        try_files $uri $uri/ =404;
        include   scgi_params;

How to start the core unit tests?

As of july, Citrine will feature a new unit test system to test the core of the language. Over the next few years, we expect to extend this test suite with all sorts of useful tests to improve the quality of the Citrine code. The unit test runner can be invoked simply from the language itself, using:

Program test.

This will start the internal unit test runner. After running all the unit tests the process will be stopped automatically. There is no way to continue a Citrine program after invoking the test runner. If a single test fails, the test suite will report the error and exit. The output from the unit test runner might look like this (although this will change from release to release):

Running Internal Tests

The unit test system is included in the regular test suite and currently resides in test file 0356. The unit test system is used to test parts of Citrine that are difficult to test from the outside like the inner workings of the Lexer, Parser, Walker, as well of specific system utilities for memory management and encoding.

Environment variables

You can use the following environment variables:


CITRINE_MEMORY_LIMIT_MB sets the memory limit in megabytes upfront. CITRINE_MEMORY_MODE selects the garbage collector setting (see Program tidiness). CITRINE_MEMORY_POOL_SHARE sets the share of the pool (2 means that you want 50% of all allocated memory to be devoted to the pool).


AST Citrine allows you to export the AST representation of any Citrine program so you can transpile or compile it to any other target language, including for example: machine code, Assembler, C, C++, Java, Lua, SQL, PHP, Perl or JavaScript.

To generate an AST-export:

ctrXX -x program.ctr

XX = your language edition

The output looks like:


The original program:

✎ write: ‘Hello’.
✎ write: ‘World!’.

The format for the AST-export is as follows, each node in the tree is represented as:


Nested nodes are between [ and ].

Opcodes for nodes:

CodeType of AST-node
52Message expression
53Unary Message
54Binary message
55Keyword Message
56String Literal
57Object Reference
58Numeric Literal
59Code Block Literal { }
60Return Statement ↲
77Instructions in a Code Block
78Parameter (in the parameters)
79End of Program
80Nested Expression between (...)


0Variable: x
1Property: ⚿ x
2Declaration: ☞ x ≔

To test the AST-export you can pipe it through the example program 'info' (available in the source tree in misc/tools):

ctrXX -x program.ctr | info Message Object Reference(✎) Keyword Message(write:) String Literal(Hello) Message Object Reference(✎) Keyword Message(write:) String Literal(World!) End

Go back to homepage.