https://github.com/rstudio/gcfgenv

A Go package for combining environment variables with gcfg configuration files.
https://github.com/rstudio/gcfgenv

configuration go

Last synced: 29 days ago
JSON representation

A Go package for combining environment variables with gcfg configuration files.

• Host: GitHub
• URL: https://github.com/rstudio/gcfgenv
• Owner: rstudio
• License: apache-2.0
• Created: 2022-02-01T15:00:10.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2024-07-02T17:20:30.000Z (7 months ago)
• Last Synced: 2024-11-10T21:12:31.067Z (3 months ago)
• Topics: configuration, go
• Language: Go
• Homepage: https://pkg.go.dev/github.com/rstudio/gcfgenv
• Size: 82 KB
• Stars: 1
• Watchers: 8
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# gcfgenv

[![Go Reference](https://pkg.go.dev/badge/github.com/rstudio/gcfgenv.svg)](https://pkg.go.dev/github.com/rstudio/gcfgenv)

`gcfgenv` is a Go package for configuring applications with environment

variables in addition to their existing configuration files.

The precise goal is to provide environment variable overrides for [`gcfg`

configurations](https://gopkg.in/gcfg.v1) without the need to specify anything

manually whatsoever. There is a strong "convention over configuration" ethos.

`gcfgenv` is **not** a general-purpose way to read environment variables into a

struct -- the package only supports to structures and conventions permitted by

`gcfg`, which are comparatively limited.

## Usage

There are only two exported functions:

* `ReadWithEnvInto()`, which wraps `gcfg.ReadInto()`; and

* `ReadFileWithEnvInto()`, which wraps `gcfg.ReadFileInto()`

Configuration fields are converted to environment variables using the follow

rules:

* Section and field names (including those using [the `gcfg` struct

  tag](https://pkg.go.dev/gopkg.in/gcfg.v1#hdr-Data_structure)) are converted to

  uppercase.

* Slice fields use `,` as a separator.

* Slice fields are appended to rather than replaced (as with the original `gcfg`

  package).

* Dashes are converted to underscores.

* Subsection names are left as-is.

For example, the following environment variables (and global prefix `APPNAME_`):

``` shell

APPNAME_SEC_FIELD=geese

APPNAME_SEC_k1_FIELD=cats

APPNAME_SEC_k1_OTHER_FIELD=zebras,elephants

```

are equivalent to the following configuration file:

``` ini

[sec]

field = geese

[sec "k1"]

field = cats

other-field = zebras

other-field = elephants

```

## Limitations

* Slice fields that may legitimately contain `,` in their entries cannot be

  parsed correctly.

* No support for setting `gcfg`'s "default values" subsection. It is not

  possible to determine after the initial configuration file pass whether a

  value was defaulted, so resetting a field's default via environment variable

  could lead to surprising results.

* Modifying subsections with whitespace in the heading (i.e. `[Section "Sub

  Section"]`) requires using environment variables with whitespace, since any

  form of automatic substitution (with e.g. `_` or `-`) would lead to ambiguity.

  However, most shells and other tools do not handle whitespace in environment

  variables well, so we recommend using `snake_case` or `kebab-case` in

  subsection headings instead.

## Versioning

`gcfgenv` follows semantic versioning.

## License

Licensed under the Apache License, Version 2.0. See `LICENSE` for details.