ddn.odf.common

Shared error types, diagnostic model, and common constants for ddn.odf.

This module provides cross-cutting types used by all ODF submodules: typed exceptions, structured diagnostics, and severity levels.

Public-facing errors and diagnostics are re-exported through ddn.odf.

enum OdfDiagnosticCode OdfSeverity
struct OdfDiagnostic OdfDiagnosticCollector
class OdfException OdfPackageException OdfUnsupportedException OdfValidationException OdfXmlException

Types 9

enumOdfSeverity

Severity level for ODF diagnostics.

INFO = 0
WARNING = 1
ERROR = 2
FATAL = 3
enumOdfDiagnosticCode

Structured diagnostic code identifying the category of an ODF problem.

Codes are grouped by subsystem: package, XML, validation, compatibility, and general errors.

UNKNOWN = 0Unrecognised or unclassified error.
INVALID_PACKAGE = 100Package is not a valid ZIP archive or is structurally corrupt.
INVALID_MIME_ENTRY = 101The `mimetype` entry exists but is empty.
MIME_MISMATCH = 102Actual MIME type does not match the expected type for the document.
MISSING_MIMETYPE = 103Package is missing the required `mimetype` entry.
MISSING_MANIFEST = 104Package is missing `META-INF/manifest.xml`.
MISSING_CONTENT = 105Package is missing `content.xml` or manifest references a missing entry.
DUPLICATE_ENTRY = 106Duplicate entry path found in the ZIP archive.
INVALID_ENTRY_PATH = 107Entry path is invalid (starts with `/`, contains `\`, or is empty).
UNSAFE_PATH = 108Entry path contains `..` indicating a path-traversal attempt.
INVALID_XML = 200XML content is structurally invalid (reserved for future use).
MALFORMED_XML = 201XML content cannot be parsed due to malformed markup.
MISSING_REQUIRED_ATTRIBUTE = 202A required XML attribute is missing from an element.
INVALID_ATTRIBUTE_VALUE = 203An XML attribute value is invalid (reserved for future use).
UNKNOWN_NAMESPACE = 204An undeclared XML namespace prefix was encountered (reserved).
UNEXPECTED_ELEMENT = 205An unexpected XML element was found (reserved).
VALIDATION_FAILURE = 300Hard validation failure (e.g. cyclic style reference).
VALIDATION_WARNING = 301Soft validation warning (e.g. duplicate style name).
UNSUPPORTED_FEATURE = 400An ODF feature is not supported by this library (reserved).
UNSUPPORTED_DOCUMENT_TYPE = 401Document MIME type is not recognized.
UNSUPPORTED_VERSION = 402ODF version is not in the supported range {1.0 .. 1.4}.
PRESERVED_UNKNOWN_ENTRY = 500Package entry not listed in the manifest (informational).
PRESERVED_UNKNOWN_XML = 501Unknown XML element preserved during round-trip (reserved).
IO_ERROR = 600General I/O error during package reading or writing (reserved).
structOdfDiagnostic

A single structured diagnostic entry describing an ODF problem or information notice.

Diagnostics can be collected during parsing, validation, or serialization and reported to the caller through options rather than thrown as exceptions.

Fields
OdfSeverity severitySeverity of this diagnostic.
OdfDiagnosticCode codeMachine-readable diagnostic code.
string messageHuman-readable message describing the problem.
string locationOptional location hint such as a package entry path or XML element name.
string xmlContextOptional XML context string for XML-related diagnostics.
string packageEntryOptional package entry path for package-related diagnostics.
classOdfException : Exception

Base exception type for all ODF errors.

Carries an OdfDiagnostic so callers can access structured error details alongside the exception message.

Fields
OdfDiagnostic diagnosticThe structured diagnostic associated with this exception.
Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
this(OdfDiagnostic diag, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
classOdfPackageException : OdfException

Thrown when an ODF package is invalid or cannot be read.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
this(OdfDiagnostic diag, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
classOdfXmlException : OdfException

Thrown when ODF XML content is malformed or invalid.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
this(OdfDiagnostic diag, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
classOdfUnsupportedException : OdfException

Thrown when a requested feature is not yet supported.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
this(OdfDiagnostic diag, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
classOdfValidationException : OdfException

Thrown when ODF validation detects fatal conformance problems.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
this(OdfDiagnostic diag, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
structOdfDiagnosticCollector

Collects ODF diagnostics during parsing, validation, or serialization.

Used in permissive workflows where problems are reported as diagnostics rather than thrown as exceptions.

Fields
private OdfDiagnostic[] _diagnostics
Methods
const(OdfDiagnostic)[] diagnostics() @property const @safe pure nothrow @nogcReturns the collected diagnostics.
size_t length() @property const @safe pure nothrow @nogcReturns the number of collected diagnostics.
void add(OdfDiagnostic diag) @safe pureAdds a diagnostic entry.
void add(OdfSeverity severity, OdfDiagnosticCode code, string message, string location = "", string xmlContext = "", string packageEntry = "") @safe pureAdds a diagnostic with explicit fields.
bool hasFatal() const @safe pure nothrow @nogcReturns `true` if any diagnostic has fatal severity.
bool hasErrors() const @safe pure nothrow @nogcReturns `true` if any diagnostic has error or fatal severity.
bool hasWarnings() const @safe pure nothrow @nogcReturns `true` if any diagnostic has warning severity.
void clear() @safe pure nothrowRemoves all collected diagnostics.