Basic syntax

Overview

TatBasicScripter component executes scripts written in Basic syntax. Current Basic syntax supports:

  • sub .. end and function .. end declarations

  • byref and dim directives

  • if .. then .. else .. end constructor

  • for .. to .. step .. next constructor

  • do .. while .. loop and do .. loop .. while constructors

  • do .. until .. loop and do .. loop .. until constructors

  • ^, *, /, and, +, -, or, <>, >=, <=, =, >, <, div, mod, xor, shl, shr operators

  • try .. except and try .. finally blocks

  • try .. catch .. end try and try .. finally .. end try blocks

  • select case .. end select constructor

  • array constructors (x = [ 1, 2, 3 ])

  • exit statement

  • access to object properties and methods (ObjectName.SubObject.Property)

Script structure

Script structure is made of two major blocks: (a) function and sub declarations and (b) main block. Both are optional, but at least one should be present in script. Some examples:

SCRIPT 1:

SUB DoSomething
   CallSomething
END SUB
 
CallSomethingElse

SCRIPT 2:

CallSomethingElse

SCRIPT 3:

FUNCTION MyFunction
   MyFunction = "Ok!"
END FUNCTION

Like in normal Basic, statements in a single line can be separated by ":" character.

Identifiers

Identifier names in script (variable names, function and procedure names, etc.) follow the most common rules in Basic: should begin with a character (a..z or A..Z), or '_', and can be followed by alphanumeric chars or '_' char. Cannot contain any other character os spaces.

Valid identifiers:

VarName
_Some
V1A2
_____Some____

Invalid identifiers:

2Var
My Name
Some-more
This,is,not,valid

Assign statements

Assign statements (assign a value or expression result to a variable or object property) are built using "=". Examples:

MyVar = 2
Button.Caption = "This " + "is ok."

New statement

TMS Scripter provides the "new" statement for Basic syntax. Since you don't provide the method name in this statement, scripter looks for a method named "Create" in the specified class. If the method doesn't exist, the statement fails. Example:

MyLabel = new TLabel(Form1)
MyFont = new TFont

In the above examples, a method named "Create" for TLabel and TFont class will be called. The method must be registered. If the method receives parameters, you can pass the parameters in parenthesis, like the TLabel example above.

Character strings

Strings (sequence of characters) are declared in Basic using double quote (") character. Some examples:

A = "This is a text"
Str = "Text "+"concat"

Comments

Comments can be inserted inside script. You can use ' chars or REM. Comment will finish at the end of line. Examples:

' This is a comment before ShowMessage
ShowMessage("Ok")
 
REM This is another comment
ShowMessage("More ok!")
 
' And this is a comment
' with two lines
ShowMessage("End of okays")

Variables

There is no need to declare variable types in script. Thus, you declare variable just using DIM directive and its name. There is no need to declare variables if scripter property OptionExplicit is set to false. In this case, variables are implicit declared. If you want to have more control over the script, set OptionExplicit property to true. This will raise a compile error if variable is used but not declared in script. Examples:

SCRIPT 1:

SUB Msg
   DIM S
   S = "Hello world!"
   ShowMessage(S)
END SUB

SCRIPT 2:

DIM A
A = 0
A = A+1
ShowMessage(A)

Note that if script property OptionExplicit is set to false, then variable declarations are not necessary in any of scripts above.

You can also declare global variables as private or public using the following syntax:

SCRIPT 3:

PRIVATE A
PUBLIC B
B = 0
A = B + 1
ShowMessage(A)

Variable declared with DIM statement are public by default. Private variables are not acessible from other scripts.

Variables can be default initialized with the following syntax:

DIM A = "Hello world"
DIM B As Integer = 5

Indexes

Strings, arrays and array properties can be indexed using "[" and "]" chars. For example, if Str is a string variable, the expression Str[3] returns the third character in the string denoted by Str, while Str[I + 1] returns the character immediately after the one indexed by I. More examples:

MyChar = MyStr[2]
MyStr[1] = "A"
MyArray[1,2] = 1530
Lines.Strings[2] = "Some text"

Arrays

Script support array constructors and support to variant arrays. To construct an array, use "[" and "]" chars. You can construct multi-index array nesting array constructors. You can then access arrays using indexes. If array is multi-index, separate indexes using ",".

If variable is a variant array, script automatically support indexing in that variable. A variable is a variant array is it was assigned using an array constructor, if it is a direct reference to a Delphi variable which is a variant array (see Delphi integration later) or if it was created using VarArrayCreate procedure.

Arrays in script are 0-based index. Some examples:

NewArray = [ 2,4,6,8 ]
Num = NewArray[1] 'Num receives "4"
MultiArray = [ ["green","red","blue"] , ["apple","orange","lemon"] ]
Str = MultiArray[0,2] 'Str receives 'blue'
MultiArray[1,1] = "new orange"

If statements

There are two forms of if statement: if...then..end if and the if...then...else..end if. Like normal Basic, if the if expression is true, the statements are executed. If there is else part and expression is false, statements after else are executed. Examples:

FUNCTION Test(I, J)

  IF J <> 0 THEN Result = I/J END IF
  IF J = 0 THEN Exit Function ELSE Result = I/J END IF
  IF J <> 0 THEN
    Exit Function
  ELSE
    Result = I/J
  END IF

END FUNCTION

If the IF statement is in a single line, you don't need to finish it with END IF:

IF J <> 0 THEN Result = I/J
IF J = 0 THEN Exit ELSE Result = I/J

while statements

A while statement is used to repeat statements, while a control condition (expression) is evaluated as true. The control condition is evaluated before the statements. Hence, if the control condition is false at first iteration, the statement sequence is never executed. The while statement executes its constituent statement repeatedly, testing expression before each iteration. As long as expression returns True, execution continues. Examples:

WHILE (Data[I] <> X) I = I + 1 END WHILE
WHILE (I > 0)
   IF Odd(I) THEN Z = Z * X END IF
   X = Sqr(X)
END WHILE
 
WHILE (not Eof(InputFile))
   Readln(InputFile, Line)
   Process(Line)
END WHILE

loop statements

Scripter support loop statements. The possible syntax are:

DO WHILE expr statements LOOP
DO UNTIL expr statements LOOP
DO statements LOOP WHILE expr
DO statement LOOP UNTIL expr

Statements will be execute WHILE expr is true, or UNTIL expr is true. If expr is before statements, then the control condition will be tested before iteration. Otherwise, control condition will be tested after iteration. Examples:

DO
   K = I mod J
   I = J
   J = K
LOOP UNTIL J = 0
 
DO UNTIL I >= 0 
   Write("Enter a value (0..9): ")
   Readln(I)
LOOP
 
DO 
   K = I mod J
   I = J
   J = K
LOOP WHILE J <> 0
 
DO WHILE I < 0 
   Write("Enter a value (0..9): ")
   Readln(I)
LOOP

for statements

Scripter support for statements with the following syntax:
FOR counter = initialValue TO finalValue STEP stepValue statements NEXT.

The for statement set counter to initialValue, repeats execution of statement until "next" and increment value of counter by stepValue, until counter reachs finalValue. Step part is optional, and if omitted stepValue is considered 1. Examples:

SCRIPT 1:

FOR c = 1 TO 10 STEP 2
   a = a + c
NEXT

SCRIPT 2:

FOR I = a TO b
   j = i ^ 2
   sum = sum + j
NEXT

select case statements

Scripter support select case statements with following syntax:

SELECT CASE selectorExpression
 CASE caseexpr1
    statement1
 ...
 CASE caseexprn
    statementn
CASE ELSE
  elsestatement
END SELECT

If selectorExpression matches the result of one of caseexprn expressions, the respective statements will be executed. Otherwise, elsestatement will be executed. Else part of case statement is optional. Example:

SELECT CASE uppercase(Fruit)
   CASE "lime" ShowMessage("green")
   CASE "orange" 
      ShowMessage("orange")
   CASE "apple" ShowMessage("red")
CASE ELSE
   ShowMessage("black")
END SELECT

function and sub declaration

Declaration of functions and subs are similar to Basic. In functions to return function values, use implicited declared variable which has the same name of the function, or use Return statement. Parameters by reference can also be used, using BYREF directive. Some examples:

SUB HelloWord
   ShowMessage("Hello world!")
END SUB
 
SUB UpcaseMessage(Msg)
   ShowMessage(Uppercase(Msg))
END SUB
 
FUNCTION TodayAsString
   TodayAsString = DateToStr(Date)
END FUNCTION
 
FUNCTION Max(A,B)
   IF A>B THEN
      MAX = A
   ELSE
      MAX = B
   END IF
END FUNCTION
 
SUB SwapValues(BYREF A, B)
   DIM TEMP
   TEMP = A
   A = B
   B = TEMP
END SUB

You can also declare subs and functions as private or public using the following syntax:

PRIVATE SUB Hello
END SUB
 
PUBLIC FUNCTION Hello
END FUNCTION

Subs and functions are public by default. Private subs and functions are not acessible from other scripts.

You can use Return statement to exit subs and functions. For functions, you can also return a valid value. Examples:

SUB UpcaseMessage(Msg)
   ShowMessage(Uppercase(Msg))
   Return
   'This line will be never reached
   ShowMessage("never displayed")
END SUB
 
FUNCTION TodayAsString
   Return DateToStr(Date)
END FUNCTION