Interpreter Basics

A script is a text file containing instructions for PCC to execute. You write scripts in your favourite text editor (and by that I mean a TEXT editor, not a word processor), and execute them in PCC using the `Load' command or the Run Script dialog. Possible text editors include MS-DOS "edit" and Windows "notepad".

PCC's syntax is roughly based on BASIC. This makes programs easy to write and understand. In addition, BASIC is a quite natural interactive interpreter language, and it will not bother you with missing semicolons and frightening curly braces.

An instruction can be one of the following:

• an expression. The expression is evaluated, and their side effects performed. Of course you can also let PCC execute an expression without side effects, but that makes no sense as the result will be immediately discarded;
• a single-line command. Single-line commands can be entered at the console, too.
• a multi-line command. These are only valid in scripts.

Examples:

  a := 10                     % expression (side effect: assignment)
  SetFCode "mkt"              % single-line command
  ForEach Ship Do SetSpeed 0  % single-line command
  If Owner$=2 Then            % multi-line command...
    SetMission 9              % ...containing two...
    Print "Hissss."           % ...single-line commands.
  EndIf

A command that started as a one-line command can not contain a multi-line command. The following example is invalid code:

  If i=1 Then Do
    % do something
  Loop While condition

This must be written as

  If i=1 Then
    Do
      % do something
    Loop While condition
  EndIf

instead.

Case is unimportant, as is indentation. However, for readability, I suggest you to follow my examples for capitalisation and spacing.

You may add comments throughout your script by starting them with a `%' sign.

The usual BASIC comment character is the single apostrophe, but that one was already taken for a more useful purpose, namely strings.

`Control statements', that's things like `If', loops, and other "special" things, are described under `Core Commands' in the Command Reference.

Scripts are only interpreted as far as needed. Errors in parts which never execute will not be detected. You may get a different error message when hitting an error from a different place. This property is common to many interpreters.

Undefined items (variables, functions) are not reported until you try to use them. An item is defined when its definition has been executed, see the Dim and Sub commands and the next section for more information.

Variables in PCC are untyped and dynamically scoped. What does this technobabble mean?

• "untyped" means, you can store any value in them: numbers (integers or real numbers), character strings, or truth values. Variables initially are EMPTY.
• "dynamically scoped" means, variables are looked up at run-time (like in Lisp), not at compile time (like in C or Pascal). If a variable X is accessed, PCC looks whether there's a variable X in the current subroutine. If there isn't, it looks if there's one in the caller of this routine, and so on until we're looking at the global variables. `With' and `ForEach' blocks also establish places to look for variables.

If you define a variable, you have to choose one of three storage classes:

• `Dim Local a' establishes a local variable. This variable is visible in the current subroutine and all routines it calls, and vanishes if you leave the current routine. You can also define local variables at top-level.
• `Dim Static a' defines a variable visible in all of the current process. It will be visible in all currently active subroutines, and all routines that will be called from this process. Caveat emptor: if there is already a local variable of the same name, the new one will immediately after its definition become invisible! `Dim Static' is identical to a `Dim Local' at top-level.
• `Dim Shared a' defines a variable visible everywhere, in all processes and all subroutines. The same problem as for `Dim Static' applies here: the new variable will immediately be shadowed by a static or local variable of the same name, if existing.

Local and static variables survive PCC exit/reload (if the process containing them survives), shared variables don't.

Variables are not available until their definition has been executed. For example, in

  Do
    Print vi
    Dim vi = 2
    vi := vi+1
  Loop Until vi=10

the `Print' statement will fail on the first iteration if there is no variable `vi' outside the `Do' loop.

If you start PCC first, it defines 25 shared variables (`A' .. `Y') for you. On the console, you can only define shared variables. Local and static variables will only be visible on the line you enter -- because each line creates a process for itself. (If you're a programmer: `A' to `Y' want to be thought of as "processor registers"; many external events may change them, for example printing or recomputing starchart labels.)

Dynamic scope can be used to "fool" subroutines you call. For example, this subroutine

  Sub FoolIt
    Local System.GameType$ = False
    OtherSub
  EndSub

makes `OtherSub' think you are registered. CALM DOWN: this does not allow a rule breach: you can't trick the parts inside PCC which actually check the rules, and because scripts are never sent to the host, cheating the host is not possible at all. Only user-written subroutines can be fooled by dynamic scope. Applications of this are, for example, getting a subroutine to run which insists to be used in PHost games only, or, a real-world example, making a minefield calculator available for unregistered users if you use an add-on that enables `mdX' and `miX' for them.