Looks for a configuration file in various formats and reads it into a configuration object.

Uses prantlf.ini, prantlf.json and prantlf.yaml. Can be combined with prantlf.cargs to override selected options from the command-line.

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)!

You can install this package either from VPM or from GitHub:

v install prantlf.config
v install --git https://github.com/prantlf/v-config

The following functions are exported:

Searches for files or directories with the specified names. The search starts in the directory start_dir and continues to a parent directory as many times as is the number depth. The dept 0 means searching only the directory start_dir. If the flg user is true, it will look to the home directory of the current user too.

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 will be returned.

config_file := find_config_file('.', [
  '.newchanges.ini',
  '.newchanges.properties',
  '.newchanges.json',
  '.newchanges.yml',
  '.newchanges.yaml',
], 10, true)

Simplifies calls to the previous function if you accept all of the configuration files extensions.

config_file := find_config_file_any('.', '.newchanges', 10, true)

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 will be returned.

config_file := find_user_config_file([
  '.newchanges.ini',
  '.newchanges.properties',
  '.newchanges.json',
  '.newchanges.yml',
  '.newchanges.yaml',
])

Simplifies calls to the previous function if you accept all of the configuration files extensions.

config_file := find_user_config_file_any('.newchanges')

Reads the file and deserialises its contents from the format assumed by the file extension to a new object.

opts := read_config[Opts]('~/.newchanges.json')!

Reads the file and deserialises its contents from the format assumed by the file extension to an existing object.

mut opts := Opts{}
opts := read_config_to('~/.newchanges.json', mut opts)!

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
   |         ^

In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.

Copyright (c) 2023-2024 Ferdinand Prantl

Licensed under the MIT license.