Configurable Parser Behaviour

[aarondglover]

Overview

Add configurable parser options to the clear-hl7-net library to provide flexible handling of unknown segments, malformed segments, and parsing errors. This enhancement enables fault-tolerant parsing for real-world scenarios where HL7 messages may contain proprietary segments or minor formatting issues.

##Goals

• Backward Compatibility: All existing code continues to work without changes (default behavior is strict)
• Thread Safety: All new components are thread-safe using ConcurrentBag and defensive copying
• Flexibility: Support both global configuration and per-call overrides
• Observability: Provide warning collection and event-based notification
• Non-Breaking: Optional parameters with defaults ensure no API breaking changes

##Design Principles

• Fail-safe defaults: Default behavior matches current strict parsing (throw on errors)
• Progressive enhancement: Users opt-in to lenient parsing when needed
• Clear semantics: Explicit enums for behavior choices
• Separation of concerns: Global vs. instance-level configuration clearly separated
• Thread Safety and Minimal Allocations

Added

• Parser Options and Configurability: Added opt-in lenient parsing modes for handling real-world HL7 messages containing unknown segments or malformed data.
  • New ParserOptions class for configuring parser behavior (thread-safe)
  • New ParserConfiguration static class for global defaults
  • New ParserWarning class for structured warning metadata
  • New ParseResult<T> class for deserialization results with warnings
  • New enums: UnknownSegmentHandling, MalformedSegmentHandling, ParserWarningType
  • Optional ParserOptions parameter on MessageSerializer.Deserialize<T>() (backward compatible)
  • New MessageSerializer.DeserializeWithWarnings<T>() method
  • Warning collection and event-based notification at both instance and global levels
  • Thread-safe implementation using ConcurrentBag<T> and defensive copying with Array.AsReadOnly()

Notes

• Default behavior remains strict (throw on errors) for full backward compatibility
• No breaking changes - all existing code continues to work unchanged
• 42 new comprehensive tests added (1037 total tests passing)
• No external dependencies added - uses built-in .NET types

[davebronson]

Hi @aarondglover and thank you for the PR! Planning to start looking through this one soon.