↓ Skip to main content
7sharp9

Configuration

How myriad.toml works, and how plugins read it.

Myriad’s configuration model is smaller than it looks from the outside: one TOML file, and two ways to tell a plugin which section of it to read.

The myriad.toml file
#

Myriad looks for myriad.toml in the current directory by default. Each built-in plugin reads its settings from a named table in that file. For the fields plugin:

[fields]
namespace = "TestFields"

namespace controls the namespace the generated module is emitted under; every built-in plugin currently exposes just that one key.

Pointing at a different config file
#

If you don’t want myriad.toml sitting in the project root, set MyriadConfigFile in the .fsproj:

<PropertyGroup>
  <MyriadConfigFile>myConfig.toml</MyriadConfigFile>
</PropertyGroup>

Telling a plugin which config section to use
#

There are two ways to wire a generator to a config table, and they map to how the input is specified:

Attribute-based: the normal case, when a plugin operates on annotated types in an F# source file. The string argument to the generator attribute is the config key:

[<Generator.Fields "fields">]
type Test1 = { one: int; two: string; three: float; four: float32 }

Here "fields" is both what tells the fields plugin which types in this file to process, and the [fields] table it reads from myriad.toml.

MyriadConfigKey: used when a plugin’s input isn’t an attributed F# type at all (for example a plain text or data file), so there’s nowhere in the source to hang an attribute. The config key is set directly on the Compile element instead:

<Compile Include="ArbitaryFile.fs">
    <MyriadFile>Test.txt</MyriadFile>
    <MyriadConfigKey>example1</MyriadConfigKey>
</Compile>

This is how the Myriad.Plugin.Example1 sample plugin gets its namespace setting.

How a plugin actually reads it
#

Whichever mechanism supplied the key, the plugin receives it through GeneratorContext:

type GeneratorContext =
    { ConfigKey: string option
      ConfigGetter: string -> (string * obj) seq
      InputFilename: string
      ProjectContext: ProjectContext option
      AdditionalParameters: IDictionary<string, string> }

ConfigKey is the string from either mechanism above; ConfigGetter is a function the plugin calls with that key to get back the matching table’s entries as (name, value) pairs. A plugin author never parses TOML directly; Myriad has already done that by the time Generate runs.

Output formatting
#

Generated code is formatted with Fantomas. If an .editorconfig file exists in or above the output file’s directory, Myriad reads its indent_size, max_line_length, end_of_line, insert_final_newline, and any fsharp_* properties and formats the generated file to match, so generated code follows the same style as everything else in the project without extra configuration. With no .editorconfig, Fantomas’s default style is used. The lookup is per output file, so different generated files in different directories can pick up different settings.

← How It Works