quakeforge/tools/qfcc/doc/qfcc.lyx

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 218
\textclass article
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Standard

This is currently just new stuff in 
\family typewriter 
\series bold 
qfcc
\family default 
\series default 
.
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Section

New Type Features
\layout Subsection

New Types
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
integer
\family default 
 32 bit signed integer
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
id
\family default 
 generic object pointer
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Class
\family default 
 class object pointer
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Protocol
\family default 
 protocol object pointer
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Method
\family default 
 method pointer
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
SEL
\family default 
 selector
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
IMP
\family default 
 message imlementation
\layout Standard


\family typewriter 
id
\family default 
, 
\family typewriter 
Class
\family default 
, 
\family typewriter 
Protocol
\family default 
, 
\family typewriter 
Method
\family default 
, 
\family typewriter 
SEL
\family default 
 and 
\family typewriter 
IMP
\family default 
 are part of 
\family typewriter 
\series bold 
qfcc
\family default 
\series default 
's Objective-QC extensions.
\layout Subsection

Enums
\layout Standard

as per C
\layout Subsection

Structures
\layout Verse


\family typewriter 
struct foo {
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
integer bar;
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
float baz;
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
void () func;
\newline 
};
\layout Standard

Structures with no elements can be declared for making opaque types (particularl
y useful for engine interface functions).
\layout Subsection

Arrays
\layout Verse


\family typewriter 
integer [13] array;
\layout Subsection

Pointers
\layout Standard

Pointers are declared the same way as arrays, but with no number in the
 
\family typewriter 
[]
\family default 
s.
 In fact, arrays are just pointers with limited bounds checking (compile
 time constant indeces).
\layout Subsection

Complex types
\layout Standard

Complex types can be created by nesting type declarations within 
\family typewriter 
()
\family default 
s.
 eg:
\layout Verse


\family typewriter 
(.float) (string name) find_field;
\layout Standard

declares a function (
\family typewriter 
find_field
\family default 
) taking a string parameter and returning a float field `offset'.
 Without the 
\family typewriter 
()
\family default 
s around the 
\family typewriter 
.float
\family default 
, the declaration would be a function field.
\layout Subsection


\family typewriter 
typedef
\layout Standard

By using 
\family typewriter 
typedef
\family default 
 complex types can be given symbolic names.
 eg:
\layout Verse


\family typewriter 
struct foo_s {};
\newline 
typedef foo_s [] foo_t;
\layout Standard

creates type 
\family typewriter 
foo_t
\family default 
 which is a pointer to the structure 
\family typewriter 
foo_s
\family default 
 (which happens to be opaque).
\layout Subsection

vararg functions
\layout Standard

Typed parameters preceding the ellipsis are allowed, eg: 
\family typewriter 
void (string fmt, ...) printf;
\layout Standard

More importantly, it is now possible to write vararg functions in QC.
 
\family typewriter 
@argc
\family default 
 gives the number of parameters passed throug the ellipsis and 
\family typewriter 
@argv
\family default 
 is an array of vectors representing the parameters passed through 
\family typewriter 
...
\family default 
.
\layout Standard


\series bold 
\emph on 
Warning: attempting to pass 
\family typewriter 
@argv
\family default 
 to another non-engine function will not work due to the changes in how
 local variables are handled by the compiler.
\layout Subsection

Improved type checking
\layout Standard

Function parameters and return types are are fully checked, including the
 number of parameters passed to a function.
 Functions with different return types and/or different parameter types
 or counts are distinct types and mixing them up will cause a type missmatch
 error.
 Similar for pointers to various types.
\layout Section

Variables
\layout Subsection

Local variables
\layout Subsubsection

Initialization
\layout Standard

Local variables of basic types can now be initialized when declared.
 eg
\layout Verse


\family typewriter 
local integer elite = 31337;
\layout Subsubsection

Unused variables
\layout Standard

Local variables that are declared but not used produce a warning.
\layout Subsubsection

Uninitialized variables
\layout Standard

Checks are done to ensure that local variables have been initialized before
 being used.
 However, these checks are not perfect and false positives are very likely
 in complex code.
 Occurances of false negatives are not known, but the possibility of their
 existance remains and any examples of false negatives should be reported
 as bugs.
\layout Subsection

Complex global variables
\layout Standard

Global array variables can be initialized using 
\family typewriter 
= { 
\emph on 
elementlist
\emph default 
 };
\family default 
.
 Element lists may be nested using 
\family typewriter 
{}
\family default 
.
 Structures cannot currently be initialized, but this is a FIXME :)
\layout Subsection

Magic variables
\layout List
\labelwidthstring 00.00.0000

@self Automagicly declared entity variable the engine will use for 
\family typewriter 
touch
\family default 
 and 
\family typewriter 
think
\family default 
 functions.
 This allows 
\family typewriter 
self
\family default 
 to be used as the object hidden parameter in methods.
\layout List
\labelwidthstring 00.00.0000

@this Automagicly declared 
\family typewriter 
id
\family default 
 field that the engine expects to point to the object associated with the
 entity.
 The engine will use this field, if it exists, to set the 
\family typewriter 
self
\family default 
 parameter to 
\family typewriter 
touch
\family default 
 and 
\family typewriter 
think
\family default 
 methods (the engine assumes it's calling a method rather than a function
 if the @this field is used.
\layout List
\labelwidthstring 00.00.0000

@argc Number of parameters passed through 
\family typewriter 
...

\family default 
 in vararg functions.
 Not valid elsewhere.
\layout List
\labelwidthstring 00.00.0000

@argv Array of vectors representing the parameters passed through 
\family typewriter 
...

\family default 
 in vararg functions.
 Not valid elsewhere.
\layout Section

Code constructs
\layout Subsection


\family typewriter 
break
\layout Standard

The 
\family typewriter 
break
\family default 
 statement can be used to leave a loop (
\family typewriter 
while
\family default 
, 
\family typewriter 
do
\family default 
 ...
 
\family typewriter 
while
\family default 
, or 
\family typewriter 
for
\family default 
) prematurely.
 The 
\family typewriter 
break
\family default 
 statement is also used to leave a 
\family typewriter 
switch
\family default 
 statement.
\layout Subsection


\family typewriter 
continue
\layout Standard

The 
\family typewriter 
continue
\family default 
 statement is used to jump to the beginning of a loop.
 In 
\family typewriter 
for
\family default 
 loops, the test and post expressions are evaluated before continuing with
 the loop.
\layout Subsection


\family typewriter 
for
\layout Standard

The 
\family typewriter 
for
\family default 
 loop is:
\layout Verse


\family typewriter 
for (
\emph on 
initialization\SpecialChar ~
expression
\emph default 
; 
\emph on 
test\SpecialChar ~
expression
\emph default 
; 
\emph on 
post\SpecialChar ~
expression
\emph default 
)
\emph on 

\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
statement
\layout Standard

and is equivalent to
\layout Verse


\family typewriter 
\emph on 
initialization\SpecialChar ~
expression
\emph default 

\newline 
while (
\emph on 
test\SpecialChar ~
expression
\emph default 
) {
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~

\emph on 
statement
\emph default 

\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~

\emph on 
post\SpecialChar ~
expression
\emph default 

\newline 
}
\layout Subsection


\family typewriter 
switch
\layout Standard

The 
\family typewriter 
switch
\family default 
 statement is used to select between multiple code blocks based on the value
 of an expression.
\layout Verse


\family typewriter 
switch (
\emph on 
test\SpecialChar ~
expression
\emph default 
) {
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
case
\emph on 
 value
\emph default 
:
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~

\emph on 
optional\SpecialChar ~
statements
\emph default 

\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
case
\emph on 
 value
\emph default 
:
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~

\emph on 
optional\SpecialChar ~
statements
\emph default 

\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
default:
\newline 
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~

\emph on 
optional\SpecialChar ~
statements
\emph default 

\newline 
}
\layout Standard

Code execution starts at the selected 
\family typewriter 
case
\family default 
 and continues on to the end of the switch block.
 Following 
\family typewriter 
case
\family default 
s do 
\emph on 
not
\emph default 
 affect code execution.
 If this behaviour is not desired, as is usual, then a 
\family typewriter 
break
\family default 
 statement is required to cause the code to jump to the end of the 
\family typewriter 
switch
\family default 
, skipping any intervening code.
 That is, just like C.
\layout Subsubsection


\family typewriter 
\emph on 
test expression
\layout Standard

The test expression may result in a float, string or integer value.
\layout Subsubsection


\family typewriter 
case 
\emph on 
value
\layout Verse


\family typewriter 
case 
\emph on 
value
\emph default 
:
\layout Standard

The case value may be of any constant type consistent with the test expression
 of the 
\family typewriter 
switch
\family default 
.
\layout Subsubsection


\family typewriter 
default
\layout Standard

If specified, this is where execution will go when no 
\family typewriter 
case
\family default 
 has been selected by the test expression.
 If not specified, and no 
\family typewriter 
case
\family default 
 has been selected by the test expression, the 
\family typewriter 
switch
\family default 
 does not execute any code within the block.
\layout Section

Expressions
\layout Subsection

Binary
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
<<\SpecialChar ~
>>
\family default 
 bit shift left and right
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
^
\family default 
 bitwise exclusive or
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
%
\family default 
 modulus
\layout Subsubsection

Assignment
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
op
\emph default 
= 
\family default 
equivalent to 
\family typewriter 
a = a 
\emph on 
op 
\emph default 
b
\family default 
.
\layout Subsection

Unary
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
~
\family default 
 bitwise not
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
&
\family default 
 address
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
++
\emph on 
e
\emph default 
\SpecialChar ~
--
\emph on 
e
\family default 
\emph default 
 pre increment and decrement
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
e
\emph default 
++\SpecialChar ~

\emph on 
e
\emph default 
--
\family default 
 post increment and decrement
\layout Subsection

Other
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
type\SpecialChar ~

\emph default 
(
\emph on 
expr
\emph default 
)
\family default 
 cast expression.
 Only works for converting between integer and float types and between pointer
 types.
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
expr
\emph default 
[
\emph on 
expr
\emph default 
] 
\family default 
array indexing.
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
expr
\emph default 
?
\emph on 
expr
\emph default 
:
\emph on 
expr 
\family default 
\emph default 
C's trinary expression
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
[
\emph on 
expr
\emph default 
\SpecialChar ~

\emph on 
exprs
\emph default 
]
\family default 
 Objective-QC message
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
@selector(
\emph on 
exprs
\emph default 
)
\family default 
 Objective-QC selector expression
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
@protocol(
\emph on 
name
\emph default 
)
\family default 
 Objective-QC protocol expression
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
@encode(
\emph on 
type
\emph default 
)
\family default 
 Objective-QC type encoding expression
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
@
\emph on 
string
\family default 
\emph default 
 Objective-QC string object.
 Currently identical to a normal QC string.
\the_end