XferLang

XferCaptureTagAttribute and XferCaptureIdAttribute

Capture XferLang metadata (tags and IDs) into sibling CLR properties during deserialization. Place the attribute on the target property and reference the source by CLR property name or by the exact document key. Properties decorated with these attributes are skipped during serialization.

using ParksComputing.Xfer.Lang.Attributes;

public class Item
{
    [XferProperty("name")]
    public string? Name { get; set; }

    // Tag targets can be string (first tag), List<string>, or string[] (all tags)
    [XferCaptureTag(nameof(Name))]         // capture tag(s) applied to the 'name' KVP (or: [XferCaptureTag("name")])
    public List<string>? NameTags { get; set; }

    // ID target is a string (nullable allowed)
    [XferCaptureId(nameof(Name))]          // capture ID applied to the 'name' KVP (or: [XferCaptureId("name")])
    public string? NameId { get; set; }
}

// Deserialization example
var xfer = @"{
    <!tag \"A\"!>
    <!tag \"B\"!>
    <!id \"z42\"!>
    name \"Widget\"
}";

var dto = XferConvert.Deserialize<Item>(xfer);
// dto!.Name == "Widget"
// dto.NameTags => ["A", "B"]
// dto.NameId   => "z42"

// Note: Properties decorated with XferCaptureTag or XferCaptureId are not serialized.
// The attribute argument may be the CLR property name (e.g., nameof(Name)) or the exact document key (e.g., "name").

Rules and edge cases:

• Target types for tags: string (captures first tag), List, or string[]; for IDs: string only.
• When no tags are present: string target => null; List => empty list; string[] => empty array.
• When no ID is present: target string remains null.
• Property resolution is case-insensitive for CLR names and respects any [XferProperty] rename; if no CLR match is found, the attribute value is treated as the literal document key.
• Tag values themselves are case-sensitive; duplicate tags are de-duplicated at parse time.
• If both [XferCaptureTag] and [XferCaptureId] are applied to the same property, an InvalidOperationException is thrown.

<! document {
    version "1.0"
    author "John Doe"
    created @2023-12-01T10:30:00@
    description "Sample configuration file"
} !>
{
    // Document content follows...
}

<! dynamicSource {
    greeting const "Welcome to our application"
    username env "USERNAME"
    config file "app.config"
    secret vault "api-key"
} !>
{
    message '<|greeting|>'
    user '<|username|>'
    settings '<|config|>'
    apiKey '<|secret|>'
}

<! chardef {
    bullet \$2022
    arrow \$2192
    check \$2713
} !>
{
    symbols [ \bullet \arrow \check ]
}

{
    <! id "user-config" !>
    section {
        name "User Settings"
        enabled ~true
    }
}

<! tag "experimental" !>
<! tag "search-index" !>
feature { enabled ~true }

<! let debug ~false !>
<! if defined _debug !>
{ note 'debug binding exists' }

<! dynamicSource { optFlag env "OPTIONAL_FLAG" } !>
<! if defined <|optFlag|> !>
{ note 'OPTIONAL_FLAG present' }

// Register a custom 'vault' source handler
DynamicSourceHandlerRegistry.RegisterHandler("vault", (sourceValue, fallbackKey) => {
    var key = sourceValue ?? fallbackKey;
    return await SecretVaultClient.GetSecretAsync(key);
});

// Register a database source handler
DynamicSourceHandlerRegistry.RegisterHandler("db", (sourceValue, fallbackKey) => {
    var query = sourceValue ?? $"SELECT value FROM config WHERE key = '{fallbackKey}'";
    return DatabaseService.ExecuteScalar(query);
});

public class ValidationProcessingInstruction : ProcessingInstruction {
    public const string Keyword = "validation";

    public ValidationProcessingInstruction(ObjectElement rules) : base(rules, Keyword) { }

    public override void ProcessingInstructionHandler() {
        if (Value is not ObjectElement obj) {
            throw new InvalidOperationException($"{Keyword} PI expects an object element");
        }

        // Process validation rules and store globally
        foreach (var kv in obj.Dictionary) {
            var fieldName = kv.Value.Key;
            var rules = kv.Value.Value;
            ValidationRegistry.RegisterRules(fieldName, rules);
        }
    }

    public override void ElementHandler(Element element) {
        // Apply validation rules to specific elements
        ValidationRegistry.ValidateElement(element);
    }
}

// Register the custom PI processor
Parser.RegisterPIProcessor(ValidationProcessingInstruction.Keyword,
    (kvp, parser) => new ValidationProcessingInstruction((ObjectElement)kvp.Value));

// Example usage in XferLang document
var xferContent = @"
<! validation {
    userEmail regex ""^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$""
    userAge range { min 0 max 120 }
} !>
{
    userEmail ""user@example.com""
    userAge 25
}";

// (1) Low-level: attach raw callbacks for existing PIs
void RegisterPIProcessor(string key, Action<KeyValuePairElement> processor);

// (2) Factory: create a strongly-typed ProcessingInstruction instance
void RegisterPIProcessor(string key, Parser.PIProcessor factory); // factory: (kvp, parser) => ProcessingInstruction

public sealed class TraceProcessingInstruction : ProcessingInstruction {
    public const string Keyword = "trace";
    public TraceProcessingInstruction(Element value) : base(value, Keyword) {
        SuppressSerialization = true; // operational only
    }
    public override void ProcessingInstructionHandler() {
        Console.WriteLine($"[TRACE-PI] {Value}");
    }
}

static ProcessingInstruction CreateTracePI(KeyValuePairElement kvp, Parser p) =>
    new TraceProcessingInstruction(kvp.Value);

var parser = new Parser();
parser.RegisterPIProcessor(TraceProcessingInstruction.Keyword, CreateTracePI);

<! trace "Starting build" !>
{ pipeline { stage "compile" } }

public override void ElementHandler(Element element) {
    if (!ShouldKeep(element)) {
        // Throw the same suppression exception style used by built-ins if you want to remove it
        throw new ConditionalElementException("Suppressed by custom PI");
    }
}

public sealed class ValidationProcessingInstruction : ProcessingInstruction {
    public const string Keyword = "validation";
    public ValidationProcessingInstruction(ObjectElement value) : base(value, Keyword) {
        SuppressSerialization = true;
    }
    public override void ProcessingInstructionHandler() {
        if (Value is not ObjectElement obj) throw new InvalidOperationException("validation PI expects object value");
        foreach (var kv in obj.Dictionary.Values) {
            var field = kv.Key;
            var ruleSpec = kv.Value;
            ValidationRegistry.Register(field, ruleSpec);
        }
    }
    public override void ElementHandler(Element element) => ValidationRegistry.Validate(element);
}

static ProcessingInstruction CreateValidationPI(KeyValuePairElement kvp, Parser p) =>
    new ValidationProcessingInstruction((ObjectElement)kvp.Value);

parser.RegisterPIProcessor(ValidationProcessingInstruction.Keyword, CreateValidationPI);

public class MyDynamicSourceResolver : DefaultDynamicSourceResolver {
    public override string? Resolve(string key) => key == "special" ? "custom-value" : base.Resolve(key);
}
var settings = new XferSerializerSettings { DynamicSourceResolver = new MyDynamicSourceResolver() };

# Clone the repository
git clone https://github.com/paulmooreparks/Xfer.git
cd Xfer

# Build the entire solution
dotnet build

# Run the tests
dotnet test

# Create NuGet packages (optional)
dotnet pack --configuration Release

# Build in Debug mode
dotnet build --configuration Debug

# Build in Release mode
dotnet build --configuration Release

# Run tests with verbose output
dotnet test --verbosity normal

# Run tests with code coverage
dotnet test --collect:"XPlat Code Coverage"