HRW4U: Allow for explicit state variable slot decl

Author: zwoop

doc/admin-guide/configuration/hrw4u.en.rst

@@ -323,9 +323,29 @@ TXN_CLOSE_HOOK                  TXN_CLOSE                End of transaction
 A special section `VARS` is used to declare variables. There is no equivalent in
 `header_rewrite`, where you managed the variables manually.
 
-.. note::
-    The section name is always required in HRW4U, there are no implicit or default hooks. There
-    can be several if/else block per section block.
+Variables and State Slots
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each variable type has a limited number of slots available:
+
+- ``bool`` - 16 slots (0-15)
+- ``int8`` - 4 slots (0-3)
+- ``int16`` - 1 slot (0)
+
+By default, slots are assigned automatically in declaration order. You can explicitly assign
+a slot number using the ``@`` syntax::
+
+    VARS {
+        priority: bool @7;      # Explicitly use slot 7
+        active: bool;           # Auto-assigned to slot 0
+        config: bool @12;       # Explicitly use slot 12
+        counter: int8 @2;       # Explicitly use int8 slot 2
+    }
+
+Explicit slot assignment is useful when you need predictable slot numbers across configurations
+or when integrating with existing header_rewrite rules that reference specific slot numbers. In
+addition, a remap configuration can use ``@PPARAM`` to set one of these slot variables explicitly
+as part of the configuration.
 
 Groups
 ------

tools/hrw4u/grammar/hrw4u.g4

@@ -80,6 +80,7 @@ NOT_TILDE     : '!~';
 COLON         : ':';
 COMMA         : ',';
 SEMICOLON     : ';';
+AT            : '@';
 
 COMMENT       : '#' ~[\r\n]* ;
 WS            : [ \t\r\n]+ -> skip ;
@@ -121,7 +122,7 @@ variablesItem
     ;
 
 variableDecl
-    : name=IDENT COLON typeName=IDENT SEMICOLON
+    : name=IDENT COLON typeName=IDENT (AT slot=NUMBER)? SEMICOLON
     ;
 
 statement

tools/hrw4u/src/symbols.py

@@ -43,21 +43,32 @@ def get_statement_spec(self, name: str) -> tuple[str, Callable[[str], None] | No
             return params.target, params.validate
         raise SymbolResolutionError(name, "Unknown operator or invalid standalone use")
 
-    def declare_variable(self, name: str, type_name: str) -> str:
+    def declare_variable(self, name: str, type_name: str, explicit_slot: int | None = None) -> str:
         try:
             var_type = types.VarType.from_str(type_name)
         except ValueError as e:
             error = SymbolResolutionError(name, f"Invalid type '{type_name}'")
             error.add_note(f"Available types: {', '.join([vt.name for vt in types.VarType])}")
             raise error
 
-        if self._var_counter[var_type] >= var_type.limit:
-            error = SymbolResolutionError(name, f"Too many '{type_name}' variables (max {var_type.limit})")
-            error.add_note(f"Current count: {self._var_counter[var_type]}")
-            raise error
+        # Determine slot number
+        if explicit_slot is not None:
+            if explicit_slot < 0 or explicit_slot >= var_type.limit:
+                raise SymbolResolutionError(
+                    name, f"Slot @{explicit_slot} out of range for type '{type_name}' (valid: 0-{var_type.limit-1})")
+            for var_name, sym in self._symbols.items():
+                if sym.var_type == var_type and sym.slot == explicit_slot:
+                    raise SymbolResolutionError(name, f"Slot @{explicit_slot} already used by variable '{var_name}'")
+
+            slot = explicit_slot
+        else:
+            used_slots = {sym.slot for sym in self._symbols.values() if sym.var_type == var_type}
+            slot = next((i for i in range(var_type.limit) if i not in used_slots), None)
+
+            if slot is None:
+                raise SymbolResolutionError(name, f"No available slots for type '{type_name}' (max {var_type.limit})")
 
-        symbol = types.Symbol(var_type, self._var_counter[var_type])
-        self._var_counter[var_type] += 1
+        symbol = types.Symbol(var_type, slot)
         self._symbols[name] = symbol
         return symbol.as_cond()
 

tools/hrw4u/src/types.py

@@ -163,13 +163,13 @@ def from_str(cls, type_str: str) -> Self:
 @dataclass(slots=True, frozen=True)
 class Symbol:
     var_type: VarType
-    index: int
+    slot: int
 
     def as_cond(self) -> str:
-        return f"%{{STATE-{self.var_type.cond_tag}:{self.index}}}"
+        return f"%{{STATE-{self.var_type.cond_tag}:{self.slot}}}"
 
     def as_operator(self, value: str) -> str:
-        return f"{self.var_type.op_tag} {self.index} {value}"
+        return f"{self.var_type.op_tag} {self.slot} {value}"
 
 
 class MapParams:

tools/hrw4u/src/visitor.py

@@ -399,17 +399,21 @@ def visitVariableDecl(self, ctx) -> None:
                 if ctx.typeName is None:
                     raise SymbolResolutionError("variable", "Missing type name in declaration")
                 name = ctx.name.text
-                type = ctx.typeName.text
+                type_name = ctx.typeName.text
+                explicit_slot = int(ctx.slot.text) if ctx.slot else None
 
                 if '.' in name or ':' in name:
                     raise SymbolResolutionError("variable", f"Variable name '{name}' cannot contain '.' or ':' characters")
 
-                symbol = self.symbol_resolver.declare_variable(name, type)
-                self._dbg(f"bind `{name}' to {symbol}")
+                symbol = self.symbol_resolver.declare_variable(name, type_name, explicit_slot)
+                slot_info = f" @{explicit_slot}" if explicit_slot is not None else ""
+                self._dbg(f"bind `{name}' to {symbol}{slot_info}")
             except Exception as e:
                 name = getattr(ctx, 'name', None)
                 type_name = getattr(ctx, 'typeName', None)
-                note = f"Variable declaration: {name.text}:{type_name.text}" if name and type_name else None
+                slot = getattr(ctx, 'slot', None)
+                note = f"Variable declaration: {name.text}:{type_name.text}" + \
+                    (f" @{slot.text}" if slot else "") if name and type_name else None
                 with self.trap(ctx, note=note):
                     raise e
                 return

tools/hrw4u/tests/data/ops/http_cntl_invalid_bool.fail.error.txt

@@ -1 +1,3 @@
-Invalid boolean value 'invalid_value'. Must be one of: 0, 1, FALSE, NO, OFF, ON, TRUE, YES
+tests/data/ops/http_cntl_invalid_bool.fail.input.txt:2:4: error: Invalid boolean value 'invalid_value'. Must be one of: 0, 1, FALSE, NO, OFF, ON, TRUE, YES
+   2 |     http.cntl.LOGGING = invalid_value;
+     |     ^

tools/hrw4u/tests/data/ops/http_cntl_quoted_bool.fail.error.txt

@@ -1 +1,3 @@
-Invalid boolean value '"true"'. Must be one of: 0, 1, FALSE, NO, OFF, ON, TRUE, YES and must not be quoted
+tests/data/ops/http_cntl_quoted_bool.fail.input.txt:2:4: error: Invalid boolean value '"true"'. Must be one of: 0, 1, FALSE, NO, OFF, ON, TRUE, YES and must not be quoted
+   2 |     http.cntl.LOGGING = "true";
+     |     ^

tools/hrw4u/tests/data/ops/skip_remap_quoted_bool.fail.error.txt

@@ -1 +1,3 @@
-Invalid boolean value '"true"'. Must be one of: 0, 1, FALSE, NO, OFF, ON, TRUE, YES and must not be quoted
+tests/data/ops/skip_remap_quoted_bool.fail.input.txt:2:4: error: Invalid boolean value '"true"'. Must be one of: 0, 1, FALSE, NO, OFF, ON, TRUE, YES and must not be quoted
+   2 |     skip-remap("true");
+     |     ^

tools/hrw4u/tests/data/vars/exceptions.txt

@@ -0,0 +1,5 @@
+# Operations tests direction exceptions
+# Format: test_name: direction
+#
+# Explicit slot assignment syntax cannot be reversed
+explicit_slots.input: hrw4u

tools/hrw4u/tests/data/vars/explicit_slots.ast.txt

@@ -0,0 +1 @@
+(program (programItem (section (varSection VARS { (variables (variablesItem (variableDecl parent_config : bool @ 7 ;)) (variablesItem (variableDecl parent_child : bool @ 12 ;)) (variablesItem (variableDecl match : bool ;)) (variablesItem (variableDecl active_flag : bool @ 3 ;)) (variablesItem (variableDecl counter : int8 @ 2 ;)) (variablesItem (variableDecl priority : int8 ;)) (variablesItem (variableDecl status : int16 ;))) }))) (programItem (section SEND_RESPONSE { (sectionBody (conditional (ifStatement if (condition (expression (term (factor parent_config)))) (block { (blockItem (statement inbound.resp.X-Parent = (value true) ;)) })))) })) <EOF>)