QScript's operators and function set
Before looking further the user must be made aware that QScript is case sensitive. So sqrt, SQRT and Sqrt are all treated differently.
Data Types
Internally QScript uses the 6 data types shown in the table below. The first 4 types are part of Java and the last two, Vector and Complex are included with the library and have no direct Java equivalents. The third column shows how other Java data types are mapped to the QScript data types.
The first column is a 'key' that is used later when discussing the data types expected by the operators and functions. For simplicity the Integer and Double have been grouped together as numeric (N).
| Key | QScript Type | Used for Java types |
|---|---|---|
| N | Integer | byte / Byte short / Short long / Long |
| N | Double | float / Float double / Double |
| B | Boolean | boolean / Boolean |
| S | String | char / Character |
| V | Vector | N/a |
| C | Complex | N/a |
Variables
All variable names must start with the an upper or lowercase letter (A-Z or a-z) followed by any combination of upper (A-Z) or lower (a-z) case letters, digits (0-9) or underscores (_). In the original version of QScript variable names had to being with the $ symbol, in version 2 the $ is still permitted but is optional. You must not use operator and function names for variable identifiers.
Variables are dynamically typed and can store a single value of any of the supported data types. If the variable is uninitialiesd (i.e. a value has not been assigned to it yet) then it will have the value 'null'.
Dynamic typing
Since QScript uses dynamic typing the data types used by an operator or passed to a function are checked at runtime. If the operator or method cannot process the data types then an error occurs and the evaluation is halted.
Operators
The following table shows all the operators supported in the default operator set. They are all infix
operators and expect 2 operands e.g. a OP b. Although it is possible add your own user defined
operators, care should be taken in setting the priority, get it wrong and it could ruin your day.
| Mathematical operators | ||||
|---|---|---|---|---|
| Operator | Description | Priority | Type | |
| + | Addition or string concatenation if either operand is type String | 24 | NSVC | |
| - | Subtraction | 24 | NVC | |
| * | Multiplication | 25 | NVC | |
| / | Division | 25 | NVC | |
| ^ | Raises one number to the power of another e.g. 28 is calculated with 2 ^ 8 | 27 | NC | |
| = | Assignment operator stores the value on the right in the variable on the left. | 15 | NBSVC | |
| Logical operators | ||||
| Operator | Description | Priority | Type | |
| && | Logical And between 2 boolean expressions | 19 | B | |
| AND | Logical And between 2 boolean expressions | 19 | B | |
| XOR | Logical Exclusive-Or between 2 boolean expressions | 18 | B | |
| || | Logical Or between 2 boolean expressions | 17 | B | |
| OR | Logical Or between 2 boolean expressions | 17 | B | |
| Comparison operators These are used to compare two numeric values or two string values and return a boolean result. |
||||
| == | Is equal to | 20 | NBSVC | |
| != | Is not equal to | 20 | NBSVC | |
| > | Is greater than | 21 | N | |
| >= | Is greater than or equal to | 21 | N | |
| < | Is less than | 21 | N | |
| <= | Is less than or equal to | 21 | N | |
Functions
The following table shows the functions supported in the default operator set. Every function has a unique name and a fixed number of parameters, QScript does not support function overloading. All functions have the same priority value of 30.
| Math functions | ||||
|---|---|---|---|---|
| Operator | Description | Type | ||
| abs(a) | Returns the absolute (positive) value of a | NC | ||
| angleBetween(a, b) | Returns the angle between 2 vectors | V | ||
| ceil(a) | Returns the largest (closest to positive infinity) whole number that is <= a | N | ||
| conj(a) | Return the conjugate of a complex number | C | ||
| cross(a, b) | Returns the cross product of 2 vectors | V | ||
| dot(a, b) | Returns the dot product of 2 vectors | V | ||
| exp(a) | Returns the exponential of a (ea) | NC | ||
| floor(a) | Returns the largest (closest to positive infinity) whole number that is <= a | N | ||
| imag(a) | Return the imaginary part of a complex number | C | ||
| int(a) | Returns the whole number generated when the fractional part is removed from a | N | ||
| lerp(a, b, t) | Linear interpolation between a and b for the parametric value t | NVC | ||
| log(a, b) | Returns the base b logarithm of a | N | ||
| log10(a) | Returns the base 10 logarithm of a | N | ||
| logE(a) | Return the natural logarithm (base e) of a | NC | ||
| mag(a) | Returns the magnitude of the vector or complex number | VC | ||
| max(a, b) | Returns the larger of a and b | N | ||
| min(a, b) | Returns the smaller of a and b | N | ||
| neg(a) | Returns the negative value of a (i.e -1 * a) | NVC | ||
| norm(a) | Returns vector or complex number of unit (1) magnitide | VC | ||
| NOT(b) | Returns the logical 'not' on a boolean expression (i.e. !b) | B | ||
| pow(a, b) | Returns ab | NC | ||
| real(a) | Return the real part of a complex number | C | ||
| rnd(a, b) | Generates a random number in the range >= a and <b | N | rndC(a) | Generates a random complex number of magnitude a | C |
| rndV(a) | Generates a random vector of magnitude a | V | ||
| round(a) | Returns the closest integer to a | N | ||
| signum(a) | Returns -1.0 if a < 0.0, +1.0 if a > 0.0 and 0.0 if a == 0.0 | N | ||
| sqrt(a) | Returns the square root of a. Returns a complex number if a is complex | NC | ||
| sqrtz(a) | Returns the square root of a. Will return a complex value if a is complex or a negative real number | NC | vX() vY() vZ() |
Returns the matching axis attribute value of a vector | V |
| Trignometric functions These functions expect angles to be in radians |
||||
| Operator | Description | Type | ||
| acos(a) | Returns the arc cosine of a | NC | ||
| asin(a) | Returns the arc sine of a | NC | ||
| atan(a) | Returns the arc tangent of a | NC | ||
| atan2(y,x) | Returns the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta). | N | ||
| cos(a) | Returns the cosine of a | NC | ||
| cosh(a) | Returns the hyperboloic cosine of a | NC | ||
| sin(a) | Returns the sine of a | NC | ||
| sinh(a) | Returns the hyperbolic sine of a | NC | ||
| tan(a) | Returns the tangent of a | NC | ||
| tanh(a) | Returns the hyperbolic tangent of a | NC | ||
| radians(a) | Converts degrees to radians | N | ||
| degrees(a) | Converts radians to degrees | N | ||
| Other functions | ||||
| Operator | Description | Type | ||
| println(s) | output the string s to System.out followed by carriage return | S | ||
| print(s) | output the string s to System.out without carriage return | S | ||
| runtime() | Returns the time (in seconds) since this script started evaluation. | |||
| WAIT(t) | Will cause the script to pause for 't' milliseconds. If t is zero then the script will pause until resumed by the user. | N | ||
| END(r) | End script evaluation and return the result r | NBSVC | ||
Vector and Complex variables
Since Java doesn't have native support for vectors or complex numbers the library provides the immutable classes, Vector and Complex. The following methods create / define vectors and complex numbers and can be thought of in the smae way as constructors in classes.
# Create a vector and multiple it by a scalar
v = vector(1, 4, 9) ; n = 3.5; v = v * 3.5;
# Create a complex number and raise it to the power of the second complex number
c = C(1, 2); c = c ^ complex(2, -4);| Functions to create vector and complex number variables | ||||
|---|---|---|---|---|
| Operator | Description | Type | ||
| V(x, y, z) vector(x , y, z) |
Specify a Vector from numeric values for x, y and z fields | N | ||
| C(re, im) complex(re, im) |
Specify a Complex number from numeric values for the real and imaginary parts. | N | ||
All the matehmatical operators are overloaded to use vectors and complex numbers. Where appropriate, mixed calculations with numeric values are permitted e.g. C * N. Some combinations make no sense, for instance dividing by a vector is inavlid but dividing by a complex number is acceptable.
Constants
The following table shows all the contants included in QScript. By convention constant identifiers are in uppercase and that is used here, although the lowercase alternatives to TRUE and FALSE are included for convenience. All constants have the same priority value of 40.
| Constant | Description | Value |
|---|---|---|
| E | e, the base of the natural logarithms | 2.7182818284590452354 |
| PI | pi, the ratio of the circumference of a circle to its diameter | 3.14159265358979323846 |
| EOL | ASCII 13, the carriage return as a string | '\n' |
| TRUE true |
Boolean true | true |
| FALSE false |
Boolean false | false |
| V000 | Zero vector | V(0, 0, 0) |
| V100 | X axis vector | V(1, 0, 0) |
| V010 | Y axis vector | V(0, 1, 0) |
| V001 | Z axis vector | V(0, 0, 1) |
Script operators
These provide conditional and loop constructs so that we can create simple algorithms. The precedence operators are used during parsing and have no effect on the evaluation phase.
| Operator | Description | NOps | Priority | Type |
|---|---|---|---|---|
| If-the-else conditional construct | ||||
| IF(b) ELSE ENDIF |
Select the expressions to be evaluated based on the boolean value b | 1 0 0 |
4 3 2 |
function marker marker |
| While-wend loop construct | ||||
| WHILE(b) WEND |
While the boolean b is true continue evaluating the expreesions inside the loop | 1 0 |
4 2 |
function marker |
| Repeat-until loop construct | ||||
| REPEAT UNTIL(b) |
Keep evaluation the evaluating the expreesions inside the loop until the boolean b is true | 0 1 |
4 2 |
marker function |
| Other operators | ||||
| END(r) | End script evaluation and return the result r | 1 | 30 | function |
| Precedence operators | ||||
| ( ) |
Parentheses - used to change the order of evaluation and to surround the function parameters | 0 0 |
12 11 |
marker marker |
| , | The comma separates the parameters passed in function calls | 0 | 9 | marker |
| ; | The semicolon separates the expressions when on the same script line | 0 | 9 | marker |