]> git.xonotic.org Git - xonotic/gmqcc.git/blob - doc/specification.tex
2e8dedf529796ad09f3b57f83384bb21b04982ea
[xonotic/gmqcc.git] / doc / specification.tex
1 \documentclass[11pt]{article}
2 \makeindex
3 \usepackage{graphicx}    % needed for including graphics e.g. EPS, PS
4 \usepackage{listings}    % for C syntax highlighting
5 \usepackage{color}
6 \usepackage{tipa}
7
8 \definecolor{dkgreen}{rgb}{0,0.6,0}
9 \definecolor{gray}{rgb}{0.5,0.5,0.5}
10 \definecolor{mauve}{rgb}{0.58,0,0.82}
11
12 % set listings colors
13 \lstset{ %
14   backgroundcolor=\color{white},  % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}
15   basicstyle=\footnotesize,       % the size of the fonts that are used for the code
16   breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
17   breaklines=true,                % sets automatic line breaking
18   captionpos=b,                   % sets the caption-position to bottom
19   commentstyle=\color{dkgreen},   % comment style
20   deletekeywords={...},           % if you want to delete keywords from the given language
21   escapeinside={\%*}{*)},         % if you want to add LaTeX within your code
22   keywordstyle=\color{blue},      % keyword style
23   language=C,                % the language of the code
24   morekeywords={entity,local},           % if you want to add more keywords to the set
25   numbers=left,                   % where to put the line-numbers; possible values are (none, left, right)
26   numbersep=5pt,                  % how far the line-numbers are from the code
27   numberstyle=\tiny\color{gray},  % the style that is used for the line-numbers
28   rulecolor=\color{black},        % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
29   showspaces=false,               % show spaces everywhere adding particular underscores; it overrides 'showstringspaces'
30   showstringspaces=false,         % underline spaces within strings only
31   showtabs=false,                 % show tabs within strings adding particular underscores
32   stepnumber=1,                   % the step between two line-numbers. If it's 1, each line will be numbered
33   stringstyle=\color{mauve},      % string literal style
34   tabsize=2,                      % sets default tabsize to 2 spaces
35   title=\lstname                  % show the filename of files included with \lstinputlisting; also try caption instead of title
36 }
37
38 \topmargin -1.5cm        % read Lamport p.163
39 \oddsidemargin -0.04cm   % read Lamport p.163
40 \evensidemargin -0.04cm
41
42 \textwidth 16.59cm
43 \textheight 21.94cm 
44 \parskip 7.2pt                         % spacing between paragraphs
45 \renewcommand{\baselinestretch}{1.5}    % 1.5 spacing between lines
46 \parindent 0pt                              % leading space for paragraphs
47 \title{The GMQCC Quake C Programming Language}
48 \author{Dale Weiler, Wolfgang Bullimer}
49
50 % subscript and superscript in text mode require
51 % strange uses of math expression scripting, which
52 % is unusable, these macros implement it using math
53 % expressions, and reimplement ^ and _ to work in
54 % text mode :-)
55 \makeatletter
56 \newcommand\textsubscript[1]{\@textsubscript{\selectfont#1}}
57 \def\@textsubscript#1{{\m@th\ensuremath{_{\mbox{\fontsize\sf@size\z@#1}}}}}
58 \newcommand\textbothscript[2]{%
59   \@textbothscript{\selectfont#1}{\selectfont#2}}
60 \def\@textbothscript#1#2{%
61   {\m@th\ensuremath{%
62     ^{\mbox{\fontsize\sf@size\z@#1}}%
63     _{\mbox{\fontsize\sf@size\z@#2}}}}}
64 \def\@super{^}\def\@sub{_}
65
66 \catcode`^\active\catcode`_\active
67 \def\@super@sub#1_#2{\textbothscript{#1}{#2}}
68 \def\@sub@super#1^#2{\textbothscript{#2}{#1}}
69 \def\@@super#1{\@ifnextchar_{\@super@sub{#1}}{\textsuperscript{#1}}}
70 \def\@@sub#1{\@ifnextchar^{\@sub@super{#1}}{\textsubscript{#1}}}
71 \def^{\let\@next\relax\ifmmode\@super\else\let\@next\@@super\fi\@next}
72 \def_{\let\@next\relax\ifmmode\@sub\else\let\@next\@@sub\fi\@next}
73 \makeatother
74
75 % set standard paper sizes
76 \setlength{\paperheight}{11in}
77 \setlength{\paperwidth}{8.5in}
78  
79 \begin{document}
80 \maketitle
81 \pagebreak
82 \tableofcontents
83 \pagebreak
84 \section{Introduction}
85 With the introduction of improvements of existing runtime environments, new features may be added to this specification.  Subclauses in the language warn implementors and programmers of usages which, though valid in themselfs, may conflict with future additions.
86
87 This specification is divided into three major subjects:
88 \begin{enumerate}
89         \item preliminary elements
90         \item the characteristics of environments that translate and execute QuakeC programs
91         \item the languages syntax, constraints, and semantics
92 \end{enumerate}
93
94 Examples are provided to illustrate possible forms of the constructions described, to better facilitate the reader.
95
96 \section{Scope}
97 This specification only specifies the form and establishes the interpretation of programs written in the GMQCC QuakeC programming language variant. It specifies:
98 \begin{enumerate}
99         \item The representation of Quake C programs;
100         \item The syntax and constraints of the Quake C language;
101         \item The semantic rules for interpreting Quake C programs;
102         \item The representation of input data to be processed by Quake C programs;
103         \item The restrictions and limits imposed by a conforming implementation of Quake C.
104 \end{enumerate}
105 This specification does not specify
106 \begin{enumerate}
107         \item The process in which Quake C programs are transformed for use by a data-processing system;
108         \item The process in which Quake C programs are invoked for use by a data-processing system;
109         \item The process in which input data is transformed for use by a Quake C program;
110         \item The process in which output data is transformed after being produces by a Quake C program;
111         \item The size of complexity involved with a Quake C program and its  data that will exceed the capacity of any specific data-processing system or the capacity of a particular processor;
112         \item The minimal requirements of a data-processing system which is capable of supporting a conforming implementation.
113 \end{enumerate}
114 These details are decided upon by the environment designer (usually the engine developer).  The details are as such subjected to implementation-defined behavior.
115
116 \section{Terms and definitions}
117 \subsection*{argument}
118 The expression in a comma-separated list bounded by parentheses in a function call expression, or a sequence of preprocessing tokens in a comma-separated list bounded by parentheses in a function-like macro invocation.
119 \subsection*{behavior}
120 The external appearance or action of an expression, statement, etc
121 \subsection*{implementation-defined behavior}
122 Unspecified behavior where each implementation decides how the choice is made.
123 \subsection*{unspecified behavior}
124 Use of an unspecified value, or other behavior where this specification provides two or more possibilities and imposes no further requirements on which is chosen in any instance (e.g. Thus any ambiguity is considered unspecified behavior).
125 \subsection*{constraint}
126 A restriction, either syntactically or semantically, by which the exposition of various language elements is to be interpreted.
127 \subsection*{implementation}
128 Particular set of software, running in a particular translation environment under particular control options, that performs translations of programs for, and supports execution of functions in, a particular execution environment.
129 \subsection*{object}
130 A region of data storage in the execution environment, the contents of which are capable of representing values.
131 \subsection*{parameter}
132 An object declared as part of a function declaration that acquires a value on entry to the function, or an identifier from the comma-separated list bounded by parentheses immediately following the macro name in a function-like macro definition.
133 \subsection*{value}
134 The precise meaning of the contents of an object when interpreted as having a specific type.
135 \subsection*{implementation-defined value}
136 An unspecified value where each implementation decides how the choice is made.
137 \subsection*{unspecified value}
138 A valid value of the relevant type where this specification imposes no requirements on which value is chosen in any instance.
139
140 \section{Conformance}
141 In this specification, "shall" is to be interpreted as a requirement on an implementation or on a program; conversely, "shall not" is to be interpreted as a prohibition on the implementation or on a program.
142
143 A conforming program is one that is acceptable to a conforming implementation.
144
145 An implementation shall be accompanied by a document that defines all implementation-defined characteristic and extensions.
146
147 \section{Enviroment}
148 \subsection{Conceptual models}
149 \subsubsection{Translation environment}
150 \paragraph{Program structure}
151 A Quake C program need not all be translated at the same time.  The text of the program is kept in units called source files. All source files become concatenated, less any source lines skipped by any of the conditional inclusion preprocessing directives.  The final concatenation becomes the program structure.
152
153 \paragraph{Translation phases}
154 \begin{enumerate}
155         \item Physical source file characters are mapped to the source character set (introducing new-line characters for end-of-line indicators) if necessary.  Trigraph and Digraph sequences are replaced by corresponding single-character internal representations.
156         \item The source file is decomposed into preprocessing tokens and sequences of white-space characters (including comments).
157         \item Preprocessing directives are executed and macro invocations expanded recursively.
158         \item Each escape sequence in character constants and string literals is converted to a member of the execution character set.
159         \item Adjacent character string literal tokens are concatenated.
160         \item White-space characters separating tokens are no longer sufficient. The resulting tokens are syntactically and semantically analyzed and translated.
161 \end{enumerate}
162
163 \paragraph{Diagnostics}
164 A conforming implementation shall produce at least one diagnostic message (identified in an implementation-defined manner) if a program structure contains a violation of any syntax rule or constraint, even if the behavior is explicitly specifies as being undefined or implementation-defined.  diagnostic messages need not be produces in other circumstances.
165 \begin{small}
166 EXAMPLE
167 \end{small}
168 \begin{lstlisting}[language=C]
169         string i;
170         float  i;
171 \end{lstlisting}
172 The following example should produce a diagnostic for the program structure.
173
174 \section{Language}
175 \subsection{Notation}
176 In the syntax notation used in this clause, syntactic categories (non-terminals) are indicated by italic type, and literal words and character set members (terminals) by bold type.  A colon (:) following a non-terminal introduces its definition.  Alternative definitions are listed on corresponding separate lines, except when prefaced by words "one of".  An optional symbol is indicated by a subscript "opt", so that\\
177 \{ expression _{opt} \}\\
178 indicates an optional expression closed in braces. When syntactic categories are refereed to in the main text, they are not italicized and words are separated by spaces instead of hyphens.
179
180 \subsection{Concepts}
181 \subsubsection{Scopes of identifiers}
182 An identifier can denote an object; a function; a tag or member of an entity, or enumeration; a typedef name; a label name; a macro name; or a macro parameter.  The same identifier can denote different entities at different points in the program.  A member of an enumeration is called an enumeration constant.  Macro names and macro parameters are not considered further here, because prior to the semantic phase of program translation any occurrences of macro names in the source file are replaced by the preprocessing token sequences that constitute their macro definitions.
183
184 For each different entity that an identifier designates, the identifier is visible (i.e., can be used) only within a region of program text called its scope.  Different entities designated by the same identifier either have different scopes, or are in different name spaces.  There are four kinds of scopes: function, global, block and function prototype. (A function prototype is a declaration of a function that declares the types of its parameters.)
185
186 A label name is the only kind of identifier that has function scope.  It can be used (in a goto statement) anywhere in the function in which it appears, and is declared implicitly by it's syntactic appearance (prefixed by a : and a statement).
187
188 Every other identifier has scoped determined by the placement of its declaration (in a declarator or type specifier).  If the declarator or type specifier that declares the identifier appears outside of any block or list of parameters, the identifier has global scope, which terminates at the end of the program structure.  If the declarator or type specifier that declares the identifier appears inside a block or within the list of parameter declarations in a function definition, the identifier has block scope, which terminates at the end of the associated block. If the declarator or type specifier that declares the identifier appears within the list of parameter declarations in a function prototype (not part of a function definition), the identifier has function prototype scope, which terminates at the end of the function declarator.  If an identifier designates two different entities in the same name space, the scopes might overlap.  If so, the scope of one entity (the inner scope) will be a strict subset of the scope of the other entity (the outer scope).  Within the inner scope, the identifier designates the entity declared in the inner scope; the entity declared in the outer scope is hidden (and is not visible) within the inner scope.
189
190 Unless explicitly stated otherwise, where this specification uses the term "identifier" to refer to some entity (as opposed to the syntactic construct), it refers to the entity in the relevant name space whose declaration is visible at the point the identifier occurs.
191
192 Unless explicitly stated otherwise, where this specification uses the term "entity", is not to be ambiguous with the entity type, but considered a semantic construct.
193
194 Two identifiers have the same scope if and only if their scopes terminate at the same point.
195
196 Enumeration tags have scope that begins just after the appearance of the tag in a type specifier that declares the tag.  Each enumeration constant has scope that begins just after the appearance of its defining enumerator in an enumeration list.  Any other identifier has scope that begins just after the completion of its declarator.
197
198 \subsubsection{Name spaces of identifiers}
199 If more than one declaration of a particular identifier is visible at any point in the program structure, the syntactic context disambiguates uses that refer to different entities.  Thus, there are separate name spaces for various categories of identifiers, as follows:
200 \begin{enumerate}
201         \item label names (disambiguated by the syntax of the label declaration and use);
202         \item the tags of enumerations
203         \item all other identifiers, called ordinary identifiers (declared in ordinary declarators or as enumeration constants).
204 \end{enumerate}
205
206 \subsubsection{Types}
207 The meaning of a value stored in an object or returned by a function is determined by the type of the expression used to access it.  (An identifier declared to be an object is the simplest such expression; the type is specified in the declaration of the identifier.)  Types are partitioned into object types(types that fully describe object) and function types(types that describe functions).
208
209 An object declares as type bool is large enough to store the values 0 and 1.
210
211 An object declared as type char is large enough to store any member of the basic execution character set.  If a member of the basic execution character set is stored in a char object, its value is guaranteed to be nonnegative.  If any other character is stored in a char, the resulting value is implemented-defined.
212
213 An object declared as type string is large enough to store any length string-literal composed of any length chars, and as such follows the same rules as an object declared as type char.
214
215 The void type comprises an empty set of values; it is an incomplete type that cannot be completed.
216
217 The float and vector type .. TODO
218
219 An enumeration comprises a set of named integer constant values.  Each enumeration constitutes a different enumerated type.
220
221 \subsubsection{Compatible type and composite type}
222 Two types have compatibility if their types are the same.
223
224 All declarations that refer to the same object or function shall have compatibility; otherwise, the behavior is undefined.
225
226 A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:
227 \begin{enumerate}
228         \item If one type is a function type with a paramater type list (function prototype), the composite type is a function prototype with the parameter type list.
229         \item If both types are function types with parameter type lists, the type of each parameter in the composite parameter type list is the composite type of the corresponding parameters.
230 \end{enumerate}
231
232 \subsection{Conversions}
233 \subsubsection{Other operands}
234 \paragraph{Lvalues, arrays, and function designators}
235 An lvalue is an expression with an object type or an incomplete type other than void; if an lvalue does not designate an object when it is evaluated, the behavior is undefined.  When an object is said to have a particular type, the type is specified by the lvalue used to designated said object.  A modifiable lvalue is an lvalue that does not have an array type, does not have a const-qualified type and does not have an incomplete type.
236
237 A function designator is an expression that has function type. A function designator with type "function returning type" is converted to an expression that has type "pointer to function returning type".
238
239 \paragraph{void}
240 The (nonexistent) value of a void expression (an expression that has type void) shall not be used in any way, and implicit or explicit conversions (except to void) shall not be applied to any such expression.  If an expression of a type not void is evaluated as a void expression, its value or designator shall be discarded. (A void expression is evaluated only for its side effects.)
241
242 \subsection{Lexical elements}
243 \subsubsection{Keywords}
244 \begin{tabular} { l l l l l }
245         for & do & while & if & else \\
246         local & return & const & switch & case \\
247         default & struct & union & break & continue \\
248         typedef & goto & namespace \\
249 \end{tabular}
250
251 \subsubsection{Identifiers}
252 \paragraph*{identifier}
253 \begin{tabular} { l }
254         identifier-nondigit \\
255         identifier identifier-nondigit \\
256         identifier-digit \\
257 \end{tabular}
258
259 \paragraph*{identifier-nondigit}
260 \begin{tabular} { l }
261         nondigit \\
262         other implementation-defined characters \\
263 \end{tabular}
264
265 \paragraph*{nondigit}
266 \begin{tabular}{ c c c c c c c c c c c c c c c c c c c c }
267         \_ & a & b & c & d & e & f & g & h & i & j & k & l & m & n & o & p & q & r & s \\
268         t & u & v & w & y & z & A & B & C & D & E & F & G & H & I & J & K & L & M & N \\
269         O & P & Q & R & S & T & U & V & W & X & Y & Z \\
270 \end{tabular}
271
272 \paragraph*{digit}
273 \begin{tabular}{c c c c c c c c c c c }
274         0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
275 \end{tabular}
276
277 \paragraph*{hex-quad}
278 \begin{tabular} { l }
279         hexadecimal-digit hexadecimal-digit \\
280 \end{tabular}
281
282 \subsubsection{Constants}
283 \label{sec:constants}
284 \paragraph*{constant}
285 \begin{tabular} { l }
286         integer-constant \\
287         floating-constant \\
288         enumeration-constant \\
289         character-constant \\
290         vector-constant \\
291 \end{tabular}
292
293 \paragraph*{integer-constant}
294 \begin{tabular} { l }
295         decimal-constant \\
296         octal-constant \\
297         hexadecimal-constant \\
298 \end{tabular}
299
300 \paragraph*{decimal-constant}
301 \begin{tabular} { l }
302         nonzero-digit \\
303         decimal-constant digit \\
304 \end{tabular}
305
306 \paragraph*{octal-constant}
307 \begin{tabular} { l }
308         0 \\
309         octal-constant octal-digit
310 \end{tabular}
311
312 \paragraph*{hexadecimal-constant}
313 \begin{tabular} { l }
314         hexadecimal-prefix hexadecimal-digit \\
315         hexadecimal-constant hexadecimal-digit \\
316 \end{tabular}
317
318 \paragraph*{hexadecimal-prefix}
319 \begin{tabular} { c c }
320         0x & 0X \\
321 \end{tabular}
322
323 \paragraph*{nonzero-digit}
324 \begin{tabular} { c c c c c c c c c }
325         1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
326 \end{tabular}
327
328 \paragraph*{octal-digit}
329 \begin{tabular}{ c c c c c c c c c }
330         0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 \\
331 \end{tabular}
332
333 \paragraph*{hexadecimal-digit}
334 \begin{tabular}{ c c c c c c c c c c c c c c c c }
335         0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & A & B & C & D & E & F \\
336 \end{tabular}
337
338 \paragraph*{floating-constant}
339 \begin{tabular} { l }
340         decimal-floating-constant \\
341         hexadecimal-floating-constant \\
342 \end{tabular}
343
344 \subsubsection{String Literals}
345 \paragraph*{string-literal}
346 \begin{tabular} { l }
347         " s-char-sequence _{opt} " \\
348         \_(" s-char-sequence _{opt} ") \\
349 \end{tabular}
350
351 \subsubsection*{s-char-sequence}
352 \begin{tabular} { l }
353         s-char \\
354         s-char-sequence s-char \\
355 \end{tabular}
356
357 \subsubsection*{s-char}
358 \begin{tabular} { l }
359         any member of the source character set except double-quote, backslash, or new-line characters \\
360         escape-sequence \\
361 \end{tabular}
362
363 \subsubsection{Header names}
364 \paragraph*{header-name}
365 \begin{tabular} { l }
366         < h-char-sequence > \\
367         " q-char-sequence " \\
368 \end{tabular}
369
370 \subsubsection*{h-char-sequence}
371 \begin{tabular} { l }
372         h-char \\
373         h-char-sequence h-char \\
374 \end{tabular}
375
376 \subsubsection*{h-char}
377 \begin{tabular} { l }
378         any member of the source character set except the new-line and > character \\
379 \end{tabular}
380
381 \subsubsection*{q-char-sequence}
382 \begin{tabular} { l }
383         q-char \\
384         q-char-sequence q-char \\
385 \end{tabular}
386
387 \subsubsection*{q-char}
388 \begin{tabular} { l }
389         any member of the source character set except the new-line and " character \\
390 \end{tabular}
391
392 \pagebreak
393
394 \subsubsection{Comments}
395 Except within a character constant, a string literal, or a comment, the characters /* introduce a comment. The contents of such a comment are examined only to find the characters */ that terminate it. (Thus /* .. */ comments do not nest.)
396
397 Expect within a character constant, a string literal, or a comment, the character // introduces a comment that includes all characters up to, but not including, the next new-line character.  The contents of such a comment are examined only to find the terminating new-line character.
398
399 \begin{small}
400 EXAMPLE
401 \end{small}
402 \begin{lstlisting}[language=C]
403 "a//b"             // four-character string literal
404 #include "//e"     // undefined behavior
405 // */              // comment, not syntax error
406 a = b/**//c;       // same as a = b / c;
407 /*//*/ foo();      // same as foo();
408 \end{lstlisting}
409
410 \subsection{Expressions}
411 An expression is a sequence of operators and operands that specifies computation of a value, or that designates an object or function, or that generates side effects, or that performs a combination thereof.
412
413 Between the previous and next sequence point an object shall have its stored value modified at most once by the evaluation of an expression.  Furthermore, the prior value shall be read only to determine the value to be stored.
414
415 The grouping of operators and operands is indicated by the syntax.  Except as specified later (for the function-call(), \&\&, \textpipe\textpipe, ?:, and comma operators), the order of evaluation of subexpressions and the order in which side effects take place are both unspecified.
416
417 Some operators (the unary \~\space, and the binary operators \textless\textless, \textgreater\textgreater, \&, \^\space, and \textpipe, collectively describe as bitwise operators) are required to have operands that have integer type.
418
419 An object shall have its stored value accessed only by an lvalue expression that has one of the following types:
420 \begin{enumerate}
421         \item A type compatible with the effective type of the object,
422         \item A qualified version of a type compatible with the effective type of the object,
423 \end{enumerate}
424
425 \subsubsection{Primary expressions}
426 \paragraph*{Syntax}
427 \begin{tabular}{ l }
428         identifier \\
429         constant \\
430         string-literal \\
431         ( expression )
432 \end{tabular}
433 \paragraph*{Semantics}
434 An identifier is a primary expression, provided it has been declares as a designating object (in which case it is an lvalue) or a function (in which case it is a function designator).
435
436 A constant is a primary expression, with type as detailed in \ref{sec:constants}.
437
438 \subsection{Constant Expressions}
439 \subsubsection{Description}
440 A constant expression can be evaluated during translation rather than runtime, and accordingly can be used in any place that a constant may be.
441 \subsubsection{Constraints}
442 Constant expressions shall not contain assignment, increment, decrement, function-call, or comma operators, except when they're contained within a subexpression that is not evaluated.
443
444 Each constant expression shall evaluate to a constant that is in the range of representable values for it's designated type.
445 \subsubsection{Semantics}
446 An expression that evaluates to a constant is required in several contexts.  If a floating expression is evaluated in the translation environment, the arithmetic precision and range shall be at least as great as if they expression were being evaluated in the execution environment.
447
448 An integer constant expression shall have integral type, and shall only have operands that are integer constants, enumeration constants, character constants, and floating constants that are the immediate operands of casts.
449
450 The semantic rules for the evaluation of a constant expression are the same as for nonconstant expressions.
451
452 An implementation may accept other forms of constant expressions
453 \subsection{Declarations}
454 \subsubsection{Constraints}
455 All declarations shall declare at least a declarator (other than the parameters of a function), a tag, or members of an enumeration.
456
457 All declarations in the same scope that refer to the same object or function shall specify compatible types.
458 \subsubsection{Semantics}
459 A declaration specifies the interpretation and attributes of a set of identifiers.  A definition of an identifier is a declaration for that identifier that:
460 \begin{enumerate}
461         \item for an object, causes storage to be reversed for that object;
462         \item for a function, includes the function body;
463         \item for an enumeration constant or typedef name, is the (only) declaration of the identifier.
464 \end{enumerate}
465
466
467 \subsection{Statement and blocks}
468 A statement specifies a specific action to be preformed.  Execpt as indicated, statements are executed in sequence.
469
470 \end{document}