config
Reading and writing INI, env and YAML settings files with dotted keys.
import config
The config package reads a program's settings from INI, YAML or env files and keeps them as one ordered list of keys and text values. Keys in sections are dotted: the key host in the [db] section of an INI file, or under db: in YAML, becomes db.host. Whatever the file format, the rest of the program reads settings the same way.
Use it for flat settings files that people edit by hand. For neighbouring jobs:
- A single environment variable of the running process: env or os.
- A
.envfile with full control over quoting,exportlines and errors: encoding.envfile, which this package uses underneath. - YAML with lists or nested data you want to walk: encoding.yaml. JSON or TOML: encoding.json, encoding.toml.
- Command line options: flag.
The usual pattern is to read the default settings, Merge the current environment's settings on top, and then read the values with the right type. Every value is stored as text; GetInt, GetFloat and GetBool convert it when you read it, and their last argument is the value to use when the key is not there at all.
The things people get wrong:
- Nothing here reports an error. A missing or unreadable file gives an empty config, a line without
=is skipped, and the typed getters fall back to your default for a value that is not a number. Check the file and the important keys yourself, as the guides below show. GetBoolis true only fortrue,1,yesandon, written in lower case.TRUEandYesare false.- In INI and env files a
#after a space starts a comment (in INI a;does too). Put quotes around values that contain them, such as passwords. - A
Configowns its memory: free each one you make, including the new ones thatMergeandSectionreturn, and free the vectorKeysreturns.
Layered settings: defaults, then overrides
Most programs read settings from more than one place: defaults shipped with the program, a file for the server it runs on, and a few values given on the command line. Merge takes two configs and returns a third in which the second one wins. Chain it to stack as many layers as you need. Keys keep the order of the base, and keys that only the override has are added at the end.
import config
func main:
defaults := "name = shop\nworkers = 4\ndebug = false\n\n[db]\nhost = localhost\nport = 5432\n"
production := "workers = 16\n\n[db]\nhost = db.internal\npool = 20\n"
mut base := config.ParseINI(defaults)
defer config.Free(base)
mut prod := config.ParseINI(production)
defer config.Free(prod)
mut flags := config.New()
defer config.Free(flags)
config.Set(flags, "debug", "yes")
mut step := config.Merge(base, prod)
defer config.Free(step)
mut final := config.Merge(step, flags)
defer config.Free(final)
print config.FormatINI(final)
println "workers:", config.GetInt(final, "workers", 1)
println "debug:", config.GetBool(final, "debug", false)
println "db:", config.Get(final, "db.host"), config.GetInt(final, "db.port", 5432), config.GetInt(final, "db.pool", 5)
endThe production file only names what differs (workers, db.host and a new db.pool), so the defaults stay the single place that lists every setting. db.port was never overridden and keeps its default.
Sections and your own settings struct
Passing one big config around means every part of the program sees every key. Section cuts out the keys under one name and drops the prefix, so a function that sets up the database only gets host, port and pool. Reading those into a struct once, at startup, keeps the rest of the code free of key names and string conversions.
import config
struct Database:
pub host: str = ""
pub port: i64 = 0
pub pool: i64 = 0
end
func read_database(c &: config.Config): Database:
ret Database {
host = config.GetOr(c, "host", "localhost"),
port = config.GetInt(c, "port", 5432),
pool = config.GetInt(c, "pool", 10)
}
end
func main:
text := "server:\n port: 8080\n host: 0.0.0.0\ndatabase:\n host: db.local\n port: 6432\nlog: warn\n"
mut c := config.ParseYAML(text)
defer config.Free(c)
mut server := config.Section(c, "server")
defer config.Free(server)
keys := config.Keys(server)
defer keys.Free()
each k in keys:
println "server", k, "=", config.Get(server, k)
end
mut dbc := config.Section(c, "database")
defer config.Free(dbc)
d := read_database(dbc)
println d.host, d.port, d.pool
println config.Len(c), config.Has(c, "log"), config.Has(c, "server")
endA YAML map such as server: is flattened into dotted keys, so the config holds only the leaf values: Has(c, "server") is false, while Has(c, "server.port") is true. Keys lists the keys in file order.
Reading files: comments, quotes and missing files
LoadINI, LoadYAML and LoadEnv read the whole file and parse it. If the file is not there they return an empty config without a word, so a typo in the path quietly leaves every setting at its default. Check the path first with fs and decide what a missing file means for your program.
import config
import fs
import io
func load_settings(path: str): config.Config:
if not fs.Exists(path):
println "no", path, "found, using built-in defaults"
mut c := config.New()
config.Set(c, "server.port", "8080")
ret c
end
ret config.LoadINI(path)
end
func main:
io.WriteFile("shop.ini", "[server]\nport = 9000 # the public port\n\n[db]\npassword = \"s3cret#2024\"\nmode = TRUE\ntags: fast\n")
mut c := load_settings("shop.ini")
defer config.Free(c)
keys := config.Keys(c)
defer keys.Free()
each k in keys:
println k, "=", "[" + config.Get(c, k) + "]"
end
println "db.mode as bool:", config.GetBool(c, "db.mode", false)
mut missing := load_settings("missing.ini")
defer config.Free(missing)
println "port:", config.GetInt(missing, "server.port", 0)
endThree details show up in the output. The comment after 9000 was cut off, and the spaces before it with it. The quoted password kept its #. The line tags: fast has no =, so it was dropped without a warning, and mode = TRUE was read but is not true for GetBool.
Check the settings at startup
The typed getters never fail. The default is used when the key is missing and also when its text does not parse: GetInt turns eighty into your default, and GetBool knows only true, 1, yes and on and their opposites false, 0, no and off, so enabled gives the default too. A typo therefore looks exactly like a missing key. It is worth checking the important keys once, when the program starts, and refusing to run with a clear list of problems.
import config
import str
func check(c &: config.Config): Vector<str>:
mut problems := Vector {} as Vector<str>
required := ["APP_PORT", "DATABASE_URL"]
each key in required:
if config.Has(c, key) == false:
problems.Push("missing " + key)
end
end
if config.Has(c, "APP_PORT"):
raw := config.Get(c, "APP_PORT")
if str.FromInt(config.GetInt(c, "APP_PORT", 0)) != raw:
problems.Push("APP_PORT is not a whole number: " + raw)
end
end
ret problems
end
func report(name: str, text: str):
mut c := config.ParseEnv(text)
defer config.Free(c)
problems := check(c)
defer problems.Free()
if problems.Len() == 0:
println name, "is fine, port", config.GetInt(c, "APP_PORT", 8080)
ret
end
println name, "has", problems.Len(), "problems:"
each p in problems:
println " ", p
end
end
func main:
mut c := config.ParseEnv("APP_PORT=eighty\nAPP_DEBUG=enabled\n")
defer config.Free(c)
println config.GetInt(c, "APP_PORT", 8080), config.GetInt(c, "APP_WORKERS", 4)
println config.GetBool(c, "APP_DEBUG", true), config.GetBool(c, "APP_CACHE", true)
report("broken.env", "APP_PORT=eighty\n")
report("good.env", "APP_PORT=9000\nDATABASE_URL=postgres://db/shop\n")
endThe check for a number compares the text with the number written back out with str.FromInt. If they differ, the text was not a plain whole number.
Change a file and write it back
Set adds or replaces a key and Remove deletes one, returning false when the key was not there. FormatINI writes the keys without a section first, then one [section] block for each prefix, and puts quotes around values that need them. Write the text with io and the next LoadINI reads back the same settings.
import config
import io
func main:
io.WriteFile("app.ini", "theme = light\n\n[editor]\nfont = mono\nsize = 12\n")
mut c := config.LoadINI("app.ini")
defer config.Free(c)
config.Set(c, "theme", "dark")
config.Set(c, "editor.size", "14")
config.Set(c, "editor.title", "My notes")
config.Set(c, "window.width", "1200")
println config.Remove(c, "editor.font"), config.Remove(c, "editor.font")
io.WriteFile("app.ini", config.FormatINI(c))
print io.ReadFile("app.ini")
mut again := config.LoadINI("app.ini")
defer config.Free(again)
println config.Get(again, "editor.title"), config.Len(again) == config.Len(c)
endComments and blank lines from the original file are not kept: ParseINI skips them, so a file the program rewrites loses them. Keep hand written notes in a separate defaults file that the program only reads.
Which function for which job
| You want | Use |
|---|---|
| Read a file from disk | LoadINI, LoadYAML, LoadEnv |
| Read text you already have | ParseINI, ParseYAML, ParseEnv |
| A value as text, with a fallback | GetOr |
| A number or a flag | GetInt, GetFloat, GetBool |
| Overrides on top of defaults | Merge |
| Only the keys of one section | Section |
| Write settings out again | FormatINI, FormatEnv, FormatEnvExport |
ParseYAML keeps only maps as dotted keys. A list becomes one value holding its text, so tags: [a, b] or a block list reads as ["a", "b"]; parse that with encoding.yaml when you need the items.
Types
Config
struct Config| Name | Type | Description |
|---|---|---|
m | collections.OrderedMap | The ordered map that keeps the keys and values in order. |
import config
func main:
mut c := config.New()
defer config.Free(c)
config.Set(c, "name", "salam")
config.Set(c, "port", "8080")
config.Set(c, "debug", "yes")
config.Set(c, "ratio", "0.5")
println config.Len(c), config.Has(c, "port"), config.Get(c, "name")
println config.GetInt(c, "port", 80), config.GetFloat(c, "ratio", 1.0), config.GetBool(c, "debug", false)
println config.GetOr(c, "host", "localhost")
println config.Remove(c, "ratio"), config.Keys(c)
endFunctions
New
func New(): ConfigThe example for this item is shown with the ones above: config-Get.salam
Len
func Len(c &: Config): intThe example for this item is shown with the ones above: config-Get.salam
Has
func Has(c &: Config, key: str): boolThe example for this item is shown with the ones above: config-Get.salam
Set
func Set(c &: Config, key: str, val: str)The example for this item is shown with the ones above: config-Get.salam
Get
func Get(c &: Config, key: str): strHas to tell a missing key from an empty value.The example for this item is shown with the ones above: config-Get.salam
GetOr
func GetOr(c &: Config, key: str, def: str): strThe example for this item is shown with the ones above: config-Get.salam
GetInt
func GetInt(c &: Config, key: str, def: i64): i64conv.ParseIntOr).The example for this item is shown with the ones above: config-Get.salam
GetFloat
func GetFloat(c &: Config, key: str, def: f64): f64The example for this item is shown with the ones above: config-Get.salam
GetBool
func GetBool(c &: Config, key: str, def: bool): booltrue, 1, yes and on in lower case are true and false, 0, no and off are false; anything else gives the default.The example for this item is shown with the ones above: config-Get.salam
Remove
func Remove(c &: Config, key: str): boolThe example for this item is shown with the ones above: config-Get.salam
Keys
func Keys(c &: Config): Vector<str>The example for this item is shown with the ones above: config-Get.salam
Section
func Section(c &: Config, name: str): Configname., and that prefix removed. Free the result.import config
import io
func main:
text := "name = salam\n\n[db]\nhost = localhost\nport = 5432\n"
mut c := config.ParseINI(text)
defer config.Free(c)
println config.Keys(c)
mut db := config.Section(c, "db")
defer config.Free(db)
println config.Get(db, "port")
print config.FormatINI(db)
io.WriteFile("app.ini", text)
mut loaded := config.LoadINI("app.ini")
defer config.Free(loaded)
println config.Get(loaded, "db.host")
endMerge
func Merge(base &: Config, override &: Config): Configbase and then of override; where both have a key, override wins and the key keeps its place from base. Free the result.import config
import io
func main:
mut base := config.ParseEnv("MODE=dev\nPORT=3000\n")
mut over := config.ParseEnv("PORT=80\nLOG=info\n")
defer config.Free(base)
defer config.Free(over)
mut merged := config.Merge(base, over)
defer config.Free(merged)
print config.FormatEnv(merged)
print config.FormatEnvExport(over)
io.WriteFile(".env", "TOKEN=abc\n")
mut loaded := config.LoadEnv(".env")
defer config.Free(loaded)
println config.Get(loaded, "TOKEN")
endFree
func Free(c &: Config)The example for this item is shown with the ones above: config-Get.salam
ParseINI
func ParseINI(text: str): Config[name] starts a section, # and ; start comment lines, values may be quoted, and lines without = are skipped. A key that appears twice keeps the last value.The example for this item is shown with the ones above: config-ParseINI.salam
ParseEnv
func ParseEnv(text: str): ConfigKEY=VALUE text, as in a .env file, with export prefixes, quotes and # comments. Keys are kept as written, with no sections.The example for this item is shown with the ones above: config-ParseEnv.salam
ParseYAML
func ParseYAML(text: str): Configimport config
import io
func main:
text := "app:\n name: salam\n port: 8080\nlog: info\n"
mut c := config.ParseYAML(text)
defer config.Free(c)
println config.Keys(c), config.GetInt(c, "app.port", 0)
io.WriteFile("app.yaml", text)
mut loaded := config.LoadYAML("app.yaml")
defer config.Free(loaded)
println config.Get(loaded, "log")
endLoadINI
func LoadINI(path: str): ConfigThe example for this item is shown with the ones above: config-ParseINI.salam
LoadEnv
func LoadEnv(path: str): ConfigThe example for this item is shown with the ones above: config-ParseEnv.salam
LoadYAML
func LoadYAML(path: str): ConfigThe example for this item is shown with the ones above: config-ParseYAML.salam
FormatINI
func FormatINI(c &: Config): str[section] per prefix. Values that need it are quoted. Comments are not kept.The example for this item is shown with the ones above: config-ParseINI.salam
FormatEnv
func FormatEnv(c &: Config): strKEY=VALUE text.The example for this item is shown with the ones above: config-ParseEnv.salam
FormatEnvExport
func FormatEnvExport(c &: Config): strexport before each line, to be run in a shell.The example for this item is shown with the ones above: config-ParseEnv.salam