Closes

README.md

@@ -463,6 +463,7 @@ The current parser supports the following DBC elements:
 - `SG_`
 - `CM_ BO_`
 - `CM_ SG_`
+- `VAL_` signal value descriptions
 
 ---
 
@@ -799,6 +800,7 @@ lines:
 - `BO_` → `DbcFrameHandler`
 - `SG_` → `DbcSignalHandler`
 - `CM_` → `DbcCommentHandler`
+- `VAL_` → `DbcValueDescriptionHandler`
 
 Grammar implementations live in `core/dbc_statement_handler.cpp`; their interface,
 context, and dispatcher live in `core/dbc_statement_handler.h`. `core/typefactory.h`
@@ -814,7 +816,7 @@ void Handle(const std::string &line, DbcParseContext &context) const override;
 Register it in the dispatcher constructor:
 
 ```cpp
-RegisterType<DbcValueHandler>("VAL_"); // after implementing DbcValueHandler
+RegisterType<MyCustomHandler>("CUSTOM_"); // after implementing MyCustomHandler
 ```
 
 Registration creates one handler; replacing a registration replaces that instance.
@@ -829,6 +831,63 @@ and database builders remain independent of statement dispatch.
 
 ---
 
+## Signal value descriptions (`VAL_`)
+
+Signal descriptions attach text to exact raw integer values:
+
+```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";
+```
+
+Each statement must occupy one physical line, contain at least one integer/text
+pair, and end with a semicolon. Spaces and tabs are accepted between fields;
+descriptions may contain whitespace, semicolons, and empty text. Inside quoted
+text, `\"` and `\\` represent a quote and a backslash; other escapes are rejected.
+Keys are decimal integers in `INT64_MIN..UINT64_MAX`, with an optional minus
+sign; plus signs, fractions, hexadecimal numbers, exponents, and overflow are
+rejected. Keys never pass through `double`.
+
+`VAL_` may appear before or after its frame and signal declarations. References
+are resolved after reading the file using the same CAN ID normalization as
+`BO_`, including bit 31 for extended identifiers. Standard and extended frames
+with the same normalized ID remain distinct. Missing or ambiguous references,
+malformed statements, and duplicate integer keys produce `path:line: description`
+errors at the originating `VAL_` line. Distinct keys from multiple statements
+are merged; `0`, `00`, and `-0` are the same key. Keys need not fit the referenced
+signal's bit width or signedness; unreachable keys simply cannot match a decode.
+
+Mappings are available as `SignalInfo::valueDescriptions` and
+`DecodeSignal::valueDescriptions`, and survive both database builders, including
+`TreeNode::GetSignal()`. Consumers can look up a decoded result directly:
+
+```cpp
+const DecodedSignalValue &value = decodedFrame.signals.at(0);
+if (const std::string *description = value.GetValueDescription()) {
+    std::cout << *description;
+}
+```
+
+`GetValueDescription()` uses the exact raw integer before factor/offset scaling.
+It returns `nullptr` for an invalid decode or an unknown value; numeric decoding
+and `physicalValue` are unchanged. A mapped empty string returns a non-null
+pointer. The pointer belongs to the signal definition and stays valid while that
+definition and mapping remain alive and unchanged.
+
+For metadata or standalone raw values, use
+`FindValueDescription(signal.valueDescriptions, rawValue)`, where `rawValue` is
+`RawSignalValue` (`std::variant<std::int64_t, std::uint64_t>`). The helper matches
+nonnegative signed and unsigned values identically and keeps negative values
+distinct from large unsigned values. Stored keys use negative `int64_t` and
+nonnegative `uint64_t`; when constructing mappings manually, normalize keys
+with `NormalizeValueKey()` before insertion.
+
+Named `VAL_TABLE_` tables, environment-variable mappings, multiline statements,
+and Qt presentation are outside this implementation.
+
+---
+
 ## Current Limitations
 
 This is still a minimal implementation.
@@ -836,7 +895,7 @@ This is still a minimal implementation.
 Not supported yet:
 
 - multiplexed signals
-- `VAL_` tables
+- named `VAL_TABLE_` tables and environment-variable value descriptions
 - `BA_` attributes
 - `BA_DEF_` definitions
 - advanced comment handling
@@ -847,8 +906,9 @@ Not supported yet:
 Additional behavior to account for:
 
 - unregistered DBC keywords are ignored
-- an `SG_` statement before the first frame is ignored
-- duplicate frame and signal definitions are not rejected
+- an `SG_` statement before the first frame is rejected
+- duplicate frame and signal definitions are not rejected globally; ambiguous
+  `VAL_` references to them are rejected
 - payload lengths are checked against storage bounds (`0..255`), rather than
   CAN or CAN FD protocol limits
 - comment handling is limited to the supported forms and already parsed targets
@@ -868,6 +928,7 @@ A practical development order would be:
 - `BO_`
 - `SG_`
 - `CM_`
+- `VAL_` signal value descriptions
 - normalized CAN ID
 - `isExtended`
 - transmitter
@@ -883,7 +944,6 @@ Recommended additions:
 
 - parent pointer in `TreeNode`
 - Qt model adapter
-- `VAL_` support for enum-style signals
 - better display strings for UI
 - selective decoding of only chosen signals
 
@@ -981,6 +1041,7 @@ Open `docs/html/index.html` to view the generated reference.
 
 See [tests/README.md](tests/README.md) for QtTest build and execution commands.
 Tests cover frame validation and error locations, Intel and Motorola extraction,
-signal syntax and payload bounds, statement dispatch, signed and unsigned
+signal syntax and payload bounds, `VAL_` syntax and reference validation,
+raw description lookup and preservation through both builders, statement dispatch, signed and unsigned
 64-bit boundaries, physical conversion, numeric output, and invalid signal
 payloads.