Add VAL_ value descriptions for enum-style signals
Description
Add support for signal value descriptions declared by VAL_ statements. These mappings allow consumers to display meaningful states such as Off, On, or Error alongside decoded numeric values.
README documents supported syntax, lookup behavior, and limitations.
Out of scope
Named VAL_TABLE_ tables, environment-variable value descriptions, multiplexing, attributes, Qt presentation, and changes to numeric scaling or decoding.
# Add `VAL_` value descriptions for enum-style signals
## Description
Add support for signal value descriptions declared by `VAL_` statements. These mappings allow consumers to display meaningful states such as `Off`, `On`, or `Error` alongside decoded numeric values.
Example:
```dbc
BO_ 256 Status: 8 ECU
SG_ State : 0|8@1+ (1,0) [0|255] "" ECU
VAL_ 256 State 0 "Off" 1 "On" 2 "Error";
```
## Scope
- Add a `VAL_` statement handler using the existing statement dispatcher and factory.
- Parse signal value-description statements completely, including the terminating semicolon, quoted descriptions, and spaces or tabs between fields.
- Match frame references using the existing CAN ID normalization rules and the standard/extended distinction.
- Store value descriptions in parsed signal metadata and preserve them in the runtime decode database and UI tree metadata.
- Preserve exact integer keys across supported signed and unsigned 64-bit ranges; do not convert keys to `double`.
- Resolve descriptions using the decoded raw integer value, before factor and offset conversion.
- Provide a documented lookup API that consumers can use without duplicating signed/unsigned matching logic.
- Keep numeric decoding unchanged when a value has no description.
- Reject malformed numbers, invalid or unresolved frame/signal references, and duplicate value keys for the same signal with a clear error.
- Merge multiple `VAL_` statements for the same signal when their value keys are distinct.
- Validate references after reading the file so that declaration order does not silently discard value descriptions; retain source locations for errors.
- Preserve the error format `path:line: description`.
## Acceptance criteria
- [ ] The example maps decoded raw values `0`, `1`, and `2` to their respective descriptions.
- [ ] Lookup uses raw values even when a signal has a nonidentity factor or offset.
- [ ] Unknown raw values remain valid numeric decode results and return no description.
- [ ] Signed negative keys and unsigned keys above `INT64_MAX` retain exact values and resolve correctly.
- [ ] Standard and extended frames with the same numeric CAN ID remain distinct.
- [ ] Value descriptions survive both database builders.
- [ ] Regression tests cover valid statements, whitespace, quoted descriptions, numeric boundaries, duplicate keys, declaration order, missing references, and malformed input.
- [ ] Existing parser and decoder tests pass.
- [ ] README documents supported syntax, lookup behavior, and limitations.
## Out of scope
Named `VAL_TABLE_` tables, environment-variable value descriptions, multiplexing, attributes, Qt presentation, and changes to numeric scaling or decoding.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Add
VAL_value descriptions for enum-style signalsDescription
Add support for signal value descriptions declared by
VAL_statements. These mappings allow consumers to display meaningful states such asOff,On, orErroralongside decoded numeric values.Example:
Scope
VAL_statement handler using the existing statement dispatcher and factory.double.VAL_statements for the same signal when their value keys are distinct.path:line: description.Acceptance criteria
0,1, and2to their respective descriptions.INT64_MAXretain exact values and resolve correctly.Out of scope
Named
VAL_TABLE_tables, environment-variable value descriptions, multiplexing, attributes, Qt presentation, and changes to numeric scaling or decoding.