Support `IncludeCondition` in `ParameterRefEntry` elements

[medley56]

Summary

Space Packet Parser supports much of the XTCE XML schema but the IncludeCondition element within ParameterRefEntry is not yet handled.

XTCE Reference: Section 5.3.4 (p. 235) of CCSDS 660.1-G-2

IncludeCondition elements allow conditional inclusion of a ParameterRefEntry in the EntryList of a SequenceContainer. The condition can only reference previously parsed parameters in the packet. During parsing, the partially-parsed packet object is available to look up these values.

XTCE Example

<xtce:SequenceContainer name="ConditionalExample">
  <xtce:EntryList>
    <xtce:ParameterRefEntry parameterRef="CSFlag"/>
    <xtce:ParameterRefEntry parameterRef="CheckSum">
      <xtce:IncludeCondition>
        <xtce:Comparison value="1" parameterRef="CSFlag"/>
      </xtce:IncludeCondition>
    </xtce:ParameterRefEntry>
  </xtce:EntryList>
</xtce:SequenceContainer>

In this example, CheckSum is only parsed if the previously-parsed CSFlag parameter equals 1.

Implementation

Current Architecture Limitation

Currently in containers.py lines 111-131, we parse SequenceContainer/EntryList elements into a simple entry_list of Parameter and SequenceContainer objects. This doesn't support:

• Conditional inclusion (via IncludeCondition)
• Repeated parameters (via RepeatEntry)
• Other ParameterRefEntry attributes

Create New ParameterRefEntry Class

Create a new class in containers.py to represent the ParameterRefEntry XML element with its optional child elements.

Attributes:

• parameter_ref: str - Name reference to the Parameter
• repeat_entry: Optional[RepeatEntry] - Repeat information (raise NotImplementedError for now)
• include_condition: Optional[MatchCriteria] - Condition for inclusion (use existing MatchCriteria types from comparisons.py)

Inheritance:

• Must inherit from common.XmlObject and common.Parseable
• Implement from_xml() to parse the XML structure
• Implement to_xml() for serialization
• Implement parse() to handle conditional parsing logic

Parse Logic:

1. If include_condition exists, evaluate it using the current packet state
2. If condition is False (or None and parameter should be skipped), return early without parsing
3. If repeat_entry exists, raise NotImplementedError with message: "RepeatEntry is not currently supported in parsing"
4. Otherwise, resolve the parameter reference and parse it normally

Scope Constraint (XTCE 5.8.4):
The IncludeCondition can only reference parameters that have already been parsed in the current container (previous entries in the EntryList). References to "future" parameters in the same container must be rejected or produce a warning.

Update SequenceContainer.from_xml()

Modify the loop at lines 111-131 to create ParameterRefEntry objects instead of directly referencing Parameter objects:

elif entry_tag_name == "ParameterRefEntry":
    parameter_name = entry.attrib["parameterRef"]
    
    # Parse optional IncludeCondition
    include_condition = None
    if (include_cond_elem := entry.find("IncludeCondition")) is not None:
        # Use existing MatchCriteria parsing logic from comparisons module
        include_condition = cls._parse_include_condition(include_cond_elem)
    
    # Parse optional RepeatEntry
    repeat_entry = None
    if entry.find("RepeatEntry") is not None:
        repeat_entry = ...  # Parse but will raise NotImplementedError during parse()
    
    # Create ParameterRefEntry object with parameter reference and conditions
    param_ref_entry = ParameterRefEntry(
        parameter_ref=parameter_name,
        include_condition=include_condition,
        repeat_entry=repeat_entry
    )
    entry_list.append(param_ref_entry)

Add Warning for Unrecognized EntryList Elements

At the end of the if-elif chain (after line 131 in current code), add:

else:
    warnings.warn(
        f"Unrecognized entry type '{entry_tag_name}' in EntryList for container "
        f"'{element.attrib['name']}'. Supported types: ParameterRefEntry, ContainerRefEntry. "
        f"Skipping this entry.",
        category=UserWarning
    )
    continue

Change Type of entry_list

The entry_list attribute in SequenceContainer should be updated to:

entry_list: list[Union[ParameterRefEntry, SequenceContainer]]

This replaces the current list[Union[parameters.Parameter, SequenceContainer]].

Backward Compatibility: The SequenceContainer.parse() method must be updated to handle ParameterRefEntry objects, which will need to resolve their parameter references and evaluate conditions during parsing.

Test Cases

1. Simple condition: Parameter included only when flag=1, excluded when flag=0
2. ComparisonList in condition: Multiple comparisons that must all be true
3. Forward reference detection: Attempting to reference a not-yet-parsed parameter should fail appropriately
4. Nested container with conditions: IncludeCondition works correctly with ContainerRefEntry
5. Size calculation accuracy: Packet bit position tracking remains accurate when parameters are conditionally skipped

References

• XTCE Section 3.4.3.6: MatchCriteria
• XTCE Section 5.3.4: IncludeCondition usage
• XTCE Section 5.8.4: Scope constraints for IncludeCondition