config
Looks for a configuration file in various formats and reads it into a configuration object.
Uses
prantlf.ini
Synopsis
Declare a structure for the configuration and read its contents from the first file found with any supported file extension:
import prantlf.config { find_config_file, read_config }
struct Config { ... }
config := if config_file := find_config_file_any('.', '.newchanges', 10, true) {
read_config[Config](config_file)!
} else {
&Config{}
}
Specify usage description and version of the command-line tool. Declare a structure with all command-line options. Import the command-line parser and parse the options and arguments:
import prantlf.cargs { Input, parse_to }
import prantlf.config { find_config_file, read_config }
const usage = '...'
struct Opts { ... }
mut opts := if config_file := find_config_file('.', [
'.newchanges.ini',
'.newchanges.properties',
'.newchanges.json',
'.newchanges.yml',
'.newchanges.yaml',
], 10, true) {
read_config[Opts](config_file)!
} else {
&Opts{}
}
cmds := parse_to(usage, Input{ version: version }, mut opts)!
Installation
You can install this package either from
VPM
v install prantlf.config
v install --git https://github.com/prantlf/v-config
API
The following functions are exported:
find_config_file(start_dir string, names []string, depth int, user bool) ?string
Searches for files or directories with the specified names. The search starts in the directory
start_dir
depth
start_dir
user
Files and directories will be matched with the specified names in the order of the names in the array. The first one matching will cause the method return the absolute path to the found file. If no file or directory with the specified names can be found,
none
config_file := find_config_file('.', [
'.newchanges.ini',
'.newchanges.properties',
'.newchanges.json',
'.newchanges.yml',
'.newchanges.yaml',
], 10, true)
find_config_file_any(start_dir string, name string, depth int, user bool) ?string
Simplifies calls to the previous function if you accept all of the configuration files extensions.
config_file := find_config_file_any('.', '.newchanges', 10, true)
find_user_config_file(names []string) ?string
Searches for files or directories with the specified names in the home directory of the current user.
Files and directories will be matched with the specified names in the order of the names in the array. The first one matching will cause the method return the absolute path to the found file. If no file or directory with the specified names can be found,
none
config_file := find_user_config_file([
'.newchanges.ini',
'.newchanges.properties',
'.newchanges.json',
'.newchanges.yml',
'.newchanges.yaml',
])
find_user_config_file_any(name string) ?string
Simplifies calls to the previous function if you accept all of the configuration files extensions.
config_file := find_user_config_file_any('.newchanges')
read_config[T](file string) !T
Reads the file and deserialises its contents from the format assumed by the file extension to a new object.
Extension | Format |
---|---|
.ini |
INI |
.properties |
INI |
.json |
JSON
|
.yml |
YAML |
.yaml |
YAML |
opts := read_config[Opts]('~/.newchanges.json')!
read_config_to[T](file string, mut cfg T) !
Reads the file and deserialises its contents from the format assumed by the file extension to an existing object.
Extension | Format |
---|---|
.ini |
INI |
.properties |
INI |
.json |
JSON
|
.yml |
YAML |
.yaml |
YAML |
mut opts := Opts{}
opts := read_config_to('~/.newchanges.json', mut opts)!
Errors
If parsing the configuration file fails because of an invalid syntax, a more descriptive message can be printed than the default, single-line one.
import prantlf.config { read_config, error_msg_full }
struct Config { ... }
if config := read_config[Config]('.newchanges.ini') {
...
} else {
eprintln(error_msg_full(err))
}
For example, parsing the following contents:
answer=42
question
will return the following short message by
err.msg()
unexpected end encountered when parsing a property name on line 2, column 9
and the following long and colourful message by
error_msg_full()
unexpected end encountered when parsing a property name:
1 | answer=42
2 | question
| ^
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.
License
Copyright (c) 2023 Ferdinand Prantl
Licensed under the MIT license.