NotableDateDocumentBuilder Class

Definition

Namespace: Bodu.Globalization.Calendar.Builder

Assembly: Bodu.Globalization.Calendar.Builder.dll

Package: Bodu.Globalization.Calendar.Builder 1.0.0

Source: NotableDateDocumentBuilder.Binary.cs

Provides a fluent, chainable API for authoring a Bodu notable-date document on the notable-date schema, with full-fidelity XML serialization, a JSON-subset surface, and materialization into a NotableDateResource through the canonical loader.

public sealed class NotableDateDocumentBuilder

Inheritance: object

NotableDateDocumentBuilder

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods: ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

NotableDateResource resource = NotableDateDocumentBuilder.Create("contoso-holidays")
    .AddAdjustmentPolicy("weekend-roll", p => p
        .When(AdjustmentTrigger.IfWeekend)
        .Then(AdjustmentAction.MoveToNextWorkingDay)
        .Emit(EmissionMode.ObservedOnly))
    .AddNotableDate("christmas", "Christmas Day", NotableDateCategory.PublicHoliday, c => c
        .AsNonWorkingByDefault()
        .AddRule("fixed", r => r
            .Fixed(12, 25)
            .WithAdjustment("weekend-roll")))
    .Build();

NotableDateService service = new(resource);

// The same model serializes to XML or JSON for storage or distribution.
NotableDateDocumentBuilder builder = NotableDateDocumentBuilder.Create("contoso-holidays")
    .AddNotableDate("new-year", "New Year's Day", NotableDateCategory.PublicHoliday, c => c
        .AddRule("fixed", r => r.Fixed(1, 1)));
string xml = builder.ToXml();
string json = builder.ToJson();

Remarks

The builder accumulates an in-memory model of the document. Calling ToXml() or Build() renders the model to XML in the urn:bodu:globalization:calendar namespace; building then loads that XML through NotableDateResourceLoader, which remains the single source of validation and assembly. The XML form expresses every feature of the schema, whereas the JSON form rendered by ToJson() is restricted to the subset the companion JSON schema can represent.

Workflow. Obtain a builder with Create() or Create(string, string), declare reusable adjustment policies with AddAdjustmentPolicy(string, Action<AdjustmentPolicyBuilder>), add each notable-date concept with AddNotableDate(string, string, NotableDateCategory, Action<NotableDateDefinitionBuilder>), then terminate by materializing a NotableDateResource with Build(), serializing with ToXml() / ToJson() / Save(string), or wrapping the result with ToProvider().

Methods

AddAdjustmentPolicy(string, Action<AdjustmentPolicyBuilder>)

Adds a reusable adjustment policy and configures it through the supplied delegate.

public NotableDateDocumentBuilder AddAdjustmentPolicy(string id, Action<AdjustmentPolicyBuilder> configure)

Parameters

id string: The stable identifier of the policy.
configure Action<AdjustmentPolicyBuilder>: A delegate that configures the policy.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentException: id is null, empty, or white-space.
ArgumentNullException: configure is null.

AddImport(string, Action<ImportBuilder>?)

Adds an import of an external resource and optionally configures its Use directives.

public NotableDateDocumentBuilder AddImport(string resource, Action<ImportBuilder>? configure = null)

Parameters

resource string: The name of the imported resource.
configure Action<ImportBuilder>: A delegate that configures the import, or null.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentException: resource is null, empty, or white-space.

AddNotableDate(string, string, NotableDateCategory, Action<NotableDateDefinitionBuilder>)

Adds a notable-date concept and configures it through the supplied delegate.

public NotableDateDocumentBuilder AddNotableDate(string id, string displayName, NotableDateCategory category, Action<NotableDateDefinitionBuilder> configure)

Parameters

id string: The stable identifier of the concept.
displayName string: The human-readable display name of the concept.
category NotableDateCategory: The category of the concept.
configure Action<NotableDateDefinitionBuilder>: A delegate that configures the concept.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentException: id or displayName is null, empty, or white-space.
ArgumentNullException: configure is null.

AddOverride(Action<OverrideBuilder>)

Adds override operations through the supplied delegate, appending to any previously configured overrides.

public NotableDateDocumentBuilder AddOverride(Action<OverrideBuilder> configure)

Parameters

configure Action<OverrideBuilder>: A delegate that configures the override operations.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException: configure is null.

Build()

Materializes the document into a validated NotableDateResource through the canonical loader.

public NotableDateResource Build()

Returns

NotableDateResource: The loaded and validated NotableDateResource.

Exceptions

InvalidOperationException: The document is incomplete: the resource identifier is missing, a concept has no rules, a rule has no strategy, or an adjustment policy is missing a trigger, action, or emission.
NotableDateValidationException: The loader produced one or more error diagnostics.

Build(Func<string, string?>?)

Materializes the document into a validated NotableDateResource, resolving imports through the supplied resolver.

public NotableDateResource Build(Func<string, string?>? importResolver)

Parameters

importResolver Func<string, string>: A delegate mapping a resource name to its XML or JSON content, or null to resolve no imports.

Returns

NotableDateResource: The loaded and validated NotableDateResource.

Exceptions

InvalidOperationException: The document is incomplete: the resource identifier is missing, a concept has no rules, a rule has no strategy, or an adjustment policy is missing a trigger, action, or emission.
NotableDateValidationException: The loader produced one or more error diagnostics.

Clone()

Creates a deep copy of this document builder.

public NotableDateDocumentBuilder Clone()

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder carrying an independent copy of the document model.

Create()

Creates an empty document builder with no resource identifier configured.

public static NotableDateDocumentBuilder Create()

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder.

Create(string, string)

Creates a document builder with the supplied resource identifier and schema version.

public static NotableDateDocumentBuilder Create(string resourceId, string schemaVersion = "1.0")

Parameters

resourceId string: The resource identifier of the document.
schemaVersion string: The schema version emitted on the root element.

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder.

Exceptions

ArgumentException: resourceId or schemaVersion is null, empty, or white-space.

FromJson(string)

Parses a JSON string into a builder.

public static NotableDateDocumentBuilder FromJson(string json)

Parameters

json string: The notable-date document JSON content.

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder populated from the JSON.

Examples

// Round-trip a document through its JSON-subset form, then materialize a resource.
NotableDateDocumentBuilder original = NotableDateDocumentBuilder.Create("contoso-holidays")
    .AddNotableDate("new-year", "New Year's Day", NotableDateCategory.PublicHoliday, c => c
        .AddRule("fixed", r => r.Fixed(1, 1)));
string json = original.ToJson();

NotableDateDocumentBuilder reparsed = NotableDateDocumentBuilder.FromJson(json);
NotableDateResource resource = reparsed.Build();

Exceptions

ArgumentException: json is null, empty, or white-space.
FormatException: json is not well-formed or is not a notable-date document.

FromJsonObject(JsonObject)

Parses a JsonObject into a builder.

public static NotableDateDocumentBuilder FromJsonObject(JsonObject json)

Parameters

json JsonObject: The notable-date document JSON object.

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder populated from the object.

Exceptions

ArgumentNullException: json is null.

FromXDocument(XDocument)

Parses an XDocument into a builder.

public static NotableDateDocumentBuilder FromXDocument(XDocument document)

Parameters

document XDocument: The notable-date document.

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder populated from the document.

Exceptions

ArgumentNullException: document is null.
FormatException: The root element is not a notable-date resource element.

FromXml(string)

Parses an XML document into a builder.

public static NotableDateDocumentBuilder FromXml(string xml)

Parameters

xml string: The notable-date document XML content.

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder populated from the XML.

Examples

// Round-trip a document through its XML form: serialize, then re-parse into an equivalent builder.
NotableDateDocumentBuilder original = NotableDateDocumentBuilder.Create("contoso-holidays")
    .AddNotableDate("new-year", "New Year's Day", NotableDateCategory.PublicHoliday, c => c
        .AddRule("fixed", r => r.Fixed(1, 1)));
string xml = original.ToXml();

NotableDateDocumentBuilder reparsed = NotableDateDocumentBuilder.FromXml(xml);
NotableDateResource resource = reparsed.Build();

Exceptions

ArgumentException: xml is null, empty, or white-space.
FormatException: xml is not well-formed or is not a notable-date document.

Load(string)

Reads a document from a file and parses it into a builder, inferring the format from the file extension.

public static NotableDateDocumentBuilder Load(string path)

Parameters

path string: The source file path. A .xml extension reads XML; a .json extension reads JSON.

Returns

NotableDateDocumentBuilder: A new NotableDateDocumentBuilder populated from the file.

Exceptions

ArgumentException: path is null, empty, white-space, or has an unrecognized extension.
FormatException: The file content is not a well-formed notable-date document.

Save(string)

Serializes the document to a file, inferring the format from the file extension.

public void Save(string path)

Parameters

path string: The destination file path. A .xml extension writes XML; a .json extension writes JSON.

Examples

NotableDateDocumentBuilder builder = NotableDateDocumentBuilder.Create("contoso-holidays")
    .AddNotableDate("new-year", "New Year's Day", NotableDateCategory.PublicHoliday, c => c
        .AddRule("fixed", r => r.Fixed(1, 1)));

// The extension selects the format: .xml writes XML, .json writes JSON.
builder.Save("contoso-holidays.xml");
builder.Save("contoso-holidays.json");

// Reload the document later and build a service over it.
NotableDateResource resource = NotableDateDocumentBuilder.Load("contoso-holidays.xml").Build();

Exceptions

ArgumentException: path is null, empty, white-space, or has an unrecognized extension.
InvalidOperationException: The document is incomplete.
NotSupportedException: A JSON target is requested but the document uses a feature the JSON subset cannot represent.

Save(string, NotableDateDocumentFormat)

Serializes the document to a file in the specified format.

public void Save(string path, NotableDateDocumentFormat format)

Parameters

path string: The destination file path.
format NotableDateDocumentFormat: The serialization format.

Exceptions

ArgumentException: path is null, empty, or white-space.
InvalidOperationException: The document is incomplete.
NotSupportedException: A JSON target is requested but the document uses a feature the JSON subset cannot represent.
NotableDateValidationException: A binary target is requested and the document produced one or more error diagnostics.

SaveBinary(Stream, Func<string, string?>?)

Compiles the document to a sealed binary rule pack written to a stream.

public void SaveBinary(Stream stream, Func<string, string?>? importResolver = null)

Parameters

stream Stream: The writable stream receiving the pack.
importResolver Func<string, string>: A delegate mapping a resource name to its XML or JSON content, or null to resolve no imports.

Exceptions

ArgumentNullException: stream is null.
InvalidOperationException: The document is incomplete.
NotableDateValidationException: The document produced one or more error diagnostics.

SaveBinary(string)

Compiles the document to a sealed binary rule pack on disk.

public void SaveBinary(string path)

Parameters

path string: The destination file path, conventionally with the .bcal extension.

Remarks

The document is materialized through Build() first, so only content that passed the canonical loader's validation is ever encoded; the pack then loads via LoadBinary(Stream) without re-parsing or re-validating.

Exceptions

ArgumentException: path is null, empty, or white-space.
InvalidOperationException: The document is incomplete.
NotableDateValidationException: The document produced one or more error diagnostics.

SaveBinary(string, Func<string, string?>?)

Compiles the document to a sealed binary rule pack on disk, resolving imports through the supplied resolver.

public void SaveBinary(string path, Func<string, string?>? importResolver)

Parameters

path string: The destination file path, conventionally with the .bcal extension.
importResolver Func<string, string>: A delegate mapping a resource name to its XML or JSON content, or null to resolve no imports.

Exceptions

ArgumentException: path is null, empty, or white-space.
InvalidOperationException: The document is incomplete.
NotableDateValidationException: The document produced one or more error diagnostics.

ToJson()

Serializes the document to an indented JSON string in the JSON-subset form.

public string ToJson()

Returns

string: The serialized JSON.

Exceptions

InvalidOperationException: The document is incomplete.
NotSupportedException: The document uses a feature the JSON subset cannot represent.

ToJsonObject()

Serializes the document to a JsonObject in the JSON-subset form.

public JsonObject ToJsonObject()

Returns

JsonObject: The serialized JSON object.

Exceptions

InvalidOperationException: The document is incomplete.
NotSupportedException: The document uses a feature the JSON subset cannot represent.

ToProvider()

Materializes the document and wraps it in a mutable provider.

public INotableDateResourceProvider ToProvider()

Returns

INotableDateResourceProvider: An INotableDateResourceProvider exposing the built resource.

Exceptions

InvalidOperationException: The document is incomplete.
NotableDateValidationException: The loader produced one or more error diagnostics.

ToXDocument()

Serializes the document to an XDocument in the urn:bodu:globalization:calendar namespace.

public XDocument ToXDocument()

Returns

XDocument: The serialized document.

Exceptions

InvalidOperationException: The document is incomplete.

ToXml()

Serializes the document to an indented XML string in the urn:bodu:globalization:calendar namespace.

public string ToXml()

Returns

string: The serialized XML.

Exceptions

InvalidOperationException: The document is incomplete.

TryBuild(out NotableDateResource?, out IReadOnlyList<NotableDateValidationDiagnostic>)

Attempts to materialize the document into a validated NotableDateResource, collecting every diagnostic instead of throwing on an invalid document.

public bool TryBuild(out NotableDateResource? resource, out IReadOnlyList<NotableDateValidationDiagnostic> diagnostics)

Parameters

resource NotableDateResource: The built resource, or null when the document does not validate.
diagnostics IReadOnlyList<NotableDateValidationDiagnostic>: Every diagnostic serialization and validation produced.

Returns

bool: true when the document built without error-severity diagnostics; otherwise false.

TryBuild(Func<string, string?>?, out NotableDateResource?, out IReadOnlyList<NotableDateValidationDiagnostic>)

Attempts to materialize the document into a validated NotableDateResource resolving imports through the supplied resolver, collecting every diagnostic instead of throwing on an invalid document.

public bool TryBuild(Func<string, string?>? importResolver, out NotableDateResource? resource, out IReadOnlyList<NotableDateValidationDiagnostic> diagnostics)

Parameters

importResolver Func<string, string>: A delegate mapping a resource name to its XML or JSON content, or null to resolve no imports.
resource NotableDateResource: The built resource, or null when the document does not validate.
diagnostics IReadOnlyList<NotableDateValidationDiagnostic>: Every diagnostic serialization and validation produced.

Returns

bool: true when the document built without error-severity diagnostics; otherwise false.

Validate()

Lints the document, returning every diagnostic the canonical loader's validation would produce - errors, warnings, and informational messages - without throwing.

public IReadOnlyList<NotableDateValidationDiagnostic> Validate()

Returns

IReadOnlyList<NotableDateValidationDiagnostic>: The collected diagnostics; empty when the document is valid.

Remarks

Validation runs the same pipeline as Build() - the document is serialized to XML and passed through NotableDateResourceLoader - so a clean result guarantees Build() succeeds for the same document. A document too incomplete to serialize (a missing resource identifier, a concept with no rules, a rule with no strategy) is reported as a BODU-CAL-BUILDER-INCOMPLETE error diagnostic rather than an exception.

Validate(Func<string, string?>?)

Lints the document against the supplied import resolver, returning every diagnostic without throwing.

public IReadOnlyList<NotableDateValidationDiagnostic> Validate(Func<string, string?>? importResolver)

Parameters

importResolver Func<string, string>: A delegate mapping a resource name to its XML or JSON content, or null to resolve no imports.

Returns

IReadOnlyList<NotableDateValidationDiagnostic>: The collected diagnostics; empty when the document is valid.

WithMetadata(string?, string?, params string[])

Sets the document metadata name, description, and sources.

public NotableDateDocumentBuilder WithMetadata(string? name = null, string? description = null, params string[] sources)

Parameters

name string: The metadata name, or null to leave it unset.
description string: The metadata description, or null to leave it unset.
sources string[]: The metadata source entries.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException: sources is null.

WithResolutionPolicy(Action<ResolutionPolicyBuilder>)

Configures the document-level resolution policy through the supplied delegate.

public NotableDateDocumentBuilder WithResolutionPolicy(Action<ResolutionPolicyBuilder> configure)

Parameters

configure Action<ResolutionPolicyBuilder>: A delegate that configures the resolution policy.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentNullException: configure is null.

WithResourceId(string)

Sets the resource identifier of the document.

public NotableDateDocumentBuilder WithResourceId(string resourceId)

Parameters

resourceId string: The resource identifier.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentException: resourceId is null, empty, or white-space.

WithSchemaVersion(string)

Sets the schema version emitted on the root element.

public NotableDateDocumentBuilder WithSchemaVersion(string schemaVersion)

Parameters

schemaVersion string: The schema version.

Returns

NotableDateDocumentBuilder: The same NotableDateDocumentBuilder instance, enabling chained calls.

Exceptions

ArgumentException: schemaVersion is null, empty, or white-space.

Applies to

Product	Versions
.NET	8, 10

Table of Contents

NotableDateDocumentBuilder Class

Definition

Examples

Remarks

Methods

AddAdjustmentPolicy(string, Action<AdjustmentPolicyBuilder>)

Parameters

Returns

Exceptions

AddImport(string, Action<ImportBuilder>?)

Parameters

Returns

Exceptions

AddNotableDate(string, string, NotableDateCategory, Action<NotableDateDefinitionBuilder>)

Parameters

Returns

Exceptions

AddOverride(Action<OverrideBuilder>)

Parameters

Returns

Exceptions

Build()

Returns

Exceptions

Build(Func<string, string?>?)

Parameters

Returns

Exceptions

Clone()

Returns

Create()

Returns

Create(string, string)

Parameters

Returns

Exceptions

FromJson(string)

Parameters

Returns

Examples

Exceptions

FromJsonObject(JsonObject)

Parameters

Returns

Exceptions

FromXDocument(XDocument)

Parameters

Returns

Exceptions

FromXml(string)

Parameters

Returns

Examples

Exceptions

Load(string)

Parameters

Returns

Exceptions

Save(string)

Parameters

Examples

Exceptions

Save(string, NotableDateDocumentFormat)

Parameters

Exceptions

SaveBinary(Stream, Func<string, string?>?)

Parameters

Exceptions

SaveBinary(string)

Parameters

Remarks

Exceptions

SaveBinary(string, Func<string, string?>?)

Parameters

Exceptions

ToJson()

Returns

Exceptions

ToJsonObject()