69 lines
5.3 KiB
Markdown
69 lines
5.3 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common.Import/Parsers/ParseVariantBase.cs
|
||
- Common/DTS.Common.Import/Parsers/DefaultParseImport.cs
|
||
- Common/DTS.Common.Import/Parsers/DTSXMLParseImport.cs
|
||
generated_at: "2026-04-16T02:06:24.270866+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "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 `IParseVariant`s 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`. |