JavaScriptEngineMBS.AddFunction(Name as String, JavaScript as String, FileName as String = "")

Dim j As New JavaScriptEngineMBS
j.AddFunction "adder", "function (x,y) { return x+y; }"

Optional provide a file name to show in stack traces.
Function source code may contain a function name, but we use only the name parameter to register the function as global one.

Some examples using this method:

• /Tools/JavaScript/JavaScript Engine
• /Tools/JavaScript/JavaScript Pixel Editing

JavaScriptEngineMBS.CallFunction(Name as String, ParamArray Params as Variant) as Variant

Dim j As New JavaScriptEngineMBS

// just add a function
j.AddFunction "adder", "function (x,y) { return x+y; }"

// call it
Dim r As Variant = j.CallFunction("adder", 2, 3)
Break // check result in debugger

Parameters are passed to the function.
If the function needs more parameter, undefined values are used to fill up.
If the function needs less parameters, additional ones are dropped.

Returns the result of the function converted to a variant.

See also:

• CallFunction(Name as String, Params() as Variant) as Variant

JavaScriptEngineMBS.CallFunction(Name as String, Params() as Variant) as Variant

Dim j As New JavaScriptEngineMBS

// just add a function
j.AddFunction "adder", "function (x,y) { return x+y; }"

// call it
Dim Params() As Variant
params.Append 3
params.Append 4
params.Append 5 // one too much -> will be ignored
Dim r As Variant = j.CallFunction("adder", params)
Break // check result in debugger

Parameters are passed to the function.
If the function needs more parameter, undefined values are used to fill up.
If the function needs less parameters, additional ones are dropped.

Returns the result of the function converted to a variant.

See also:

• CallFunction(Name as String, ParamArray Params as Variant) as Variant

JavaScriptEngineMBS.CallFunctionMT(Name as String, ParamArray Params as Variant) as Variant

Threaded version of CallFunction. If events or delegates are called on main thread, the preemptive thread waits for answer.

Parameters are passed to the function.
If the function needs more parameter, undefined values are used to fill up.
If the function needs less parameters, additional ones are dropped.

Returns the result of the function converted to a variant.

The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.

See also:

• CallFunctionMT(Name as String, Params() as Variant) as Variant

Some examples using this method:

• /Tools/JavaScript/JavaScript Pixel Editing

JavaScriptEngineMBS.CallFunctionMT(Name as String, Params() as Variant) as Variant

Threaded version of CallFunction. If events or delegates are called on main thread, the preemptive thread waits for answer.

Parameters are passed to the function.
If the function needs more parameter, undefined values are used to fill up.
If the function needs less parameters, additional ones are dropped.

Returns the result of the function converted to a variant.

The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.

See also:

• CallFunctionMT(Name as String, ParamArray Params as Variant) as Variant

JavaScriptEngineMBS.DateComponentsToTime(date as JavaScriptDateComponentsMBS) as Double

Dim j As New JavaScriptEngineMBS

Dim d As New JavaScriptDateComponentsMBS
d.Year = 1970
d.Month = 1
d.day = 1

// shows zero as that's the start point in time for unix
MsgBox "Start Time: "+Str(j.DateComponentsToTime(d))

Convert components (year, month, day, etc), interpreted in UTC, into a time value. The weekday argument is ignored in the conversion. If the component values are invalid, an error is thrown.

There are some differences to the ECMAScript Date.UTC() built-in:

• There's no special handling of two-digit years. For example, Date.UTC(99, 0, 1) gets interpreted as 1999-01-01. If time is 99, it's interpreted as the year 99.
• The milliseconds component is allowed fractions (sub-millisecond resolution) so that the resulting time value may have fractions.

JavaScriptEngineMBS.Destructor

JavaScriptEngineMBS.Evaluate(JavaScript as String) as Variant

Dim j As New JavaScriptEngineMBS

Dim v As Variant = j.Evaluate("2+3")
MsgBox v.StringValue

This may include definition of functions and objects and using them.
Result is converted to variant and returned.

JavaScriptEngineMBS.EvaluateMT(JavaScript as String) as Variant

Threaded version of Evaluate. If events or delegates are called on main thread, the preemptive thread waits for answer.

This may include definition of functions and objects and using them.
Result is converted to variant and returned.

The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.

JavaScriptEngineMBS.EvaluateToString(JavaScript as String) as String

Dim j As New JavaScriptEngineMBS

Dim s As String = j.EvaluateToString("2+3")
MsgBox s

This may include definition of functions and objects and using them.
Result is converted to string in JavaScript and returned as Xojo string.

Some examples using this method:

• /Tools/JavaScript/JavaScript AES/JavaScript AES
• /Tools/JavaScript/JavaScript Engine
• /Tools/JavaScript/LibPhoneNumber/JavaScript LibPhoneNumber

JavaScriptEngineMBS.GlobalMemoryBlock(PropertyName as String) as MemoryBlock

A normal memoryblock passed as parameter to a function or property would be copied.
This method allows you to define a buffer in JavaScript to reference the bytes in a memoryblock, so all changes are visible in Xojo directly.

You can assign nil as value to clear a memoryblock.
(Read and Write computed property)

Some examples using this property:

• /Tools/JavaScript/JavaScript Pixel Editing

JavaScriptEngineMBS.GlobalProperty(PropertyName as String) as Variant

Dim j As New JavaScriptEngineMBS

j.GlobalProperty("Hello") = "World"
MsgBox j.GlobalProperty("Hello")

Values are converted to/from variant.
(Read and Write computed property)

JavaScriptEngineMBS.GlobalPropertyJSON(PropertyName as String) as String

Dim j As New JavaScriptEngineMBS

j.GlobalProperty("Hello") = "World"
MsgBox j.GlobalPropertyJSON("Hello")

j.GlobalPropertyJSON("test") = "[1,2,3]"
MsgBox j.GlobalPropertyJSON("test")

Same as GlobalProperty, but needs JSON text.
(Read and Write computed property)

JavaScriptEngineMBS.InitModules

Only calls JS.InitModules once on a new instance of the JavaScript engine.
Define your own Duktape.modSearch() to provide environment specific module lookups.
After these steps, require() will be registered to the global object and the module system is ready to use.

JavaScriptEngineMBS.LoadFunction(Name as String, Data as Memoryblock) as Boolean

Dim j As New JavaScriptEngineMBS

// just add a function
j.AddFunction "adder", "function (x,y) { return x+y; }"

// get byte code
Dim m As MemoryBlock = j.SaveFunction("adder")

// and load back with new name
dim b as Boolean = j.LoadFunction("adder2", m)

// call it
Dim r As Variant = j.CallFunction("adder2", 2, 3)
break // check result in debugger

Load a buffer containing bytecode, recreating the original ECMAScript function (with some limitations). You must ensure that the bytecode has been dumped with a compatible Duktape version and that the bytecode has not been modified since. Loading bytecode from an untrusted source is memory unsafe and may lead to exploitable vulnerabilities.

Returns true in case of success or false on failure.

JavaScriptEngineMBS.Now as Double

This is seconds since 1st January 1970 multiplied by 1000 and may contain fraction with microseconds.

Get current time in POSIX milliseconds, as seen by the ECMAScript environment. The return value matches Date.now() with the reservation that sub-millisecond resolution may be available.

JavaScriptEngineMBS.RegisterFunction(Name as String, theDelegate as JavaScriptEngineDelegateMBS, ArgCount as Integer = -1, tag as Variant = nil)

Dim j As New JavaScriptEngineMBS

j.RegisterFunction "MyFunction", AddressOf testFunction, 1, Nil

// call in JavaScript
Dim x As Variant = j.Evaluate("MyFunction(123);")

// call via plugin
Dim r As Variant = j.CallFunction("MyFunction", "Hello")

Break

'Public Function testFunction(Name as String, Params() as Variant, tag as Variant) as Variant
'  MsgBox params(0).StringValue
'  Return "ok"
'End Function

ArgCount can be in range from -1 to 15.
If -1 is passed, we allow variable number of arguments.
Tag is passed to delegate and allows you to pass a context object to the delegate.

Some examples using this method:

• /Tools/JavaScript/JavaScript Engine

JavaScriptEngineMBS.SaveFunction(Name as String) as MemoryBlock

Dim j As New JavaScriptEngineMBS

// just add a function
j.AddFunction "adder", "function (x,y) { return x+y; }"

// get byte code
Dim m As MemoryBlock = j.SaveFunction("adder")

// and load back with new name
dim b as Boolean = j.LoadFunction("adder2", m)

// call it
Dim r As Variant = j.CallFunction("adder2", 2, 3)
break // check result in debugger

Dump an ECMAScript function at stack top into bytecode, replacing the function with a buffer containing the bytecode data. The bytecode can be loaded back using LoadFunction().

JavaScriptEngineMBS.TimeToDateComponents(time as Double) as JavaScriptDateComponentsMBS

Dim j As New JavaScriptEngineMBS

// get now
Dim t1 As Double = j.Now

// as compoents
Dim d1 As JavaScriptDateComponentsMBS   = j.TimeToDateComponents(t1)
Dim s1 As String = d1.SQLDateTime
// looks right?

Break

Convert a time value to components (year, month, day, etc) interpreted in UTC. If the time value is invalid, e.g. beyond the valid ECMAScript time range, an error is thrown.

There are some differences to the ECMAScript Date UTC accessors like Date.prototype.getUTCMinutes():

The time value is allowed to have fractions (sub-millisecond resolution) so that the millisecond component may also have fractions.