conf

README

conf

(yes I am that creative with names)

I have been using ini for managing configuration files in go for quite some time. One of the things that had bothered me though, was that it really was a pain to set up for small projects, as it's just boilerplate code over and over. So I decided to write my own configuration file system, and now I'm here.

Quick start

package main

import (
	"github.com/thehowl/conf"
)

type myConf struct {
	Port     string `description:"The port from which the application will take HTTP requests"`
	Password string
	MaxUsers int
}

func main() {
	c := myConf{}
	err := conf.Load(&c, "myapp.conf")
	if err == conf.ErrNoFile {
		// You can export your conf to a file, so you can write default values.
		conf.Export(myConf{
			Port:     ":8080",
			Password: "hunter2",
			MaxUsers: 9001,
		}, "myapp.conf")
		fmt.Println("Please compile the configuration file (myapp.conf.)")
		return
	}
	if err != nil {
		panic(err)
	}
	// You can now use the values in `c` without thinking about the actual configuration ever again!
	fmt.Printf("%#v\n", c)
}

Configuration file format

; This is an example configuration file generated with `conf`. Comments are done using semicolons.
;
; This is a simple string value in the configuration:
String=Hello world!

; Note that there are no spaces between the field (key) name and its value. Conf does not trim strings.
; int, float, uint values are done just as easily. You just need to write that they're of that type in
; the struct, and conf will do all the magic!
Int=481

; There are also bools.
Bool=1
; Bools are retrieved through [ParseBool](https://golang.org/pkg/strconv/#ParseBool), as such they
; need to be one of 1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False.

; But, what about strings with newlines?
AreTheyPossible=Yes\
They\
Are!
; If you need to export a flag with a multiline string, conf will automatically escape it.
;
; By the way, conf automatically ignores lines without a valid field=value combination, including
; empty lines, so you can use them as comments, although discouraged.
So yes, this line will be silently ignored!
=This one, too!
And this one, too!=

; Escaping can not only be done with newlines. Here's what you can possibly escape!
Fields\=With\=Equal\=Signs=can be escaped!
Comments=Can \; be escaped!
Oh yeah, fields=can also have spaces and what not in them.; You can also write comments straight after a value!

; And that's all you need to know for using `conf`!

License

MIT

Documentation

Overview

Package conf lets you manage configuration files in the easiest way possible, without the unnecessary pain.

Example

package main

import (
	"fmt"

	"github.com/thehowl/conf"
)

type myConf struct {
	Name string
	Age  int
}

const myConfString = `Name=Jack
Age=19`

func main() {
	c := myConf{}
	conf.LoadRaw(&c, []byte(myConfString))
	fmt.Printf("%#v\n", c)
}

Index

• Variables
• func Escape(s string) string
• func Export(from interface{}, filename string) error
• func ExportRaw(from interface{}) ([]byte, error)
• func Load(into interface{}, filename string) error
• func LoadRaw(into interface{}, data []byte) error
• func MustExport(from interface{}, filename string)
• func MustExportRaw(from interface{}) []byte
• func MustLoad(into interface{}, filename string)
• func MustLoadRaw(into interface{}, data []byte)
• type FieldValue
  • func Parse(data []byte) []FieldValue

Examples

• Package

Variables

var (
	ErrNoFile     = errors.New("conf: the configuration file doesn't exist")
	ErrNotAStruct = errors.New("conf: the passed into/from variable is not a pointer to a struct")
)

The only custom errors this package will return.

Functions

func Escape

func Escape(s string) string

Escape escapes characters for then putting it into conf field/values without issues.

func Export

func Export(from interface{}, filename string) error

Export uses ExportRaw to put the data into a file, specified with its name.

func ExportRaw

func ExportRaw(from interface{}) ([]byte, error)

ExportRaw can create a []byte that can then be loaded back by LoadRaw to get a struct's original form back. I suck at explaining stuff.

func Load

func Load(into interface{}, filename string) error

Load unmarshals a file into the struct passed as the argument "into".

func LoadRaw

func LoadRaw(into interface{}, data []byte) error

LoadRaw allows you to load into a struct some raw data bytes.

func MustExport

func MustExport(from interface{}, filename string)

MustExport panics if Export returns an error, removing error checking from your code. For the lazy.

func MustExportRaw

func MustExportRaw(from interface{}) []byte

MustExportRaw panics if ExportRaw returns an error, removing error checking from your code. For the lazy.

func MustLoad

func MustLoad(into interface{}, filename string)

MustLoad has the same behaviour as Load, but panics if it returns an error.

func MustLoadRaw

func MustLoadRaw(into interface{}, data []byte)

MustLoadRaw has the same behaviour as LoadRaw, but panics if it returns an error.

Types

type FieldValue

type FieldValue struct {
	Field string
	Value string
}

FieldValue is a field=value pair in the configuration.

func Parse

func Parse(data []byte) []FieldValue

Parse converts some bytes into various FieldValue pairs.