BridgeInterface.lua File Reference

Go to the source code of this file.

Functions
bridge	IgnoreErrors (opts)
	Check whether the ignore_errors option is set in an options table.
bridge	HandleError (opts, fmt,...)
	Handle a Bridge module error in a uniform way.
bridge	ParseLuaData (blob, opts)
	Parse a Lua data blob string and return the resulting Lua value.
bridge	ResolveRegisterPath (path, opts)
	Resolve a register path string to a Mach4 register handle.
bridge	ResolveIOPath (path, opts)
	Resolve an I/O path string to a Mach4 I/O handle.
bridge	GlobalCommand (command, opts)
	Execute a global Bridge command and return the parsed result.
bridge	GetRemoteServerNames (opts)
	Retrieve the list of configured remote Bridge server names.
bridge BridgeInterface	new (opts)
	Construct a new BridgeInterface object connected to a named remote Bridge server.
bridge BridgeInterface	GetOpt_MachAPIRaiseErrors ()
	Check whether the MachAPI_raise_errors option is enabled for this interface.
bridge BridgeInterface	HandleError (...)
	Delegate error handling to the global bridge.HandleError using this object's options.

Function Documentation

GetOpt_MachAPIRaiseErrors()

bridge BridgeInterface GetOpt_MachAPIRaiseErrors

(

)

Check whether the MachAPI_raise_errors option is enabled for this interface.

Inspects the instance's opts table for the MachAPI_raise_errors flag. If the opts table is nil or the flag is not set, returns false. When enabled, API calls that return non-zero MachAPI error codes will raise an error rather than silently continuing.

Returns

(boolean) True if MachAPI_raise_errors is enabled, false otherwise

Note

Documentation generated by AI on 2026-03-03

GetRemoteServerNames()

bridge GetRemoteServerNames

(

opts

)

Retrieve the list of configured remote Bridge server names.

Sends the 'GetRemoteServerNames' global command via bridge.GlobalCommand() and returns the resulting array of server nickname strings. This list is used during BridgeInterface construction to validate that the requested remote server is available.

Parameters

opts	(table|nil) Optional options table with keys: ignore_errors (boolean): If true, suppress errors instead of raising them

Returns

(table|nil) Array of remote server name strings, or nil on error

local names, _ = bridge.GetRemoteServerNames()
-- names = {'head', 'opt', ...}

See also

bridge.GlobalCommand() for the underlying command mechanism

Note

Documentation generated by AI on 2026-03-03

GlobalCommand()

bridge GlobalCommand	(	command	,
		opts	)

Execute a global Bridge command and return the parsed result.

Sends a command string to the Bridge plugin's global command register (BridgeRemoteServers/global.lua) using mc.mcRegSendCommand(). The register handle is cached after the first successful resolution to avoid repeated lookups. The raw response string is parsed as Lua data via bridge.ParseLuaData() before being returned.

If the register cannot be resolved or the command fails, the error is handled via bridge.HandleError() and nil is returned.

Parameters

command	(string) The global command name to send (e.g. 'GetRemoteServerNames')
opts	(table|nil) Optional options table with keys: ignore_errors (boolean): If true, suppress errors instead of raising them

Returns

(any|nil) The parsed Lua data returned by the command, or nil on error

local result = bridge.GlobalCommand('GetRemoteServerNames')
if result ~= nil then
    for _, name in ipairs(result) do print(name) end
end

See also

bridge.ParseLuaData() for response parsing

bridge.ResolveRegisterPath() for register handle resolution

Note

Documentation generated by AI on 2026-03-03

HandleError() [1/2]

bridge BridgeInterface HandleError

(

...

)

Delegate error handling to the global bridge.HandleError using this object's options.

Calls the module-level bridge.HandleError function using the instance's stored options (self._opts). This method provides a consistent way to report errors within a BridgeInterface object without needing to pass the options table explicitly at each call site.

Parameters

fmt	(string) Format string for the error message (printf-style)
...	(any) Variable arguments to format into the message string

Returns

(nil) Always returns nil

Note

Documentation generated by AI on 2026-03-03

HandleError() [2/2]

bridge HandleError	(	opts	,
		fmt	,
			... )

Handle a Bridge module error in a uniform way.

Formats the provided message using string.format() (with safe fallback if formatting fails), logs it via w.Log(), and then raises an error via w.Error() unless the ignore_errors option is set in the opts table. This function is the central error handler for the entire BridgeInterface module.

If formatting the message itself causes an error, a fallback representation of the format string and arguments is used to avoid introducing new errors during error handling.

Parameters

opts	(table|nil) Options table controlling error behavior: ignore_errors (boolean): If true, log the message but do not raise an error
fmt	(string) Printf-style format string for the error message
...	(any) Variable arguments to substitute into the format string

-- Raise an error (default behavior)
bridge.HandleError(nil, "[Bridge] Cannot connect to '%s'", server_name)
 
-- Log only, do not raise
bridge.HandleError({ignore_errors=true}, "[Bridge] Warning: '%s' unavailable", name)

See also

bridge.IgnoreErrors() for how the ignore_errors flag is evaluated

Note

Documentation generated by AI on 2026-03-03

IgnoreErrors()

bridge IgnoreErrors

(

opts

)

Check whether the ignore_errors option is set in an options table.

Inspects the provided opts table for the ignore_errors key. Returns false if opts is nil, not a table, or if opts.ignore_errors is not explicitly true. This function is used by bridge.HandleError() to decide whether to suppress errors or raise them.

Parameters

opts	(table|nil) The options table to inspect. May be nil or any non-table type.

Returns

(boolean) True if opts.ignore_errors == true, false otherwise

bridge.IgnoreErrors(nil)                      -- returns false
bridge.IgnoreErrors({})                       -- returns false
bridge.IgnoreErrors({ignore_errors = true})   -- returns true
bridge.IgnoreErrors({ignore_errors = false})  -- returns false

See also

bridge.HandleError() for the primary consumer of this function

Note

Documentation generated by AI on 2026-03-03

new()

bridge BridgeInterface new

(

opts

)

Construct a new BridgeInterface object connected to a named remote Bridge server.

Creates and initializes a BridgeInterface instance for the given remote server nickname. The constructor performs the following steps:

1. Copies the provided options into the new object.
2. Queries available remote server names via bridge.GetRemoteServerNames().
3. Verifies that client_nickname is among the configured servers.
4. Resolves the heartbeat I/O path (BridgeRemoteServers/<nick>.active).
5. Resolves the API command register (BridgeRemoteServers/<nick>.api.lua).
6. Dynamically adds all API functions defined in bridge.ClientAPICalls as methods.

If any step fails and ignore_errors is not set, an error is raised and nil is returned.

Parameters

client_nickname	(string) The name of the remote Bridge server to connect to (e.g. 'head')
opts	(table|nil) Optional configuration table with keys: ignore_errors (boolean): If true, suppress errors instead of raising them MachAPI_raise_errors (boolean): If true, raise errors on non-zero MachAPI return codes

Returns

(table|nil) A new BridgeInterface object, or nil if the server could not be found or configured

-- Typical usage
local head_machine = w.bridge.BridgeInterface:new('head')
 
-- Ignore errors if the remote is unavailable
local opt_machine = w.bridge.BridgeInterface:new('opt', {ignore_errors = true})
 
-- Raise errors on MachAPI failures
local strict = w.bridge.BridgeInterface:new('opt', {MachAPI_raise_errors = true})

See also

bridge.GetRemoteServerNames() for server discovery

bridge.ClientAPICalls for the list of dynamically added API methods

Note

Documentation generated by AI on 2026-03-03

ParseLuaData()

bridge ParseLuaData	(	blob	,
		opts	)

Parse a Lua data blob string and return the resulting Lua value.

Accepts a string containing Lua data (e.g. a serialized table or scalar value) and evaluates it, returning the result. The function handles two special prefix cases before standard parsing:

1. '#FILE <path>' - The actual data is read from the given file path, which is then deleted ("consumed") after reading.
2. '#<keyword>
   Details

   ' - Treated as a remote error; HandleError is called and nil is returned.

   For standard blobs, the string is wrapped as 'return <blob>' and loaded with load(), then executed via w.pcall(). Any parse or execution error is reported via HandleError.

   Parameters

   blob	(string) The raw Lua data string to parse, optionally prefixed with a special directive
   opts	(table|nil) Optional options table with keys: ignore_errors (boolean): If true, suppress errors instead of raising them

   Returns

   (any|nil) The parsed Lua value (table, number, string, etc.), or nil on error

   -- Parse a simple value
   local val = bridge.ParseLuaData('42')          -- returns 42
    
   -- Parse a table
   local tbl = bridge.ParseLuaData('{a=1, b=2}')  -- returns {a=1, b=2}
    
   -- Large data via file reference
   local big = bridge.ParseLuaData('#FILE C:\\tmp\\bridge_result.lua')

   Warning

   The '#FILE' directive deletes the referenced file after reading it.

   See also

   bridge.HandleError() for error reporting behavior

   Note

   Documentation generated by AI on 2026-03-03

ResolveIOPath()

bridge ResolveIOPath	(	path	,
		opts	)

Resolve an I/O path string to a Mach4 I/O handle.

Calls mc.mcIoGetHandle() with the given path string. If the call succeeds (rc == mc.MERROR_NOERROR), the I/O handle is returned. Otherwise the error is reported via bridge.HandleError() and nil is returned. Paths follow the Mach4 I/O naming convention (e.g. 'BridgeRemoteServers/head.active').

Parameters

path	(string) The I/O path to resolve (e.g. 'BridgeRemoteServers/head.active')
opts	(table|nil) Optional options table with keys: ignore_errors (boolean): If true, suppress errors instead of raising them

Returns

(number|nil) The I/O handle on success, or nil if the path could not be resolved

local hIo = bridge.ResolveIOPath('BridgeRemoteServers/head.active')
if hIo == nil then
    -- handle error
end

See also

bridge.ResolveRegisterPath() for resolving register paths

Note

Documentation generated by AI on 2026-03-03

ResolveRegisterPath()

bridge ResolveRegisterPath	(	path	,
		opts	)

Resolve a register path string to a Mach4 register handle.

Calls mc.mcRegGetHandle() with the given path string. If the call succeeds (rc == mc.MERROR_NOERROR), the register handle is returned. Otherwise the error is reported via bridge.HandleError() and nil is returned. Paths follow the Mach4 register naming convention (e.g. 'BridgeRemoteServers/global.lua').

Parameters

path	(string) The register path to resolve (e.g. 'BridgeRemoteServers/head.api.lua')
opts	(table|nil) Optional options table with keys: ignore_errors (boolean): If true, suppress errors instead of raising them

Returns

(number|nil) The register handle on success, or nil if the path could not be resolved

local hReg = bridge.ResolveRegisterPath('BridgeRemoteServers/global.lua')
if hReg == nil then
    -- handle error
end

See also

bridge.ResolveIOPath() for resolving I/O paths

Note

Documentation generated by AI on 2026-03-03