XML Modular Scenarios (Include)

Description

FERS allows simulation configurations to be split across multiple XML files using the <include> tag within the main scenario file. This enables modularity and reusability of configuration sections (e.g., defining standard platform setups or antenna models in separate files). The system processes these includes recursively, merging the content of the included files into the main document before final parsing and validation.

Assumptions

• Assumes <include> tags specify correct file paths, either absolute or relative to the directory containing the including file.
• Assumes the target files specified in <include> tags exist, are readable, and contain well-formed XML content suitable for merging.
• Assumes that include directives do not form circular dependencies (e.g., File A includes File B, and File B includes File A), ensuring the recursive inclusion process terminates.
• Assumes the basic merging strategy (copying all child nodes from the included file's root into the main document at the location of the <include> tag) is adequate for the user's intended configuration structure.

Limitations

• Include Tag Location for Removal: The post-merge cleanup step (removeIncludeElements) is currently implemented to only remove <include> tags that are direct children of the <simulation> root element. Includes nested deeper within the structure might persist in the final merged document representation used for validation, potentially causing issues if the schema doesn't expect them there.
• Simple Merging Strategy: The merging process is a straightforward copy of XML nodes. It does not handle potential conflicts like duplicate element IDs defined across different included files, nor does it support more advanced merging strategies (e.g., overriding specific elements based on include order).
• Error Reporting Clarity: Errors encountered while parsing or validating content originating from an included file might be reported against the final merged document structure, potentially making it difficult to trace the error back to the specific originating included file or the include chain leading to it.
• Post-Merge Validation: XML validation (if enabled using DTD/XSD) is performed on the fully merged document. Errors within included files are only detected after the merging process is complete, not independently beforehand.

Related Components

• xml_parser.cpp: Contains the main orchestration logic (addIncludeFilesToMainDocument) and discovery (collectIncludeElements).
• libxml_wrapper.cpp: Handles the lower-level XML operations via libxml2, including merging (mergeXmlDocuments), cleanup (removeIncludeElements), and loading included files (XmlDocument::loadFile).
• XML Scenario Loading
• XML Validation (DTD-XSD)

Validation Status

• Needs Verification: The robustness of the recursive inclusion, merging, error reporting, and cleanup process needs specific testing, especially concerning the identified limitations.
• Key Areas for Validation:
  • Correct handling of relative paths for includes nested at different directory levels.
  • Behavior with missing or malformed included files (Are error messages clear? Does it fail gracefully?).
  • Impact of <include> tags not being direct children of the root on the removeIncludeElements function and subsequent validation steps.
  • Verification that content is merged correctly in various valid scenarios (e.g., multiple includes, includes within includes).
  • Testing for circular include detection/handling (Does it terminate gracefully with an error, or hang?).
• Priority: Medium (Important for usability and defining complex scenarios, but potential for subtle configuration bugs exists due to limitations).