Script Globals

script.globals

Values and functions available in every script without requiring any module: the script's input payload, the current node directory, and stdlib-style helpers for loading modules and debug printing.

`Data`

field

Data

The inbound message/request payload.

The inbound message/request payload passed to main(Data). For Source HTTP nodes this is the raw HTTP request text; for Transform/LLP nodes it is the message body.

Usage

local raw = Data

Returns

string — the raw inbound payload.

Example

local Raw = Data
print(#Raw)

`__node_dir`

field

__node_dir

Deprecated. Filesystem path to the current node directory - use linkiir.sys.nodeDir().

Deprecated: use linkiir.sys.nodeDir() instead. Filesystem path to the current node directory, set by the runtime before script execution. Still populated and not scheduled for removal, but linkiir.sys.nodeDir() is the documented form. Concatenating it onto a schema name is no longer needed either - a relative schema path already resolves against the node directory.

Usage

local nodeDir = linkiir.sys.nodeDir()

Returns

string — absolute path to the node directory.

Example

-- Deprecated form:
local SchemaPath = __node_dir .. '/demo.json'

-- Current form - relative schema paths resolve against the node directory:
local Msg = linkiir.data.extract{ schema = 'demo.json', data = Data }

`require`

function

require(modname)

Load a Lua module.

Loads a Lua module. Search path: node dir (including any linked library dependencies, staged there at run time), then the project's common/ dir (shared modules), then system defaults.

Usage

local mod = require "modname"

Parameters

Name	Type	Required	Description
`modname`	string	Yes	Module name (e.g. "legacy_adapter").

Returns

module table

Errors

Raises a Lua error when the module cannot be found.

Example

local Adapter = require('legacy_adapter')
Adapter.transform(Data)

`print`

function

print(...)

Print values to stdout.

Prints values to stdout, prefixed with the node ID.

Usage

print(Msg:name(), Msg:count())

Parameters

Name	Type	Required	Description
`...`	any	No	Values to print (variadic).

Returns

Example

print('processing', linkiir.sys.guid(128))

`trace`

function

trace(...)

Pretty-print values to stdout.

Pretty-prints values to stdout (legacy debug trace). Recursively expands tables.

Usage

trace(SomeTable)

Parameters

Name	Type	Required	Description
`...`	any	No	Values to pretty-print (variadic).

Returns

Example

trace({ id = 1, items = { 'a', 'b' } })

`type`

function

type(v)

Type name of a value.

Returns the type of its only argument, coded as a string: "nil", "boolean", "number", "string", "table", "function", "thread", or "userdata".

Usage

type(v)

Parameters

Name	Type	Required	Description
`v`	any	Yes	Value to inspect.

Returns

string

Example

print(type(Data))     -- "string"
print(type(nil))      -- "nil"
print(type({}))       -- "table"

`tostring`

function

tostring(v)

Convert a value to a printable string.

Receives a value of any type and converts it to a string in a reasonable format.

Usage

tostring(v)

Parameters

Name	Type	Required	Description
`v`	any	Yes	Value to convert.

Returns

string

Example

print(tostring(42))     -- "42"
print(tostring(nil))    -- "nil"

`tonumber`

function

tonumber(e [, base])

Convert a value to a number.

Tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, returns that number; otherwise returns nil. An optional base (2-36) interprets e as an integer in that base.

Usage

tonumber(e, base)

Parameters

Name	Type	Required	Description
`e`	any	Yes	Value to convert.
`base`	integer	No	Numeric base (2-36) for string conversion.

Returns

number, or nil if the conversion fails

Example

print(tonumber('42'))      -- 42
print(tonumber('2A', 16)) -- 42
print(tonumber('abc'))    -- nil

`pairs`

function

pairs(t)

Iterate all key/value pairs of a table.

Returns three values (next, t, nil) so that a generic for loop iterates over all key/value pairs of table t, in an undefined order.

Usage

for k, v in pairs(t) do ... end

Parameters

Name	Type	Required	Description
`t`	table	Yes	Table to iterate.

Returns

next, t, nil (for use in a generic for loop)

Example

local Headers = { ['Content-Type'] = 'text/plain', ['X-Id'] = '123' }
for k, v in pairs(Headers) do
   print(k, v)
end

`ipairs`

function

ipairs(t)

Iterate the array part of a table in order.

Returns three values so that a generic for loop iterates over the pairs (1, t[1]), (2, t[2]), ..., up to the first nil value.

Usage

for i, v in ipairs(t) do ... end

Parameters

Name	Type	Required	Description
`t`	table	Yes	Table (array) to iterate.

Returns

iterator function, t, 0 (for use in a generic for loop)

Example

local Files = linkiir.sys.fs.list{ path = '/inbound' }
for i, f in ipairs(Files) do
   print(i, f)
end

`next`

function

next(t [, k])

Low-level table iterator.

Returns the next key/value pair after key k in table t, in an undefined order; returns nil when there are no more. Called with k = nil (or omitted) returns the first pair. Underlies pairs().

Usage

next(t, k)

Parameters

Name	Type	Required	Description
`t`	table	Yes	Table to iterate.
`k`	any	No	Previous key; omit to get the first pair.

Returns

nextKey, nextValue, or nil when exhausted

Example

local k, v = next(Headers)
while k do
   print(k, v)
   k, v = next(Headers, k)
end

`select`

function

select(index, ...)

Count or pick from a variadic argument list.

If index is the string "#", returns the total number of extra arguments. Otherwise returns all arguments from index onward.

Usage

select(index, ...)

Parameters

Name	Type	Required	Description
`index`	integer\|string	Yes	1-based position, or "#" for the count.
`...`	any	No	Variadic arguments.

Returns

the selected arguments, or a count when index is "#"

Example

local function Count(...)
   return select('#', ...)
end
print(Count('a', 'b', 'c'))  -- 3
print(select(2, 'a', 'b', 'c'))  -- "b"  "c"

`error`

function

error(message [, level])

Raise a Lua error.

Terminates the last protected function called (or the whole script) and returns message as the error object. level controls where position info is added (1 = the caller of error, the default).

Usage

error(message, level)

Parameters

Name	Type	Required	Description
`message`	any	Yes	Error value, usually a string.
`level`	integer	No	Position-info level. Default 1.

Returns

does not return

Example

if not Resp then error('request failed') end

`assert`

function

assert(v [, message])

Raise an error if v is falsy.

If v is false or nil, calls error(message), using "assertion failed!" as a default message. Otherwise returns all its arguments.

Usage

assert(v, message)

Parameters

Name	Type	Required	Description
`v`	any	Yes	Value to check.
`message`	any	No	Error value used when v is falsy.

Returns

v, ... (all arguments, unchanged, when v is truthy)

Example

local Mrn = assert(Msg.PID[3][1][1]:value(), 'missing MRN')

`pcall`

function

pcall(f, ...)

Call a function in protected mode.

Calls f with the given arguments in protected mode: any error inside f is caught instead of propagating. Returns true plus f's results on success, or false plus the error object on failure.

Usage

local ok, result = pcall(f, ...)

Parameters

Name	Type	Required	Description
`f`	function	Yes	Function to call.
`...`	any	No	Arguments to pass to f.

Returns

true, results... on success
false, errorObject on failure

Example

local Ok, Msg, MsgType = pcall(linkiir.data.extract, { schema = 'demo.json', data = Data })
if not Ok then error('extract failed: ' .. tostring(Msg)) end

`xpcall`

function

xpcall(f, msgh)

Call a function in protected mode with a message handler.

Like pcall, but calls the message handler msgh in the context of the error, before the stack unwinds — useful for attaching a traceback.

Usage

local ok, result = xpcall(f, msgh)

Parameters

Name	Type	Required	Description
`f`	function	Yes	Function to call (no arguments).
`msgh`	function	Yes	Message handler, called with the error object.

Returns

true, results... on success
false, handlerResult on failure

Example

local Ok, Err = xpcall(function() return riskyStep() end, debug.traceback)
if not Ok then print(Err) end

`unpack`

function

unpack(list [, i [, j]])

Expand a table into multiple return values.

Returns the elements from the given table list, from list[i] to list[j]. Defaults are i = 1 and j = #list.

Usage

unpack(list, i, j)

Parameters

Name	Type	Required	Description
`list`	table	Yes	Table (array) to expand.
`i`	integer	No	Start index. Default 1.
`j`	integer	No	End index. Default #list.

Returns

the unpacked values

Example

local Args = { 'a', 'b', 'c' }
print(unpack(Args))  -- "a"  "b"  "c"

`rawequal`

function

rawequal(v1, v2)

Compare two values without metamethods.

Checks whether v1 is equal to v2, without invoking the __eq metamethod.

Usage

rawequal(v1, v2)

Parameters

Name	Type	Required	Description
`v1`	any	Yes	First value.
`v2`	any	Yes	Second value.

Returns

boolean

Example

print(rawequal(1, 1))  -- true

`rawget`

function

rawget(t, k)

Read a table field without metamethods.

Gets the real value of t[k], without invoking the __index metamethod.

Usage

rawget(t, k)

Parameters

Name	Type	Required	Description
`t`	table	Yes	Table to read.
`k`	any	Yes	Key to read.

Returns

the raw value

Example

print(rawget(SomeTable, 'id'))

`rawset`

function

rawset(t, k, v)

Write a table field without metamethods.

Sets the real value of t[k] to v, without invoking the __newindex metamethod. Returns t.

Usage

rawset(t, k, v)

Parameters

Name	Type	Required	Description
`t`	table	Yes	Table to modify.
`k`	any	Yes	Key to set.
`v`	any	Yes	Value to set.

Returns

Example

rawset(SomeTable, 'id', 42)

`setmetatable`

function

setmetatable(t, metatable)

Attach a metatable to a table.

Sets the metatable for table t. Returns t.

Usage

setmetatable(t, metatable)

Parameters

Name	Type	Required	Description
`t`	table	Yes	Table to modify.
`metatable`	table\|nil	Yes	New metatable, or nil to remove it.

Returns

Example

local Vector = setmetatable({ x = 1, y = 2 }, VectorMeta)

`getmetatable`

function

getmetatable(t)

Read a table's metatable.

Returns the metatable of t, or nil if it has none (or the metatable's __metatable field, if that is set).

Usage

getmetatable(t)

Parameters

Name	Type	Required	Description
`t`	any	Yes	Value to inspect.

Returns

table, or nil

Example

local Meta = getmetatable(Vector)

`collectgarbage`

function

collectgarbage([opt [, arg]])

Control the garbage collector.

Runs garbage-collector actions. With no arguments, performs a full collection cycle. opt selects the action (e.g. "collect", "count", "step").

Usage

collectgarbage(opt, arg)

Parameters

Name	Type	Required	Description
`opt`	string	No	Action name. Default "collect".
`arg`	any	No	Argument for the selected action.

Returns

depends on opt (e.g. current memory use in Kbytes for "count")

Example

collectgarbage()               -- full collection cycle
print(collectgarbage('count'))  -- current memory use, in Kbytes

`_VERSION`

field

_VERSION

The running Lua version string.

A global variable (not a function) holding a string with the running Lua version, e.g. "Lua 5.1".

Usage

print(_VERSION)

Returns

string

Example

print(_VERSION)  -- "Lua 5.1"

`_G`

field

_G

The global environment table.

The table representing the script's global environment. Reading/writing _G.x is equivalent to reading/writing the global variable x.

Usage

_G.SomeGlobal

Returns

table

Example

_G.Counter = 0
print(Counter)  -- 0

`dofile`

function

dofile([filename])

Execute a Lua file as a chunk.

Loads and immediately runs the Lua chunk in filename (or stdin, if omitted), in the global environment. Errors propagate to the caller, unprotected. Prefer require for loading reusable modules — dofile re-runs the file every call and has no module caching.

Usage

dofile(path)

Parameters

Name	Type	Required	Description
`filename`	string	No	Path of the Lua file to run. Default stdin.

Returns

whatever the chunk returns

Example

dofile(linkiir.sys.nodeDir() .. '/helpers.lua')

`loadfile`

function

loadfile([filename])

Load a Lua file without running it.

Loads a chunk from filename (or stdin, if omitted) without running it. Returns the compiled chunk as a function, or nil plus an error message on a syntax error.

Usage

local chunk, err = loadfile(path)

Parameters

Name	Type	Required	Description
`filename`	string	No	Path of the Lua file to load. Default stdin.

Returns

function on success; nil, errorMessage on failure

Example

local Chunk, Err = loadfile(linkiir.sys.nodeDir() .. '/helpers.lua')
if Chunk then Chunk() end

`loadstring`

function

loadstring(string [, chunkname])

Compile a Lua chunk from a string.

Loads a chunk from the given string without running it. Returns the compiled chunk as a function, or nil plus an error message on a syntax error. chunkname is used in error messages and debug info.

Usage

local chunk, err = loadstring(code)

Parameters

Name	Type	Required	Description
`string`	string	Yes	Lua source code.
`chunkname`	string	No	Name used in error messages/tracebacks. Default the string itself.

Returns

function on success; nil, errorMessage on failure

Example

local Chunk = loadstring('return 1 + 1')
print(Chunk())  -- 2

`load`

function

load(func [, chunkname])

Compile a Lua chunk from a reader function.

Loads a chunk using func, a reader function repeatedly called with no arguments that must return successive pieces of the chunk's source (or nil/empty string to signal the end). Returns the compiled chunk as a function, or nil plus an error message on a syntax error.

Usage

local chunk, err = load(reader)

Parameters

Name	Type	Required	Description
`func`	function	Yes	Reader function returning successive source chunks.
`chunkname`	string	No	Name used in error messages/tracebacks.

Returns

function on success; nil, errorMessage on failure

Example

local Parts = { 'return ', '1 + 1' }
local I = 0
local Chunk = load(function() I = I + 1 return Parts[I] end)
print(Chunk())  -- 2

`getfenv`

function

getfenv([f])

Read a function's environment table.

Returns the current environment table of f (a function, or a stack-level integer; default 1, the calling function).

Usage

getfenv(f)

Parameters

Name	Type	Required	Description
`f`	function\|integer	No	Function, or stack level. Default 1.

Returns

table

Example

local Env = getfenv(1)

`setfenv`

function

setfenv(f, table)

Set a function's environment table.

Sets the environment for the function f (a function, or a stack-level integer, where 1 means the calling function) to table. Returns f when f is a function.

Usage

setfenv(f, table)

Parameters

Name	Type	Required	Description
`f`	function\|integer	Yes	Function, or stack level.
`table`	table	Yes	New environment table.

Returns

f (when f is a function)

Example

local Sandbox = setmetatable({}, { __index = _G })
setfenv(SomeFn, Sandbox)

`module`

function

module(name [, ...])

Create or enter a named module.

Legacy Lua 5.1 module system: creates (or reuses) a table for module name, sets it as the value of the global name and of package.loaded[name], and sets it as the new environment of the running function, so subsequent top-level function/variable definitions become fields of the module. Optional arguments are 'module modifiers' such as package.seeall. Superseded in most modern Lua code by returning a table from a plain chunk loaded via require.

Usage

module('mymodule')

Parameters

Name	Type	Required	Description
`name`	string	Yes	Module name.
`...`	function	No	Optional module modifiers, e.g. package.seeall.

Returns

none

Example

module('mymodule', package.seeall)

function greet(name)
   return 'hello, ' .. name
end

Data​

__node_dir​

require​

print​

trace​

type​

tostring​

tonumber​

pairs​

ipairs​

next​

select​

error​

assert​

pcall​

xpcall​

unpack​

rawequal​

rawget​

rawset​

setmetatable​

getmetatable​

collectgarbage​

_VERSION​

_G​

dofile​

loadfile​

loadstring​

load​

getfenv​

setfenv​

module​

`Data`

`__node_dir`

`require`

`print`

`trace`

`type`

`tostring`

`tonumber`

`pairs`

`ipairs`

`next`

`select`

`error`

`assert`

`pcall`

`xpcall`

`unpack`

`rawequal`

`rawget`

`rawset`

`setmetatable`

`getmetatable`

`collectgarbage`

`_VERSION`

`_G`

`dofile`

`loadfile`

`loadstring`

`load`

`getfenv`

`setfenv`

`module`