DP44/enriched-qwen3-coder-next/Common/DTS.Common.Import/Parsers.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Import/Parsers/ParseVariantBase.cs Common/DTS.Common.Import/Parsers/DefaultParseImport.cs Common/DTS.Common.Import/Parsers/DTSXMLParseImport.cs	2026-04-16T02:06:24.270866+00:00	Qwen/Qwen3-Coder-Next-FP8	1	6317dc1ace913c30

Parsers

Documentation: Import Parsing Module

1. Purpose

This module provides foundational infrastructure and concrete implementations for parsing import files into a structured ImportObject. It defines an extensible parsing pipeline via the IParseImport interface, with base abstractions (ParseVariantBase) for variant-specific parsing logic and two concrete import processors: DefaultParseImport (generic, variant-driven parsing) and DTSXMLParseImport (XML-specific parsing with UI integration, cancellation support, and post-processing for DAS-linked hardware). The module serves as the core engine for transforming raw file inputs into domain objects used throughout the DTS import workflow.

2. Public Interface

ParseVariantBase (abstract class)

• string FileName { get; set; }
  Gets or sets the name of the file being parsed by this variant. Set by the caller before Parse is invoked.
• abstract void Parse(ref ImportObject importObject)
  Parses the file (identified by FileName) and mutates the provided ImportObject by adding or updating its contents. Must be implemented by derived classes.

DefaultParseImport (concrete class)

• DefaultParseImport(ImportObject importObject, IEnumerable<IParseVariant> parseVariants)
  Constructor. Initializes the parser with a target ImportObject and a sequence of IParseVariant implementations to apply.
• ImportObject Parse(IEnumerable<string> importFiles)
  Processes each file in importFiles using the configured IParseVariants via a ParseProcessor. Returns the mutated _importObject.
  Note: The same ImportObject instance passed to the constructor is returned (though mutated internally).

DTSXMLParseImport (concrete class)

• DTSXMLParseImport(ImportObject importObject, IImportNotification importNotification, Func<bool> isCancelled = null, bool skipNormalizing = false)
  Constructor. Initializes the XML parser with a target ImportObject, notification sink, optional cancellation delegate, and flag to skip normalization.
• List<IUIItems> UIItems { get; set; }
  Gets or sets UI-related items (e.g., progress indicators, messages) to be used by the underlying processor.
• ImportObject Parse(IEnumerable<string> importFiles)
  Processes XML files via XMLParseProcessor, applies post-processing (AssignLinkedDASSerials), and returns the mutated _importObject.
  Note: UIItems is assigned to the processor before processing.

AssignLinkedDASSerials (private method in DTSXMLParseImport)

• void AssignLinkedDASSerials(ref ImportObject importObject)
  Post-processes importObject.Hardware() to populate LinkedDASSerials for pseudo-rack hardware: for each pseudo-rack (IsPseudoRack() == true), collects all hardware items whose ParentDAS matches the rack’s SerialNumber, and stores their serials in LinkedDASSerials.

3. Invariants

• ParseVariantBase.Parse must mutate importObject in-place (via ref), not replace it.
• FileName must be set on each IParseVariant instance before calling Parse(ref ImportObject) (enforced by caller, not by class).
• DTSXMLParseImport.Parse always calls AssignLinkedDASSerials after processing, ensuring LinkedDASSerials is populated for pseudo-rack hardware.
• DefaultParseImport does not modify the importFiles sequence; it only iterates over it.
• DTSXMLParseImport supports cancellation via the _isCancelled delegate (behavior depends on XMLParseProcessor implementation, not visible here).

4. Dependencies

• Depends on:
  • DTS.Common.Import.Interfaces namespace (IParseImport, IParseVariant, IImportNotification, IUIItems).
  • DTS.Slice.Users namespace (for IImportNotification, IUIItems).
  • ImportObject type (used throughout; definition not provided here).
  • Internal types: ParseProcessor, XMLParseProcessor (referenced but not documented here).
• Depended on by:
  • Unknown from source alone. Likely consumed by higher-level import orchestration (e.g., UI layers, batch import services).

5. Gotchas

• DefaultParseImport reuses the same ImportObject instance passed to its constructor; callers must be aware that the returned object is the same reference, not a copy.
• DTSXMLParseImport.AssignLinkedDASSerials only processes hardware where IsPseudoRack() returns true; non-rack hardware is skipped.
• DTSXMLParseImport does not validate importFiles for XML format—assumes correctness (handled by XMLParseProcessor).
• UIItems must be set on DTSXMLParseImport before calling Parse to be effective (assigned to processor inside Parse).
• skipNormalizing flag behavior is not visible in this module—depends on XMLParseProcessor implementation.
• AssignLinkedDASSerials uses LINQ query materialization (as string[] ?? matches.ToArray()) but does not guard against null Hardware()—potential NullReferenceException if importObject.Hardware() returns null.