config

README

Config

A Go package for creating and using JSON configuration files.

Package config provides methods to read, write and update configurations.

The intended use case is in programs that make calls to API's that accept POST requests with JSON payloads.

The package is designed to be simple and easy to use. It is not intended to be a general-purpose configuration library with robust type checking and validation and support for multiple formats.

On the other hand, JSON is widely used and the approach taken in the design of config can cope with nested JSON objects to an arbitrary depth.

Install

$> go get github.com/Michael-F-Ellis/config

Usage:

import github.com/Michael-F-Ellis/config
// Creating a Config
cfg := Config{
		/* initialize with desired values */
		"foo": "bar",
		"baz": 42.,
		"boo": true,
		"qux": []any{"quux", "corge"},
		"g_rault": map[string]any{
			"garply": "waldo",
			"fred":   42.42,
		}
	}
// Serializing
err := cfg.Write("some/path/myconfig.json")

// Reading
othercfg, err := cfg.Read("some/other/path/otherconfig.json")

// Updating (in memory)
cfg.Update(othercfg) // replaces or adds key:value pairs

// Check for key existence
has := cfg.HasKey("baz") // true

// Check nested key existence
has = cfg.HasKeyNested("grault", "fred") // true

// Get the value of a nested key
v, ok := cfg.Get("g_rault", "garply") // waldo, true

// Validate and use a shortcut
s := cfg.UniqueMatchOf("GR", '_') // g_rault matches
if s != "" {
	value := cfg[s]["fred"]
}

Documentation

Overview

Package config provides methods to read, write and update configurations. The intended use case is in programs that need to make use of API's that accept POST requests with JSON payloads. The package is designed to be simple and easy to use. It is not intended to be a general-purpose configuration library with robust type checking and validation.

Index

• func ConfigFromString(s string) (map[string]any, error)
• func Get(c map[string]any, keys ...string) (value any, ok bool)
• func HasKey(c map[string]any, key string) bool
• func HasKeyNested(c map[string]any, keys ...string) bool
• func Read(filepath string) (c map[string]any, err error)
• func Set(c map[string]any, value any, keys ...string)
• func Update(source, target map[string]any)
• func Write(cfg map[string]any, filepath string) (err error)
• type Config
  • func (c Config) CompareTypes(refCfg Config, prefix string, mismatches *[]string, notFound *[]string)
  • func (c Config) UniqueKeyMatchOf(k string, ignore []rune) string
• type Translation
  • func (t Translation) Apply(cFrom, cTo map[string]any, sep string) error

Functions

func ConfigFromString

func ConfigFromString(s string) (map[string]any, error)

ConfigFromString returns a config from a string The string should be in the form of a JSON object. Opening and closing braces are optional.

func Get

func Get(c map[string]any, keys ...string) (value any, ok bool)

Get returns the value of a (nested) key in the configuration and a boolean indicating whether the key exists.

func HasKey

func HasKey(c map[string]any, key string) bool

HasKey returns true if the key exists in the configuration.

func HasKeyNested

func HasKeyNested(c map[string]any, keys ...string) bool

HasKeyNested returns true if the nested key exists in the configuration.

func Read

func Read(filepath string) (c map[string]any, err error)

Read reads a configuration from a file. If the read is successful and the file text can be unmarshalled, Read overwrites the target configuration. Otherwise, an error is returned and the target configuration is not affected. Note that the behavior of json.Unmarshal is such that Unmarshal stores one of these in interface values:

bool for JSON booleans, float64 for JSON numbers, string for JSON strings, []any for JSON arrays, map[string]any, for JSON objects, nil for JSON null.

Thus, you can't get an integer back from a JSON number and any code that needs an integer will have to do the conversion itself.

func Set

func Set(c map[string]any, value any, keys ...string)

Set sets the value of a (nested) key in the configuration. If the key does not exist, it is added to the configuration. If the key exists, the value is updated. If the key is nested, the nested map is created if it does not exist.

func Update

func Update(source, target map[string]any)

Update updates a target configuration with the values from another configuration (source). If a key exists only in the source configuration, It is added to target. If a key exists in both configurations, the value from the source configuration is used. Keys that are only present in the target configuration are not affected. Map values are updated recursively.

func Write

func Write(cfg map[string]any, filepath string) (err error)

Write writes a configuration to a file as a JSON string. Write returns and error if the configuration cannot be serialized or if the file cannot be written.

Types

type Config

type Config map[string]any

In this package, a configuration is represented as a map[string]any and serialized to a file in JSON format.

func (Config) CompareTypes

func (c Config) CompareTypes(refCfg Config, prefix string, mismatches *[]string, notFound *[]string)

CompareTypes compares the types of keys in two Config objects. The function compares the types of keys in the Config object with the keys in the reference Config object. The function returns two slices of strings. The first slice contains the keys where the types do not match. The second slice contains the keys that are in the Config object but not in the reference Config object.

func (Config) UniqueKeyMatchOf

func (c Config) UniqueKeyMatchOf(k string, ignore []rune) string

UniqueKeyMatchOf returns the unique key, if any, that matches the given shortcut, k. If there is no match or more than one match, the function returns an empty string. The comparison is case-insensitive and ignores the characters in the ignore slice. Thus, frob would match FROB, fRoB, and frobish. If the ignore slice contains '_', frob would also match _f_ro_b_.

type Translation

type Translation map[string]string

func (Translation) Apply

func (t Translation) Apply(cFrom, cTo map[string]any, sep string) error

Apply() interprets the keys and values of a Translation object as paths to nested values in a Config object. It splits the keys and values by the separator and then sets the values in cTo to the corresponding values in cFrom.