»

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:

t "SOURCE" "TARGET"
s "SOURCE" "TARGET"
d "SOURCE" "TARGET"
x "SOURCE" "TARGET"

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.

List of symbols:

icon code keys
2054ALT+
26CFALT.
26BFALTk
261EALT=
2190ALT+
21B2ALT,
270EALT'
2264ALT<
2265ALT>
2260ALTu
2022ALT-
×00D7ALT*
÷00F7ALT/
2009ALT; (thin space)
‘’ 2018+2019ALT "
“” 201C+201DALT "

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:

Request 
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;
        scgi_pass 127.0.0.1:4000;
        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
[1][2][3][4][5][6][7][8][9][10][11][12][13][14][15][16][17][18][19][20][21][22][23][24][25][26][27]...

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
CITRINE_MEMORY_MODE
CITRINE_MEMORY_POOL_SHARE

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-Export

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:

52;0;0;;[57;0;3;✎;;55;0;6;write:;[56;0;5;Hello;;];];52;0;0;;[57;0;3;✎;;55;0;6;write:;[56;0;6;World!;;];];79;0;0;;;

The original program:

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

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

{TYPE} ; {MODIFIER} ; {LENGTH OF VALUE BUFFER} ; {VALUE BUFFER} ; {NESTED NODES}

Nested nodes are between [ and ].

Opcodes for nodes:

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

Modifiers:

CodeMeaning
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.