Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

 

Code Block
titleExample
Function Main() As Void
 
       dim cavemen[10]
 
       cavemen.push("fred")
       cavemen.push("barney")
       cavemen.push("wilma")
       cavemen.push("betty")
 
       for each caveman in cavemen
             print caveman
       end for
 
End Function

Statement Syntax

Each line may contain a single statement. However, a colon (:) may be used to separate multiple statements on a single line.

Code Block
titleExample
myname = "fred"
if myname="fred" then yourname = "barney":print yourname

LIBRARY

LIBRARY Filename.brs

BrightScript 3.0 allows you to add your own BrightScript libraries (.brs files), which can then be utilized by your script. To include a library, use the LIBRARY statement in your script or at the BrightScript shell prompt. The LIBRARY statement(s) must occur at the beginning of a script, before any other statements, functions, operators, etc.

The system locates a library by searching the directory containing the current script, as well as the SYS:/script-lib/ directory. Note that the Run() function does not currently change the path of a LIBRARY statement to that of the called script (i.e. the system will continue searching the directory of the caller script). On the other hand, running a script directly from the BrightSign shell does modify the library search path to that of the called script.

The first statement will include a library in the same folder as the script, while the second will include a library in a sub-folder.

Code Block
LIBRARY "myBSL1.brs"
LIBRARY "new_lib/myBSL2.brs"

 

The following statement will include the bslCore.brs library, which has some useful BrightScript features, from the SYS:/script-lib/ directory.

Code Block
LIBRARY "v30/bslCore.brs"

DIM 
Anchor
dim
dim

DIM Name (dim1, dim2, …, dimK)

The DIM (“dimension”) statement provides a shortcut for creating roArray objects. It sets the variable Name to type “roArray”. It can create arrays of arrays as needed for multi-dimensionality. The dimension passed to DIM is the index of the maximum entry to be allocated (i.e. the array initial size = dimension+1), though the array will be resized larger automatically if needed.

The following two lines create identical arrays.

Code Block
Dim array[5]
array = CreateObject("roArray", 6, true)
Note
titleNote

The expression x[a,b] is equivalent to x[a][b].

The following script demonstrates useful operations on a DIM array.

Code Block
Dim c[5, 4, 6]


For x = 1 To 5
   For y = 1 To 4
        For z = 1 To 6
           c[x, y, z] = k
           k = k + 1
       End for
   End for
End for


k=0
For x = 1 To 5
    For y = 1 To 4
       For z = 1 To 6
          If c[x, y, z] <> k Then print"error" : Stop
          if c[x][y][z] <> k then print "error":stop
          k = k + 1
          End for
   End for
End for

 

Assignment ("=")

variable = expression

The assignment statement (“=”) assigns a variable to a new value.

In each of the following lines, the variable on the left side of the equals operator is assigned the value of the constant or expression on the right side of the equals operator.

Code Block
a$="a rose is a rose"
b1=1.23
x=x-z1

END

The END statement terminates script execution normally.

STOP

The STOP statement interrupts script execution, returns a “STOP” error, and invokes the debugger. Use the cont command at the debugger prompt to continue execution of the script or the step command to execute a single step in the script.

GOTO

GOTO label

The GOTO statement transfers program control to the line number specified by Label. The GOTO label statement results in a branching operation. A label is an identifier terminated with a colon on a line that contains no other statements or expressions. 

Code Block
titleExample
mylabel:
print "Hello World"
goto mylabel

RETURN

RETURN expression

The RETURN statement returns from a function back to its caller. If the function is not type Void, RETURN can also return a value to the caller.

PRINT

PRINT [#output_object], [@location], item list

The PRINT statement prints an item or list of items in the console. The item(s) may be strings, integers, floats, variables, or expressions. An object with an ifInt, ifFloat, or ifString interface may also be printed. If the output_object is specified, this statement will print to an object with an ifStreamSend interface.

If the statement is printing a list of items, the items must be separated with semicolons or commas. If semicolons are used, spaces are not inserted between printed items; if commas are used, the cursor will automatically advance to the next print zone before printing the next item.

Positive numbers and zero are printed with a leading space (without a plus sign). Spaces are not inserted before or after strings.

Code Block
titleExample
> x=5:print 25; " is equal to"; x ^2
> run
25 is equal to 25
Code Block
titleExample
> a$="string"
> print a$;a$,a$;" ";a$
> run
stringstring          string string

 

Each print zone in the following example is 16 characters wide. The cursor moves to the next print zone each time a comma is encountered.

Code Block
> print "zone 1","zone 2","zone 3","zone 4"
> run
zone 1          zone 2           zone 3           zone 4
Code Block
titleExample
> print "print statement #1 ";
> print "print statement #2"
> run
print statement #1 print statement #2

 

In some cases, semicolons can be dropped. For example, the following statement is legal:

Code Block
Print "this is a five "5"!!"

 

A trailing semicolon overrides the cursor-return so that the next PRINT statement begins where the last left off. If no trailing punctuation is used with a PRINT statement, the cursor drops to the beginning of the next line.

[@location]

If the console you are printing to has the ifTextField interface, you can use the @ character to specify where printing will begin.

Code Block
titleExample
print #m.text_field,@width*(height/2-1)+(width-len(msg$))/2,msg$;

Whenever you use PRINT @ on the bottom line of the display, an automatic line-feed causes all displayed lines to move up one line. To prevent this from happening, use a trailing semicolon at the end of the statement.

TAB (expression)

This statement moves the cursor to the specified position on the current line (modulo the width of the console if the TAB position is greater than the console width).

Code Block
titleExample
print tab(5)"tabbed 5";tab(25)"tabbed 25"

 

Note the following about the TAB statement:

  • The TAB statement may be used several times in a PRINT list.
  • No punctuation is required after a TAB statement.
  • Numerical expressions may be used to specify a TAB position.
  • The TAB statement cannot be used to move the cursor to the left.
  • If the cursor is beyond the specified position, the TAB statement is ignored.

POS(x)

This statement returns an integer that indicates the current cursor position from 0 to the maximum width of the window. This statement requires a dummy argument in the form of any numeric expression.

Code Block
print tab(40) pos(0)   'prints 40 at position 40

print "these" tab(pos(0)+5)"words" tab(pos(0)+5)"are";
print tab(pos(0)+5)"evenly" tab(pos(0)+5)"spaced"

FOR / END FOR

FOR counter_variable = initial_value TO final_value STEP increment / END FOR

The FOR statement creates an iterative loop that allows a sequence of program statements to be executed a specified number of times.

The initial_value, final_value, and increment can be any expression. The first time the FOR statement is executed, these three variables are evaluated and their values are saved; changing the variables during the loop will have no affect on the operation of the loop. However, the counter_variable must not be changed, or the loop will not operate normally. The first time the FOR statement is executed, the counter is set to both the value and type of the initial_value.

At the beginning of each loop, the value of the counter_variable is compared with the final_value. If the value of the counter_variable is greater than the final_value, the loop will complete and execution will continue with the statement following the END FOR statement. If, on the other hand, the counter has not yet exceeded the final_value, control passes to the first statement after the FOR statement. If increment is a negative number, the loop will complete when the value of the counter_variable is less than the final_value.

When program flow reaches the END FOR statement, the counter is incremented by the specified increment amount (or decremented if increment is a negative value). If the STEP [increment] language is not included in the FOR statement, the increment defaults to 1.

Use EXIT FOR to exit a FOR block prematurely.

The following script decrements i at the beginning of each loop until it is less than 1.

Code Block
for i=10 to 1 step -1
       print i
end for

FOR EACH IN / END FOR

FOR EACH item IN object / END FOR

The FOR EACH statement can iterate through a set of items in any object that has an ifEnum interface (i.e. an enumerator). The FOR block is terminated with the END FOR statement. Objects that are ordered intrinsically (such as roList) are enumerated in order, while objects that have no intrinsic order (such as roAssociativeArray) are enumerated in apparent random order. It is possible to delete entries as they are enumerated.

Use EXIT FOR to exit a FOR block prematurely.

The following objects can be enumerated: roList, roArray, roAssociativeArray, roMessagePort.

The following script iterates over an associative array in random order, prints each key/value pair, then deletes it.

Code Block
aa={joe: 10, fred: 11, sue:9}
For each n in aa
   Print n;aa[n]
   aa.delete[n]
end for

WHILE / EXIT WHILE

WHILE expression / EXIT WHILE

A WHILE loop executes until the specified expression is false. Use the EXIT WHILE statement to exit a WHILE block prematurely.

Code Block
k=0
while k<>0
   k=1
   Print "loop once"
end while
 
while true
   Print "loop once"
   Exit while
End while

IF / THEN / ELSE

IF expression THEN statements [ELSE statements]

Note

This is the single-line form of the IF THEN ELSE statement; see the next section for more details about the block form of the IF THEN ELSE statement.

The IF statement instructs the interpreter to test the following expression. If the expression is True, control will proceed to the statements immediately following the expression. If the expression is False, control will jump to either the matching ELSE statement (if there is one) or to the next program line after the block.

Code Block
titleExample
if x>127 then print "out of range" : end

 

THEN is optional in the above and similar statements. However, THEN is sometimes required to eliminate ambiguity, as in the following example

Code Block
if y=m then m=o 'won't work without THEN

Block IF / ELSEIF / THEN / ENDIF

The block (i.e. multi-line) form of IF / THEN / ELSE has the following syntax:

Code Block
If BooleanExpression [ Then ]
   [ Block ]
   [ ElseIfStatement+ ]
   [ ElseStatement ]
End If
 
ElseIfStatement ::=
   ElseIf BooleanExpression [ Then ]
   [ Block ]
 
ElseStatement ::=
   Else
   [ Block ]
Code Block
titleExample
vp_msg_loop:
        msg=wait(tiut, p)
        if type(msg)="rovideoevent" then                                            
            if debug then print "video event";msg.getint()
            if lm=0 and msg.getint() = meden then
                if debug then print "videofinished"
                retcode=5
                return
            endif
        else if type(msg)="rogpiobutton" then
            if debug then print "button press";msg
            if esc0 and msg=b0 then retcode=1:return
            if esc1 and msg=b1 then retcode=2:return
            if esc2 and msg=b2 then retcode=3:return
            if esc3 and msg=b3 then retcode=4:return
        else if type(msg)=" Invalid" then
            if debug then print "timeout"
            retcode=6
            return
        endif
 
        goto vp_msg_loop

Function() As Type / End Function

Function name(parameter As Type, …) As Type

Note

Each function has its own scope.

A function is declared using the Function() statement. The parentheses may contain one or more optional parameters; parameters can also have default values and expressions.

The type of each parameter may be declared. The return type of the function may also be declared. If a parameter type or return type is not declared, it is Dynamic by default. Intrinsic types are passed by value (and a copy is made), while objects are passed by reference. The Sub statement can be used instead of Function as a shortcut for creating a function with return type Void.

A parameter can be one of the following types:

  • Integer
  • Float
  • Double
  • String
  • Object
  • Dynamic

 

The function return can be one of the following types:

  • Void
  • Integer
  • Float
  • Double
  • String
  • Object
  • Dynamic

"M" Identifier 
Anchor
m_identifier
m_identifier

If a function is called from an associative array, then the local variable m is set to the associative array in which the function is stored. If the function is not called from an associative array, then its m variable is set to an associative array that is global to the module and persists across calls.

The m identifier should only be used for the purpose stated above: We do not recommend using m as a general-purpose identifier.

Code Block
titleExample
sub main()
   obj={
       add: add
       a: 5
       b: 10
       }
 
   obj.add()
   print obj.result
end sub
 
function add() As void
    m.result=m.a+m.b
end function

Anonymous Functions

A function without a name declaration is considered anonymous.

The following is a simple anonymous function declaration:

Code Block
myfunc=function (a, b)
       Return a+b
end function
 
print myfunc(1,2)

 

Anonymous functions can also be used with associative-array literals:

Code Block
q = {
 
starring : function(o, e)
str = e.GetBody()
print "Starring: " + str 
toks = box(str).tokenize(",")
for each act in toks
actx = box(act).trim()
if actx <> "" then
print "Actor: [" + actx + "]"
                o.Actors.Push(actx)
endif
end for
return 0
end function
}
 
q.starring(myobj, myxml)