gosimpleconf/Readme.md

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