Update doc/specification.tex
[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
7 \definecolor{dkgreen}{rgb}{0,0.6,0}
8 \definecolor{gray}{rgb}{0.5,0.5,0.5}
9 \definecolor{mauve}{rgb}{0.58,0,0.82}
10
11 % set listings colors
12 \lstset{ %
13   backgroundcolor=\color{white},  % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}
14   basicstyle=\footnotesize,       % the size of the fonts that are used for the code
15   breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
16   breaklines=true,                % sets automatic line breaking
17   captionpos=b,                   % sets the caption-position to bottom
18   commentstyle=\color{dkgreen},   % comment style
19   deletekeywords={...},           % if you want to delete keywords from the given language
20   escapeinside={\%*}{*)},         % if you want to add LaTeX within your code
21   keywordstyle=\color{blue},      % keyword style
22   language=C,                % the language of the code
23   morekeywords={entity,local},           % if you want to add more keywords to the set
24   numbers=left,                   % where to put the line-numbers; possible values are (none, left, right)
25   numbersep=5pt,                  % how far the line-numbers are from the code
26   numberstyle=\tiny\color{gray},  % the style that is used for the line-numbers
27   rulecolor=\color{black},        % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
28   showspaces=false,               % show spaces everywhere adding particular underscores; it overrides 'showstringspaces'
29   showstringspaces=false,         % underline spaces within strings only
30   showtabs=false,                 % show tabs within strings adding particular underscores
31   stepnumber=1,                   % the step between two line-numbers. If it's 1, each line will be numbered
32   stringstyle=\color{mauve},      % string literal style
33   tabsize=2,                      % sets default tabsize to 2 spaces
34   title=\lstname                  % show the filename of files included with \lstinputlisting; also try caption instead of title
35 }
36
37 \topmargin -1.5cm        % read Lamport p.163
38 \oddsidemargin -0.04cm   % read Lamport p.163
39 \evensidemargin -0.04cm
40
41 \textwidth 16.59cm
42 \textheight 21.94cm 
43 \parskip 7.2pt                         % spacing between paragraphs
44 \renewcommand{\baselinestretch}{1.5}    % 1.5 spacing between lines
45 \parindent 0pt                              % leading space for paragraphs
46 \title{The GMQCC Quake C Programming Language}
47 \author{Dale Weiler, Wolfgang Bullimer}
48
49 % subscript and superscript in text mode require
50 % strange uses of math expression scripting, which
51 % is unusable, these macros implement it using math
52 % expressions, and reimplement ^ and _ to work in
53 % text mode :-)
54 \makeatletter
55 \newcommand\textsubscript[1]{\@textsubscript{\selectfont#1}}
56 \def\@textsubscript#1{{\m@th\ensuremath{_{\mbox{\fontsize\sf@size\z@#1}}}}}
57 \newcommand\textbothscript[2]{%
58   \@textbothscript{\selectfont#1}{\selectfont#2}}
59 \def\@textbothscript#1#2{%
60   {\m@th\ensuremath{%
61     ^{\mbox{\fontsize\sf@size\z@#1}}%
62     _{\mbox{\fontsize\sf@size\z@#2}}}}}
63 \def\@super{^}\def\@sub{_}
64
65 \catcode`^\active\catcode`_\active
66 \def\@super@sub#1_#2{\textbothscript{#1}{#2}}
67 \def\@sub@super#1^#2{\textbothscript{#2}{#1}}
68 \def\@@super#1{\@ifnextchar_{\@super@sub{#1}}{\textsuperscript{#1}}}
69 \def\@@sub#1{\@ifnextchar^{\@sub@super{#1}}{\textsubscript{#1}}}
70 \def^{\let\@next\relax\ifmmode\@super\else\let\@next\@@super\fi\@next}
71 \def_{\let\@next\relax\ifmmode\@sub\else\let\@next\@@sub\fi\@next}
72 \makeatother
73
74 % set standard paper sizes
75 \setlength{\paperheight}{11in}
76 \setlength{\paperwidth}{8.5in}
77  
78 \begin{document}
79 \maketitle
80 \pagebreak
81 \tableofcontents
82 \pagebreak
83 \section {Terms and definitions}
84 \subsection*{object}
85 A region of data storage in the execution environment, the contents of which can represent values.
86 \subsection*{implementation}
87 A 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 (typically a Quake engine).
88 \subsection*{argument}
89 Expression in the comma-separated list bounded by the parentheses in a function call expression, or a sequence of preprocessing tokens in the comma-separated list bounded by the parentheses in a function-like macro invocation.
90 \subsection*{parameter}
91 Object declared as part of a function declaration or definition that acquires a value on entry to the function, or an identifier from the comma-separated list bound by the parentheses immediately following the macro name in a function-like macro definition.
92 \subsection*{value}
93 Precise meaning of the contents of an object when interpreted as having a specific type.
94
95 \section{Conceptual models}
96 \subsection{Translation environment}
97 \subsubsection{Program structure}
98 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.
99
100 \subsubsection{Translation phases}
101 \begin{enumerate}
102         \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.
103         \item The source file is decomposed into preprocessing tokens and sequences of white-space characters (including comments).
104         \item Preprocessing directives are executed and macro invocations expanded recursively.
105         \item Each escape sequence in character constants and string literals is converted to a member of the execution character set.
106         \item Adjacent character string literal tokens are concatenated.
107         \item White-space characters separating tokens are no longer sufficient. The resulting tokens are syntactically and semantically analyzed and translated.
108 \end{enumerate}
109
110 \subsection{Execution environment}
111 \section{Environmental considerations}
112 \subsection{Runtime considerations}
113 TODO
114 \pagebreak
115
116 \section{Notation}
117 \subsection{Document notation}
118 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\\
119 \{ expression _{opt} \}\\
120 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.
121 \subsection{Language notation}
122 TODO
123
124 \section{Concepts}
125 \subsection{Scopes of identifiers}
126 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.
127
128 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.)
129
130 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).
131
132 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.
133
134 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.
135
136 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.
137
138 Two identifiers have the same scope if and only if their scopes terminate at the same point.
139
140 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.
141
142 \subsection{Name spaces of identifiers}
143 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:
144 \begin{enumerate}
145         \item label names (disambiguated by the syntax of the label declaration and use);
146         \item the tags of enumerations
147         \item all other identifiers, called ordinary identifiers (declared in ordinary declarators or as enumeration constants).
148 \end{enumerate}
149
150 \subsection{Types}
151 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).
152
153 An object declares as type bool is large enough to store the values 0 and 1.
154
155 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.
156
157 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.
158
159 The void type comprises an empty set of values; it is an incomplete type that cannot be completed.
160
161 The float and vector type .. TODO
162
163 An enumeration comprises a set of named integer constant values.  Each enumeration constitutes a different enumerated type.
164
165 \section{Lexical elements}
166 \subsection{Keywords}
167 \begin{tabular} { l l l l l }
168         for & do & while & if & else \\
169         local & return & const & switch & case \\
170         default & struct & union & break & continue \\
171         typedef & goto & namespace \\
172 \end{tabular}
173
174 \subsection{Identifiers}
175 \subsubsection*{identifier}
176 \begin{tabular} { l }
177         identifier-nondigit \\
178         identifier identifier-nondigit \\
179         identifier-digit \\
180 \end{tabular}
181
182 \subsubsection*{identifier-nondigit}
183 \begin{tabular} { l }
184         nondigit \\
185         other implementation-defined characters \\
186 \end{tabular}
187
188 \subsubsection*{nondigit}
189 \begin{tabular}{ c c c c c c c c c c c c c c c c c c c c }
190         \_ & a & b & c & d & e & f & g & h & i & j & k & l & m & n & o & p & q & r & s \\
191         t & u & v & w & y & z & A & B & C & D & E & F & G & H & I & J & K & L & M & N \\
192         O & P & Q & R & S & T & U & V & W & X & Y & Z \\
193 \end{tabular}
194
195 \subsubsection*{digit}
196 \begin{tabular}{c c c c c c c c c c c }
197         0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
198 \end{tabular}
199
200 \subsubsection*{hex-quad}
201 \begin{tabular} { l }
202         hexadecimal-digit hexadecimal-digit \\
203 \end{tabular}
204
205 \subsection{Constants}
206 \subsubsection*{constant}
207 \begin{tabular} { l }
208         integer-constant \\
209         floating-constant \\
210         enumeration-constant \\
211         character-constant \\
212         vector-constant \\
213 \end{tabular}
214
215 \subsubsection*{integer-constant}
216 \begin{tabular} { l }
217         decimal-constant \\
218         octal-constant \\
219         hexadecimal-constant \\
220 \end{tabular}
221
222 \subsubsection*{decimal-constant}
223 \begin{tabular} { l }
224         nonzero-digit \\
225         decimal-constant digit \\
226 \end{tabular}
227
228 \subsubsection*{octal-constant}
229 \begin{tabular} { l }
230         0 \\
231         octal-constant octal-digit
232 \end{tabular}
233
234 \subsubsection*{hexadecimal-constant}
235 \begin{tabular} { l }
236         hexadecimal-prefix hexadecimal-digit \\
237         hexadecimal-constant hexadecimal-digit \\
238 \end{tabular}
239
240 \subsubsection*{hexadecimal-prefix}
241 \begin{tabular} { c c }
242         0x & 0X \\
243 \end{tabular}
244
245 \subsubsection*{nonzero-digit}
246 \begin{tabular} { c c c c c c c c c }
247         1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
248 \end{tabular}
249
250 \subsubsection*{octal-digit}
251 \begin{tabular}{ c c c c c c c c c }
252         0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 \\
253 \end{tabular}
254
255 \subsubsection*{hexadecimal-digit}
256 \begin{tabular}{ c c c c c c c c c c c c c c c c }
257         0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & A & B & C & D & E & F \\
258 \end{tabular}
259
260 \subsubsection*{floating-constant}
261 \begin{tabular} { l }
262         decimal-floating-constant \\
263         hexadecimal-floating-constant \\
264 \end{tabular}
265
266 \subsection{String Literals}
267 \subsubsection*{string-literal}
268 \begin{tabular} { l }
269         " s-char-sequence _{opt} " \\
270         \_(" s-char-sequence _{opt} ") \\
271 \end{tabular}
272
273 \subsubsection*{s-char-sequence}
274 \begin{tabular} { l }
275         s-char \\
276         s-char-sequence s-char \\
277 \end{tabular}
278
279 \subsubsection*{s-char}
280 \begin{tabular} { l }
281         any member of the source character set except double-quote, backslash, or new-line characters \\
282         escape-sequence \\
283 \end{tabular}
284
285 \subsection{Header names}
286 \subsubsection*{header-name}
287 \begin{tabular} { l }
288         < h-char-sequence > \\
289         " q-char-sequence " \\
290 \end{tabular}
291
292 \subsubsection*{h-char-sequence}
293 \begin{tabular} { l }
294         h-char \\
295         h-char-sequence h-char \\
296 \end{tabular}
297
298 \subsubsection*{h-char}
299 \begin{tabular} { l }
300         any member of the source character set except the new-line and > character \\
301 \end{tabular}
302
303 \subsubsection*{q-char-sequence}
304 \begin{tabular} { l }
305         q-char \\
306         q-char-sequence q-char \\
307 \end{tabular}
308
309 \subsubsection*{q-char}
310 \begin{tabular} { l }
311         any member of the source character set except the new-line and " character \\
312 \end{tabular}
313
314 \pagebreak
315
316 \subsection{Comments}
317 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.)
318
319 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.
320
321 \begin{small}
322 EXAMPLE
323 \end{small}
324 \begin{lstlisting}[language=C]
325 "a//b"             // four-character string literal
326 #include "//e"     // undefined behavior
327 // */              // comment, not syntax error
328 a = b/**//c;       // same as a = b / c;
329 /*//*/ foo();      // same as foo();
330 \end{lstlisting}
331
332 \section{Expressions}
333 TODO
334
335 \section{Constant Expressions}
336 \subsection{Description}
337 A constant expression can be evaluated during translation rather than runtime, and accordingly can be used in any place that a constant may be.
338 \subsection{Constraints}
339 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.
340
341 Each constant expression shall evaluate to a constant that is in the range of representable values for it's designated type.
342 \subsection{Semantics}
343 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.
344
345 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.
346
347 The semantic rules for the evaluation of a constant expression are the same as for nonconstant expressions.
348
349 An implementation may accept other forms of constant expressions
350 \section{Declarations}
351 \subsection{Constraints}
352 All declarations shall declare at least a declarator (other than the parameters of a function), a tag, or members of an enumeration.
353
354 All declarations in the same scope that refer to the same object or function shall specify compatible types.
355 \subsection{Semantics}
356 A declaration specifies the interpretation and attributes of a set of identifiers.  A definition of an identifier is a declaration for that identifier that:
357 \begin{enumerate}
358         \item for an object, causes storage to be reversed for that object;
359         \item for a function, includes the function body;
360         \item for an enumeration constant or typedef name, is the (only) declaration of the identifier.
361 \end{enumerate}
362
363
364 \section{Statement and blocks}
365 A statement specifies a specific action to be preformed.  Execpt as indicated, statements are executed in sequence.
366
367 \section{Preprocessing directives}
368 TODO
369
370 \end{document}