Class HumlSerializer

Namespace: Huml.Net

Assembly: Huml.Net.dll

Provides static methods for serialising and deserialising HUML documents. This is the single public entry point for the library, mirroring the System.Text.Json.JsonSerializer pattern. All internal pipeline classes (Huml.Net.Serialization.HumlSerializerImpl, Huml.Net.Serialization.HumlDeserializer, Huml.Net.Parser.HumlParser) are internal — consumers interact only through this class.

public static class HumlSerializer

Inheritance: object

HumlSerializer

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

Deserialize(string, Type, HumlOptions?)

Deserialises a HUML string into an object of targetType.

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static object? Deserialize(string huml, Type targetType, HumlOptions? options = null)

Parameters

huml string: The HUML string.
targetType Type: The target type.
options HumlOptions: Parsing options; defaults to Default.

Returns

object: A populated object, or null if the HUML value is null.

Exceptions

HumlParseException: Thrown when the HUML input is invalid.
HumlDeserializeException: Thrown when mapping to targetType fails.

Deserialize<T>(ReadOnlySpan<char>, HumlOptions?)

Deserialises a HUML character span into T. This is the single implementation overload; the Deserialize<T>(string, HumlOptions?) overload delegates here via AsSpan().

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static T Deserialize<T>(ReadOnlySpan<char> huml, HumlOptions? options = null)

Parameters

huml ReadOnlySpan<char>: The HUML document as a character span.
options HumlOptions: Parsing options; defaults to Default.

Returns

T: A populated instance of T.

Type Parameters

T: The target type.

Exceptions

HumlParseException: Thrown when the HUML input is invalid.
HumlDeserializeException: Thrown when mapping to T fails.

Deserialize<T>(string, HumlOptions?)

Deserialises a HUML string into T. This overload converts huml to a span and delegates to the Deserialize<T>(ReadOnlySpan<char>, HumlOptions?) implementation.

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static T Deserialize<T>(string huml, HumlOptions? options = null)

Parameters

huml string: The HUML string.
options HumlOptions: Parsing options; defaults to Default.

Returns

T: A populated instance of T.

Type Parameters

T: The target type.

Examples

var huml = """
    %HUML v0.2.0
    Host: "localhost"
    Port: 8080
    """;
var config = HumlSerializer.Deserialize<ServerConfig>(huml);
// config.Host == "localhost", config.Port == 8080

Exceptions

HumlParseException: Thrown when the HUML input is invalid.
HumlDeserializeException: Thrown when mapping to T fails.

Parse(string, HumlOptions?)

Parses a HUML string and returns the document AST without mapping to a .NET type. Useful for validation — throws HumlParseException if the input is invalid.

public static HumlDocument Parse(string huml, HumlOptions? options = null)

Parameters

huml string: The HUML string to parse.
options HumlOptions: Parsing options; defaults to Default.

Returns

HumlDocument: The HumlDocument AST root.

Examples

// Validate without binding to a type — throws HumlParseException on invalid input.
HumlDocument doc = HumlSerializer.Parse("""
    %HUML v0.2.0
    name: "example"
    """);

Exceptions

HumlParseException: Thrown when the HUML input is invalid.

Populate<T>(ReadOnlySpan<char>, T, HumlOptions?)

Populates an existing instance of T with values deserialised from a HUML character span. Properties present in the HUML document overwrite the corresponding property on existing; properties absent from the document are left unchanged. This is the single implementation overload; the Populate<T>(string, T, HumlOptions?) overload delegates here via AsSpan().

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static void Populate<T>(ReadOnlySpan<char> huml, T existing, HumlOptions? options = null)

Parameters

huml ReadOnlySpan<char>: The HUML document as a character span.
existing T: The existing instance to populate. Must not be null.
options HumlOptions: Parsing options; defaults to Default.

Type Parameters

T: The type of the existing instance. Must be a reference type.

Exceptions

ArgumentNullException: Thrown when existing is null.
ArgumentException: Thrown when T is a value type (struct).
HumlParseException: Thrown when the HUML input is invalid.
HumlDeserializeException: Thrown when mapping to T fails.

Populate<T>(string, T, HumlOptions?)

Populates an existing instance of T with values deserialised from a HUML string. Properties present in the HUML document overwrite the corresponding property on existing; properties absent from the document are left unchanged. This overload converts huml to a span and delegates to the Populate<T>(ReadOnlySpan<char>, T, HumlOptions?) implementation.

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static void Populate<T>(string huml, T existing, HumlOptions? options = null)

Parameters

huml string: The HUML string.
existing T: The existing instance to populate. Must not be null.
options HumlOptions: Parsing options; defaults to Default.

Type Parameters

T: The type of the existing instance. Must be a reference type.

Examples

var config = new ServerConfig { Host = "localhost", Port = 10 };
HumlSerializer.Populate("""
    %HUML v0.2.0
    Port: 50
    """, config);
// config.Host is still "localhost" (absent from the document)
// config.Port is now 50 (overwritten)

Exceptions

ArgumentNullException: Thrown when existing is null.
ArgumentException: Thrown when T is a value type (struct).
HumlParseException: Thrown when the HUML input is invalid.
HumlDeserializeException: Thrown when mapping to T fails.

Serialize(object?, Type, HumlOptions?)

Serialises value of the given type to a HUML string.

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static string Serialize(object? value, Type type, HumlOptions? options = null)

Parameters

value object: The value to serialise. May be null.
type Type: The declared type to use for serialisation.
options HumlOptions: Serialisation options; defaults to Default.

Returns

string: A HUML-formatted string.

Exceptions

HumlSerializeException: Thrown when serialisation fails.

Serialize<T>(T, HumlOptions?)

Serialises value to a HUML string.

[RequiresUnreferencedCode("HUML serialisation and deserialisation require types that cannot be statically analysed. Use a future HumlTypeInfo overload for NativeAOT applications.")]
[RequiresDynamicCode("HUML serialisation and deserialisation may require runtime code generation. Use a future HumlTypeInfo overload for NativeAOT applications.")]
public static string Serialize<T>(T value, HumlOptions? options = null)

Parameters

value T: The value to serialise.
options HumlOptions: Serialisation options; defaults to Default.

Returns

string: A HUML-formatted string.

Type Parameters

T: The type of the value to serialise.

Examples

var config = new ServerConfig { Host = "localhost", Port = 8080 };
string huml = HumlSerializer.Serialize(config);
// %HUML v0.2.0
// Host: "localhost"
// Port: 8080

Exceptions

HumlSerializeException: Thrown when serialisation fails.