Standard library · System and tools

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 .env file with full control over quoting, export lines 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.
  • GetBool is true only for true, 1, yes and on, written in lower case. TRUE and Yes are 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 Config owns its memory: free each one you make, including the new ones that Merge and Section return, and free the vector Keys returns.

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.

config-layers.salam
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)
end
Outputname = shop workers = 16 debug = yes [db] host = db.internal port = 5432 pool = 20 workers: 16 debug: true db: db.internal 5432 20

The 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.

config-sections.salam
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")
end
Outputserver port = 8080 server host = 0.0.0.0 db.local 6432 10 5 true false

A 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.

config-files.salam
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)
end
Outputserver.port = [9000] db.password = [s3cret#2024] db.mode = [TRUE] db.mode as bool: false no missing.ini found, using built-in defaults port: 8080

Three 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.

config-validate.salam
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")
end
Output8080 4 true true broken.env has 2 problems: missing DATABASE_URL APP_PORT is not a whole number: eighty good.env is fine, port 9000

The 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.

config-save.salam
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)
end
Outputtrue false theme = dark [editor] size = 14 title = "My notes" [window] width = 1200 My notes true

Comments 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 wantUse
Read a file from diskLoadINI, LoadYAML, LoadEnv
Read text you already haveParseINI, ParseYAML, ParseEnv
A value as text, with a fallbackGetOr
A number or a flagGetInt, GetFloat, GetBool
Overrides on top of defaultsMerge
Only the keys of one sectionSection
Write settings out againFormatINI, 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
A set of settings: dotted keys with text values, in the order they were first set.
NameTypeDescription
mcollections.OrderedMapThe ordered map that keeps the keys and values in order.
config-Get.salam
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)
end
Output4 true salam 8080 0.5 true localhost true ["name", "port", "debug"]

Functions

New

func New(): Config
Empty settings.

The example for this item is shown with the ones above: config-Get.salam

Len

func Len(c &: Config): int
The number of keys.

The example for this item is shown with the ones above: config-Get.salam

Has

func Has(c &: Config, key: str): bool
True when the key is there.

The example for this item is shown with the ones above: config-Get.salam

Set

func Set(c &: Config, key: str, val: str)
Sets a key's value. A new key goes at the end; an existing one keeps its place.

The example for this item is shown with the ones above: config-Get.salam

Get

func Get(c &: Config, key: str): str
A key's value, or an empty string when the key is missing. Use Has 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): str
A key's value, or the default.

The example for this item is shown with the ones above: config-Get.salam

GetInt

func GetInt(c &: Config, key: str, def: i64): i64
A key's value as a whole number, or the default when the key is missing or its text is not a whole number (see conv.ParseIntOr).

The example for this item is shown with the ones above: config-Get.salam

GetFloat

func GetFloat(c &: Config, key: str, def: f64): f64
A key's value as a decimal, or the default when the key is missing or its text is not a number.

The example for this item is shown with the ones above: config-Get.salam

GetBool

func GetBool(c &: Config, key: str, def: bool): bool
A key's value as a boolean, or the default when the key is missing. true, 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): bool
Removes a key, returning false when it was not there.

The example for this item is shown with the ones above: config-Get.salam

Keys

func Keys(c &: Config): Vector<str>
A new vector with every key, in order. Free it.

The example for this item is shown with the ones above: config-Get.salam

Section

func Section(c &: Config, name: str): Config
New settings with only the keys that start with name., and that prefix removed. Free the result.
config-ParseINI.salam
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")
end
Output["name", "db.host", "db.port"] 5432 host = localhost port = 5432 localhost

Merge

func Merge(base &: Config, override &: Config): Config
New settings with every key of base and then of override; where both have a key, override wins and the key keeps its place from base. Free the result.
config-ParseEnv.salam
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")
end
OutputMODE=dev PORT=80 LOG=info export PORT=80 export LOG=info abc

Free

func Free(c &: Config)
Releases the settings' memory.

The example for this item is shown with the ones above: config-Get.salam

ParseINI

func ParseINI(text: str): Config
Reads INI text. [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): Config
Reads KEY=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): Config
Reads YAML text, flattening nested maps into dotted keys. A list is stored as one value holding its text.
config-ParseYAML.salam
import 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")
end
Output["app.name", "app.port", "log"] 8080 info

LoadINI

func LoadINI(path: str): Config
Reads an INI file. A missing file gives an empty config, not an error.

The example for this item is shown with the ones above: config-ParseINI.salam

LoadEnv

func LoadEnv(path: str): Config
Reads an env file. A missing file gives an empty config, not an error.

The example for this item is shown with the ones above: config-ParseEnv.salam

LoadYAML

func LoadYAML(path: str): Config
Reads a YAML file. A missing file gives an empty config, not an error.

The example for this item is shown with the ones above: config-ParseYAML.salam

FormatINI

func FormatINI(c &: Config): str
Turns the settings into INI text: keys without a dot first, then one [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): str
Turns the settings into KEY=VALUE text.

The example for this item is shown with the ones above: config-ParseEnv.salam

FormatEnvExport

func FormatEnvExport(c &: Config): str
Like the env form, with export before each line, to be run in a shell.

The example for this item is shown with the ones above: config-ParseEnv.salam