Global utility functions

BrightScript has a set of standard, module scope, functions. These
functions are stored in the global object. If the compiler sees a
reference to one of the global functions, it directs the runtime to call
the appropriate global object member.

Sleep(milliseconds as Integer) as Void

This function causes the script to pause for the specified time, without
wasting CPU cycles. There are 1000 milliseconds in one
second.

sleep(1000) ' sleep for 1 second
sleep(200) ' sleep 2/10 of a second
sleep(3000) ' sleep three seconds

Wait(timeout as Integer, port as Object) as Object

This function waits on objects that are "waitable" (those that have a
MessagePort interface). Wait() returns the event object that was posted
to the message port. If timeout is zero, "wait" will wait for ever.
Otherwise, Wait will return after timeout milliseconds if no messages
are received. In this case, Wait returns a type "invalid".

Example

p = CreateObject("roMessagePort")
s = CreateObject("roScreen")
s.SetPort(p)
msg = Wait(0, p)
print Type(msg) ' e.g. roUniversalControlEvent
print msg.GetInt() ' button number

GetInterface(object as Object, ifname as String) as Interface

Each BrightScript Component has one or more interfaces. This function
returns a value of type "Interface". Note that generally BrightScript Components allow you to skip the
interface specification. In which case, the appropriate interface within
the object is used. This works as long as the function names within the
interfaces are unique.

FindMemberFunction(object as Object, funName as String) As Interface

Returns the interface from the object that provides the specified
function, or invalid if not found.

For example:

print FindMemberFunction({}, "Count") '= <Interface: ifAssociativeArray>

UpTime(dummy as Integer) as Float

Returns the uptime of the system since the last reboot in seconds.

RebootSystem() as Void

Requests the system to perform a soft reboot. The Roku platform has
disabled this feature.

ListDir(path as String) as Object

Returns a List object containing the contents of the directory path
specified.

For example:

 BrightScript> l=ListDir("pkg:/movies")
 BrightScript> print l
 test_movie_3.vob
 test_movie_4.vob
 test_movie_1.vob
 test_movie_2.vob

ReadAsciiFile(filepath as String) as String

This function reads the specified file and returns the data as a string.

The file can be encoded as either UTF-8 (which includes the 7-bit ASCII
subset) or UTF-16.

An empty string is returned if the file can not be read.

For example:

text=ReadAsciiFile("tmp:/config.txt")

WriteAsciiFile(filepath as String, text as String) as Boolean

This function writes the specified string data to a file at the
specified location.

The string data is written as UTF-8 encoded (which includes the 7-bit
ASCII subset).

The function returns true if the file was successfully written.

For example:

WriteAsciiFile("tmp:/config.txt", "the text to write")

CopyFile(source as String, destination as String) as Boolean

Make a copy of a file.

MoveFile(source as String, destination as String) as Boolean

Rename a file.

MatchFiles(path as String, pattern_in as String) as Object

Search a directory for filenames that match a certain
pattern. Pattern is a wildmat expression. Returns a List object.
This function checks all the files in the directory specified against
the pattern specified and places any matches in the returned roList.

The returned list contains only the part of the filename that is matched
against the pattern not the full path.
The pattern may contain certain special characters:

• A '?' matches any single character.
• A '*' matches zero or more arbitrary characters.
• The character class '[...]' matches any single character specified
  within the brackets. The closing bracket is treated as a member of
  the character class if it immediately follows the opening bracket.
  i.e. '[]]' matches a single close bracket. Within the class '-'
  can be used to specify a range unless it is the first or last
  character. e.g. '[A-Cf-h]' is equivalent to '[ABCfgh]'.
• A character class can be negated by specifying '^' as the first
  character. To match a literal '^' place it elsewhere within the
  class.
• The characters '?', '*' and '[' lose their special meaning if
  preceded by a single ''. A single '' can be matched as ''.

For example:

files = MatchFiles(".", "*.mpg")

DeleteFile(file as String) as Boolean

Delete the specified file.

DeleteDirectory(dir as String) as Boolean

Deletes the specified directory. It is only possible to delete an empty
directory.

CreateDirectory(dir as String) as Boolean

Creates the specified Directory. Only one directory can be created at a
time

FormatDrive(drive as String , fs_type as String) as Boolean

Formats a specified drive using the specified filesystem.

StrToI(str as String) as Dynamic

Return the integer value of the string, or 0 if nothing is parsed.

RunGarbageCollector() as Object

This function runs the garbage collector on the current thread. It returns and Associative array with some statistics regarding the garbage collection.
See the Garbage collection section of this manual for more detail. You don't normally need to call
this function.

For example:

BrightScript Debugger> a=[]
BrightScript Debugger> a[0]=a
BrightScript Debugger> a=invalid
BrightScript Debugger> print RunGarbageCollector()
COUNT: 3
ORPHANED: 1
ROOT: 2

ParseJson(jsonString as String, flags = "" as String) as Object

This function will parse a string formatted according to RFC4627 and
return an equivalent BrightScript object (consisting of booleans,
integer and floating point numbers, strings, roArray, and
roAssociativeArray objects). If the string is not syntactically
correct, Invalid will be returned. A few other things to note:

• As of Roku OS 14.6, you can use the d option in order to use double-precision floating point values (roDouble) to improve the precision of the parsed numbers. This helps developers handle JSON payloads from server-side ad insertion (SSAI) providers that use floating-point values to represent time values.

• By default, any roAssociativeArray objects in the returned objects will be
  case sensitive. To return a case-insensitive structure, set the flags parameter to "i".

  If the "i" option is used, and the jsonString includes multiple keys that match case-insensitively, duplicates are overwritten and only the last matching values are preserved.

• An error will be returned if arrays/associative arrays are nested
  more than 256 levels deep.

For example, lets say your service returns a JSON object that contains a
list of photo URLs:

{
      "photos" : [
           {
                 "title" : "View from the hotel",
                 "url" : "http://example.com/images/00012.jpg"
           },
           {
                 "title" : "Relaxing at the beach",
                 "url" : "http://example.com/images/00222.jpg"
           },
           {
                 "title" : "Flat tire",
                 "url" : "http://example.com/images/00314.jpg"
           }
      ]
}

searchRequest = CreateObject("roUrlTransfer")
searchRequest.SetURL("http://api.example.com/services/rest/getPhotos")
response = ParseJson(searchRequest.GetToString())
for each photo in response.photos
    GetImage(photo.title, photo.url)
end for

FormatJson(json as Object, flags = 0 as Integer) as String

Formats a supported data type as a JSON string.

Data types supported are booleans, integer and floating point numbers,
strings, roArray, and roAssociativeArray objects.

Passing invalid into this function returns "null".

An error will be returned if arrays/associative arrays are nested more
than 256 levels deep.

If an error occurs an empty string will be returned.

Normally non-ASCII characters are escaped in the output string as
"\uXXXX" where XXXX is the hexadecimal representation of the Unicode
character value.

Output flags (optional)

Example

euroStr = Chr(&h20AC)

'* By default, non-ASCII Unicode characters are escaped in JSON style
print FormatJSON(euroStr)
' => "\u20AC"

'* If specified, non-ASCII Unicode characters are not escaped.
print FormatJSON(euroStr, &h0001)
' => "€"

Behavior flags (optional)

Example

list = CreateObject("roList")
obj = {list:list, n:1}

'* By default, attempting to format with any unsupported type fails and returns an empty string.
print FormatJSON(obj)
' => BRIGHTSCRIPT: BRIGHTSCRIPT: ERROR: FormatJSON: list: Value type not supported: roList

'* If specified, unsupported values can be output as JSON 'null' values.
'* (In this case, no error diagnostics are printed to the console).
print FormatJSON(obj, &h0100)
' => {"list":null,"n":1}

'* If specified, unsupported values can be output as diagnostic string values.
'* The diagnostic string is the component type in angle brackets.
'* (In this case, no error diagnostics are printed to the console).
print FormatJSON(obj, &h0200)
' => {"list":"<roList>","n":1}

FormatJson(json as Object, flags = "" as String) as String

The same as the previous FormatJson method, but accepts the flags parameter as a string.

Tr(source as String) as String

Translates the source string into the language of the current locale.
The function looks for a translations.xml file in the XLIFF format in
the pkg:/locale subdirectory named for the current locale (see
ifDeviceInfo.GetCurrentLocale for the list
of currently-supported locales). If the translations.xml file exists for
the current locale, and contains the source string with a translated
string, the function returns the translated string. Otherwise, the
function returns the original source string.

In some cases you may want to include a placeholder marker in a
localizable string that gets dynamically substituted with a value at
runtime.
One way to accomplish that is to use the Replace method on the string
value returned from the Tr() lookup.

For example:

`text = Tr("Video will start in %1 seconds").Replace("%1",
numSeconds.ToStr())`