aconf

README

aconf

HOCON format reading/parsing library written in golang

Motivation

Storing configuration information in human friendly format is a requirement common across projects of all sizes.
The HOCON format, made popular by the Akka project, provides a specification which describes a configuration file format for precisely this purpose.
There are many popular config file formats/API's in the world of golang - most popular being TOML, YAML, INI, etc. While these formats are popular, I believe none provide the flexibility provided by the HOCON format.
The aconf library has been designed with the aim of attempting to allow Golang developers make full use of the HOCON configuration format using an extremely simple API.

Getting the library

go get -u github.com/en-vee/aconf

Features

• Similar to the encoding/json library, one can Unmarshal/Decode a HOCON file into a go struct
• Specify config properties as Units such as duration and size.
• Specify config properties as Arrays of primitives or arrays of objects

API Usage

• Define the HOCON Configuration file. All property keys will need to start with a capital letter

A {
    B = 10
    T = 25 seconds
    C = [1, 2, 3, 4]
}

• Create a HOCON parser by providing an io.Reader to read the file

reader, err := os.Open("/path/to/configFilename.conf")
parser := &aconf.HoconParser{}

• Declare a go struct to match the configuration file format. Note that all the members of the go struct need to be exported/capitalized and the field names within the struct should exactly match the field names in the HOCON config file.
• Struct Tags are also supported with the key being hocon. An example is shown below. The tag key must be hocon

type ConfigFile struct {
    A struct {
        B int `hocon:"b"`
        T time.Duration
        C []int
    }
}

• Call the Parse method to decode the Configuration file contents into the pointer to the struct

var appConfig = &ConfigFile{}
if err := parser.Parse(reader, appConfig); err != nil {
			fmt.Printf("Error %v", err)
}

• If the Parse method returns without errors, the appConfig pointer in the example above will be populated with the values from the config file. For example, appConfig.B = 10 or appConfig.T = 25s
• Be sure to have a look at the parser_test.go file for various examples of Config file formats

Documentation

Index

• Constants
• type ErrLexerInvalidDuration
  • func (e *ErrLexerInvalidDuration) Error() string
• type ErrLexerInvalidSize
  • func (e *ErrLexerInvalidSize) Error() string
• type ErrLexerInvalidToken
  • func (e *ErrLexerInvalidToken) Error() string
• type ErrLexerNotInitialized
  • func (l *ErrLexerNotInitialized) Error() string
• type ErrReaderNil
  • func (e *ErrReaderNil) Error() string
• type HoconLexer
  • func NewLexer(reader io.Reader) (*HoconLexer, error)
  • func (lexer *HoconLexer) Run() ([]HoconToken, error)
• type HoconParser
  • func (parser *HoconParser) FieldByName(fieldName string, v reflect.Value) reflect.Value
  • func (parser *HoconParser) Parse(hoconContentReader io.Reader, v interface{}) error
• type HoconToken
• type HoconTokenType
• type LexInvalidTokenErr
  • func (e *LexInvalidTokenErr) Error() string
• type LexLocation
• type LexScannerErr
  • func (e *LexScannerErr) Error() string
• type ParserInvalidArrayErr
  • func (err *ParserInvalidArrayErr) Error() string
• type ParserInvalidInputFieldErr
  • func (err *ParserInvalidInputFieldErr) Error() string
• type ParserInvalidRuneErr
  • func (err *ParserInvalidRuneErr) Error() string
• type ParserInvalidTargetErr
  • func (err *ParserInvalidTargetErr) Error() string
• type ParserInvalidTokenTypeErr
  • func (err *ParserInvalidTokenTypeErr) Error() string
• type ParserUnbalancedParenthesesErr
  • func (err *ParserUnbalancedParenthesesErr) Error() string

Constants

const HASH = 0x23

const HoconWS = 0x20

const NL = 0x0A

Types

type ErrLexerInvalidDuration

type ErrLexerInvalidDuration struct {
	// contains filtered or unexported fields
}

func (*ErrLexerInvalidDuration) Error

func (e *ErrLexerInvalidDuration) Error() string

type ErrLexerInvalidSize

type ErrLexerInvalidSize struct {
	// contains filtered or unexported fields
}

func (*ErrLexerInvalidSize) Error

func (e *ErrLexerInvalidSize) Error() string

type ErrLexerInvalidToken

type ErrLexerInvalidToken struct {
	TokenText string
	LexLocation
}

func (*ErrLexerInvalidToken) Error

func (e *ErrLexerInvalidToken) Error() string

type ErrLexerNotInitialized

type ErrLexerNotInitialized struct{}

func (*ErrLexerNotInitialized) Error

func (l *ErrLexerNotInitialized) Error() string

type ErrReaderNil

type ErrReaderNil struct{}

func (*ErrReaderNil) Error

func (e *ErrReaderNil) Error() string

type HoconLexer

type HoconLexer struct {
	// contains filtered or unexported fields
}

func NewLexer

func NewLexer(reader io.Reader) (*HoconLexer, error)

NewLexer instantiates a new HoconLexer using the provided io.Reader Returns an error in case of

func (*HoconLexer) Run

func (lexer *HoconLexer) Run() ([]HoconToken, error)

Run returns a list of acceptable tokens for the parser to perform syntactical checking. It is upto the parser to perform concatenation of strings, checking for sequence of tokens, ensuring no dangling tokens are present etc.

Keys are anything to the left of an = or :

Values are unquoted strings and quoted strings to the right of an = or :

A Key/Path expression must always start on a new line

Trailing spaces in Values should be trimmed, unless they are in a quoted string.

type HoconParser

type HoconParser struct {
	// contains filtered or unexported fields
}

func (*HoconParser) FieldByName

func (parser *HoconParser) FieldByName(fieldName string, v reflect.Value) reflect.Value

func (*HoconParser) Parse

func (parser *HoconParser) Parse(hoconContentReader io.Reader, v interface{}) error

type HoconToken

type HoconToken struct {
	Type  HoconTokenType
	Value string
	LexLocation
}

type HoconTokenType

type HoconTokenType uint8

const (
	Integer HoconTokenType = iota
	Float
	Boolean
	Identifier
	Duration
	Size
	Key
	Text
	LeftBrace
	RightBrace
	LeftBracket
	RightBracket
	LeftParen
	RightParen
	Equals
	Colon
	Comma
	NewLine
	Other
)

type LexInvalidTokenErr

type LexInvalidTokenErr struct {
	LexLocation
	// contains filtered or unexported fields
}

func (*LexInvalidTokenErr) Error

func (e *LexInvalidTokenErr) Error() string

type LexLocation

type LexLocation struct {
	// contains filtered or unexported fields
}

type LexScannerErr

type LexScannerErr struct {
	LexLocation
	// contains filtered or unexported fields
}

func (*LexScannerErr) Error

func (e *LexScannerErr) Error() string

type ParserInvalidArrayErr

type ParserInvalidArrayErr struct {
	LexLocation
	// contains filtered or unexported fields
}

func (*ParserInvalidArrayErr) Error

func (err *ParserInvalidArrayErr) Error() string

type ParserInvalidInputFieldErr

type ParserInvalidInputFieldErr struct {
	// contains filtered or unexported fields
}

func (*ParserInvalidInputFieldErr) Error

func (err *ParserInvalidInputFieldErr) Error() string

type ParserInvalidRuneErr

type ParserInvalidRuneErr struct {
}

func (*ParserInvalidRuneErr) Error

func (err *ParserInvalidRuneErr) Error() string

type ParserInvalidTargetErr

type ParserInvalidTargetErr struct {
	// contains filtered or unexported fields
}

func (*ParserInvalidTargetErr) Error

func (err *ParserInvalidTargetErr) Error() string

type ParserInvalidTokenTypeErr

type ParserInvalidTokenTypeErr struct {
	// contains filtered or unexported fields
}

func (*ParserInvalidTokenTypeErr) Error

func (err *ParserInvalidTokenTypeErr) Error() string

type ParserUnbalancedParenthesesErr

type ParserUnbalancedParenthesesErr struct {
	LexLocation
}

func (*ParserUnbalancedParenthesesErr) Error

func (err *ParserUnbalancedParenthesesErr) Error() string