cfgman

Config loader for V with support for:

• JSON config files
• environment variable overrides
• .env file loading
• nested struct field mapping
• python-dotenv-style parsing for env files

cfgman is useful when you want a typed config struct in V and want values to come from both a config file and environment variables.

Features

• Load JSON into a typed V struct
• Override struct fields from environment variables
• Load variables from a .env file before applying overrides
• Support nested structs with prefix expansion
• Parse .env values with support for:
  • comments
  • export KEY=value
  • quoted values
  • inline comments for unquoted values
  • ${VAR} expansion from earlier parsed variables or the process environment

Installation

v install --git https://github.com/Te4nick/cfgman.git

Add import into .v files

import cfgman

Quick Start

Given this config struct:

module main

import cfgman

struct AppConfig {
pub:
	port int
	addr string
}

And a config.json file:

{
  "port": 8080,
  "addr": "127.0.0.1"
}

You can load it like this:

module main

import cfgman

struct AppConfig {
pub:
	port int
	addr string
}

fn main() {
	cfg := cfgman.load[AppConfig](cfg_file_path: 'config.json')!

	println(cfg.port)
	println(cfg.addr)
}

How Loading Works

cfgman.load[T]() applies sources in this order:

1. Start with T{}
2. If cfg_load_file is enabled, parse the JSON config file into the struct
3. If env_load_file is enabled, load variables from the .env file into the process environment
4. If env_overrides is enabled, apply matching environment variables onto the struct fields

Primary API

load[T](params CfgParams) !T

Loads a typed config struct from JSON and environment variables.

cfg := cfgman.load[MyConfig](
	cfg_file_path: 'config.json'
	env_file_path: '.env'
	env_load_file: true
	env_prefix: 'MYAPP'
	env_overrides: true
)!

parse_json_file[T](path string) !T

Parses a JSON file into a struct without applying any environment variables.

cfg := cfgman.parse_json_file[MyConfig]('config.json')!

env_values(data string) !map[string]string

Parses raw .env text.

values := cfgman.env_values('PORT=8080\nHOST=127.0.0.1\n')!

parse_env_file(path string) !map[string]string

Parses a .env file and returns its key/value pairs without mutating the process environment.

values := cfgman.parse_env_file('.env')!
println(values['DATABASE_URL'])

load_env_file(path string, overrides bool) !map[string]string

Loads a .env file into the process environment.

• When overrides is false, existing process environment values are preserved.
• When overrides is true, file values replace existing environment variables.

loaded := cfgman.load_env_file('.env', false)!
println(loaded)

CfgParams

@[params]
pub struct CfgParams {
pub:
	env_overrides bool = true
	env_prefix string = 'CFGMAN'
	env_load_file bool
	env_file_path string = '.env'
	cfg_load_file bool = true
	cfg_file_path string = 'config.json'
}

Fields

env_overrides

If true, environment variables override values loaded from JSON.

env_prefix

Prefix used to map environment variables to struct fields.

Default:

CFGMAN

A field named port becomes:

CFGMAN_PORT

env_load_file

If true, load_env_file() is called before environment overrides are applied.

env_file_path

Path to the .env file.

Default:

.env

cfg_load_file

If true, the JSON config file is loaded.

cfg_file_path

Path to the JSON config file.

Default:

config.json

Environment Variable Mapping

Field names are mapped using:

<PREFIX>_<FIELD_NAME_UPPERCASE>

Example:

struct AppConfig {
pub:
	port int
	addr string
}

With prefix MYAPP, the loader reads:

MYAPP_PORT
MYAPP_ADDR

Field Attributes

Struct fields can declare cfgman attributes to control how cfgman treats environment overrides.

Supported forms:

@[cfgman: 'json']
@[cfgman: 'env']
@[cfgman: 'env:CUSTOM_NAME']
@[cfgman: 'both']
@[cfgman: '-']

You attach these attributes directly to struct fields.

@[cfgman: 'json']

Loads the field from JSON only.

struct Config {
pub:
	port int
	api_key string @[cfgman: 'json']
}

With this setup:

• port can still be overridden from env
• api_key is loaded only from JSON

Example:

{
  "port": 8080,
  "api_key": "from_json"
}

CFGMAN_PORT=9000
CFGMAN_API_KEY=from_env

Result:

port = 9000
api_key = from_json

@[cfgman: 'env']

Loads the field from environment only.

JSON values for that field are ignored, and the field remains at its zero value if no matching env variable exists.

struct Config {
pub:
	port int
	token string @[cfgman: 'env']
}

Example JSON:

{
  "port": 8080,
  "token": "ignored-json"
}

If CFGMAN_TOKEN is not set:

token = ''

If CFGMAN_TOKEN=from_env:

token = from_env

@[cfgman: 'env:CUSTOM_NAME']

Overrides the environment variable name for a field.

struct Config {
pub:
	port int @[cfgman: 'env:CUSTOM_PORT']
	addr string
}

This field now reads CUSTOM_PORT instead of CFGMAN_PORT or <PREFIX>_PORT.

Example:

CUSTOM_PORT=7000

@[cfgman: 'both']

Marks the field as using the default behavior explicitly.

struct Config {
pub:
	port int @[cfgman: 'both']
}

This is equivalent to not setting the attribute.

@[cfgman: '-']

Disables both JSON and env handling for the field.

The field is left unchanged at its default value unless you set it manually after loading.

struct Config {
pub:
	computed string @[cfgman: '-']
}

Combined usage

The cfgman attribute value is comma-separated, so you can combine source selection and a custom env name.

struct Config {
pub:
	port int @[cfgman: 'both,env:APP_HTTP_PORT']
	secret string @[cfgman: 'json']
	computed string @[cfgman: '-']
}

Attribute Example

module main

import cfgman

struct Config {
pub:
	port int @[cfgman: 'env:CUSTOM_PORT']
	token string @[cfgman: 'json']
	secret string @[cfgman: 'env']
	computed string @[cfgman: '-']
	host string
}

fn main() {
	cfg := cfgman.load[Config](
		cfg_file_path: 'config.json'
		env_prefix: 'APP'
	) or {
		panic(err)
	}

	println(cfg.port)
	println(cfg.token)
	println(cfg.host)
}

If:

{
  "port": 8080,
  "token": "json-token",
  "secret": "ignored-json-secret",
  "computed": "ignored-json-value",
  "host": "127.0.0.1"
}

And the environment contains:

CUSTOM_PORT=5050
APP_TOKEN=env-token
APP_SECRET=env-secret
APP_HOST=0.0.0.0

Then the result is:

port = 5050
token = json-token
secret = env-secret
computed = ''
host = 0.0.0.0

Nested Structs

Nested structs extend the prefix recursively.

struct DatabaseConfig {
pub:
	host string
	port int
}

struct AppConfig {
pub:
	debug bool
	database DatabaseConfig
}

With env_prefix: 'MYAPP', the supported variables are:

MYAPP_DEBUG
MYAPP_DATABASE_HOST
MYAPP_DATABASE_PORT

Example:

module main

import cfgman

struct DatabaseConfig {
pub:
	host string
	port int
}

struct AppConfig {
pub:
	debug bool
	database DatabaseConfig
}

fn main() {
	cfg := cfgman.load[AppConfig](
		cfg_file_path: 'config.json'
		env_prefix: 'MYAPP'
	) or {
		panic(err)
	}

	println(cfg.debug)
	println(cfg.database.host)
	println(cfg.database.port)
}

Type Conversion Rules

Environment variable values are assigned using JSON decoding for non-string fields.

That means these work naturally:

MYAPP_PORT=8080
MYAPP_DEBUG=true
MYAPP_RATIO=1.25

For string fields, the raw environment value is used directly.

Example:

struct AppConfig {
pub:
	port int
	debug bool
	name string
}

MYAPP_PORT=3000
MYAPP_DEBUG=true
MYAPP_NAME=demo

Full Example

config.json

{
  "port": 8080,
  "addr": "127.0.0.1",
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

.env

export MYAPP_PORT=9000
MYAPP_DATABASE_HOST=db.internal

V code

module main

import cfgman

struct DatabaseConfig {
pub:
	host string
	port int
}

struct AppConfig {
pub:
	port int
	addr string
	database DatabaseConfig
}

fn main() {
	cfg := cfgman.load[AppConfig](
		cfg_file_path: 'config.json'
		env_load_file: true
		env_file_path: '.env'
		env_prefix: 'MYAPP'
	) or {
		panic(err)
	}

	println(cfg)
}

Result

• port becomes 9000 from .env
• addr stays 127.0.0.1 from JSON
• database.host becomes db.internal from .env
• database.port stays 5432 from JSON

Working With .env Files

The parser supports a practical subset of python-dotenv-style syntax.

Basic assignments

PORT=8080
HOST=127.0.0.1
DEBUG=true

Comments

# full-line comment
PORT=8080 # inline comment

export

export APP_NAME=myapp

Double-quoted values

PASSWORD="pa#ss word"
MESSAGE="hello\nworld"

Single-quoted values

TOKEN='raw value'

Empty values

EMPTY=

Variable expansion

APP_NAME=cfgman
URL=https://example.com/${APP_NAME}

Expansion can resolve from:

• variables parsed earlier in the same .env content
• variables already present in the process environment

Example:

module main

import cfgman
import os

fn main() {
	os.setenv('DOMAIN', 'example.com', true)
	values := cfgman.env_values('APP=demo\nURL=https://\${DOMAIN}/\${APP}\n') or {
		panic(err)
	}
	println(values['URL'])
}

Output:

https://example.com/demo

Parsing .env Without Loading It

Use parse_env_file() when you want to inspect values without mutating the environment:

module main

import cfgman

fn main() {
	values := cfgman.parse_env_file('.env') or {
		panic(err)
	}

	for k, v in values {
		println('${k}=${v}')
	}
}

Loading .env Into The Process Environment

Use load_env_file() when you want a .env file to populate os.getenv() values:

module main

import cfgman
import os

fn main() {
	cfgman.load_env_file('.env', false) or {
		panic(err)
	}

	println(os.getenv('DATABASE_URL'))
}

Error Cases

The env parser returns an error for malformed lines such as:

• missing =
• invalid key names
• unterminated quoted values

Current Limitations

These points reflect the current implementation.

• JSON loading depends on x.json2.decode
• Environment overrides are applied to struct fields only
• Default field names map from V field names to uppercase env names
• .env expansion supports ${VAR} syntax, not $VAR
• Recursive or circular expansion is not specially handled
• Single-quoted values are treated as literal text
• Double-quoted values support basic escape sequences only: \n, \r, \t