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.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

no

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

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

Documentation

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


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(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(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(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(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(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(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(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))

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(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(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(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(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 typecheck 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

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(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 typecheck 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()

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

AUTOMAGICTABLE parameters

None

AUTOMAGICTABLE returns

A new automagic 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(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 typecheck fails.

REVERSETABLE Usage

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

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 typecheck fails.

COUNT Usage

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

EXTRACTKEYS(tab)

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

EXTRACTVALUES(tab)

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