Utility

Utility functions for working in Lua.

Require

require(id)

DescriptionParametersReturn value

Functions similar to the standard lua require function but takes a script id. It will evaluate the script and can be used to share functions between scripts.

• id:Uuid script id

• Boolean true if found, false if not

Len

len(ls)

DescriptionParametersReturn value

Returns the length of a table. The # notation can also be used as #listVar.

• table:String input table

• Number number of items in the table

Get

get(table, path)

DescriptionParametersReturn value

Get an item from a table using a dot notation path.

• table:Table input table
• path:String dot notation path

• Any item at the path or nil

First, Last, At

first(table)
last(table)
at(table, key)

DescriptionParametersReturn value

Get the first, last or specific item from a table.

• table:Table input table
• key:Any numeric index or string key

• Any first item from the table or nil

Param

param(path)

DescriptionParametersReturn value

Get a parameter from the enviroment.

• path:String path to the parameter

• Any Item available at that path or nil

Mock

mock(path, value)

DescriptionParametersReturn value

Add a parameter to the enviroment for testing purposes; if there are actual environment values they will override the parameters supplied to mock.

• path:String path to the enviroment
• value:Any any value

No return value

Random

random(low, high)

DescriptionParametersReturn value

Return a random value between low and high

• low:Integer lower limit inclusive
• high:Integer upper limit exclusive

• Integer Random value

FromJson

FromJson(text)

DescriptionParametersReturn value

Convert a JSON string to a Lua table.

• text:String string as serialized JSON

• Table Lua table

ToJson

ToJson(table)

DescriptionParametersReturn value

Convert a Lua table to a serialized JSON string

• table:Table Lua table

• String serialized JSON string with either an object or JSON scalar as root

ToJsonArray

ToJsonArray(table)

DescriptionParametersReturn value

Convert a Lua table to a serialized JSON Array string

• table:Table Lua table

• String serialized JSON string with an Array as root

Sleep

Sleep(ms)

DescriptionParametersReturn value

Sleeps for a period of time. The Sleep function can be used to throttle script behavior or allow reads to catch up with writes.

• There can be 50-100 ms delay between writing values and them being available for read.
• If the script consumes all available allocated CPU for an extended period it will be terminated.

If the script processes a very large list of data and contains many read or write requests use Sleep to keep the script from consuming all available resources.

• ms:Number milliseconds to sleep for

No return value

ToLocalDate

ToLocalDate(value)

DescriptionParametersReturn value

Convert a string to a date.

• value:String parseable string representing a date in ISO8601 format

Date

FormatDate

FormatDate(value, format)

DescriptionParametersReturn value

Parse a string in ISO8601 format to a date and then format for usage. Use the following date formats. Some example ISO8601 strings include 2008-03-01, 20080301 and 2008-03-01T13:00:00Z.

• value:String parseable string representing a date in ISO8601 format
• format:String date format

String

ParseDateTime

ParseDateTime(str, format)

DescriptionParametersReturn valueFormat options

Parse a string into an ISO date time string

• str:String string in any readable date time format
• format:String format the str parameter is in

Date in ISO8601 format

Symbol  Meaning                      Presentation  Examples
------  -------                      ------------  -------
G       era                          text          AD
C       century of era (>=0)         number        20
Y       year of era (>=0)            year          1996

x       weekyear                     year          1996
w       week of weekyear             number        27
e       day of week                  number        2
E       day of week                  text          Tuesday; Tue

y       year                         year          1996
D       day of year                  number        189
M       month of year                month         July; Jul; 07
d       day of month                 number        10

a       halfday of day               text          PM
K       hour of halfday (0~11)       number        0
h       clockhour of halfday (1~12)  number        12

H       hour of day (0~23)           number        0
k       clockhour of day (1~24)      number        24
m       minute of hour               number        30
s       second of minute             number        55
S       fraction of second           millis        978

z       time zone                    text          Pacific Standard Time; PST
Z       time zone offset/id          zone          -0800; -08:00; America/Los_Angeles

'       escape for text              delimiter
''      single quote                 literal       '

Now

Now()

Description

Return the current UTC date formatted as YYYY-MM-DD. This will be UTC date. If a local date is needed see Today below that takes a timezone identifier.

Timestamp

Timestamp()

Description

Return the current UTC date as a fully ISO datetime string.

DateDiff

DateDiff(date1, date2, span)

DescriptionParametersReturn value

Difference between two dates.

DateDiff("2023-01-01", "2023-01-08", "day")

-- Return value: 7

• date1:String parseable string representing a date in ISO8601 format
• date2:String parseable string representing a date
• span:Enumeration hour | day | week | year

Returns an integer with the difference between the dates in with span as the unit

DateAdd

DateAdd(date, span, period)

DescriptionParametersReturn value

Add a period from the date.

DateAdd('2023-01-01', 'day', 7)

-- Return value: 2023-01-08

• date:String parseable string representing a date in ISO8601 format
• span:Enumeration hour | day | week | year
• period:Int count of the span unit

Date in YYYY-MM-DD format or ISO format (if span is hour)

DateSubtract

DateSubtract(date, span, period)

DescriptionParametersReturn value

Subtract a period from the date.

• date:String parseable string representing a date in ISO8601 format
• span:Enumeration hour | day | week | year
• period:Int count of the span unit

Date in YYYY-MM-DD format or ISO format (if span is hour)

DateMove

DateMove(date, move)

DescriptionParametersReturn value

Move to a the start of a week, month or year.

DateMove("2022-03-12", "startOfWeek")

• date:String parseable string representing a date in ISO8601 format
• move:Enumeration startOfWeek | startOfMonth | startOfYear

Date in YYYY-MM-DD format

MarkdownToHtml

MarkdownToHtml(markdown)

DescriptionParametersReturn value

Convert markdown syntax to HTML

• markdown:String valid Markdown

String with HTML syntax

Env

core.Env(handle)

DescriptionParametersReturn value

Look up an environment variable

• handle:String the handle of the env variable

• String value of the env variable

Today

Today(timezoneid)

DescriptionParametersReturn value

Today in a specific timezone

Time zone id list is available at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

• id:String Time zone id

• YYYY-MM-DD string for the day in the specified time zone

LastCallResponse

LastCallResponse()

DescriptionParametersReturn value

Last response object for any API call.

None

• message - API call dependent message
• result - boolean