esi-tool

This library contains various helper functions of different type, not really matching one of the major topics.

Changes

Version Date Description s:i Release

1.0.5

2020-12-08

TFS code synchronisation

1.72

1.0.4

2020-07-24

added SHALLOWCOPY and MERGETABLE

1.0.3

2020-03-10

Fix links and section titles in the docs

1.0.2

2019-11-22

GETREFERENCE update and documentation

1.0.1

2018-06-24

added FILETOTABLE

1.36

1.0.0

2018-06-03

First system:inmation inclusion

1.34

0.1.5

2018-06-03

extended NUMBERTYPE for a range checking option

0.1.4

2018-05-29

type checks added

0.1.1

2018-05-27

Initial release

Dependencies

library version built-in Notes

esi-string

0.1.2

yes

for STRING

Known Issues

  • Documentation (this markdown file) is not completed

  • Unit tests are missing

Available functions

The library supplies the following public functions:

BOOLEANTYPE a simple check for Lua data type boolean

FUNCTIONTYPE a simple check for Lua data type function

GETREFERENCE a simple check for Lua data type function

IIF an immediate if, missing in Lua

INFO to comply with the ESI standard

ISOBJECT a simple check for valid inmation objects as parameters

NILTYPE a simple check for Lua data type nil

NUMBERTYPE a check for Lua data type number, optionally a range

RELTIME translates a relative time mask in a millisecond posix time

STRINGTYPE a simple check for Lua data type string

TABLETYPE a simple check for Lua data type table

THREADTYPE a simple check for Lua data type thread

USERDATATYPE a simple check for Lua data type userdata

READONLYTABLE

CHECKTYPE

SHALLOWCOPY

DEEPCOPY

MEMOIZE

AUTOMAGICTABLE

REVERSETABLE

MERGETABLE

COUNT

EXTRACTKEYS

EXTRACTVALUES

Documentation

The library functions are documented in detail in the following sections.

IIF

IIF(condition, trueret, falseret)

Tests a condition and returns one of two results depending on the evaluation result.

Note: In principle, all three parameters are optional, but unless at least condition and trueret are something different than nil, the function can return itself something different than nil.

IIF parameters

condition (variant, optional)

Anything might be passed into the function as condition, but it will only return the trueret parameter in case the condition evaluates to true.

trueret (variant, optional)

Anything might be passed into the function as trueret, but it will only return the trueret parameter in case the condition evaluates to true.

falseret (variant, optional)

Anything might be passed into the function as falseret, but it will only return the falseret parameter in case the condition evaluates to false. If this parameter is not specified it will return nil in this case.

IIF throws

no errors

IIF Usage

local T=require('esi-tool')
local str=T:IIF(12>11,"the logic works","oops!")
assert(str~="oops!")

INFO

ESI requirement. Not documented for brevity.

ISOBJECT

ISOBJECT(par)

Tests par to be a proper inmation object data structure.

ISOBJECT parameters

par (variant, required)

Anything might be passed into the function, but it will only return true if the following conditions are met:

  1. It is a table

  2. It has a field named ObjectName of type string

  3. The ObjectName is not empty

ISOBJECT returns

true if the above conditions are met, false otherwise.

ISOBJECT throws

no errors

ISOBJECT Usage

local T=require('esi-tool')
assert(T:ISOBJECT(inmation.getobject("/System")))
...

RELTIME

RELTIME(mask,from)

Calculates relative time from either current component time or a given time reference. The relative distance is expressed by a string, which can be composed of day(s), hour(s), minute(s) and second(s).

RELTIME parameters

mask (string, required)

A string like "-1d" or "-1d" or "1d", all equivalent. The leading -sign is always assumed and refers to now - or in case the from parameter is given - to the point in time which the from parameter holds. The plus or minus sign can be omitted, if it is ommitted a minus is the default. As such, the +-sign needs to be specified for the calculation of future points in time.

Mask element (Token) Valid expressions

Days

"d","D","days","day"

Hours

"h","H","hours","hour"

Minutes

"m","M","minutes","minute","mins","min"

Seconds

"s","S","seconds","second","secs","sec"

The parsing happens case-insensitive, so all equivalent uppercase tokens would work as well.

from (string or number, optional)

In case from is supplied as a string, it must be supplied as ISO8601 compliant UTC time string, such as "2018-02-23T17:50:23.000Z".

In case from is supplied as a number, it will be interpreted as milliseconds since EPOCH UTC, also known as POSIX time. This is the internal inmation standard time.

RELTIME returns

the calculated POSIX time as a number (It can easily transformed in its string equivalent by using inmation.gettime()), or nil in case of an invalid mask.

RELTIME throws

no errors

RELTIME Usage

local ts=TOOL:RELTIME("*-1d 6h 40m")
assert(ts)
return inmation.gettime(ts)

or (using a weird mask)

local ts=TOOL:RELTIME("1 dAy 6 HourS    40        mINs")
assert(ts)
return inmation.gettime(ts)

or (with given reference time)

local ts=TOOL:RELTIME("1D6H40M","2018-01-01T12:00:00.000Z")
assert(ts)
return inmation.gettime(ts)

TABLETYPE

TABLETYPE(t)

Tests t to be a Lua data type table.

TABLETYPE parameters

t (variant, required)

TABLETYPE returns

true if the parameter t is a Lua data type table, false otherwise.

TABLETYPE throws

no errors

TABLETYPE Usage

local TOOL=require('esi-tool')
local t={}
table.insert(t,'something')
assert(TOOL:TABLETYPE(t))

BOOLEANTYPE

BOOLEANTYPE(x)

Tests x to be a Lua data type boolean.

BOOLEANTYPE parameters

x (variant, required)

BOOLEANTYPE returns

true if the parameter x is a Lua data type boolean, false otherwise.

BOOLEANTYPE throws

no errors

BOOLEANTYPE Usage

local TOOL=require('esi-tool')
local a=1==1
assert(TOOL:BOOLEANTYPE(a))

NUMBERTYPE

NUMBERTYPE(n, rangelo, rangehi)

Tests n to be a Lua data type number. It can optionally check for a range.

NUMBERTYPE parameters

n (variant, required)

The variable to check for the proper number type.

rangelo (number, optional)

An optional low range to check in case n is a number.

rangehi (number, optional)

An optional high range to check in case n is a number.

NUMBERTYPE returns

true if the parameter n is a Lua data type number (and in the range, in case a range was specified), false otherwise.

NUMBERTYPE throws

no errors

NUMBERTYPE Usage

local TOOL=require('esi-tool')
local n=3.14
assert(TOOL:NUMBERTYPE(n))

or

local TOOL=require('esi-tool')
local n=42*2.1
assert(TOOL:NUMBERTYPE(n,1,100))

STRINGTYPE

STRINGTYPE(s)

Tests s to be a Lua data type string.

STRINGTYPE parameters

s (variant, required)

STRINGTYPE returns

true if the parameter s is a Lua data type string, false otherwise.

STRINGTYPE throws

no errors

STRINGTYPE Usage

local TOOL=require('esi-tool')
local s='hi'
assert(TOOL:STRINGTYPE(s))

FUNCTIONTYPE

FUNCTIONTYPE(f)

Tests f to be a Lua data type function.

FUNCTIONTYPE parameters

f (variant, required)

FUNCTIONTYPE returns

true if the parameter f is a Lua data type function, false otherwise.

FUNCTIONTYPE throws

no errors

FUNCTIONTYPE Usage

local TOOL=require('esi-tool')
local function f(a,b)
    return a+b
end
assert(TOOL:FUNCTIONTYPE(f))

GETREFERENCE

GETREFERENCE(tbl: table, tableParts: table, default: nil|any, func: nil|function)

GETREFERENCE is a save way to get an element from a table, without getting nil exception. It is also possible to add a default return value, if the element is not found or nil. To get a higher flexibility, it is possible to provide a function that is called on the found element. This function is not called to a nil value or the default value. If the function throws an error, the default value is returned.

GETREFERENCE parameters

tbl (table, required) tableParts (table, required) default (any,not required) func (function,not required)

GETREFERENCE returns

The found element or the provided default value.

GETREFERENCE throws

no errors

GETREFERENCE Usage

local TOOL=require('esi-tool')
local source={
    ["Header"]={
                ["ReportName"]="Test",
                ["Start"]=inmation.now(),
                ["Count"]="2 m",
            },
}
local time2str= function(t) return inmation.gettime(t) end
local countFunc= function(c) return c * 10 end

local name=TOOL:GETREFERENCE(source,{"Header","ReportName"},"no Report Name")
local start_time_=TOOL:GETREFERENCE(source,{"Header","Start"},"no start time",time2str)
local end_time=TOOL:GETREFERENCE(source,{"Header","End"},"no end time",time2str)
local count=TOOL:GETREFERENCE(source,{"Header","Count"},0,countFunc)
return "Report: " .. name .. "; Start: " .. start_time_ .. "; End: " .. end_time.. "; Count: " .. tostring(count)
--> Report: Test; Start: 2019-11-22T09:22:51.141Z; End: no end time; Count: 0

NILTYPE

NILTYPE(y)

Tests y to be a Lua data type nil.

NILTYPE parameters

y (variant, required)

NILTYPE returns

true if the parameter y is a Lua data type nil, false otherwise.

NILTYPE throws

no errors

NILTYPE Usage

local TOOL=require('esi-tool')
local y
assert(TOOL:NILTYPE(y))

THREADTYPE

THREADTYPE(z)

Tests z to be a Lua data type thread.

THREADTYPE parameters

z (variant, required)

THREADTYPE returns

true if the parameter z is a Lua data type thread, false otherwise.

THREADTYPE throws

no errors

USERDATATYPE

USERDATATYPE(u)

Tests u to be a Lua data type userdata.

USERDATATYPE parameters

u (variant, required)

USERDATATYPE returns

true if the parameter u is a Lua data type userdata, false otherwise.

USERDATATYPE throws

no errors

READONLYTABLE

READONLYTABLE(tab)

Returns a read-only version of the table passed

READONLYTABLE parameters

tab (table, required)

READONLYTABLE returns

A Lua table which is a readonly version of the original table.

READONLYTABLE throws

Throws error if no Lua table/invalid type is passed.

READONLYTABLE Usage

local TOOL=require('esi-tool')
local roversion = TOOL:READONLYTABLE({somkey = "somevalue"})

CHECKTYPE

CHECKTYPE(somevariable, expectedtype, throwlevel)

Returns a read-only version of the table passed

CHECKTYPE parameters

somevariable (variant, required)
expectedtype (table or string, required)
throwlevel (number, optional)

CHECKTYPE returns

Nothing

CHECKTYPE throws

Throws error if the type check fails.

CHECKTYPE Usage

local TOOL=require('esi-tool')
TOOL:CHECKTYPE({somekey = "somevalue"}, "table")
TOOL:CHECKTYPE({somekey = "somevalue"}, {"table", "string"}) --now tables and strings are allowed

SHALLOWCOPY

SHALLOWCOPY(tab)

Returns a shallow copy (metatables are omitted) of the table passed

SHALLOWCOPY parameters

tab (table, required)

SHALLOWCOPY returns

A shallow copy of the table passed.

SHALLOWCOPY throws

Throws error if the typecheck fails.

SHALLOWCOPY Usage

local TOOL=require('esi-tool')
b = {{},{},{}}
c = TOOL:SHALLOWCOPY(b)

DEEPCOPY

DEEPCOPY(tab)

Returns a deep copy of the table passed

DEEPCOPY parameters

tab (table, required)

DEEPCOPY returns

A deep copy of the table passed.

DEEPCOPY throws

Throws error if the typecheck fails.

DEEPCOPY Usage

local TOOL=require('esi-tool')
b = {{},{},{}}
c = TOOL:DEEPCOPY(b)

MEMOIZE

MEMOIZE(func)

Returns a memoized (caching) version of the function passed.

MEMOIZE parameters

func (function, required)

MEMOIZE returns

The memoizing version of the function passed

MEMOIZE throws

Throws error if the type check fails.

MEMOIZE Usage

local TOOL = require('esi-tool')
function triangle(x)
    if x == 0 then
        return 0
    end
    return x+triangle(x-1)
end
--print(triangle(40000)) -- stack overflow: too much recursion
triangle = TOOL:MEMOIZE(triangle) -- make triangle function memoized, so it "remembers" previous results
-- seed triangle's cache
for i=0, 40000 do
    triangle(i)
end
print(triangle(40000)) -- 800020000, instantaneous result

AUTOMAGICTABLE

AUTOMAGICTABLE()

Returns a table whose fields are initialized on access (no "attempt to index a nil value" error)

AUTOMAGICTABLE parameters

None

AUTOMAGICTABLE returns

A new auto-magic table.

AUTOMAGICTABLE throws

Nothing

AUTOMAGICTABLE Usage

local TOOL = require('esi-tool')
local a = TOOL:AUTOMAGICTABLE()
a.b.c.d = "a.b and a.b.c are automatically created"

REVERSETABLE

REVERSETABLE(tab)

Returns a Lua table with inverted key-value-pairs of the table passed

REVERSETABLE parameters

tab (table, required)

REVERSETABLE returns

A Lua table with inverted key-value-pairs of the table passed

REVERSETABLE throws

Throws error if the type check fails.

REVERSETABLE Usage

local TOOL = require('esi-tool')
local a = {somekey = "someval"}
local b = TOOL:REVERSETABLE(a)
--b is now {["someval"] = somekey}

MERGETABLE

MERGETABLE(t1, t2)

Adds key-value pairs of the second table to the first one

MERGETABLE parameters

t1 (table, required) t2 (table, required)

MERGETABLE throws

Throws error if the type check fails.

MERGETABLE Usage

local TOOL = require('esi-tool')
local t1 = { key1 = "val1" }
local t2 = { key2 = "val2" }
TOOL:MERGETABLE(t1, t2)
--t1 is now { ke1 = "val1", key2 = "val2" }

COUNT

COUNT(tab)

Can be used count elements even in non-ordered (non-array) Lua tables (dictionaries)

COUNT parameters

tab (table, required)

COUNT returns

A Lua number representing the number of key-value-pairs in the passed table.

COUNT throws

Throws error if the type check fails.

COUNT Usage

local TOOL = require('esi-tool')
local a = {somekey = "someval"}
local b = TOOL:COUNT(a)
--b is now 1

EXTRACTKEYS

EXTRACTKEYS(tab)

Extracts the keys of the table passed and returns an ordered Lua table containing the keys.

EXTRACTVALUES

EXTRACTVALUES(tab)

Extracts the values of the table passed and returns an ordered Lua table containing the keys.