appenv

README

appenv

Application options manager for golang

What's this?

In developing applications in golang, we want to manage many options for it. And they often are in a file, envars or the keyring.

It is too heavy and bores developers to manage them. So appenv generates codes to do it.

• Load/save function
• Configuration accessor (get, set or unset them with application)

Usage

Read documents: pkg.go.dev

WHY?

Why appenv does NOT provide any generator:

Even if it is done, there's not much diference in usage.

i.e. You may create the generation shell script (or Makefile or ...).

appenv-gen \
  -package github.com/kyoh86/appenv/env \
  -outdir ../ \
  -opt github.com/kyoh86/appenv/env.Token -store keyring -store envar

I think that we can read and maintin go code easier than shell script.

Install

$ go get github.com/kyoh86/appenv

LICENSE

This is distributed under the MIT License.

Documentation

Overview

Package appenv build option handlers to manage application options.

Usage index

Using this library, follow each step below.

1. Define options.

2. Create a generator.

3. Call that generator (`go run <main>`).

Then you can access or configure options with generated function (GetAccessor, GetConfig or GetAppenv). Each step is explained below.

Define options

You can define options with just creating structs that implement `appenv/types.Value` that have `Value()`, `Default()`, `MarshalText` and `UnmarshalText`.

If you want to define a primitive (like `string`) option, you can embed `types.XXXValue` like below.

Sample:

type Token struct {
	types.StringValue
}

Create a generator

`appenv` does NOT provide any tools like `xxx-generate`. Creating a generator, calling it, you can get the handlers. To generate, you may call `appenv.Generate` function with options.

Options are built by `appenv.Opt` from `Value`s that you defined in above. `appenv.Opt` receives `store` options that specify where the option will be stored to or loaded from. Now `appenv` supports stores: YAML file, keyring or environment variables.

Each option can store to / be loaded from multiple `store`.

Generation code should be tagged like `// +build generate`. The tag may prevent the generator from being unintendedly built. You can write the go:generate directive to call it from `go generate`.

//+build generate

//go:generate go run -tags generate .

func main() {
	appenv.Generate(...)
}

See: https://pkg.go.dev/github.com/kyoh86/appenv#example-Generate

Access options with generated function

See: Example (GetAccess)

Configure options with generated function

See: Example (GetConfig)

Example (GetAccess)

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/kyoh86/appenv/internal/out"
)

func main() {
	var (
		yamlFile    = strings.NewReader(`{token: xxxxx}`)
		envarPrefix = "APPENV_EXAMPLE_ACCESS_"
	)

	os.Setenv(envarPrefix+"HOST_NAME", "kyoh86.dev")

	// Get options from file and envar.
	// out.GetAccess is generated function.
	access, err := out.GetAccess(yamlFile, envarPrefix)
	if err != nil {
		panic(err)
	}

	fmt.Println(access.Token())
	fmt.Println(access.HostName())
}

Output:

xxxxx
kyoh86.dev

Example (GetConfig)

package main

import (
	"os"
	"strings"

	"github.com/kyoh86/appenv/internal/out"
)

func main() {
	var (
		yamlFile = strings.NewReader(`{token: xxxxx}`)
	)

	// Load current option from file and build handler.
	// out.GetConfig is generated function.
	config, err := out.GetConfig(yamlFile)
	if err != nil {
		panic(err)
	}

	// Change option
	if err := config.HostName().Set("example.com"); err != nil {
		panic(err)
	}

	// Save to file (put to std-out for example
	if err := config.Save(os.Stdout); err != nil {
		panic(err)
	}
}

Output:

token: xxxxx
hostName: example.com

Index

• func Generate(packagePath, outDir string, options ...*option) error
• func Opt(value types.Value, s store, stores ...store) (d *option)
• func StoreEnvar() store
• func StoreKeyring() store
• func StoreYAML() store
• type Generator
  • func (g *Generator) Do(packagePath, outDir string, options ...*option) error

Examples

• Package (GetAccess)
• Package (GetConfig)
• Generate
• Opt

Functions

func Generate

func Generate(packagePath, outDir string, options ...*option) error

Generate a configuration handlers from options.

Name, type and default value of options must be defined like: https://pkg.go.dev/github.com/kyoh86/appenv/internal/def

Example

package main

import (
	"github.com/kyoh86/appenv"
	"github.com/kyoh86/appenv/internal/def"
)

const (
	outputPackagePath = "github.com/kyoh86/appenv/internal/out"
	outputDir         = "./internal/out"
)

func main() {
	if err := appenv.Generate(
		outputPackagePath,
		outputDir,
		// Use "Token" option in the YAML file
		appenv.Opt(new(def.Token), appenv.StoreYAML()),
		// Use "hostName" option in the YAML file and HOST_NAME environment variable
		appenv.Opt(new(def.HostName), appenv.StoreYAML(), appenv.StoreEnvar()),
		// Use "DRY_RUN" option in the environment variable
		appenv.Opt(new(def.DryRun), appenv.StoreEnvar()),
	); err != nil {
		panic(err)
	}
}

func Opt

func Opt(value types.Value, s store, stores ...store) (d *option)

Opt describes an option with a defined value and the stores (StoreYAML, StoreEnvar() or StoreKeyring()).

Example

package main

import (
	"github.com/kyoh86/appenv"
	"github.com/kyoh86/appenv/types"
)

type HostName struct {
	types.StringValue
}

func main() {
	_ = appenv.Generate(
		"",
		"",
		// Pass "hostName" option in the YAML file and HOST_NAME environment variable to generator.
		appenv.Opt(new(HostName), appenv.StoreYAML(), appenv.StoreEnvar()),
	)
}

func StoreEnvar

func StoreEnvar() store

StoreEnvar will load option value from a environment variables.

func StoreKeyring

func StoreKeyring() store

StoreKeyring will store option value into the keyring services.

func StoreYAML

func StoreYAML() store

StoreYAML will store option value into the YAML file.

Types

type Generator

type Generator struct {
	PackageName string
	BuildTag    string
	// contains filtered or unexported fields
}

Generator will generate a configuration handlers from options with custom package name and custom build tag.

func (*Generator) Do

func (g *Generator) Do(packagePath, outDir string, options ...*option) error