conf

README

Conf

Conf provides easy and powerfull methods to access configurations stored in hjson, json, env files. You pass root configurations directory to the package and it will parse all config files recursively. Provide your own Evaluators and make a dynamic config files by calling your applications functions.

Features

• Recursively access config files stored in directories with a dot
• Get entire config objects as map[string]interface{}
• Built in methods for accessing string int float64 int64 []string []int []float []interface map[string]interface{}
• Use HJSON or JSON syntax for configuration files
• Use .env file to override environment variables
• USE .env.test file to override environment variables in test mode
• Use env("environment variable name", "default value") in configuration files to access environment varaiables in config files
• Provide your own Evaluators to access custom app variables while parsing configurations

Documentation

Dependencies

• godotenv
• hjson-go

Installation

go get github.com/peyman-abdi/conf

Usage

Basic usage

import "peyman-abdi/conf"
...

config, err := conf.New("/path/to/configs/dir", "/path/to/envs/dir", nil)
if err != nil {
    fmt.Println(err)
}

config.GetString("filename.object.innerobject.value", "default")
config.GetString("dir.another_dir.filename.object.array[3].value", "default")
...

Access Environment Variables in config files

use env() function in json/hjson files to access environment variables

// app.hjson
{
    server: {
        port: env(PORT, 8080),
        host: env(HOST, "localhost"),
    },
    database: {
        table: env(TABLE),
        password: env(PASSWORD),
        username: env(USERNAME, "root"),
    },
    debug: true,
    logger: {
        other: "vairables",
    }
}

// .env
HOST=github.com
PASSWORD=secret

// main.go
config.GetInt("app.server.port", 0) 				// returns 8080
config.GetString("app.server.host", "domain.com") 	// returns "github.com"
config.GetString("app.database.table", "my_table") 	// returns "my_table"
config.GetString("app.database.password", "") 		// returns "secret"
config.GetString("app.database.username", "user") 	// returns "root"

Custom Evaluators

Use custom evaluators to build your own functions to be used inside json/hjson files.

// my_evals.go
type MyJoinEvaluatorFunction struct {
}
var _ conf.EvaluatorFunction = (*MyJoinEvaluatorFunction)(nil)

func (_ *MyJoinEvaluatorFunction) GetFunctionName() string {
   return "myJoinFunction" // the function name used in hjson/json files
}
func (_ *MyJoinEvaluatorFunction) Eval(params []string, def interface{}) interface{} {
    if len(params) > 0 {
        return strings.Join(params, "::")
    }
    return def
}


// my.hjson
{
    joined: myJoinFunction(1,2,3,4,5)
}

// main.go
config, err := conf.New("/path/to/configs/dir", "/path/to/envs/dir", []conf.EvaluatorFunction {
   new(MyJoinEvaluatorFunction),
})

config.GetString("my.joined", "") // returns "1::2::3::4::5"

you can use this functionallity and add more power to your config files, like:

• relative pathes
• time functions
• os dependant evaluations
• ...

Documentation

Overview

Package conf provides all functionality required for parsing and accessing configuration files. You can use a hjson/json/env files as configurations and access them recursively with dots

Index

• type Config
  • func New(configDir string, envDir string, evalFunctions []EvaluatorFunction) (config *Config, err error)
  • func (c *Config) Get(key string, def interface{}) interface{}
  • func (c *Config) GetAsString(key string, def string) string
  • func (c *Config) GetBoolean(key string, def bool) bool
  • func (c *Config) GetFloat(key string, def float64) float64
  • func (c *Config) GetFloatArray(key string, def []float64) []float64
  • func (c *Config) GetInt(key string, def int) int
  • func (c *Config) GetInt64(key string, def int64) int64
  • func (c *Config) GetIntArray(key string, def []int) []int
  • func (c *Config) GetMap(key string, def map[string]interface{}) map[string]interface{}
  • func (c *Config) GetString(key string, def string) string
  • func (c *Config) GetStringArray(key string, def []string) []string
  • func (c *Config) GetUInt64(key string, def uint64) uint64
  • func (c *Config) IsSet(key string) bool
• type EvaluatorFunction

Types

type Config

type Config struct {
	ConfigsMap            map[string]interface{}
	EvaluatorFunctionsMap map[string]EvaluatorFunction
}

Config object for accessing configurations as a map all files are parsed at Creation time and recursively added to the ConfigsMap. Its much better and easier to use Getter functions of the struct. But when accessing full config objects are needed they are available with GetMap function or throw the ConfigsMap object

func New

func New(configDir string, envDir string, evalFunctions []EvaluatorFunction) (config *Config, err error)

New creates a new config parser with config files at path configDir. Argument envDir can be an empty string which will cause the function to ignore .env parsing Config files with extensions .hjson and .json will be opened at this point and all files will be parsed resulting in a fast access time If there are any Evaluation needed those will be applied when accessing variables All folders inside configDir will recursively scanned for .hjson and .json files and any config will be accessible by its relative path connected with dots An error may happen during reading files like access denied if the error causes

func (*Config) Get

func (c *Config) Get(key string, def interface{}) interface{}

Get returns the raw interface{} value of a key You have to convert it to your desired type If you have used a custom EvaluatorFunction to generate the value simply cast the interface{} to your desired type

func (*Config) GetAsString

func (c *Config) GetAsString(key string, def string) string

GetAsString converts the value of the key to string and returns it, if the key does not exist returns the def value

func (*Config) GetBoolean

func (c *Config) GetBoolean(key string, def bool) bool

GetBoolean checks if the value of the key can be converted to boolean or not if not or if the key does not exist returns the def value valid values are true,false,1,0

func (*Config) GetFloat

func (c *Config) GetFloat(key string, def float64) float64

GetFloat checks if the value of the key can be converted to float64 or not if not or if the key does not exist returns the def value

func (*Config) GetFloatArray

func (c *Config) GetFloatArray(key string, def []float64) []float64

GetFloatArray checks if the value of the key can be converted to []float64 or not if not or if the key does not exist returns the def value

func (*Config) GetInt

func (c *Config) GetInt(key string, def int) int

GetInt checks if the value of the key can be converted to int or not if not or if the key does not exist returns the def value

func (*Config) GetInt64

func (c *Config) GetInt64(key string, def int64) int64

GetInt64 checks if the value of the key can be converted to int64 or not if not or if the key does not exist returns the def value

func (*Config) GetIntArray

func (c *Config) GetIntArray(key string, def []int) []int

GetIntArray checks if the value of the key can be converted to []int or not if not or if the key does not exist returns the def value

func (*Config) GetMap

func (c *Config) GetMap(key string, def map[string]interface{}) map[string]interface{}

GetMap returns the raw config object as map of strings

func (*Config) GetString

func (c *Config) GetString(key string, def string) string

GetString checks if the value of the key can be converted to string or not if not or if the key does not exist returns the def value

func (*Config) GetStringArray

func (c *Config) GetStringArray(key string, def []string) []string

GetStringArray checks if the value of the key can be converted to []string or not if not or if the key does not exist returns the def value

func (*Config) GetUInt64

func (c *Config) GetUInt64(key string, def uint64) uint64

GetInt64 checks if the value of the key can be converted to int64 or not if not or if the key does not exist returns the def value

func (*Config) IsSet

func (c *Config) IsSet(key string) bool

IsSet returns true if there is value for key, false otherwise

type EvaluatorFunction

type EvaluatorFunction interface {
	// Evaluate the input arguments and return the value
	// if an error happened just return the def value
	Eval(params []string, def interface{}) interface{}

	// Get the name of the function
	// Returned value of this function is the string
	// that is used inside config files to call this evaluator
	GetFunctionName() string
}

EvaluatorFunction lets you create dynamic config values they act like functions inside your hjson/json files each function when called inside config files can have any number of arguments and they are passed to the Eval function.