Value Handlers

Value handlers are a way to extend the supported type set of .skconfig. They are used when loading to convert string forms to actual objects (parsing/deserialisation) and when writing to convert objects to their string representations, for saving (serialisation). User-registered value handlers are called auxiliary value handlers.

Registration is done with the following effect:

register [a] [new] [script] config[uration] %string% [value] handler (with|using) %object%

Auxiliary value handlers are always checked last, after the default ones have all failed. They are local to the script they have been registered in and are automatically used in all configuration-related elements within that script. For example, a script can register a value handler and use it without any special syntax.

An auxiliary value handler is represented by a two-argument function or section. The first argument is the input and the second is a boolean indicating whether parsing or serialisation should happen. A value of true means parsing, while a value of false means serialisation. If a value handler returns nothing, it means it has failed and the next one is tried. If all of them fail, an error is thrown.

An auxiliary parser also has a string identifier which can be used for ordering.

Example itemtype parser:

function handle_itemtype(input: object, parse: boolean) :: object:
    if {_parse} is true: # We should be parsing; it means {_input} is a string
        return {_input} parsed as itemtype # If parsing fails, it will return none => failure
    else: # Serialise; it means {_input} is an object
        if {_object} is an itemtype: # Ensure it's an itemtype; we don't want to conflict with something else!
            return "%{_object}%"

on load:
    register configuration "itemtype" value handler using function "handle_itemtype"

Now configurations can use item types :)

Cross-script value handlers

The keen users among you might have noticed that the loading and writing effects actually have a special part at the end:

load [script] config[uration] %string% in[to] %~objects% [(with|using) [value] handlers %-objects%]
(write|map) [script] config[uration] %~objects% (to|in[to]) [file] %string% [(with|using) [value] handlers %-objects%]

Paired with the following expression, this is used for accessing value handlers across multiple scripts.

[config[uration]] [value] handlers (from|of|for) script[s] %strings%

Now a script can use another script's value handlers.

load configuration "config.skconfig" into {config::*} using value handlers (value handlers of script "external.sk")

Do keep in mind that doing this will use the other script's value handlers exclusively (along with the default .skconfig ones). This means that, to also use the ones defined in the current script, one should do:

# 'script' is an expression returning the current script's name. The actual name can also be used.
load configuration "config.skconfig" into {config::*} using value handlers (value handlers of scripts ("external.sk", script))