DP44/enriched-qwen3-coder-next/DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/DiskUtility.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/Exceptional.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/ExceptionalList.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/AttributeCoder.cs	2026-04-16T04:58:12.148784+00:00	Qwen/Qwen3-Coder-Next-FP8	1	290a5af10b3d9412

Documentation: DatabaseExport.Utilities Module

1. Purpose

This module provides foundational utilities for the DatabaseExport subsystem, specifically supporting attribute-based encoding/decoding of enum values and basic file/path name validation. It enables a consistent pattern for associating metadata (attributes) with enum members and mapping between those metadata values and the enums themselves. The module also establishes a base class hierarchy (Exceptional, ExceptionalList<T>) for type-specific exception handling, allowing callers to catch exceptions by their originating class type. This module is part of a legacy codebase targeting database version 57 export functionality.

2. Public Interface

DiskUtility

A static utility class for validating file and path names.

• ValidateFileAndPathNameChars(string nameToValidate)
  • Signature: public static bool ValidateFileAndPathNameChars(string nameToValidate)
  • Behavior: Returns true if nameToValidate contains no characters from Path.GetInvalidFileNameChars() or Path.GetInvalidPathChars(), has non-zero length after trimming, and does not contain a period (.). Returns false otherwise.
  • Note: Explicitly rejects any string containing . (e.g., file extensions), beyond standard OS-invalid characters.

Exceptional

An abstract base class for enabling type-specific exception handling.

• No public methods or properties.
• Purpose: Serves as a marker base class. Derived classes may define nested Exception types (as shown in the remarks), but the base class itself provides no runtime behavior beyond being serializable.

ExceptionalList<T>

A generic list class inheriting from List<T> for type-specific exception handling.

• No public methods or properties beyond those inherited from List<T>.
• Purpose: Provides a base type that can be subclassed to define custom exception types (e.g., MyList : ExceptionalList<int> { public class Exception : System.Exception { ... } }), per the pattern described in the remarks.

AttributeCoder<TargetType, AttributeType, AttributeValueType>

A generic helper for mapping between enum values (TargetType), their associated attributes (AttributeType), and extracted values (AttributeValueType).

• Delegates:

  • AttributeValueExtractionMethod(AttributeType attribute) → AttributeValueType
    Defines how to extract an AttributeValueType from an AttributeType instance.
  • AttributeValueEqualityComparisonMethod(AttributeValueType, AttributeValueType) → bool
    Defines custom equality logic for AttributeValueType. If null, defaults to Equals().

• Constructors:

  • AttributeCoder(AttributeValueExtractionMethod, AttributeValueEqualityComparisonMethod = null)
    Initializes the coder. Throws Exception if attributeValueExtractionMethod is null. Stores both delegates.

• Methods:

  • DecodeAttributeValue(TargetType target) → AttributeValueType
    Extracts the single AttributeValueType from the attribute attached to target.
    • Internally calls DecodeAttributeValues(target) and asserts exactly one value exists.
    • Throws Exception if no attributes found or if multiple attributes exist.
  • DecodeAttributeValues(TargetType target) → List<AttributeValueType>
    Extracts all AttributeValueTypes from attributes of type AttributeType attached to target.
    • Uses reflection: target.GetType().GetField(target.ToString()) to get the FieldInfo of the enum field named by target.ToString().
    • Retrieves custom attributes of type AttributeType on that field.
    • Applies _extractAttributeValue to each attribute to produce the list.
  • EncodeAttributeValue(AttributeValueType attributeValue) → TargetType
    Returns the single TargetType enum value whose attribute has attributeValue.
    • Internally calls DehashAttributeValue(attributeValue) and asserts exactly one match.
    • Throws Exception if zero or multiple matches.
  • DehashAttributeValue(AttributeValueType attributeValue) → List<TargetType>
    Returns all TargetType enum values whose attributes match attributeValue.
    • Enumerates all values of TargetType via Enum.GetValues(typeof(TargetType)).
    • For each, calls DecodeAttributeValue(target) and compares to attributeValue using either _areAttributeValuesEqual (if provided) or Equals().
    • Throws Exception if no matches found.

3. Invariants

• DiskUtility.ValidateFileAndPathNameChars:

  • A valid name must be non-empty after trimming, contain no invalid filename/path characters (per Path.GetInvalidFileNameChars()/Path.GetInvalidPathChars()), and contain no . characters.
  • Critical constraint: The presence of . alone causes rejection, regardless of other validity.

• AttributeCoder:

  • DecodeAttributeValue and EncodeAttributeValue assume exactly one attribute per enum field and exactly one enum field per attribute value, respectively. They throw if this is violated.
  • DecodeAttributeValues and DehashAttributeValue do not assume uniqueness and return lists.
  • DecodeAttributeValues relies on the TargetType being an enum and that target.ToString() yields a valid field name on the enum type.
  • The AttributeType must be applied as a custom attribute on the enum field (not the value itself), and GetField(target.ToString()) must succeed.
  • AttributeValueExtractionMethod must be non-null; AttributeValueEqualityComparisonMethod may be null (defaults to Equals).

4. Dependencies

This module depends on:

• System.IO (for Path.GetInvalidFileNameChars(), Path.GetInvalidPathChars())
• System.Linq (for Cast<T>(), Where(), Select(), ToList())
• System.Diagnostics (for Debug.Assert)
• System.Collections.Generic (for List<T>)
• System (for Exception, SerializableAttribute, Enum)

This module is depended upon by:

• Inferred: Other modules in DatabaseExport (not visible here) likely use AttributeCoder to map between enums and metadata (e.g., database column types, export options).
• DiskUtility is likely used by export logic that constructs file paths dynamically.
• Exceptional/ExceptionalList<T> are base types; specific subclasses (not provided) are used throughout the codebase for typed exceptions.

5. Gotchas

• DiskUtility.ValidateFileAndPathNameChars:

  • The explicit ban on . is non-standard and may conflict with typical file naming conventions (e.g., .txt, data.csv). This is likely intentional to prevent extension confusion in internal naming, but is a critical constraint.
  • Validation is case-sensitive for content (e.g., .. is invalid, but .. is not explicitly checked beyond . presence).

• AttributeCoder:

  • Fragile reflection usage: target.GetType().GetField(target.ToString()) assumes the TargetType is an enum and that ToString() returns the exact field name. If TargetType is not an enum, or if custom ToString() overrides exist, this will fail.
  • No support for multiple attributes per field: DecodeAttributeValues collects all attributes of AttributeType, but DecodeAttributeValue expects exactly one and throws otherwise.
  • Equality semantics: If _areAttributeValuesEqual is null, Equals() is used. Value types (e.g., int, string) usually work, but reference types may require custom equality (e.g., for case-insensitive strings).
  • Exception messages are not localized: Commented-out Resources.* strings indicate localization was intended but not implemented. All exceptions use hardcoded English strings.
  • No null-safety on target: Passing null to DecodeAttributeValue/DecodeAttributeValues will throw NullReferenceException before reaching intended error handling.
  • EncodeAttributeValue/DehashAttributeValue are inverses only if the mapping is bijective: If multiple enum values map to the same attribute value, EncodeAttributeValue will fail.

• Exceptional/ExceptionalList<T>:

  • These classes provide no runtime behavior beyond inheritance. Their utility relies on subclasses defining nested Exception types (as shown in remarks), which are not present in the provided source. Callers must infer usage from comments.
  • ExceptionalList<T> adds no functionality beyond List<T>; it is only a marker for exception hierarchy.