configurator

README

ZKits Configurator Library

About

This package is a library of ZKits project. The configurator supports loading config targets from anywhere through built-in or custom loaders.

Install

go get -u -v github.com/edoger/zkits-configurator

Usage

package main

import (
	"github.com/edoger/zkits-configurator"
)

func main() {
	// Create a new configurator.
	c := configurator.New()

	// Add config files.
	// The parameter format must be the format required by filepath.Glob().
	c.AddFile("/path/to/*.json")
	c.AddFile("/path/to/*.yaml")
	c.AddFile("/path/to/*.toml")
	c.AddFile("/path/to/*.xml")

	// Load config file by name.
	// Usually, the file ext name can be omitted, and the configurator is intelligent enough.
	item, err := c.Load("file.name")
	if err != nil {
		panic(err)
	}

	item.IsEmpty() // Is empty file?
	item.Len()     // File content length.
	item.Bytes()   // Get file content as []byte.
	item.String()  // Get file content as string.
	item.Reader()  // Get file content as io.Reader.

	// Variable used to bind config content.
	object := make(map[string]interface{})

	// Bind config content to object as json/xml/toml/yaml format.
	item.JSON(&object)
	item.XML(&object)
	item.TOML(&object)
	item.YAML(&object)
	// These methods can also be used!
	c.LoadJSON("file.name", &object)
	c.LoadXML("file.name", &object)
	c.LoadTOML("file.name", &object)
	c.LoadYAML("file.name", &object)

	// Register a custom configuration loader (which takes precedence over the built-in file loader).
	c.Use(configurator.LoaderFunc(func(target string) (configurator.Item, error) {
		// Do something!
		return nil, nil
	}))
	// We provide a built-in configuration file loader.
	loader := configurator.NewFileLoader()
	loader.MustAddFile("/path/to/other/*.json")
	// You can register more loaders, they just need to implement the configurator.Loader interface.
	c.Use(loader)
}

License

Apache-2.0

Documentation

Index

• Variables
• type Configurator
  • func New() Configurator
• type FileItem
  • func NewFileItem(s string) (FileItem, error)
• type FileLoader
  • func NewFileLoader() FileLoader
• type Item
  • func NewItemFromBytes(data []byte) Item
  • func NewItemFromReader(r io.Reader) (Item, error)
  • func NewItemFromString(s string) Item
• type Loader
• type LoaderFunc
  • func (f LoaderFunc) Load(target string) (Item, error)

Variables

var (
	// ErrEmptyItem reports that the config item content is empty.
	// This error is returned when trying to bind an empty configuration item to any object.
	ErrEmptyItem = errors.New("configurator: empty item")

	// ErrNotFound indicates that the configuration target was not found.
	// When a configuration target cannot be loaded in all loaders, this error will be returned.
	ErrNotFound = errors.New("configurator: not found")
)

Types

type Configurator

type Configurator interface {
	// Use registers a custom configuration loader.
	// The last registered configuration loader will have the highest priority.
	Use(Loader) Configurator

	// AddFile adds one or more config files to the current loader.
	// The given parameter need to comply with the search rules supported
	// by filepath.Glob.
	// This method comes from the built-in configuration file loader.
	AddFile(string) error

	// Load loads the given config target.
	// If the given config target does not exist, ErrNotFound is returned.
	// We will give priority to the custom loader. If there is no available config loader
	// or all registered config loaders cannot load the config target (the semantic target
	// does not exist), it will be automatically delegated to the built-in config file loader.
	Load(string) (Item, error)

	// LoadJSON loads the given config target and binds it to the given object as json.
	LoadJSON(string, interface{}) error

	// LoadXML loads the given config target and binds it to the given object as xml.
	LoadXML(string, interface{}) error

	// LoadTOML loads the given config target and binds it to the given object as toml.
	LoadTOML(string, interface{}) error

	// LoadYAML loads the given config target and binds it to the given object as yaml.
	LoadYAML(string, interface{}) error
}

Configurator defines the configuration manager.

func New

func New() Configurator

New creates and returns a new Configurator instance.

type FileItem

type FileItem interface {
	Item

	// Path returns the config file absolute path.
	Path() string

	// Base returns the config file base name.
	Base() string

	// Name returns the config file name (without extension name).
	Name() string
}

FileItem interface defines the config file item.

func NewFileItem

func NewFileItem(s string) (FileItem, error)

NewFileItem returns the config file item created from the given file path. An error is returned only if a failure occurs to read the contents of the given config file.

type FileLoader

type FileLoader interface {
	Loader

	// AddFile adds one or more config files to the current loader.
	// The given parameter need to comply with the search rules supported
	// by filepath.Glob.
	AddFile(string) error

	// MustAddFile adds one or more config files to the current loader.
	// This method is very similar to AddFile, the only difference is that it panics
	// when the add fails.
	MustAddFile(pattern string) FileLoader
}

FileLoader interface defines the config file loader.

func NewFileLoader

func NewFileLoader() FileLoader

NewFileLoader creates and returns a config file loader instance.

type Item

type Item interface {
	// IsEmpty determines whether the current config item content is empty.
	IsEmpty() bool

	// Len returns the current config item content length.
	Len() int

	// Bytes returns the current config item content bytes.
	Bytes() []byte

	// Bytes returns the current config item content string.
	String() string

	// Bytes returns the current config item content reader.
	Reader() io.Reader

	// JSON binds the current config item to the given object as json format.
	// If the current configuration item is empty, ErrEmptyItem will be returned.
	JSON(interface{}) error

	// XML binds the current config item to the given object as xml format.
	// If the current configuration item is empty, ErrEmptyItem will be returned.
	XML(interface{}) error

	// TOML binds the current config item to the given object as toml format.
	// If the current configuration item is empty, ErrEmptyItem will be returned.
	TOML(interface{}) error

	// YAML binds the current config item to the given object as yaml format.
	// If the current configuration item is empty, ErrEmptyItem will be returned.
	YAML(interface{}) error
}

Item interface defines the config item.

func NewItemFromBytes

func NewItemFromBytes(data []byte) Item

NewItemFromBytes creates and returns a config item from the given bytes.

func NewItemFromReader

func NewItemFromReader(r io.Reader) (Item, error)

NewItemFromReader creates and returns a config item from the given reader.

func NewItemFromString

func NewItemFromString(s string) Item

NewItemFromString creates and returns a config item from the given string.

type Loader

type Loader interface {
	// Load loads the given config target.
	// If this method returns a non-nil error, the entire configuration search and
	// loading process will be terminated immediately. If the returned Item is nil,
	// the next loader in the queue will be automatically run.
	Load(string) (Item, error)
}

Loader interface defines the config target loader.

type LoaderFunc

type LoaderFunc func(string) (Item, error)

LoaderFunc type defines the config target function loader.

func (LoaderFunc) Load

func (f LoaderFunc) Load(target string) (Item, error)

Load loads the given config target.