init
This commit is contained in:
114
enriched-partialglm/Common/DTS.Common.Import/Parsers.md
Normal file
114
enriched-partialglm/Common/DTS.Common.Import/Parsers.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
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-16T11:43:16.787826+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "6317dc1ace913c30"
|
||||
---
|
||||
|
||||
# Documentation: DTS.Common.Import.Parsers
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides parsing infrastructure for importing data files into the system. It defines an abstract base class for parse variants (`ParseVariantBase`) and concrete implementations of the `IParseImport` interface (`DefaultParseImport` and `DTSXMLParseImport`) that orchestrate file parsing operations. The module acts as a bridge between raw import files and structured `ImportObject` instances, supporting both generic and XML-specific parsing workflows.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### ParseVariantBase (Abstract Class)
|
||||
|
||||
**Implements:** `IParseVariant`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `FileName` | `public string FileName { get; set; }` | Property to store the name of the file being parsed. |
|
||||
| `Parse` | `public abstract void Parse(ref ImportObject importObject)` | Abstract method that derived classes must implement to perform parsing logic. Receives `ImportObject` by reference, allowing the object to be modified or replaced. |
|
||||
|
||||
---
|
||||
|
||||
### DefaultParseImport (Class)
|
||||
|
||||
**Implements:** `IParseImport`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| Constructor | `public DefaultParseImport(ImportObject importObject, IEnumerable<IParseVariant> parseVariants)` | Initializes the parser with an `ImportObject` instance and a collection of `IParseVariant` implementations. |
|
||||
| `Parse` | `public ImportObject Parse(IEnumerable<string> importFiles)` | Orchestrates parsing by creating an internal `ParseProcessor` with the configured variants and files. Returns the processed `ImportObject`. |
|
||||
|
||||
---
|
||||
|
||||
### DTSXMLParseImport (Class)
|
||||
|
||||
**Implements:** `IParseImport`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| Constructor | `public DTSXMLParseImport(ImportObject importObject, IImportNotification importNotification, Func<bool> isCancelled = null, bool skipNormalizing = false)` | Initializes the XML parser with an `ImportObject`, notification interface, optional cancellation callback, and optional flag to skip normalization. |
|
||||
| `UIItems` | `public List<IUIItems> UIItems { get; set; }` | Property for UI items configuration, passed to the internal `XMLParseProcessor`. |
|
||||
| `Parse` | `public ImportObject Parse(IEnumerable<string> importFiles)` | Creates an `XMLParseProcessor`, processes files, then calls `AssignLinkedDASSerials` to link pseudo-rack hardware. Returns the processed `ImportObject`. |
|
||||
|
||||
**Private Methods:**
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `AssignLinkedDASSerials(ref ImportObject importObject)` | Iterates over hardware objects, identifies pseudo-racks via `IsPseudoRack()`, and assigns `LinkedDASSerials` array to any pseudo-rack whose `SerialNumber` matches other hardware's `ParentDAS` value. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
1. **ParseVariantBase.Parse**: The `ImportObject` parameter is passed by reference (`ref`), meaning implementations may modify or replace the object entirely.
|
||||
|
||||
2. **DefaultParseImport**: The `_importObject` field is reassigned after parsing via `parseProcesser.Process()`. The same `_parseVariants` collection provided at construction is used throughout the instance lifetime.
|
||||
|
||||
3. **DTSXMLParseImport**:
|
||||
- `_importNotification` is required (no null check visible in source).
|
||||
- `_isCancelled` and `_skipNormalizing` are optional parameters with default values (`null` and `false` respectively).
|
||||
- `AssignLinkedDASSerials` only modifies hardware where `IsPseudoRack()` returns `true` and matching child hardware exists.
|
||||
|
||||
4. **Hardware Linking Logic**: In `AssignLinkedDASSerials`, linked serials are only assigned if `matches.Any()` returns true; otherwise, `LinkedDASSerials` is left unchanged (not explicitly cleared).
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### This module depends on:
|
||||
|
||||
| Dependency | Used In |
|
||||
|------------|---------|
|
||||
| `DTS.Common.Import.Interfaces` | All three files (for `IParseVariant`, `IParseImport`, `ImportObject`, `IImportNotification`) |
|
||||
| `DTS.Slice.Users` | `DTSXMLParseImport.cs` (for `IUIItems`) |
|
||||
| `System.Collections.Generic` | `DefaultParseImport.cs`, `DTSXMLParseImport.cs` |
|
||||
| `System.Linq` | `DefaultParseImport.cs`, `DTSXMLParseImport.cs` |
|
||||
| `System.Threading.Tasks` | `DefaultParseImport.cs` |
|
||||
| `System.Text` | `DefaultParseImport.cs` |
|
||||
|
||||
### External types referenced (not defined in source):
|
||||
|
||||
| Type | Source File | Notes |
|
||||
|------|-------------|-------|
|
||||
| `ImportObject` | All | Core data structure, defined elsewhere |
|
||||
| `IParseVariant` | `ParseVariantBase.cs` | Interface definition not shown |
|
||||
| `IParseImport` | `DefaultParseImport.cs`, `DTSXMLParseImport.cs` | Interface definition not shown |
|
||||
| `ParseProcessor` | `DefaultParseImport.cs` | Concrete class, definition not shown |
|
||||
| `XMLParseProcessor` | `DTSXMLParseImport.cs` | Concrete class, definition not shown |
|
||||
| `IImportNotification` | `DTSXMLParseImport.cs` | Interface definition not shown |
|
||||
| `IUIItems` | `DTSXMLParseImport.cs` | Interface definition not shown |
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
1. **Namespace Inconsistency**: `DTSXMLParseImport.cs` is in namespace `DTS.Common.Import` while the other two files are in `DTS.Common.Import.Parsers`. This may cause confusion when locating classes.
|
||||
|
||||
2. **Unused Imports**: `System.Threading.Tasks` and `System.Text` are imported in `DefaultParseImport.cs` but no async/await or text encoding operations are visible in the source.
|
||||
|
||||
3. **Field Reassignment**: Both `DefaultParseImport` and `DTSXMLParseImport` reassign their `_importObject` field during `Parse()`. If the same instance is used for multiple `Parse()` calls, the original `ImportObject` passed to the constructor will be overwritten.
|
||||
|
||||
4. **Null Handling Not Visible**: Neither class validates constructor parameters for null. Behavior with null `importObject`, `parseVariants`, or `importNotification` is undefined from source alone.
|
||||
|
||||
5. **UIItems Property Injection**: `DTSXMLParseImport.UIItems` must be set before calling `Parse()` if UI items are required by `XMLParseProcessor`. The property is not set in the constructor.
|
||||
Reference in New Issue
Block a user