# Configuration Library

## Theory of Operation

The core philosophy of this library is to standardize configuration handling with sensible, consistent defaults.

There are two types of configuration files:

1.  A simple environment-style `KEY=VALUE` file (defined by `config.proto` in this package).
2.  An application-specific Protobuf file (e.g., `<appname>.proto`).

---

### 1. Basic Application Configuration

This configuration uses a simple, environment-style file for basic settings. The file is loaded from the following locations, in order of precedence (later files override earlier ones):

1.  `/usr/share/doc/<appname>/config.text`
2.  `/etc/default/<appname>`
3.  `~/.config/<appname>/config.text`

**Note:** These files **must** only contain `KEY=VALUE` pairs.

---

### 2. Application-Specific Protobuf Configuration

This is for the application's main data structure, defined in its own `.proto` file. By default, these files are always located in a standard location.

For an application named `forge` using a `forge.proto` definition, the default file path is:

-   `~/.config/forge/forge.text`

The default paths and filenames can be overridden by setting the appropriate values in the basic application config file (see #1 above).

---

## Code Example & Notes

The `autogenpb` tool provides powerful automation. If you follow its conventions, the configuration and cache management functions work seamlessly.

For a `.proto` file containing the message `Repos`, the function `GetProtobufName(pb)` will return `"repos"`.

Consequently, the standard functions `ConfigLoad()`, `ConfigSave()`, `CacheLoad()`, and `CacheSave()` will automatically handle the correct files without any extra code:

-   **Config:** `~/.config/<appname>/repos.pb`
-   **Cache:** `~/.cache/<appname>/repos.pb`

```protobuf
// message Repos {
//         string                      uuid                     = 1;
//         string                      version                  = 2;
//         repeated Repo               repos                    = 3;
```