Skip to content

Configuration

This part of the documentation is currently under construction.

Transformers can register a configuration definition for Bright to provide custom rules in its configuration file. These allow a user to specify how a transformer should act, such as appending a comment to the end of a file rather than the start. For transformers that inject new nodes into the CST, it is advisable that you define a configuration.

Setup

As written in Your First Transformer, a configuration is defined like so:

1
2
3
4
5
6
7
local config = {
    some_option = {
        description = "Should do xyz",
        default = true
    }
}
type Config = bright.Config<typeof(config)>

Which maps to the following TOML:

1
2
[rules.<transformer-name>]
some_option = true

Your function will be provided a table that conforms to the newly-created Config type as its second argument when it's invoked:

1
2
3
4
5
6
7
8
9
local function transformer(cst: bright.Cst, config: Config): bright.Cst
    if config.some_option then
        print("huzzah!")
    end
end

return {
    bright.defineTransformer("transformer", config, transformer)
}

Even if the configuration isn't defined in bright.toml, Bright will always provide values based on your default settings. A default is mandatory because of this. Transformers cannot stop working because a configuration isn't provided, but the default operation should be documented.

The description field of your configuration is used by Bright's config command. This generates a transformer rule block and outputs it to the terminal, primarily to make it easier for end users to discover what configuration options your transformer has.

Type Validation

If an option is of the wrong type in the configuration file, Bright will throw a runtime error stating this.

Any type is valid as an option type, as long as it can be resolved down to a singular type and not a union, intersection, or negation. If you do accidentally stumble into this, the type checker will throw an error like so:

1
'Config' type function errored at runtime: some_option cannot be a union

If you want to provide multiple possible values for a singular option key, you can use a table:

1
2
3
4
5
6
7
8
9
local config = {
    some_option = {
        description = "Should do xyz"
        default = {
            a = true,
            b = 123
        }
    }
}

And you will get a type like so:

1
2
3
4
5
6
type Config = {
    read some_option: {
        a: boolean,
        b: number
    }
}

Warning

By using a table type, Bright cannot check if a configuration is valid at runtime, meaning that the onus is on you to validate and throw an appropriate error.