Class HumlOptions

Namespace

Huml.Net.Versioning

Assembly

Huml.Net.dll

Configuration options for HUML parsing and serialisation.

public sealed class HumlOptions

Inheritance

object

HumlOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Document size: Huml.Net does not enforce a maximum document size. There is no built-in limit on the number of bytes or characters in an input document beyond MaxRecursionDepth. When parsing untrusted input, enforce size constraints in the caller before passing the document to any Huml.* method.

Fields

AutoDetect

Auto-detect options: reads the %HUML vX.Y directive from the document header, validates the declared version against Huml.Net.Versioning.SpecVersionPolicy.MinimumSupported and Huml.Net.Versioning.SpecVersionPolicy.Latest, and dispatches UnknownVersionBehaviour (Throw / UseLatest / UsePrevious) when the version is unrecognised. Falls back to V0_2 when no header is present. Equivalent to Default.

public static readonly HumlOptions AutoDetect

Field Value

HumlOptions

Default

Default options: reads the %HUML header to determine spec version (Header), falling back to V0_2 when no header is present. Unknown version behaviour is Throw. Equivalent to AutoDetect.

public static readonly HumlOptions Default

Field Value

HumlOptions

LatestSupported

Options pinned to the latest supported spec version (V0_2) with version taken from Options, ignoring any %HUML header in the document. Use when you always want v0.2 rules regardless of document content.

public static readonly HumlOptions LatestSupported

Field Value

HumlOptions

LatestSupportedAutoDetect

Options that read the %HUML header and fall back to the latest supported spec version (V0_2) when the declared version is unknown or outside the support window. Unlike Default and AutoDetect, this preset never throws HumlUnsupportedVersionException — unsupported versions are silently treated as the latest supported version. Use when consuming documents from heterogeneous sources where version drift is expected.

public static readonly HumlOptions LatestSupportedAutoDetect

Field Value

HumlOptions

Strict

Maximum-strictness preset. Enables every validation toggle:

• Reads the %HUML version header and throws HumlUnsupportedVersionException for unknown versions.
• Throws HumlDeserializeException for any HUML key that does not map to a target property (see UnmappedMemberHandling).
• Throws HumlSerializeException for duplicate dictionary keys during serialisation (see ValidateDuplicateKeysOnWrite).

Required-property enforcement via [HumlRequired] is unconditional and is always active regardless of this preset. Mirrors the STJ .NET 10 JsonSerializerOptions.Strict pattern.

public static readonly HumlOptions Strict

Field Value

HumlOptions

Properties

CollectionFormat

Controls the default output format for collections during serialisation. Multiline (the default) emits indented block format. Inline emits key:: a, b, c for scalar-only sequences and key:: k: v, k2: v2 for scalar-valued dictionaries. Collections containing non-scalar items silently fall back to multiline.

public CollectionFormat CollectionFormat { get; init; }

Property Value

CollectionFormat

Converters

A read-only list of HumlConverter instances consulted during serialisation and deserialisation when no property-level or type-level HumlConverterAttribute is present. The first converter whose CanConvert(Type) returns true for a given type is used.

public IReadOnlyList<HumlConverter> Converters { get; init; }

Property Value

IReadOnlyList<HumlConverter>

Remarks

Assign a List<T> or array at construction time via the object-initialiser syntax: Converters = new List<HumlConverter> { myConverter }. The property is read-only after construction — mutation after first use produces non-deterministic results because converter resolution results are cached.

DefaultIgnoreCondition

Gets or sets the global condition under which properties are omitted from serialisation output. Defaults to Never, preserving all existing serialisation behaviour.

public HumlIgnoreCondition DefaultIgnoreCondition { get; init; }

Property Value

HumlIgnoreCondition

Remarks

This option applies globally to every property during serialisation. The full precedence chain (highest to lowest) is: per-property [HumlProperty(OmitIfDefault = true)] → class-level [HumlIgnoreDefaults] → DefaultIgnoreCondition. If any higher-priority rule fires, this option is not evaluated for that property.

No changes are required from existing consumers — all code using the default Never value behaves identically to previous releases.

IsReadOnly

Gets a value indicating whether this HumlOptions instance has been locked against further mutation. Pre-built instances (Default, LatestSupported, AutoDetect) are read-only from the moment the type is first accessed.

public bool IsReadOnly { get; }

Property Value

bool

MaxRecursionDepth

Maximum recursion depth allowed during parsing. Exceeding this limit throws HumlParseException instead of risking an unrecoverable StackOverflowException. Default is 64. Valid range: [1, 1024].

public int MaxRecursionDepth { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

Thrown if value is less than 1 or greater than 1024.

NumberHandling

Controls how numeric values are handled during serialisation and deserialisation.

public HumlNumberHandling NumberHandling { get; init; }

Property Value

HumlNumberHandling

Remarks

When AllowReadingFromString is set, a ScalarKind.String scalar (e.g. a quoted HUML value such as "42") may be coerced to a numeric target type during deserialisation. Without this flag, assigning a quoted string to a numeric property throws HumlDeserializeException.

When WriteAsString is set, finite numeric values (integers, float, double, decimal) are emitted as quoted HUML strings rather than bare numeric literals. NaN, +inf, and -inf are always emitted unquoted regardless of this setting — they are HUML native scalar kinds.

Combining WriteAsString and AllowReadingFromString produces a round-trip-safe configuration.

PropertyNamingPolicy

The naming policy used to convert .NET property names to HUML keys during serialisation and deserialisation. null (the default) means the .NET property name is used as-is (ordinal-exact, PascalCase by default in C#).

public HumlNamingPolicy? PropertyNamingPolicy { get; init; }

Property Value

HumlNamingPolicy

Remarks

Use KebabCase for HUML documents that use kebab-case keys (the most common HUML convention). A HumlPropertyAttribute name override always takes precedence over this policy. This policy applies to .NET property names only — it does not affect Dictionary<string, T> string keys.

SpecVersion

The HUML spec version to use when parsing or serialising.

public HumlSpecVersion SpecVersion { get; init; }

Property Value

HumlSpecVersion

TypeInfoResolver

An optional resolver that provides pre-computed type metadata for HUML (de)serialisation, bypassing reflection for registered types. Return null to use the default reflection path.

public IHumlTypeInfoResolver? TypeInfoResolver { get; init; }

Property Value

IHumlTypeInfoResolver

Remarks

Set this property on a HumlOptions instance to register a custom IHumlTypeInfoResolver. When the resolver returns null for a type, the built-in reflection path is used as a fallback. Both the serialiser and the deserialiser consult this resolver before falling back to reflection; HumlGeneratedContext (the source-generator base class) is the primary implementation.

UnknownVersionBehaviour

Behaviour when an unsupported version is declared in the document header.

public UnknownVersionBehaviour UnknownVersionBehaviour { get; init; }

Property Value

UnknownVersionBehaviour

UnmappedMemberHandling

Controls how the deserialiser handles HUML keys that do not map to any property on the target type and are not captured by a [HumlExtensionData] property.

public UnmappedMemberHandling UnmappedMemberHandling { get; init; }

Property Value

UnmappedMemberHandling

Remarks

Skip (the default) silently ignores unknown keys, preserving forward-compatibility with documents produced by newer HUML writers.

Disallow throws HumlDeserializeException listing the unrecognised key. If the type has a [HumlExtensionData] property, unknown keys are routed there and the exception is suppressed — extension data is an explicit opt-in for unknown keys and takes precedence over Disallow.

ValidateDuplicateKeysOnWrite

When true, Huml.Net.Serialization.HumlSerializerImpl throws HumlSerializeException if two entries in the same dictionary produce the same key string (compared using Ordinal) during serialisation.

public bool ValidateDuplicateKeysOnWrite { get; init; }

Property Value

bool

Remarks

The check fires on the key as emitted — the string produced by calling ToString() on each dictionary key object. Two entries whose keys are distinct objects but return the same string from ToString() will collide.

Keys are compared using Ordinal, matching the deserialiser's key-lookup comparer. Keys that differ only in casing (e.g. "Foo" vs "foo") are treated as distinct.

Each nested dictionary has its own independent seen-key set; a key present in an outer dictionary does not collide with a key of the same name in a nested dictionary.

Note: this check covers the multiline dictionary path (SerializeDictionaryBody) only. Inline dictionaries emitted via CollectionFormat.Inline are not checked.

Defaults to false to preserve existing behaviour. Set to true in strict serialisation pipelines to catch write/read asymmetry early: the HUML deserialiser already rejects duplicate keys at parse time, so silently emitting them creates documents that cannot be round-tripped.

VersionSource

Where to read the spec version from.

public VersionSource VersionSource { get; init; }

Property Value

VersionSource

Methods

MakeReadOnly()

Marks this instance as read-only. Subsequent calls to any future mutable setter will throw InvalidOperationException. This call is idempotent.

public void MakeReadOnly()