# PocketC Language

The language is very similar to standard C in syntax, but has a different feature set. Most notably, there are no structs, no typedefs, and some operators are not supported, such as the comma and the conditional operator (?:). A string data type has been added, and values are somewhat loosely typed. The next section is for those who are already somewhat familiar with C. A complete guide is also available for those not familiar with C.

## Brief guide to the PocketC language

### Data Types

There are five types in PocketC: 32-bit signed integers (`int`), 32-bit floating point numbers (`float`), 8-bit signed characters (`char`), null-terminated strings (`string`), pointers (`pointer`), and single-dimensional arrays.

### Expressions

An expression consists of any number of variables, function calls, and constants of any type, joined by operators and parentheses. Thus, the following expressions are valid:

    3 + 5
    6.7 + 23
    "Hello " + "World"
    5*3 + foobar()

When an expression contains values of different types, the two values are first cast to the same type, and then the operator applied. For example in the following expression:

`5.7 + 8`

The 8 is first cast to a float (8.0), and the two numbers are added (5.7 + 8.0). This becomes slightly more interesting when we use strings. For example:

`"The result is " + (5 + 8)`

5 is first added to 8, resulting in 13. The 13 is then converted to a string, and appended to "The result is " resulting in "The result is 13".However,

`"The result is " + 5 + 8`

would result in "The result is 58", since the the 5 is first converted to a string, then appended to "The result is "...

Of course, explicit casting is possible:

`56 + (int)"7"`

evaluates to 63.

The following operators are provided (in order of precedence (lowest first), with associativity):

Operator | Assoc | Description
--- | --- | ---
= | right | assigns the value of the expression on the right to the variable on the left.
|| | left | logical 'or', returns 0 if false, 1 if true
&& | left | logical 'and'
| | left | bitwise 'or'
^ | left | bitwise 'xor'
& | left | bitwise 'and'
== != < <= > >= | left | relational operators
<< >> | left | bitwise shift operators. The operands must be int or char.
+ - | left | addition, subtraction
* / % | left | multiplication, division, modulus
- ! ++ -- ~ * [] () & @[] | left | unary operators, pointer dereferencing, address operator, function call (for pointers to functions), array subscripts (for pointers), and the character access operator ( @[] e.g. string str = "bob"; str@[0] = 'B'; )

Note: No shortcut logic is performed on the operands of || and &&
Note2: The compound assignment operators (+=, -=, *=, etc.) are not supported.
Note3: The comma and conditional operator (?:) are not supported.

### Variables

- The following variable types are supported: `int, float, char, string, pointer,` and single-dimensional arrays.
- Local variables must be declared before any code in a function.
- It is best to create larger arrays as globals rather than locals.
- Variable initializers ARE supported (as of version 3.5). The initialization expressions must be constants, and of the correct type. Array initialization is also available. (e.g. string days[7] = { "Sun", "Mon" };). If not all array elements are specified, the final elements use defaults (0 or ""). (i.e. int x[3] = {1, 2}; // x[2] == 0)
- All variables, global and local, are initialized to zero or the empty string.
- Variable names can be up to 31 characters long and are case sensitive.

### Pointers

A pointer is defined by the `pointer` type, not `int*`, for example. Importantly, pointers in PocketC are not typed. Instead, they take on the type of the data to which they point. Additionally, a pointer can refer to a function, and would be used as follows:

    func(int x) { return 5*x; }

    main() {
       pointer ptr;
       int result;

       ptr = func;
       result = (*ptr)(7);
       puts("5*7=" + result);
    }

Additionally, pointer values are not addresses to actual PalmOS memory.

### String Character Accessor

To get or set an individual character within a string variable, use stringVariable@[index]. The index of the first character is 0. You will produce a runtime error if you attempt to access a character that is past the end of the string. Example:

    string str = "bob";
    ...
    puts(str@[1]); // Prints the second letter of str
    str@[1] = 'X'; // changes str from "bob" to "bXb"

Note: the string character accessor cannot be used with pointers, nor can the address of the resulting string be take. In other words, the following expressions are not valid: &str@[i], *pstr@[i], (*pstr)@[i]

### Statements

The following statements are fully supported: `for, while, do, break, continue, if, then, return, switch, case, default`. Strings can be used in switch statements.
Note: `for` requires a condition expression (i.e. `for (;;)` is not legal, instead, use `for (;true;)` or `while (true)`) Also, the comma operator is not supported.

### Functions

- Functions are declared without a return type. Because of loose typing, it is possible to return any type or even multiple types. The type returned is the type of the expression in the executed return statement. If no return value is specified, a function returns integer 0.
- Local variables must come before any function code.
- There must be a main function that takes no parameters.
- Functions cannot take arrays as parameters. They can, however, take pointers as arguments, allowing the same functionality.
- A function cannot be called before it is defined.
- Function prototypes ARE allowed (as of version 3.02).
- Recursion is allowed.

### Include

- Only three levels of includes are supported (i.e. if memo A includes B which includes C which includes D, D may not include any memos)
- Do not append '//' to the include file name
- The included file can begin with '/$' instead of '//' to hide it from the compile form
- The include file may be a doc file. Note: PocketC will search for a matching memo before trying to find a matching doc file.
- On the Desktop Edition, any slashes in a path must be escaped

Example:

    // My large applet
    include "Part1"
    include "Part2"

    main() {
    // call functions defined in other memos
    }

Note: `include` can only be used at the top level (i.e. you cannot use `include` within a function)

### Library

- Use the keyword `library` to use a native library.
- DO NOT use this keyword with MathLib. MathLib functions are available as built-in functions.

Example:

    // My Applet
    library "PocketCLib"

    main() {
    int x;
    // call functions defined by native library
    x = times5(7); // Where times5(int) is defined by "PocketCLib"
    }

### Special characters

There are two ways to add special characters to a string. The first is by appending them by number, such as:

    str = "Here is a neat little square: " + (char)149;

The other method is through using escape sequences. The following escape sequences are supported:

Escape sequence | \\ | \' | \" | \n | \t | \x
--- | --- | --- | --- | --- | --- | ---
Interpretation | \ | ' | " | newline | tab | character specified by the following two hex digits. Example: '\x95' is the block character (decimal 149)

### Preprocessor

The following preprocessor directives are supported: #define, #undef, #ifdef, #ifndef, #else, #endif. Macros cannot take parameters. The following constants are predefined: `__PKTC__, __PKTC_PALM__,` and if PocketC Desktop Edition is compiling a .prc file, `__PKTC_PRC__.`