Global

Description

Extends the Global context object with convenience properties and functions.

The DSE static object contains useful information about the current running environment.

Static Public Member Functions
ArrayBuffer	atob (any data)
String	btoa (any data)
void	clearAllTimers ()
void	clearInstanceTimers (instanceName)
void	gc ()
String	hash (any data, String algorithm="md5")
void	include (String scriptFile)
void	require (String id)
Locale	locale (name)
String	Format (String format)
String	sprintf (String format,...args)

Member Function Documentation

atob()

ArrayBuffer atob ( any  data )

static

Decodes data bytes of base-64 encoded plain text and returns it as binary data ("ascii to binary") in a ArrayBuffer container.

data can be a string or ArrayBuffer (or similar collection of ASCII bytes). Note that strings are automatically converted to ASCII (Latin 1 encoding). To avoid any conversion, pass an ArrayBuffer (or similar).

btoa()

String btoa ( any  data )

static

Returns data bytes as base-64 encoded plain text ("binary to ascii").

data can be a ArrayBuffer or a string. Note that data strings are automatically converted to UTF-8 text before decoding. To avoid any conversion, pass an ArrayBuffer (or similar raw collection of bytes).

clearAllTimers()

void clearAllTimers ( )

static

Immediately terminates any and all timers started with setTimeout() or setInterval() within the current engine instance.

If invoked in a Shared engine, will stop all timers started by any scripts/expressions running in the Shared instance.
If invoked in a Private engine, affects only the timers for that particular named instance.

See also

clearInstanceTimers()

clearInstanceTimers()

void clearInstanceTimers ( instanceName  )

static

Immediately terminates any and all timers started with setTimeout() or setInterval() for the given instanceName (State name).

If the instance doesn't exist or has no running timers then this function does nothing.
If invoked in a Private engine instance, this has the same effect as clearAllTimers().

See also

clearAllTimers()

gc()

void gc ( )

static

Runs the garbage collector.

The garbage collector will attempt to reclaim memory by locating and disposing of objects that are no longer reachable in the script environment. Normally this is taken care of automatically by the script engine on a regular basis, but this function can be used to explicitly initiate collection as soon as possible.

hash()

String hash ( any  data, String  algorithm = "md5"  )

static

Returns a cryptographic hash of data using given algorithm as a string of hexadecimal characters.

data can be a byte array (eg. ArrayBuffer) or string or anything that can be converted to an array/collection of bytes.

The default algorithm is MD5. The following algorithms are supported:

• md4 Generate an MD4 hash sum
• md5 Generate an MD5 hash sum
• sha1 Generate an SHA-1 hash sum
• sha224 Generate an SHA-224 hash sum (SHA-2).
• sha256 Generate an SHA-256 hash sum (SHA-2).
• sha384 Generate an SHA-384 hash sum (SHA-2).
• sha512 Generate an SHA-512 hash sum (SHA-2).
• sha3_224 Generate an SHA3-224 hash sum.
• sha3_256 Generate an SHA3-256 hash sum.
• sha3_384 Generate an SHA3-384 hash sum.
• sha3_512 Generate an SHA3-512 hash sum.
• keccak_224 Generate a Keccak-224 hash sum.
• keccak_256 Generate a Keccak-256 hash sum.
• keccak_384 Generate a Keccak-384 hash sum.
• keccak_512 Generate a Keccak-512 hash sum.

Throws a TypeError if algorithm isn't one of the types listed above.

include()

void include ( String  scriptFile )

static

Read and evaluate scriptFile as JavaScript in the current scripting engine context (global object) at the location of this function call.

Any errors produced by the script are raised and reported into the current context.

To get just the contents of a file, w/out evaluating it, use File.read().

If a relative scriptFile path is used:

• It is first resolved relative to the current script/module file (in which the include() call is used).
• If that fails (the file is not found), it is then resolved using the current value of the DSE.SCRIPTS_BASE_DIR property (the plugin's Script Files Base Directory setting in Touch Portal or relative to the plugin's install location).
• If the included file still cannot be located at that point, an exception is thrown.

Exceptions

Error

- file loading fails for any reason (file not found/etc).

See also

require()

require()

void require ( String  id )

static

Used to import all or part of JavaScript modules or JSON objects.

The id parameter specifies the name of a module or file to import from, which can be a relative or absolute path to a file, or the name of a previously-registered module (for example provided with the plugin's default environment or registered by the user).

Files with a .json extension are treated as JSON objects. All other file names are treated as ECMAScript Modules. Note that there is currently no support for CommonJS-style module features (within the modules themselves).

If a relative file path is used in the id parameter, then:

• It is first resolved relative to the current script/module file (in which the require() call is used).
• If that fails (the file is not found), it is then resolved using the current value of the DSE.SCRIPTS_BASE_DIR property (the plugin's Script Files Base Directory setting in Touch Portal or relative to the plugin's install location).
• If the included file still cannot be located at that point, an exception is thrown.

require() can also be used to import built-in named modules (provided by DSE). These are documented separately. Currently there is no way to add custom named modules, but this may change in the future. For an example (and so far the only module), see Clipboard.

require() can be used anywhere within a script, not just at the top like import statements. This also means modules or objects can be imported conditionally, inside an if block, for example.

require() mimics parts of both ECMAScript import() method and the Node.js require() function. Unlike the former, it is synchronous. Unlike the latter, it does not provide any additional features to the module being loaded (eg. "global" variables like module.exports).

Examples:

// Importing a local module with a path relative to the current
// script's directory. (On Windows, this would resolve to .\path\myLocalModule.)
const myModule = require('./path/myModule');
// All of the module's exported functions/variables are now available in the `myModule` scope/namespace.
 
// Importing only some of a module's exports:
const { valueToClipboard } = require("../examples/Clipboard/clipboard.mjs");
// The `valueToClipboard()` function is now available in the current namespace.
 
// Using an alias for the import:
const { toString: genericToString } = require("../genericModule.mjs");
// The `genericToString()` function is now in the current namespace as an alias to `isString()` exported from "genericModule.mjs".
 
// Importing a JSON file:
const jsonData = require('./path/filename.json');
// All JSON objects from the file are now available in the `jsonData` scope/namespace.
 
// Importing a specific object from a JSON file:
const { item } = require('./path/filename.json');
// The `item` object is now available in the current namespace.
 
// Importing a specific object from a JSON file with an alias:
const { result.item: jsonDataItem } = require('./path/filename.json');
// The `jsonDataItem` object is now available in the current namespace as an alias to the `result.item` object from the file.

Exceptions

Error

- file loading fails for any reason (file not found/etc).

See also

include()

Since

v1.2

locale()

Locale locale ( name  )

static

Returns a JS object representing the locale with the specified name, which has the format "language[_territory][.codeset][@modifier]" or "C", where:

• language is a lowercase, two-letter, ISO 639 language code.
• territory is an uppercase, two-letter, ISO 3166 country code.
• codeset and modifier are ignored (the syntax is allowed just to keep with the standard).
• The separator character between language and territory may be an underscore (_) or dash (-).

If the name parameter is empty, returns the default Locale which the application was started with.
If the string violates the locale format, or language is not a valid ISO 369 code, the "C" locale is used instead.
If country is not present, or is not a valid ISO 3166 code, the most appropriate country is chosen for the specified language.

Format()

String Format ( String  format )

static

Equivalent to the String.format() extension method.

Provides .NET style string formatting.

sprintf()

String sprintf ( String  format,   args  )

static

For formatting strings, works like the classic C printf() function.

Formats format string using the provided arguments in args, if any.

Parameters

format	The formatting string used to format the additional arguments.
args	Zero or more arguments for the format string.

Examples (from cppreference.com):

var s = "Hello";
sprintf("[%10s]\n",          s);
sprintf("[%-10s]\n",         s);
sprintf("[%*s]\n",       10, s);
sprintf("[%-10.*s]\n",    4, s);
sprintf("[%-*.*s]\n", 10, 4, s);
// output:
//  [     Hello]
//  [Hello     ]
//  [     Hello]
//  [Hell      ]
//  [Hell      ]
 
sprintf("Decimals: %i %d %.6i %i %.0i %+i %i\n",
                    1, 2,   3, 0,   0,  4,-4);
// output:
//   Decimals: 1 2 000003 0  +4 -4
 
sprintf("Rounding: %f %.0f %.32f\n", 1.5, 1.5, 1.3);
sprintf("Padding: %05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
sprintf("Scientific: %E %e\n", 1.5, 1.5);
// output:
//   Rounding: 1.500000 2 1.30000000000000004440892098500626
//   Padding: 01.50 1.50  1.50
//   Scientific: 1.500000E+00 1.500000e+00

There are many format references online. Here's one from Alvin Alexander (just ignore the references to Java and Perl).

Or an official reference at cppreference.com.

This function is originally from the Locutus project. The original reference is available on their site.

See also

String.format() for .NET style formatted strings.