converter

Provides a means to convert a field from a Node to a complex type

When filling the config, it might be useful to store types which are not only simple string and integer, such as URL, BigInt, or any other library type not directly under the user's control.

To allow reading those values from the config file, a Converter may be used. The converter will tell the ConfigFiller how to convert from Node to the desired type T.

If the type is under the user's control, one can also add a constructor accepting a single string, or define the fromString method, both of which are tried if no Converter is found.

For types not under the user's control, there might be different ways to parse the same type within the same struct, or neither the ctor nor the fromString method may be defined under that name. The exmaple below uses parse in place of fromString, for example.

/// Complex structure representing the age of a person based on its birthday
public struct Age
{
    ///
    public uint birth_year;
    ///
    public uint birth_month;
    ///
    public uint birth_day;

    /// Note that this will be picked up automatically if named `fromString`
    /// but this struct might be a library type.
    public static Age parse (string value) { /+ Magic +/ }
}

public struct Person
{
    ///
    @Converter!Age((Node value) => Age.parse(value.as!string))
    public Age age;
}

Note that some fields may also be of multiple YAML types, such as DUB's dependencies, which is either a simple string ("vibe-d": "~>1.0 "), or an in its complex form ("vibe-d": { "version": "~>1.0" }). For those use cases, a Converter is the best approach.

To avoid repeating the field type, a convenience function is provided:

public struct Age
{
    public uint birth_year;
    public uint birth_month;
    public uint birth_day;
    public static Age parse (string value) { /+ Magic +/ }
}

public struct Person
{
    /// Here `converter` will deduct the type from the delegate argument,
    /// and return an instance  of `Converter`. Mind the case.
    @converter((Node value) => Age.parse(value.as!string))
    public Age age;
}