- Generated by
1.16.1
|
Mach Modules Documentation
Lua Module API Documentation
|
Go to the source code of this file.
Functions | |
| dump (o) | |
| Recursively serialize a Lua value to a human-readable string. | |
| debugWxMsgBox (str) | |
| Display a wxWidgets message box when debug mode is enabled. | |
| data | IgnoreErrors (opts) |
| Check whether the ignore_errors option is enabled in an options table. | |
| data | HandleError (opts, fmt,...) |
| Format and report an error message, optionally raising a Lua error. | |
| data | ResolveRegisterPath (path, opts) |
| Resolve a register path string to a Mach4 register handle. | |
| data | LogEvent (inst, optional, attrs, eventTitle,...) |
| Log an event to the Bridge plugin with error protection. | |
| data | QuickLog (inst, eventTitle,...) |
| Log a titled event to the Bridge plugin with no attributes or optional data. | |
| inverseTable (values) | |
| Create an inverse mapping of a table, swapping keys and values. | |
| data DirectQuery | QueryEventsByEventId (inst, eventInstance) |
| Query events from the Bridge plugin filtered by a specific event ID. | |
| data DirectQuery | QueryEventsByType (inst, type) |
| Query events from the Bridge plugin filtered by event type. | |
| data DirectQuery | QueryEventTypeByEventId (inst, eventId) |
| Query the event type name for a given event ID from the Bridge plugin. | |
| data DirectQuery | QueryEventsByTimestamp (inst, startTimestamp, endTimestamp) |
| Query events from the Bridge plugin within an optional timestamp range. | |
| data DirectQuery | QueryEventsByTag (inst, tag) |
| Query events from the Bridge plugin filtered by a specific tag. | |
| debugWxMsgBox | ( | str | ) |
Display a wxWidgets message box when debug mode is enabled.
Shows a modal wx.wxMessageBox() dialog with the provided string only when data.debug is set to true. Has no effect when data.debug is false. Used throughout the module to emit diagnostic output during development without modifying production behavior.
| str | (string) The message string to display in the dialog |
| dump | ( | o | ) |
Recursively serialize a Lua value to a human-readable string.
If the input is a table, iterates over all key-value pairs and formats each as '[key] = value', recursively serializing nested tables. Non-table values are converted using tostring(). Primarily used for debug output and diagnostic message boxes throughout the module.
| o | (any) The value to serialize. May be a table, number, string, boolean, or any other Lua type |
| data HandleError | ( | opts | , |
| fmt | , | ||
| ... ) |
Format and report an error message, optionally raising a Lua error.
Constructs an error message from a format string and optional variadic arguments using string.format(), protected by w.pcall() in case formatting itself fails. If formatting fails, a fallback representation is used. The message is always written to the Mach4 log via w.Log(). If opts.ignore_errors is not true, the error is also raised via w.Error().
| opts | (table) Options table. Supports 'ignore_errors' (boolean): if true, logs the error but does not raise it |
| fmt | (string) A format string for the error message, compatible with string.format() |
| ... | (any) Optional format arguments to apply to fmt |
| data IgnoreErrors | ( | opts | ) |
Check whether the ignore_errors option is enabled in an options table.
Validates that opts is a non-nil table, then returns whether opts.ignore_errors is explicitly set to true. Used throughout the module to determine whether errors should be suppressed or raised.
| opts | (table|nil) The options table to inspect. If nil or not a table, returns false |
| inverseTable | ( | values | ) |
Create an inverse mapping of a table, swapping keys and values.
Iterates over all key-value pairs in the input table and constructs a new table where each original value becomes a key and each original key becomes the corresponding value. Useful for converting named column arrays into index-lookup tables. If duplicate values exist in the input, only the last key mapped to that value will be retained.
| values | (table) The table whose keys and values will be swapped |
| data LogEvent | ( | inst | , |
| optional | , | ||
| attrs | , | ||
| eventTitle | , | ||
| ... ) |
Log an event to the Bridge plugin with error protection.
Wraps data._LogEvent() in a protected call via w.pcall() to prevent errors in the event logging logic from propagating to the caller. If the inner call fails, the error message is written to the Mach4 log via w.Log() and execution continues normally. All arguments are forwarded to data._LogEvent().
| inst | (number) The Mach4 instance handle to log the event for |
| optional | (table) Optional metadata table, may include 'requiredTags' array |
| attrs | (table) Attributes table with string, number, or boolean values to include in the event |
| eventTitle | (string) The title of the event to log |
| ... | (any) Optional format arguments applied to eventTitle |
| data DirectQuery QueryEventsByEventId | ( | inst | , |
| eventInstance | ) |
Query events from the Bridge plugin filtered by a specific event ID.
Constructs a JSON query for events matching the given event instance ID and sends it to the Bridge plugin via the direct query interface. For each matching row, it performs an additional lookup to resolve the event type name. Returns a table of rows containing event type, event instance, and timestamp. Raises a Lua error if the 'timestamp' column is absent from the query result. Returns an empty table if no results are found or column data is missing.
| inst | (number) The Mach4 instance handle to query events for |
| eventInstance | (any) The event instance ID used to filter events |
| data DirectQuery QueryEventsByTag | ( | inst | , |
| tag | ) |
Query events from the Bridge plugin filtered by a specific tag.
Constructs a JSON query for events associated with the given tag and sends it to the Bridge plugin via the direct query interface. For each matching event, it performs an additional lookup to resolve the event type name. Returns a table of rows, each containing the event type, event instance, and timestamp. If no matching events are found or column data is missing, returns an empty table. Raises a Lua error if expected columns are absent from the query result.
| inst | (number) The Mach4 instance handle to query events for |
| tag | (string) The tag string used to filter events |
| data DirectQuery QueryEventsByTimestamp | ( | inst | , |
| startTimestamp | , | ||
| endTimestamp | ) |
Query events from the Bridge plugin within an optional timestamp range.
Constructs a JSON query for events between the given start and end timestamps and sends it to the Bridge plugin via the direct query interface. Either timestamp argument may be nil to leave that bound open. For each matching event row, it performs an additional lookup to resolve the event type name by event ID. Returns a table of rows containing event type, event instance, and timestamp. Raises a Lua error if expected columns ('eventInstance' or 'timestamp') are absent from the result.
| inst | (number) The Mach4 instance handle to query events for |
| startTimestamp | (number|nil) The start of the timestamp range to query, or nil for no lower bound |
| endTimestamp | (number|nil) The end of the timestamp range to query, or nil for no upper bound |
| data DirectQuery QueryEventsByType | ( | inst | , |
| type | ) |
Query events from the Bridge plugin filtered by event type.
Constructs a JSON query for events of the specified type and sends it to the Bridge plugin via the direct query interface. For each matching event row, it performs an additional lookup to resolve the event type name by event instance ID. Returns a table of rows containing event type, event instance, and timestamp. Raises a Lua error if expected columns ('eventInstance' or 'timestamp') are absent from the query result. Includes debug message box output for the first row when data.debug is enabled.
| inst | (number) The Mach4 instance handle to query events for |
| type | (string) The event type string used to filter events |
| data DirectQuery QueryEventTypeByEventId | ( | inst | , |
| eventId | ) |
Query the event type name for a given event ID from the Bridge plugin.
Constructs a JSON query for the 'eventtypes' table filtered by the given event ID and sends it to the Bridge plugin via the direct query interface. Returns the event type name string from the first matching row. If eventId is nil, or if the query returns no results, or if the expected 'eventTypeName' column is not present, returns nil without raising an error.
| inst | (number) The Mach4 instance handle to query event types for |
| eventId | (any) The event ID used to look up the corresponding event type name |
| data QuickLog | ( | inst | , |
| eventTitle | , | ||
| ... ) |
Log a titled event to the Bridge plugin with no attributes or optional data.
Convenience wrapper around data.LogEvt() that passes empty tables for the optional and attributes arguments. Supports variadic format arguments for the event title. If additional arguments are provided via the global arg table, they are unpacked and forwarded to data.LogEvt().
| inst | (number) The Mach4 instance handle to log the event for |
| eventTitle | (string) The title of the event to log, optionally used as a format string |
| ... | (any) Optional format arguments applied to eventTitle |
| data ResolveRegisterPath | ( | path | , |
| opts | ) |
Resolve a register path string to a Mach4 register handle.
Calls mc.mcRegGetHandle() with the given path. If the handle is successfully retrieved, it is returned directly. If the lookup fails and opts.ignore_errors is not set, an error is reported via data.HandleError() with the resolved error message. Returns nil on failure.
| path | (string) The full register path string to resolve (e.g., 'Data/queue_event') |
| opts | (table) Options table. Supports 'ignore_errors' (boolean): if true, suppresses error reporting on failure |
1.16.1