115 lines
3.6 KiB
Markdown
115 lines
3.6 KiB
Markdown
# gosimpleconf
|
|
|
|
```sh
|
|
go get git.wisellama.rocks/Wisellama/gosimpleconf@v0.1.0
|
|
```
|
|
|
|
This is a small library for parsing super simple configuration files
|
|
similar to Unix conf files.
|
|
|
|
It expects a file with the following format:
|
|
* Lines with key-values pairs separated by `=` (e.g. `foo = bar`)
|
|
* Lines that start with `#` are ignored (used for comments)
|
|
* Empty and whitespace-only lines are ignored
|
|
* Lines with some data but no `=` will cause an error.
|
|
* Lines with multiple `=` are split on the literal first `=` seen, any remaining are part of the value.
|
|
|
|
The key-values pairs are simply parsed as strings and plopped into a
|
|
map for you to do whatever your program wants with them. If you need a
|
|
value to not be a string, you will have to convert the value from a
|
|
string as needed for your program (e.g. using the `strconv` library).
|
|
|
|
## Example
|
|
|
|
Here's an example config file `file.conf`
|
|
```conf
|
|
url = www.wisellama.rocks
|
|
number_of_widgets = 1337
|
|
pi = 3.141592653589793238462643383
|
|
environment = production
|
|
|
|
# Quotes are optional
|
|
name = Dude guy
|
|
description = "Just some dude it was"
|
|
|
|
# Additional equals are just part of the value
|
|
base64_tacos = dGFjb3M=
|
|
a=b=c
|
|
# key: 'a', value: 'b=c'
|
|
```
|
|
|
|
Then to load that config file into a map:
|
|
|
|
```go
|
|
configMap, err := gosimpleconf.Configure("file.conf")
|
|
```
|
|
|
|
Then everything is a string. You can parse it as needed.
|
|
```go
|
|
var piStr string = configMap["pi"]
|
|
pi, err := strconv.ParseFloat(value, 64)
|
|
```
|
|
|
|
### Command-Line Flag Overrides
|
|
|
|
By default, the `Configure()` function will figure out which keys
|
|
exist in the config map and set those as cli flags that you can
|
|
override. For example, with the config file above, you could override
|
|
the `url` key with a cli flag:
|
|
```sh
|
|
./program --url=newthing.wisellama.rocks
|
|
```
|
|
|
|
If you don't want to support cli flag overrides, you can directly call
|
|
`ReadFile("file.conf")` instead.
|
|
|
|
If you want to support other cli flags that don't map to a config
|
|
setting, they must be set up before calling `Configure()`. This is
|
|
because the `ParseFlags()` function calls `flag.Parse()` to get all
|
|
the values for the config map overrides. You could also work around
|
|
this by calling `ReadFile` and `ParseFlags` yourself and add your
|
|
other logic in between the two calls.
|
|
|
|
### Default Config
|
|
|
|
You can specify a default configuration to return if the given config
|
|
file doesn't exist. Here's an example:
|
|
|
|
```go
|
|
defaultConfig := gosimpleconf.ConfigMap{
|
|
"game.title": "Some Game",
|
|
"log.writeToFile": "false",
|
|
}
|
|
configMap, err := gosimpleconf.ConfigureWithDefaults("file_that_doesnt_exist.conf", defaultConfig)
|
|
```
|
|
|
|
Then if the config file can't be found, the default config map values
|
|
will be used instead. You can still override the default values with
|
|
cli flags.
|
|
|
|
## Why?
|
|
|
|
I've always seen configuration files similar to this show up in
|
|
Unix-like systems and programs, but it doesn't seem to be fully
|
|
standardized under a real name other than just "conf files". The
|
|
closest I've seen are INI files, but those don't seem to fit the style
|
|
I was looking for (they don't use `#` for comments and they support
|
|
sections in square brackets `[section]`).
|
|
|
|
Instead, I just wanted the bare minimum configuration format of `foo =
|
|
bar` on each line with `#` for comments. So that's what this library
|
|
does.
|
|
|
|
## This project looks abandoned
|
|
|
|
This library is so simple that I almost never expect to need to update
|
|
it unless Go fundamentally breaks the language in the future. So while
|
|
the project may eventually look like it has been abandoned, it is
|
|
rather simply "complete". (*gasp* I know, such a rare thing in the
|
|
software world).
|
|
|
|
## License
|
|
|
|
This project is licensed under the 2-Clause BSD License (a permissive
|
|
open source license). See `License.md` for the full text.
|