|
| 1 | +"""Helper functions for decoding event messages.""" |
| 2 | + |
| 3 | +import re |
| 4 | + |
| 5 | +# Regex to match spaces where we need to embed params in the event message templates, |
| 6 | +# e.g. {p0}, {p1+2}, {p3:dict}, {p4+1|dict} |
| 7 | +EMBEDDED_PARAM_RE = re.compile(r"\{p(\d+)(?:\+(\d+))?(?::[\w]+)?(?:\|(\w+))?\}") |
| 8 | + |
| 9 | + |
| 10 | +def render_event_template( |
| 11 | + event_description_template: str, params_bytes: list, msg_json_data: dict |
| 12 | +) -> str: |
| 13 | + """ |
| 14 | + Produce an event message string by replacing placeholders with parameter values. |
| 15 | +
|
| 16 | + Example template: |
| 17 | + "Event {p0} occurred with value {p1+2:dictName}" |
| 18 | +
|
| 19 | + This would replace {p0} with the hex value of params[0], and replace {p1+2:dictName} |
| 20 | + with the combined hex value of params[1] and params[2] (treated as big-endian bytes) |
| 21 | + looked up in the dictionary named "dictName" for a human-readable string, or |
| 22 | + rendered as hex if not found in the dictionary. |
| 23 | +
|
| 24 | + Parameters |
| 25 | + ---------- |
| 26 | + event_description_template : str |
| 27 | + The event message template containing placeholders like {p0}, {p1+2}, |
| 28 | + {p3:dict}, {p4+1|dict}. |
| 29 | + params_bytes : list |
| 30 | + The list of parameter values to substitute into the template. |
| 31 | + msg_json_data : dict |
| 32 | + Mapping of parameter values to human-readable strings for decoding event |
| 33 | + messages. |
| 34 | +
|
| 35 | + Returns |
| 36 | + ------- |
| 37 | + str |
| 38 | + The rendered event message with placeholders replaced by parameter values. |
| 39 | + """ |
| 40 | + |
| 41 | + def replace(m: re.Match[str]) -> str: |
| 42 | + """ |
| 43 | + Replace a single placeholder match with the corresponding parameter value. |
| 44 | +
|
| 45 | + Parameters |
| 46 | + ---------- |
| 47 | + m : re.Match[str] |
| 48 | + A regex match object for a placeholder in the template. |
| 49 | +
|
| 50 | + Returns |
| 51 | + ------- |
| 52 | + str |
| 53 | + The string to replace the placeholder with. |
| 54 | + """ |
| 55 | + # We are parsing the placeholder value here to determine which parameter |
| 56 | + # to substitute and how to format them. |
| 57 | + # group one is the parameter index e.g. p0-3 |
| 58 | + idx = int(m.group(1)) |
| 59 | + # group two is the optional byte length e.g. +2 (so we know how many params |
| 60 | + # to combine) |
| 61 | + n_bytes = int(m.group(2)) if m.group(2) else 1 |
| 62 | + # group three is an optional dictionary name to use for decoding this parameter |
| 63 | + dict_name = m.group(3) |
| 64 | + value = 0 |
| 65 | + for i in range(n_bytes): |
| 66 | + # combine the next n_bytes params into a single integer value, treating |
| 67 | + # them as big-endian bytes |
| 68 | + value = (value << 8) | ( |
| 69 | + params_bytes[idx + i] if idx + i < len(params_bytes) else 0 |
| 70 | + ) |
| 71 | + # If a dictionary name is provided use it to decode the value, otherwise just |
| 72 | + # render as hex. |
| 73 | + if dict_name: |
| 74 | + resolved = msg_json_data.get(dict_name, {}).get( |
| 75 | + value, f"0x{value:0{2 * n_bytes}X}" |
| 76 | + ) |
| 77 | + return f"{dict_name}({resolved})" # wrap with dict name |
| 78 | + |
| 79 | + return f"{value:02x}" |
| 80 | + |
| 81 | + # Replace all placeholders in the template using the replace function defined above. |
| 82 | + return EMBEDDED_PARAM_RE.sub(replace, event_description_template) |
0 commit comments