#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass scrbook
\language american
\inputencoding latin1
\fontscheme pslatex
\graphics dvips
\float_placement htb
\paperfontsize 12
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1in
\topmargin 1in
\rightmargin 0.5in
\bottommargin 1in
\secnumdepth 2
\tocdepth 2
\paragraph_separation skip
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 2
\paperpagestyle headings

\layout Title

The Ruamoko Programming Language
\layout Author

Bill Currie 
\begin_inset Formula $\bullet$
\end_inset 

 Jeff Teunissen
\layout Publishers

QuakeForge Press
\layout Uppertitleback

This manual is free; you can redistribute it and/or modify it under the
 terms of the GNU General Public License as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any later
 version.
\newline 

\newline 
This manual is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.
 See the GNU General Public License for more details.
\newline 

\newline 
You should have received a copy of the GNU General Public License along
 with this manual: if not, write to:
\newline 

\newline 
Free Software Foundation, Inc.
\newline 
59 Temple Place - Suite 330
\newline 
Boston MA 02111-1307
\newline 
USA
\layout Lowertitleback

Copyright © 2002-2003 Bill Currie and Jeff Teunissen
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Addchap

Preface
\layout Standard

In December 1996, Id Software released 
\emph on 
Quake
\emph default 
 to the world.
 It's doubtful that they knew at the time that it would spark a revolution
 -- but such a revolution happened.
 To the game industry's surprise, people were getting the game not just
 to play it, but to 
\emph on 
change
\emph default 
 it\SpecialChar \@.
 For the first time, people could make whole new games based on the Quake
 engine without having to rewrite the whole game -- and in fact you couldn't
 rewrite the whole game, because the main source code wasn't available to
 the general public.
 What 
\series bold 
was
\series default 
 available was something new -- the game wasn't just a game, it was a virtual
 machine that had a byte-code instruction set -- and it had a compiler that
 you could use to make new games to run inside that engine.
 The language (called 
\emph on 
QuakeC
\emph default 
) was kind of crude, and the compiler was even more crude -- but it was
 a revolutionary development.
\layout Standard

Now, let's fast-forward to another December -- this time, three years later.
 In another revolutionary move, Id Software released the source code to
 the complete Quake engine.
 This gave many people the opportunity to do a lot more than just make 
\begin_inset Quotes eld
\end_inset 

mods
\begin_inset Quotes erd
\end_inset 

 for Quake.
 Instead, people could make all-new games without using Quake itself.
 Many projects started up around this source code, with many aims\SpecialChar \ldots{}
but one
 project grew to be the most dominant: That project is 
\emph on 
QuakeForge
\emph default 
.
\layout Standard

QuakeForge has developed a number of interesting things involving the Quake
 engine, but most of them are beyond the scope of this manual.
 This manual documents the 
\emph on 
Ruamoko
\begin_inset Foot
collapsed true

\layout Standard

The name Ruamoko comes from the Maori name for their god of volcanoes and
 earthquakes.
 According to myth, Ruamoko is not yet born, and when he shakes inside the
 Earth-mother, the world trembles.
\end_inset 


\emph default 
 language, a language based on Id Software's QuakeC, but which has been
 expanded in ways far beyond the original language.
\layout Standard

The idea behind this book is to give new programmers a solid foundation
 in both of the programming models (procedural and object-oriented) supported
 by the Ruamoko language, while giving experienced Ruamoko programmers a
 complete reference for development of game code.
\layout Standard


\begin_inset FloatList figure

\end_inset 


\layout Part

Classical Programming in Ruamoko
\layout Chapter


\begin_inset LatexCommand \label{cha:A-Tutorial-Introduction}

\end_inset 

Introduction: Foot, Meet Mister Rocket Launcher
\layout Standard

Let us begin with a quick introduction to Ruamoko.
 Our aim here is to show the basic elements of the language in real programs,
 but without getting bogged down in details or rules.
 At this point, we're not even trying to be complete, or even precise (except
 that the examples are meant to be correct).
 We want to get you as quickly as possible to the point where you can write
 useful programs, and to do that we have to concentrate on the basics: variables
 and constants, arithmetic, flow control, functions, and the rudiments of
 input and output.
 We are intentionally leaving out of this chapter features of Ruamoko that
 are important for writing bigger programs, or programs to run in an actual
 Quake engine.
 These include entities, structures, pointers, most of the operators, objects,
 and the standard builtin library.
\layout Standard

This approach has its drawbacks.
 Most notable is that the complete story on any particular language feature
 is not found here, and the brief tutorial, just by being brief, may be
 misleading.
 And because the examples don't use the full power of Ruamoko, they may
 not be as elegant or concise as they could be; we 
\series bold 
have
\series default 
 tried to minimize these effects, but be warned.
 Another drawback is that later chapters will repeat some of what's presented
 here.
 We hope that the repetition will help more than it annoys.
\layout Standard

In any case, experienced programmers should be able to get an idea, from
 this chapter, of some of the things that can be done in Ruamoko, for their
 own needs.
 Beginners should supplement it by writing small, similar programs of their
 own.
 Both groups can use it as a framework on which to hang the more detailed
 descriptions that begin in later chapters.
\layout Section

Getting Started
\layout Standard

The best way to learn a new programming language is by writing programs
 in it.
 The first program one writes is almost always the same for all new languages:
 print the phrase 
\begin_inset Quotes eld
\end_inset 

Hello, world!
\begin_inset Quotes erd
\end_inset 

 on the screen.
\layout Standard

This is the big hurdle.
 To get past it, you have to be able to create the program text somewhere,
 compile it, load it successfully, load it, run it, and find out where the
 output went.
 With these mechanical details mastered, everything else is relatively easy.
\layout Standard


\begin_inset Float figure
wide false
collapsed true

\layout LyX-Code
\line_top \line_bottom 

\begin_inset Include \verbatiminput{hello.r}
preview false

\end_inset 


\layout Caption


\begin_inset LatexCommand \label{cap:Hello-World}

\end_inset 


\begin_inset Quotes eld
\end_inset 

Hello World
\begin_inset Quotes erd
\end_inset 


\end_inset 

A Ruamoko program that does this simple task is found in Figure 
\begin_inset LatexCommand \vref{cap:Hello-World}

\end_inset 

.
 To run this program, you first have to compile it.
 To compile it, you need to save the source code into a file (for example,
 
\family typewriter 
hello.r
\family default 
), then compile it with the command 
\family typewriter 
\series bold 
qfcc -o qwaq.dat hello.r
\family default 
\series default 
.
\layout Standard

If you haven't screwed anything up, such as omitting a character or misspelling
 something, the compilation will proceed.
 You should be rewarded with something that looks something like Figure
 
\begin_inset LatexCommand \vref{cap:qfcc-output}

\end_inset 

.
\begin_inset Float figure
wide false
collapsed true

\layout LyX-Code

  
\begin_inset Include \verbatiminput{qfcc-output.txt}
preview false

\end_inset 


\layout Caption


\family typewriter 

\begin_inset LatexCommand \label{cap:qfcc-output}

\end_inset 


\series bold 
qfcc
\family default 
\series default 
 output
\end_inset 


\layout Standard

You run 
\family typewriter 
qwaq.dat
\family default 
 by issuing the command 
\family typewriter 
\series bold 
qwaq
\family default 
\series default 
.
 The program should print 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
Hello, world!
\family default 

\begin_inset Quotes erd
\end_inset 

 to your screen.
\layout Standard

Now, for some explanations regarding the program itself.
 All Ruamoko programs, regardless of size, consist mainly of 
\emph on 
functions
\emph default 
 and 
\emph on 
variables
\emph default 
.
 A function contains statements that tell the compiler what computing operations
 you want to do, and variables store values used during the operation of
 the program.
 Ruamoko functions are roughly equivalent to C's functions, or Pascal's
 procedures and functions.
 Our example is a function called 
\family typewriter 
main
\family default 
.
 You can create functions with just about any name you like, but 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
main
\family default 

\begin_inset Quotes erd
\end_inset 

 is special -- program execution begins there
\begin_inset Foot
collapsed true

\layout Standard

This is not precisely true.
 When used in a game engine, there are certain other functions that are
 called by the engine during the course of a game.
\end_inset 

.
 This means that every program must have a 
\family typewriter 
main
\family default 
 function somewhere.
\layout Standard

The main function will usually call other functions to do its job -- some
 of them you write, and some of them are provided by the virtual machine
 your program runs inside.
 The first lines of the program (the ones beginning with 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
#include
\family default 

\begin_inset Quotes erd
\end_inset 

) tell the compiler to include information about the standard variables,
 constants, 
\emph on 
fields
\emph default 

\begin_inset LatexCommand \index{fields}

\end_inset 

, and 
\emph on 
engine functions
\begin_inset Foot
collapsed true

\layout Standard

also known as 
\emph on 
builtins
\emph default 
.
\end_inset 


\emph default 

\begin_inset LatexCommand \index{functions, engine}

\end_inset 

 provided by the environment
\begin_inset Foot
collapsed true

\layout Standard

The environment will be described later.
\end_inset 

.
\layout Standard

One way of communicating data between functions is for the calling function
 to provide a list of values, called 
\emph on 
arguments
\emph default 

\begin_inset LatexCommand \index{arguments}

\end_inset 

, to the function it calls.
 The parentheses after the function's name surround the 
\emph on 
argument list
\emph default 

\begin_inset LatexCommand \index{argument list}

\end_inset 

.
 In this example, main is defined to be a function that expects no arguments,
 which is indicated by an empty list:\SpecialChar ~

\family typewriter 
()
\family default 
.
\layout Standard

The statements of a function are enclosed in curly braces,\SpecialChar ~

\family typewriter 
{}
\family default 
.
 The function 
\family typewriter 
main
\family default 
 contains only one statement,
\family typewriter 
 printf ("Hello, world!
\backslash 
n")
\family default 
.
 This is a 
\emph on 
function call
\emph default 
, which transfers control from one function to another.
 A function is called by giving its name, followed by a list of arguments
 enclosed by parentheses, so this calls the function 
\family typewriter 
printf
\family default 
 with the argument 
\family typewriter 
"Hello, world!
\backslash 
n"
\family default 
.
 
\family typewriter 
printf
\family default 
 is an engine function that prints output, in this case the string of characters
 between the quotes.
\layout Standard

A sequence of characters between double quotes, like 
\family typewriter 
"Hello, world!
\backslash 
n"
\family default 
, is called a 
\emph on 
string constant
\emph default 
 or simply a 
\emph on 
string
\emph default 
.
 For the moment, our only use of strings will be as arguments for 
\family typewriter 
printf
\family default 
 and other functions.
\layout Standard

The sequence 
\family typewriter 

\backslash 
n
\family default 
 in the string is Ruamoko notation for the 
\emph on 
newline character
\emph default 
, which when printed tells the terminal (or a game client) to advance to
 the next line in the output.
 If you leave out the 
\family typewriter 

\backslash 
n
\family default 
, you will find that there is no advance after the character string is printed.
 You must use 
\family typewriter 

\backslash 
n
\family default 
 to include a newline character in the printf argument; if you try to insert
 a newline yourself into the string, the Ruamoko compiler will give you
 an error message when you compile the program.
\layout Standard


\begin_inset Float figure
wide false
collapsed true

\layout LyX-Code
\line_top \line_bottom 

\begin_inset Include \verbatiminput{hello2.r}
preview false

\end_inset 


\layout Caption


\begin_inset LatexCommand \label{cap:A-different-Hello}

\end_inset 

A different 
\begin_inset Quotes eld
\end_inset 

Hello World
\begin_inset Quotes erd
\end_inset 


\end_inset 

The 
\family typewriter 
printf()
\family default 
 function never supplies a newline automatically, so several calls may be
 used to build up an output line in stages.
 Our first program could just as easily been written as it is in figure
 
\begin_inset LatexCommand \vref{cap:A-different-Hello}

\end_inset 

, and it would have produced identical output.
\layout Standard

Note that 
\family typewriter 

\backslash 
n
\family default 
 represents only a single character.
 An 
\emph on 
escape character
\emph default 
 like 
\family typewriter 

\backslash 
n
\family default 
 gives you a general way to express hard-to-type or invisible characters.
 Among the others are 
\family typewriter 

\backslash 
t
\family default 
 for a tab, 
\family typewriter 

\backslash 
b
\family default 
 for a backspace, 
\family typewriter 

\backslash 
"
\family default 
 for a double-quote, and 
\family typewriter 

\backslash 

\backslash 

\family default 
 for the backslash character itself.
 There is a complete list in [section]
\layout Section

Variables and Mathematical Expressions
\layout Standard


\begin_inset Float figure
wide false
collapsed true

\layout LyX-Code
\line_top \line_bottom 

\begin_inset Include \verbatiminput{radians.r}
preview false

\end_inset 


\layout Caption


\begin_inset LatexCommand \label{cap:Degrees-to-radians}

\end_inset 

Degrees to radians
\end_inset 

In figure 
\begin_inset LatexCommand \vref{cap:Degrees-to-radians}

\end_inset 

, we find a simple program uses the formula 
\begin_inset Formula $R=D\,\times\,(\frac{\pi}{180})$
\end_inset 

 to print a table of various angles in both their degrees and radian equivalents.
\layout Standard

The line 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
/* Print a silly conversion table between degrees and radians */
\family default 

\begin_inset Quotes erd
\end_inset 

 and the three parts that say things like 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
// lower limit
\family default 

\begin_inset Quotes erd
\end_inset 

 are 
\emph on 
comments
\emph default 

\begin_inset LatexCommand \index{comments}

\end_inset 

.
 Characters between 
\family typewriter 
/*
\family default 
 and 
\family typewriter 
*/
\family default 
, and anything between 
\family typewriter 
//
\family default 
 and the next line, are ignored by the compiler; they may be used freely
 to make a program easier for humans to understand.
 Comments may appear anywhere a blank space, or a tab, or a newline can.
\layout Standard

In Ruamoko, all variables must be declared before they are used., usually
 at the beginning of the function before any statements.
 A declaration
\begin_inset LatexCommand \index{declaration, variable}

\end_inset 

 announces the properties of variables to the compiler; it consists of a
 type name and a list of one or more variables, such as
\layout LyX-Code

float   degrees, radians;
\newline 
integer lower, upper, step;
\layout Standard

The type 
\family typewriter 
float
\family default 
 means that the 
\family typewriter 
degrees
\family default 
 and 
\family typewriter 
radians
\family default 
 variables are floating-point numbers (numbers that can have a fractional
 part), and the type 
\family typewriter 
integer
\family default 
 means that the 
\family typewriter 
lower
\family default 
, 
\family typewriter 
upper
\family default 
, and 
\family typewriter 
step
\family default 
 variables are integers -- that is, they are whole numbers.
\layout Standard

Unlike C, in which 
\family typewriter 
int
\family default 
 and 
\family typewriter 
float
\family default 
 can have different sizes depending on the machine, Ruamoko variables always
 have a size that is a multiple of 4 bytes (32 bits).
\layout Standard

Ruamoko provides four basic data types
\begin_inset LatexCommand \index{types, basic}

\end_inset 

:
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="4" columns="2">
<features>
<column alignment="left" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
float
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

floating-point numbers
\end_inset 
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
integer
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
whole numbers, with a range between -2147483648 and 2147483647.
\end_inset 
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
string
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
text strings
\end_inset 
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family typewriter 
vector
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
three-dimensional floating-point vectors
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\layout Standard

There are more types than just these four, but this is the list of 
\emph on 
basic types
\emph default 
.
 There are also 
\emph on 
arrays
\emph default 
, 
\emph on 
structures
\emph default 
, and 
\emph on 
unions
\emph default 
 of these basic types, 
\emph on 
pointers
\emph default 
 to them, and functions that return them, all of which we'll meet later.
\layout Standard

The computation in the conversion program begins with the assignment statements
\layout LyX-Code

lower = 0;
\newline 
upper = 360;
\newline 
step = 45;
\layout Standard

which set the variables to their initial values.
 In Ruamoko, as in C, a statement is terminated by the semicolon character.
\layout Standard

Each line of the table is computed in the same manner, so we use a loop
 that repeats once per output line; this is the purpose of the 
\family typewriter 
while
\family default 
 loop
\layout LyX-Code

while (degrees <= upper) {
\newline 
    
\begin_inset Formula $\vdots$
\end_inset 


\newline 
}
\layout Standard

The 
\family typewriter 
while
\family default 
 loop works like this: The condition in parentheses is tested.
 If it is true (if 
\family typewriter 
degrees
\family default 
 is less than or equal to 
\family typewriter 
upper
\family default 
), the body of the loop (the three statements enclosed in the block delimited
 by the curly braces) is executed.
 Then the condition is tested again, and if it's true again, the body is
 executed again.
 If and when the condition becomes false (
\family typewriter 
degrees
\family default 
 exceeds 
\family typewriter 
upper
\family default 
), the loop ends and execution continues at the statement following the
 loop's end.
 Since there are no more statements in the program, the end of the loop
 terminates the program.
\layout Standard

The body of a while loop can be one or more statements enclosed in braces
 (called a block, or compound statement), or a single statement without
 braces, as in
\layout LyX-Code

while (i < n)
\newline 
    i = i * 2;
\layout Standard

In either case, we will always indent the statements controlled by the while
 by one tab stop (which we will show as four spaces), so you can see at
 a glance which statements are inside the loop.
 The indentation emphasizes the logical structure of the program.
 The compiler does not care how your program looks, but proper indentation
 and spacing are critical in making programs easy for people (including
 you) to read.
 We recommend writing only one statement per line, and using blanks around
 operators to make groupings clear.
 The positions of braces is less important, though you should be warned
 that many programmers have passionate beliefs about how braces should be
 used.
 We have chosen the so-called 
\begin_inset Quotes eld
\end_inset 

One True Brace Style
\begin_inset Quotes erd
\end_inset 

, which is the style that Brian Kernighan and Dennis Ritchie used in their
 book 
\bar under 
The C Programming Language
\bar default 
, for consistency.
 Pick a style that suits you, and use it consistently in your own work,
 but be prepared to adapt to the styles of other programmers when writing
 as a group.
\layout Standard

Most of the work gets done inside the loop.
 The radians for the angle are computed and assigned to the 
\family typewriter 
radians
\family default 
 variable using the statement
\layout LyX-Code

radians = degrees * (PI / 180);
\layout Standard

This example also shows a bit more of how 
\family typewriter 
printf()
\family default 
 works.
 
\family typewriter 
printf()
\family default 
 is a general-purpose output formatting function, which we will describe
 in detail in [chapter].
 Its first argument is a string to be printed, with each 
\family typewriter 
%
\family default 
 indicating where one of the other (second, third, and so on) arguments
 is to be substituted, and in what form it is to be output.
 For instance, 
\family typewriter 
%f
\family default 
 specifies a 
\family typewriter 
float
\family default 
 argument, so the statement
\layout LyX-Code

printf("%f
\backslash 
t%f
\backslash 
n", degrees, radians);
\layout Standard

causes the values of the two 
\family typewriter 
float
\family default 
 variables 
\family typewriter 
degrees
\family default 
 and 
\family typewriter 
radians
\family default 
 to be printed, with a tab (
\family typewriter 

\backslash 
t
\family default 
) between them.
\layout Chapter

Types, Operators, and Expressions
\layout Standard

Variables and constants are the basic data units manipulated in a program.
 Declarations list the variables to be used, and state what type they have
 and perhaps what the initial values for them are.
 Operators specify what is to be done to them.
 Expressions combine variables and constants to produce new values.
 The type of a unit determines the set of values it can have and what operations
 are permissible for it.
 These building blocks are the subject of this chapter.
\layout Section

Variable Names
\layout Standard

Though we didn't say it in Chapter 
\begin_inset LatexCommand \ref{cha:A-Tutorial-Introduction}

\end_inset 

, there are some restrictions on variable names and symbolic constants.
 Names are composed of letters and digits; the first character must be a
 letter (the underscore, 
\begin_inset Quotes eld
\end_inset 

_
\begin_inset Quotes erd
\end_inset 

, counts as a letter -- it's often useful for improving the readability
 of long names).
 Don't begin variable names with an underscore, however, since functions
 beginning with _ are reserved for library and engine functions.
 Upper-case and lower-case are distinct, so x and X are two different names.
 Traditional practice is to use lower-case or mixed case for variable names,
 and all upper-case for 
\emph on 
symbolic constants
\emph default 
, also known as 
\emph on 
defines
\emph default 
.
 Keywords like if, else, integer, float, etc.
 are reserved -- you can't use them as variable names.
\layout Section

Constants
\layout Standard

An integer constant like 
\family typewriter 
5678
\family default 
 is an integer.
 Floating-point constants contain a decimal point (
\family typewriter 
123.4
\family default 
) or an exponent (
\family typewriter 
1e-2
\family default 
) or both (
\family typewriter 
1.2e3
\family default 
).
\layout Standard

The value of an integer can be specified in octal (base 8, 0
\begin_inset Formula $\ldots$
\end_inset 

7) or hexadecimal (base 16, 0
\begin_inset Formula $\ldots$
\end_inset 

F, hereafter called 
\begin_inset Quotes eld
\end_inset 

hex
\begin_inset Quotes erd
\end_inset 

) instead of decimal.
 A leading 
\family typewriter 
0
\family default 
 (zero) on an integer constant means octal; a leading 
\family typewriter 
0x
\family default 
 or 
\family typewriter 
0X
\family default 
 means hex.
 For example, decimal 31 can be written as 
\family typewriter 
037
\family default 
 in octal, or 
\family typewriter 
0x1f
\family default 
 or 
\family typewriter 
0X1F
\family default 
 in hex.
\layout Standard

Certain characters can be represented in string constants by escape sequences
 like 
\family typewriter 

\backslash 
n
\family default 
 (newline); these sequences look like two characters, but represent only
 one.
 In addition, an arbitrary byte value can be represented by
\layout LyX-Code


\backslash 
o
\layout Standard

where 
\family typewriter 
o
\family default 
 is one to three octal digits or by
\layout LyX-Code


\backslash 
xh
\layout Standard

where 
\family typewriter 
h
\family default 
 is one or more hex digits.
 So we might write
\layout LyX-Code

"vtab = 
\backslash 
013"
\layout Standard

or, in hex, 
\layout LyX-Code

"vtab = 
\backslash 
x0b"
\layout Standard

The complete set of escape sequences is found in Table 
\begin_inset LatexCommand \ref{cap:Escape-sequences}

\end_inset 

.
\layout Standard


\begin_inset Float table
wide false
collapsed true

\layout Standard


\hfill 

\begin_inset  Tabular
<lyxtabular version="3" rows="14" columns="2">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Sequence
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Description
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
a
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Alert (bell) character
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
b
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

backspace
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
f
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

form feed
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
n
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

newline
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
r
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

carriage return
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
t
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

tab character
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 

\backslash 

\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

backslash
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
?
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

question mark
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
'
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

single quote
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
"
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

double quote
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
ooo
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

octal number
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
xhh
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

hex number
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\backslash 
^
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

alternate character set (toggles)
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\hfill 

\layout Caption


\begin_inset LatexCommand \label{cap:Escape-sequences}

\end_inset 

Escape sequences
\end_inset 


\layout Chapter

Control Constructs: Kneel Before Zod
\layout Chapter

Arrays and Pointers: Pull Pin, Then Throw 
\bar under 
GRENADE
\layout Chapter

Breaking Up The Program: Now Where Did I Put That?
\layout Part

Object-Oriented Programming in Ruamoko
\layout Part

Language Reference
\layout Chapter

Types
\layout Standard

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

New Type Features
\layout Subsection

New Types
\layout Labeling
\labelwidthstring 00.00.0000


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


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


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


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


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


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


\family typewriter 
IMP
\family default 
 message implementation
\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

Enumerators
\layout Standard

as per C
\layout Subsection

Structures
\layout LyX-Code

struct foo {
\newline 
    integer bar;
\newline 
    float baz;
\newline 
    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 LyX-Code

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 (compile-time) bounds checking
 (constant indices).
\layout Subsection

Complex types
\layout Standard

Complex types can be created by nesting type declarations within 
\family typewriter 
()
\family default 
s.
 e.g.:
\layout LyX-Code

(.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.
 e.g.:
\layout LyX-Code

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

Variable-argument functions
\layout Standard

Typed parameters preceding the ellipsis are allowed, e.g.: 
\family typewriter 
void (string fmt, \SpecialChar \ldots{}
) 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 through the ellipsis and 
\family typewriter 
@argv
\family default 
 is an array of vectors representing the parameters passed through 
\family typewriter 
\SpecialChar \ldots{}

\family default 
.
\layout Standard


\series bold 
\emph on 
Warning: attempting to pass 
\family typewriter 
@argv
\family default 
 to a non-engine function will not work.
 This is because of 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 mismatch
 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.
 e,g,
\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.
 Occurrences of false negatives are not known, but the possibility of their
 existence 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 
element-list
\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 Labeling
\labelwidthstring 00.00.0000


\family typewriter 
@self
\family default 
 Automagically-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 Labeling
\labelwidthstring 00.00.0000


\family typewriter 
@this
\family default 
 Automagically-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 Labeling
\labelwidthstring 00.00.0000


\family typewriter 
@argc
\family default 
 Number of parameters passed through 
\family typewriter 
\SpecialChar \ldots{}

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


\family typewriter 
@argv
\family default 
 Array of vectors representing the parameters passed through 
\family typewriter 
\SpecialChar \ldots{}

\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 
 \SpecialChar \ldots{}
 
\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 LyX-Code

for (
\emph on 
initialization-expression
\emph default 
; 
\emph on 
test-expression
\emph default 
; 
\emph on 
post-expression
\emph default 
)
\layout LyX-Code


\emph on 
    statement
\layout Standard

and is equivalent to
\layout LyX-Code


\emph on 
initialization expression
\layout LyX-Code

while (
\emph on 
test expression
\emph default 
) {
\layout LyX-Code


\emph on 
    statement
\layout LyX-Code


\emph on 
    post expression
\layout LyX-Code

}
\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 LyX-Code

switch (
\emph on 
test expression
\emph default 
) {
\newline 
   case
\emph on 
 value
\emph default 
:
\newline 

\emph on 
        optional statements
\newline 

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

\emph on 
        optional statements
\emph default 

\newline 
    default:
\newline 

\emph on 
        optional 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 behavior 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 Labeling
\labelwidthstring 00.00.0000


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


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


\family typewriter 
%
\family default 
 modulus
\layout Subsubsection

Assignment
\layout Labeling
\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 Labeling
\labelwidthstring 00.00.0000


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


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


\family typewriter 
++
\emph on 
e
\emph default 
\SpecialChar ~
--
\emph on 
e
\family default 
\emph default 
 pre-increment and decrement
\layout Labeling
\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 Labeling
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
type\SpecialChar ~

\emph default 
(
\emph on 
expr
\emph default 
)
\family default 
 cast expression.
 Works only for converting between integer and float types and between pointer
 types.
\layout Labeling
\labelwidthstring 00.00.0000


\family typewriter 
\emph on 
expr
\emph default 
[
\emph on 
expr
\emph default 
] 
\family default 
array indexing.
\layout Labeling
\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 Labeling
\labelwidthstring 00.00.0000


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

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


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


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


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


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


\begin_inset LatexCommand \printindex{}

\end_inset 


\the_end
