config

Documentation

Overview

Package config is an automatic configuration loader for cairo-dock.

Config will fills the data of a struct from an INI config file with reflection. Groups and keys in the file can be matched with the data struct by name or by a special "conf" tag.

GetKey  : Only parse using the field name. Names and keys need to be UpperCase.
GetTag  ; Only parse using the "conf" tag of the field.
GetBoth : Parse using both methods (tag is used when defined, name as fallback).

Parsing errors are stored in the Errors field.

Example for a single group

Load the data from the file and UnmarshalGroup a group.

conf, e := config.NewFromFile(filepath) // Special conf reflector around the config file parser.
if e != nil {
	return e
}
data := &groupConfiguration{}
conf.UnmarshalGroup(data, groupName, config.GetKey)

Example with multiple groups

To load data from many groups splitted in according strucs, like applets config, you have to define the main struct with a "group" tag that match the group in the config file.

data := &appletConf{}
e := config.Load(filepath, data, config.GetBoth)

Structs data for the examples

This is an example of applet data with the common Icon group (Name, Debug, and optional Icon).

type appletConf struct {
	cdtype.ConfGroupIconBoth `group:"Icon"`
	groupConfiguration       `group:"Configuration"`
}

type groupConfiguration struct {
	DisplayText   int
	DisplayValues int

	GaugeName string

	IconBroken  string
	VolumeStep  int
	StreamIcons bool
}

Index

• Constants
• func GetBoth(struc reflect.StructField) string
• func GetFromFile(log cdtype.Logger, filename string, call func(cdtype.ConfUpdater)) error
• func GetKey(struc reflect.StructField) string
• func GetTag(struc reflect.StructField) string
• func Load(log cdtype.Logger, filename, confdir, appdir string, v interface{}, ...) (cdtype.Defaults, []func(cdtype.AppAction), []error, error)
• func SetFileVersion(log cdtype.Logger, filename, group, oldver, newver string) error
• func SetToFile(log cdtype.Logger, filename string, call func(cdtype.ConfUpdater) error) error
• func UpdateFile(log cdtype.Logger, filename, group, key string, value interface{}) error
• type Config
  • func NewEmpty(log cdtype.Logger, configFile string) *Config
  • func NewFromFile(log cdtype.Logger, configFile string) (*Config, error)
  • func NewFromReader(reader io.Reader) (*Config, error)
  • func (c *Config) Cancel()
  • func (c *Config) GetComment(group, key string) (string, error)
  • func (c *Config) MarshalGroup(v interface{}, group string, fieldKey cdtype.GetFieldKey) error
  • func (c *Config) ParseGroups(call func(group string, keys []cdtype.ConfKeyer))
  • func (c *Config) Save() error
  • func (c *Config) Set(group, key string, uncast interface{}) error
  • func (c *Config) SetComment(group, key, comment string) error
  • func (c *Config) SetNewVersion(group, oldver, newver string) error
  • func (c *Config) UnmarshalGroup(v interface{}, group string, fieldKey cdtype.GetFieldKey) []error
  • func (c *Config) Unmarshall(v interface{}, fieldKey cdtype.GetFieldKey) cdtype.Defaults
  • func (c *Config) Valuer(group, key string) valuer.Valuer
• type KeyBase
  • func ParseKeyComment(keyComment string) (*KeyBase, byte)

Constants

const (
	ParseFlagCairoOnly  = '*'
	ParseFlagOpenGLOnly = '&'
)

Modifier to show a widget according to the display backend.

Functions

func GetBoth

func GetBoth(struc reflect.StructField) string

GetBoth is a cdtype.GetFieldKey test that matches by the struct tag if

defined, otherwise use the field name.

func GetFromFile

func GetFromFile(log cdtype.Logger, filename string, call func(cdtype.ConfUpdater)) error

GetFromFile gets a conf updater in read only.

func GetKey

func GetKey(struc reflect.StructField) string

GetKey is a cdtype.GetFieldKey test that matches by the field name.

func GetTag

func GetTag(struc reflect.StructField) string

GetTag is a cdtype.GetFieldKey test that matches by the struct tag if defined.

func Load

func Load(log cdtype.Logger, filename, confdir, appdir string, v interface{}, fieldKey cdtype.GetFieldKey) (cdtype.Defaults, []func(cdtype.AppAction), []error, error)

Load loads a config file and fills a config data struct.

Returns parsed defaults data, the list of parsing errors, and the main error if the load failed (file missing / not readable).

log        Logger.
filename   Full path to the config file.
appdir     Application directory, to find templates.
v          The pointer to the data struct.
fieldKey   Func to choose what key to load for each field.
           Usable methods provided: GetKey, GetTag, GetBoth.

func SetFileVersion

func SetFileVersion(log cdtype.Logger, filename, group, oldver, newver string) error

SetFileVersion replaces the version in a config file. The given group must represent the first group of the file.

func SetToFile

func SetToFile(log cdtype.Logger, filename string, call func(cdtype.ConfUpdater) error) error

SetToFile gets a conf updater in read/write mode.

func UpdateFile

func UpdateFile(log cdtype.Logger, filename, group, key string, value interface{}) error

UpdateFile udates one key in a configuration file.

Types

type Config

type Config struct {
	*ini.File // Extends the real config.

	Errors []error
	// contains filtered or unexported fields
}

Config file unmarshall. Parsing errors will be stacked in the Errors field.

func NewEmpty

func NewEmpty(log cdtype.Logger, configFile string) *Config

NewEmpty creates a new empty Config parser. Also locks files access.

func NewFromFile

func NewFromFile(log cdtype.Logger, configFile string) (*Config, error)

NewFromFile creates a ConfUpdater for the given config file (full path). This lock files access. Ensure you Save or Cancel fast.

func NewFromReader

func NewFromReader(reader io.Reader) (*Config, error)

NewFromReader creates a new Config parser with reflection to fill fields.

func (*Config) Cancel

func (c *Config) Cancel()

Cancel releases the file locks.

func (*Config) GetComment

func (c *Config) GetComment(group, key string) (string, error)

GetComment gets the comment for the key.

func (*Config) MarshalGroup

func (c *Config) MarshalGroup(v interface{}, group string, fieldKey cdtype.GetFieldKey) error

MarshalGroup fills the config with data from the struct provided.

The group param must match a group in the file with the format [MYGROUP]

func (*Config) ParseGroups

func (c *Config) ParseGroups(call func(group string, keys []cdtype.ConfKeyer))

ParseGroups calls the given func for every group with its list of keys.

func (*Config) Save

func (c *Config) Save() error

Save saves the edited config to disk, and releases the file locks.

func (*Config) Set

func (c *Config) Set(group, key string, uncast interface{}) error

Set sets a config value.

func (*Config) SetComment

func (c *Config) SetComment(group, key, comment string) error

SetComment sets the comment for the key.

func (*Config) SetNewVersion

func (c *Config) SetNewVersion(group, oldver, newver string) error

SetNewVersion replaces the version in a config file. The given group must represent the first group of the file.

func (*Config) UnmarshalGroup

func (c *Config) UnmarshalGroup(v interface{}, group string, fieldKey cdtype.GetFieldKey) []error

UnmarshalGroup parse a config group to fill the ptr to struct provided.

The group param must match a group in the file with the format [MYGROUP]

func (*Config) Unmarshall

func (c *Config) Unmarshall(v interface{}, fieldKey cdtype.GetFieldKey) cdtype.Defaults

Unmarshall fills a struct of struct with data from config. The First level is config group, matched by the key group. Second level is data fields, matched by the supplied GetFieldKey func.

func (*Config) Valuer

func (c *Config) Valuer(group, key string) valuer.Valuer

Valuer returns the valuer for the given group/key combo.

type KeyBase

type KeyBase struct {
	NbElements        int                  // number of values stored in the key.
	AuthorizedValues  []string             //
	Text              string               // label for the key.
	Tooltip           string               // mouse over tooltip text.
	IsAlignedVertical bool                 // orientation for the key widget box.
	DisplayMode       cdglobal.DisplayMode // Dock display backend: all, cairo or opengl.
}

KeyBase defines a configuration entry options parsed from comment.

func ParseKeyComment

func ParseKeyComment(keyComment string) (*KeyBase, byte)

ParseKeyComment parse comments for a key.