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 |
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
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
.
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 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)
NUMBERTYPE
NUMBERTYPE(n, rangelo, rangehi)
Tests n
to be a Lua data type number
. It can optionally check for a range.
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 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
CHECKTYPE
CHECKTYPE(somevariable, expectedtype, throwlevel)
Returns a read-only version of the table passed
MEMOIZE
MEMOIZE(func)
Returns a memoized (caching) version of the function passed.
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)
REVERSETABLE
REVERSETABLE(tab)
Returns a Lua table with inverted key-value-pairs of the table passed
COUNT
COUNT(tab)
Can be used count elements even in non-ordered (non-array) Lua tables (dictionaries)