File Format - Contents - Scripting the Simulation

INTRODUCTION TO APESCRIPT

ApeScript was developed with a number of requirements. These included;

   (1)   Simple language - easy to learn, easy to maintain
   (2)   Stable memory footprint - no allocation/free issues
   (3)   Minimal crashes - good error handling and abort
   (4)   Small code - maintains the Simulation's small size

From these basic elements the ApeScript language was built on a C/C++/Java style syntax with a couple of minor differences. Anyone familiar with these languages should have no problem with ApeScript. Similarly, as ApeScript is extremely simple, a non-programmer should be able to pick up ApeScript too.

In addition, there are a series of ApeScript examples and discussion notes to assist novice and advanced developers.

ELEMENTS

Comments in ApeScript are denoted between /* and */.

   /* This is an example comment */

   /*
      This is also a comment
   */

ApeScript has two basic types numbers and variables. The variables may be pre-defined variables that come from the Simulation environment but other variables can be created on the fly.

A variable can only be made up of letters and underscore (_). No numbers can be included in a variable name.

A variable is defined through use. If a variable is not set at the time it is defined it is assumed the variable equals zero. For example;

   this_is_a_test = what_is_the_value + 5;

Would set this_is_a_test to 5 and if it was reused what_is_the_value to 0. Whilst this example is a created one, it is good to make distinct variable names to avoid any confusion with the Simulation variables. The numbers defined in ApeScript need to be whole integer numbers of the range from 0 to 65535. You can not define an ApeScript number as negative from the initial definition. However you can define a negative number through a subtraction. For example;

   negative_five = 0 - 5;

Similarly you can create numbers larger than 65535 through addition or multiplication. With this method you can create numbers between the range of -4294967296 to 4294967295.

OPERATORS

In addition to numbers and variables, ApeScript allow the following mathematical and logical operators;

   -   Subtract
   +   Add
   *   Multiply
   /   Divide
   %   Modulus
   &   Binary And
   ^   Binary Xor
   |   Binary Or
   >>  Bit Shift Right
   <<  Bit Shift Left
   >   Greater Than
   <   Less Than
   >=  Greater Than or Equal To
   <=  Less Than or Equal To
   ==  Logical Equal To
   !=  Logical Not Equal To
   &&  Logical And
   ||  Logical Or

In order to maintain a small code-base for the interpreter only a single operation can be performed per line of code. Brackets can not be used with reference to operators. In C, a line of code may read;

   /* C example */
   number_value = ( number1 + number2 ) * 45;

In ApeScript this would be written;

   number_value = number_one + number_two;
   number_value = number_value * 45;

IF/WHILE

ApeScript has two additional operators, if and while. This provides conditional and loops respectively. If you require a standard ''for'' loop from 0 to 9, you can write it in ApeScript as follows;

   while ( loop_condition < 10 ) {
      loop_condition = loop_condition + 1;   
   }

Similarly, if you want to execute a section of ApeScript in a particular condition, you can use an if-statement;

   if ( particular_condition ) {
   }

While loops and if-statements can be layered. For example;

   while ( loop_condition < 230 ) {
      if ( loop_condition < 150 ) {   
         loop_condition = loop_condition + 1;
      }
      loop_condition = loop_condition * 3;
   }

FUNCTIONS

Functions are central to ApeScript. The being function is similar to main in C. Functions are special variables that are saved are in execution code memory allocations. They can be treated as variables. The code within the functions are not executed until they are run. Thus functions can be defined out of order provided the being function is placed last.

   function ( physically_first ) {
      test_value = 3;
      run ( called_first );
   }

   function ( called_first ) {
      test_value = test_value + 4;
   }

   function ( being ) {
      test_value = 1;
      run ( called_first );
      run_function = physically_first;
      if ( test_value > 7 ) {
         run_function = called_first;
      }
      run ( run_function );
   }

ERRORS

For simplicity error reports are tracked per version release. If ApeScript reports an error, check it against this list for possible causes/fixes.

LIMITS

With both variable allocation and while/if nesting (i.e. the number of layers of { }) there are limits for both. Developing actual ApeScript code for practical solutions, you should never reach these limits however if you have found a limit for your ApeScript code, please get in contact;

   tom at nobleape dot com

As these limits can be extended for actual use cases.

MAILING LIST

The Noble Ape developer mailing list can provide feedback to your ApeScript questions. If you are starting out with ApeScript and you want a community, subscribe to the mailing list;

   http://www.nobleape.com/mailman/listinfo/developer_nobleape.com

In addition to the active contributions to the mailing list, the link above provides an archive of the developer mailing list too.


File Format - Contents - Scripting the Simulation