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