Skip to content

Latest commit

 

History

History
142 lines (103 loc) · 4.32 KB

README.md

File metadata and controls

142 lines (103 loc) · 4.32 KB
Raw

ozzo-config

GoDoc Build Status Coverage Status Go Report

Other languages

Description

ozzo-config is a Go package for handling configurations in Go applications. It supports

  • reading JSON (with comments), YAML, and TOML configuration files
  • merging multiple configurations
  • accessing any part of the configuration
  • configuring an object using a part of the configuration
  • adding new configuration file formats

Requirements

Go 1.2 or above.

Installation

Run the following command to install the package:

go get github.com/go-ozzo/ozzo-config

Getting Started

The following code snippet shows how you can use this package.

package main

import (
    "fmt"
    "github.com/go-ozzo/ozzo-config"
)

func main() {
    // create a Config object
    c := config.New()

    // load configuration from a JSON string
    c.LoadJSON([]byte(`{
        "Version": "2.0",
        "Author": {
            "Name": "Foo",
            "Email": "bar@example.com"
        }
    }`))

    // get the "Version" value, return "1.0" if it doesn't exist in the config
    version := c.GetString("Version", "1.0")

    var author struct {
        Name, Email string
    }
    // populate the author object from the "Author" configuration
    c.Configure(&author, "Author")

    fmt.Println(version)
    fmt.Println(author.Name)
    fmt.Println(author.Email)
    // Output:
    // 2.0
    // Foo
    // bar@example.com
}

Loading Configuration

You can load configuration in three ways:

c := config.New()

// load from one or multiple JSON, YAML, or TOML files.
// file formats are determined by their extensions: .json, .yaml, .yml, .toml
c.Load("app.json", "app.dev.json")

// load from one or multiple JSON strings
c.LoadJSON([]byte(`{"Name": "abc"}`), []byte(`{"Age": 30}`))

// load from one or multiple variables
data1 := struct {
    Name string
} { "abc" }
data2 := struct {
    Age int
} { 30 }
c.SetData(data1, data2)

When loading from multiple sources, the configuration will be obtained by merging them one after another recursively.

Accessing Configuration

You can access any part of the configuration using one of the Get methods, such as Get(), GetString(), GetInt(). These methods require a path parameter which is in the format of X.Y.Z and references the configuration value located at config["X"]["Y"]["Z"]. If a path does not correspond to a configuration value, a zero value or an explicitly specified default value will be returned by the method. For example,

// Retrieves "Author.Email". The default value "bar@example.com"
// should be returned if "Author.Email" is not found in the configuration.
email := c.GetString("Author.Email", "bar@example.com")

Changing Configuration

You can change any part of the configuration using the Set method. For example, the following code changes the configuration value config["Author"]["Email"]:

c.Set("Author.Email", "bar@example.com")

Configuring Objects

You can use a configuration to configure the properties of an object. For example, the configuration corresponding to the JSON structure {"Name": "Foo", "Email": "bar@example.com"} can be used to configure the Name and Email fields of a struct.

When configuring a nil interface, you have to specify the concrete type in the configuration via a type element in the configuration map. The type should also be registered first by calling Register() so that it knows how to create a concrete instance.

New Configuration File Formats

ozzo-config supports three configuration file formats out-of-box: JSON (can contain comments), YAML, and TOML. To support reading new file formats, you should modify the config.UnmarshalFuncMap variable by mapping a new file extension to the corresponding unmarshal function.