conf

README

🌳 Go YAML/JSON Configuration

Coding simple !go function to grab current !k8s context

This conf Bonzai branch is for safely managing any configuration as single, local YAML/JSON using industry standards for local configuration and system-safe writes. Use it to add a conf subcommand to any other Bonzai command, or to your root Bonzai tree (z). All commands that use conf that are composed into a single binary, no matter where in the tree, will use the same local conf file even though the position within the file will be qualified by the tree location.

By default, importing conf will assigned a new implementation of bonzai.Configurer to Z.Conf (satisfying any Z.Cmd requirement for configuration) and will use the name of the binary (Z.ExeName) as the directory name within os.UserConfDir with a config.yaml file name. To override this behavior, create a new pkd/conf.Conf struct assign Id, Dir and File, and then assign that to Z.Conf.

Install

This command can be installed as a standalone program (for combined use with shell scripts perhaps) or composed into a Bonzai command tree.

Standalone

go install github.com/rwxrob/conf/cmd/conf@latest

Composed

package z

import (
	Z "github.com/rwxrob/bonzai/z"
	"github.com/rwxrob/conf"
)

var Cmd = &bonzai.Cmd{
	Name:     `z`,
	Commands: []*Z.Cmd{help.Cmd, conf.Cmd},
}

Note conf is designed to be composed only in monolith mode (not multicall binary).

Tab Completion

To activate bash completion just use the complete -C option from your .bashrc or command line. There is no messy sourcing required. All the completion is done by the program itself.

complete -C conf conf

If you don't have bash or tab completion check use the shortcut commands instead.

Embedded Documentation

All documentation (like manual pages) has been embedded into the source code of the application. See the source or run the program with help to access it.

Documentation

Overview

Package conf helps generically manage configuration data in YAML files (and, by extension JSON, which is a YAML subset) using the gopkg.in/yaml.v3 package (v2 is not compatible with encoding/json creating unexpected marshaling errors).

The package provides the high-level functions called by the Bonzai™ branch command of the same name allowing it to be consistently composed into any to any other Bonzai branch. However, composing into the root is generally preferred to avoid configuration name space conflicts and centralize all configuration data for a single Bonzai tree monolith for easy transport.

Rather than provide functions for changing individual values, this package assumes editing of the YAML files directly and provider helpers for system-wide safe concurrent writes and queries using the convention yq/jq syntax. Default directory and file permissions are purposefully more restrictive than the Go default (0700/0600).

Index

• Variables
• type C
  • func (c C) Data() (string, error)
  • func (c C) DirPath() string
  • func (c C) Edit() error
  • func (c C) Exists() bool
  • func (c C) Init() error
  • func (c C) OverWrite(newconf any) error
  • func (c C) Path() string
  • func (c C) Print() error
  • func (c C) Query(q string) (string, error)
  • func (c C) QueryPrint(q string) error
  • func (c C) SoftInit() error

Examples

• C.OverWrite

Variables

var Cmd = &Z.Cmd{

	Name:      `conf`,
	Summary:   `manage conf in {{execonfdir "config.yaml"}}`,
	Version:   `v0.8.2`,
	Copyright: `Copyright 2021 Robert S Muhlestein`,
	License:   `Apache-2.0`,
	Commands:  []*Z.Cmd{help.Cmd, dataCmd, initCmd, editCmd, fileCmd, queryCmd},
	Description: `
		The **{{.Name}}** Bonzai branch is for safely managing any
		configuration as single, local YAML/JSON using industry standards
		for local configuration and persistence to a file using system-wide
		semaphores for safety. Use it to add a **{{.Name}}** subcommand to
		any other Bonzai command, or to your root Bonzai tree. Either way,
		the same single configuration file is used, only the path within the
		configuration data is affected by the position of the **{{.Name}}**
		command.

		Querying configuration data can be easily accomplished with the
		**query** command that uses the same selection syntax as the **yq**
		Go utility (the same **yqlib** is used).

		All changes to configuration values are done via the **edit** command
		since configurations may be complex and deeply nested in some cases
		and promoting the automatic changing of configuration values opens
		the possibility that one buggy composed command might overwrite one
		or all the configurations for everything everything else composed
		into the binary.

		CAUTION: Take particular note that all commands composed into
		a single binary, no matter where in the tree, will use the same
		local config file even though the position within the file will be
		qualified by the tree location. Therefore, any composite command can
		read the configurations of any other composite command within the
		same binary. This is by design, but all commands composed together
		should always be vetted for safe practices.

		[The **vars** Bonzai branch is recommended when wanting to persist
		performant local data between command executions.]`,
}

Types

type C

type C struct {
	Id   string // usually application name
	Dir  string // usually os.UserConfigDir
	File string // usually config.yaml
}

func (C) Data

func (c C) Data() (string, error)

Data returns a string buffer containing all of the configuration file data for the given configuration. An empty string is returned and an error logged if any error occurs.

func (C) DirPath

func (c C) DirPath() string

DirPath is the Dir and Id joined.

func (C) Edit

func (c C) Edit() error

Edit opens the given configuration the local editor. See fs/file.Edit for more.

func (C) Exists

func (c C) Exists() bool

Exists returns true if a configuration file exists at Path.

func (C) Init

func (c C) Init() error

Init initializes the configuration directory (Dir) for the current user and given application name (Id) using the standard os.UserConfigDir location. The directory is completely removed and new configuration file(s) are created.

Consider placing a confirmation prompt before calling this function when term.IsInteractive is true. Since Init uses fs/{dir,file}.Create you can set the file.DefaultPerms and dir.DefaultPerms if you prefer a different default for your permissions.

Permissions in the fs package are restrictive (0700/0600) by default to allow tokens to be stored within configuration files (as other applications are known to do). Still, saving of critical secrets is not encouraged within any flat configuration file. But anything that a web browser would need to cache in order to operate is appropriate (cookies, session tokens, etc.).

func (C) OverWrite

func (c C) OverWrite(newconf any) error

OverWrite marshals any Go type and overwrites the configuration File in a way that is safe for all callers of OverWrite in this current system for any operating system using go-internal/lockedfile (taken from the to internal project itself, https://github.com/golang/go/issues/33974) but applying the file.DefaultPerms instead of the 0666 Go default.

Example

package main

import (
	"fmt"
	"os"

	"github.com/rwxrob/conf"
	"github.com/rwxrob/fs/dir"
)

func main() {

	c := conf.C{Id: `foo`, Dir: `testdata`, File: `config.yaml`}

	thing := struct {
		Some  string
		Other string
	}{"some", "other"}

	if err := c.OverWrite(thing); err != nil {
		fmt.Println(err)
	}

	dir.Create(`testdata/foo`)
	defer os.RemoveAll(`testdata/foo`)

	if err := c.OverWrite(thing); err != nil {
		fmt.Println(err)
	}
	c.Print()

}

Output:

some: some
other: other

func (C) Path

func (c C) Path() string

Path returns the combined Dir and File.

func (C) Print

func (c C) Print() error

Print prints the Data to standard output with an additional line return.

func (C) Query

func (c C) Query(q string) (string, error)

Query returns a YAML string matching the given yq query for the given configuration and strips any initial or trailing white space (usually just the single new line at then added by yq). Currently, this function is implemented by calling rwxrob/yq.

func (C) QueryPrint

func (c C) QueryPrint(q string) error

QueryPrint prints the output of Query.

func (C) SoftInit

func (c C) SoftInit() error

SoftInit calls Init if not Exists.