Merge branch 'master' into martin-t/cleanup
[xonotic/xonotic.wiki.git] / NewQC.md
1 New QC Syntax
2 =============
3
4 It is possible that at some point we decide to switch QC-compiler which requires some changes to the code.
5
6 ~~For more information see http://dev.xonotic.org/projects/bocc~~
7
8 (Update: Blub's bocc compiler didn't make it, but someone else came along, both devs [joined forces](https://github.com/graphitemaster/gmqcc/graphs/contributors) and brought us [GMQCC](https://graphitemaster.github.io/gmqcc/doc.html).
9  This is now the QuakeC compiler used by the Xonotic project.)
10
11 Clean syntax:
12 -------------
13
14 In fteqcc there are some ambiguities regarding fieldpointers, function pointers, and field-return-types etc.
15 A clean syntax is needed, the current implementation uses the following:
16
17 |definition|meaning|
18 |----------|-------|
19 |`float foo`|global variable|
20 |`float .foo`|entity field|
21 |`.float foo`|fieldpointer|
22 |`.float .foo`|entity field of type fieldpointer|
23 |`float foo(void)`|function|
24 |`float foo*(void)`|function pointer|
25 |`.float foo(void)`|function returning a fieldpointer .float|
26 |`.float foo*(void)`|function pointer, returning a fieldpointer .float|
27 |`float .foo(void)`|entity field of type function returning float|
28 |`.float .foo(void)`|entity field of type function returning fieldpointer|
29
30 Function definitions:
31 ---------------------
32
33 The old-style QC way of defining functions will not be supported, so
34
35     void(float x) something = { ... }
36
37 becomes
38
39     void something(float x) { ... }
40
41 which is the most common way to define functions in the xonotic code already anyway.
42
43 Constants:
44 ----------
45
46 From now on, the code
47
48     float x = 3
49
50 does what the first instinct tells you: it creates a global with the initial value 3. Contrary to old QC, where it created a constant.
51 To create a constant use:
52
53     const float x = 3
54
55 Extendable functions:
56 ---------------------
57
58 Since menuQC has some funny macro: ACCUMULATE\_FUNCTIONS, it seemed like a nice syntactical sugar to allow the following:
59
60     float myfunc() extendable
61     {
62         float mylocal = 3;
63     }
64
65     /* other code */
66
67     float myfunc()
68     {
69         mylocal += 5;
70         if (mylocal > 20)
71             return mylocal;
72     }
73
74     /* optionally: */
75     float myfunc() final
76     {
77         return 3;
78     }
79
80 Variadic parameters (do not use yet)
81 ------------------------------------
82
83 (This might get changed to be more flexible so do not rely on this syntax…)
84
85 Another “enhancement” is the possibility to have functions with variadic parameter lists. However, the only way to sanely access them (until pointers are allowed) is via a recursive way.
86 Here’s an example that assumes float parameters and prints them one after the other:
87
88     void printfloats(float count, float first, ...)
89     {
90         if (count <= 0) // if there are no parameters, return
91             return;
92         if (count == 1) { // If there's one parameter, print it, plus a new-line
93             print(strcat(ftos(first), "\n"));
94             return;
95         }
96         // Otherwise we have multiple parameters left, so print the float, and add a comma
97         print(strcat(ftos(first), ", "));
98         myprint(count-1, ...);
99     }
100
101 So `myprint(4, 1, 2, 3, 4)` would print "1, 2, 3, 4\\n"
102