Back to godoc.org
github.com/magiconair/properties

Package properties

v1.8.0
Latest Go to latest

The latest major version is .

Published: May 15, 2018 | License: BSD-2-Clause | Module: github.com/magiconair/properties

Overview

Package properties provides functions for reading and writing ISO-8859-1 and UTF-8 encoded .properties files and has support for recursive property expansion.

Java properties files are ISO-8859-1 encoded and use Unicode literals for characters outside the ISO character set. Unicode literals can be used in UTF-8 encoded properties files but aren't necessary.

To load a single properties file use MustLoadFile():

p := properties.MustLoadFile(filename, properties.UTF8)

To load multiple properties files use MustLoadFiles() which loads the files in the given order and merges the result. Missing properties files can be ignored if the 'ignoreMissing' flag is set to true.

Filenames can contain environment variables which are expanded before loading.

f1 := "/etc/myapp/myapp.conf"
f2 := "/home/${USER}/myapp.conf"
p := MustLoadFiles([]string{f1, f2}, properties.UTF8, true)

All of the different key/value delimiters ' ', ':' and '=' are supported as well as the comment characters '!' and '#' and multi-line values.

! this is a comment
# and so is this

# the following expressions are equal
key value
key=value
key:value
key = value
key : value
key = val\
      ue

Properties stores all comments preceding a key and provides GetComments() and SetComments() methods to retrieve and update them. The convenience functions GetComment() and SetComment() allow access to the last comment. The WriteComment() method writes properties files including the comments and with the keys in the original order. This can be used for sanitizing properties files.

Property expansion is recursive and circular references and malformed expressions are not allowed and cause an error. Expansion of environment variables is supported.

# standard property
key = value

# property expansion: key2 = value
key2 = ${key}

# recursive expansion: key3 = value
key3 = ${key2}

# circular reference (error)
key = ${key}

# malformed expression (error)
key = ${ke

# refers to the users' home dir
home = ${HOME}

# local key takes precedence over env var: u = foo
USER = foo
u = ${USER}

The default property expansion format is ${key} but can be changed by setting different pre- and postfix values on the Properties object.

p := properties.NewProperties()
p.Prefix = "#["
p.Postfix = "]#"

Properties provides convenience functions for getting typed values with default values if the key does not exist or the type conversion failed.

# Returns true if the value is either "1", "on", "yes" or "true"
# Returns false for every other value and the default value if
# the key does not exist.
v = p.GetBool("key", false)

# Returns the value if the key exists and the format conversion
# was successful. Otherwise, the default value is returned.
v = p.GetInt64("key", 999)
v = p.GetUint64("key", 999)
v = p.GetFloat64("key", 123.0)
v = p.GetString("key", "def")
v = p.GetDuration("key", 999)

As an alternative properties may be applied with the standard library's flag implementation at any time.

# Standard configuration
v = flag.Int("key", 999, "help message")
flag.Parse()

# Merge p into the flag set
p.MustFlag(flag.CommandLine)

Properties provides several MustXXX() convenience functions which will terminate the app if an error occurs. The behavior of the failure is configurable and the default is to call log.Fatal(err). To have the MustXXX() functions panic instead of logging the error set a different ErrorHandler before you use the Properties package.

properties.ErrorHandler = properties.PanicHandler

# Will panic instead of logging an error
p := properties.MustLoadFile("config.properties")

You can also provide your own ErrorHandler function. The only requirement is that the error handler function must exit after handling the error.

  properties.ErrorHandler = func(err error) {
	     fmt.Println(err)
      os.Exit(1)
  }

  # Will write to stdout and then exit
  p := properties.MustLoadFile("config.properties")

Properties can also be loaded into a struct via the `Decode` method, e.g.

type S struct {
    A string        `properties:"a,default=foo"`
    D time.Duration `properties:"timeout,default=5s"`
    E time.Time     `properties:"expires,layout=2006-01-02,default=2015-01-01"`
}

See `Decode()` method for the full documentation.

The following documents provide a description of the properties file format.

http://en.wikipedia.org/wiki/.properties

http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load%28java.io.Reader%29

Example

Code:

// Decode some key/value pairs with expressions
p, err := Load([]byte("key=value\nkey2=${key}"), ISO_8859_1)
if err != nil {
	log.Fatal(err)
}

// Get a valid key
if v, ok := p.Get("key"); ok {
	fmt.Println(v)
}

// Get an invalid key
if _, ok := p.Get("does not exist"); !ok {
	fmt.Println("invalid key")
}

// Get a key with a default value
v := p.GetString("does not exist", "some value")
fmt.Println(v)

// Dump the expanded key/value pairs of the Properties
fmt.Println("Expanded key/value pairs")
fmt.Println(p)
value
invalid key
some value
Expanded key/value pairs
key = value
key2 = value

Index

Examples

func LogFatalHandler

func LogFatalHandler(err error)

LogFatalHandler handles the error by logging a fatal error and exiting.

func PanicHandler

func PanicHandler(err error)

PanicHandler handles the error by panicking.

type Encoding

type Encoding uint

Encoding specifies encoding of the input data.

const (

	// UTF8 interprets the input data as UTF-8.
	UTF8 Encoding

	// ISO_8859_1 interprets the input data as ISO-8859-1.
	ISO_8859_1
)

type ErrorHandlerFunc

type ErrorHandlerFunc func(error)

ErrorHandlerFunc defines the type of function which handles failures of the MustXXX() functions. An error handler function must exit the application after handling the error.

var ErrorHandler ErrorHandlerFunc = LogFatalHandler

ErrorHandler is the function which handles failures of the MustXXX() functions. The default is LogFatalHandler.

type Loader

type Loader struct {
	// Encoding determines how the data from files and byte buffers
	// is interpreted. For URLs the Content-Type header is used
	// to determine the encoding of the data.
	Encoding Encoding

	// DisableExpansion configures the property expansion of the
	// returned property object. When set to true, the property values
	// will not be expanded and the Property object will not be checked
	// for invalid expansion expressions.
	DisableExpansion bool

	// IgnoreMissing configures whether missing files or URLs which return
	// 404 are reported as errors. When set to true, missing files and 404
	// status codes are not reported as errors.
	IgnoreMissing bool
}

func (*Loader) LoadAll

func (l *Loader) LoadAll(names []string) (*Properties, error)

LoadAll reads the content of multiple URLs or files in the given order into a Properties struct. If IgnoreMissing is true then a 404 status code or missing file will not be reported as error. Encoding sets the encoding for files. For the URLs see LoadURL for the Content-Type header and the encoding.

func (*Loader) LoadBytes

func (l *Loader) LoadBytes(buf []byte) (*Properties, error)

Load reads a buffer into a Properties struct.

func (*Loader) LoadFile

func (l *Loader) LoadFile(filename string) (*Properties, error)

LoadFile reads a file into a Properties struct. If IgnoreMissing is true then a missing file will not be reported as error.

func (*Loader) LoadURL

func (l *Loader) LoadURL(url string) (*Properties, error)

LoadURL reads the content of the URL into a Properties struct.

The encoding is determined via the Content-Type header which should be set to 'text/plain'. If the 'charset' parameter is missing, 'iso-8859-1' or 'latin1' the encoding is set to ISO-8859-1. If the 'charset' parameter is set to 'utf-8' the encoding is set to UTF-8. A missing content type header is interpreted as 'text/plain; charset=utf-8'.

type LogHandlerFunc

type LogHandlerFunc func(fmt string, args ...interface{})

LogHandlerFunc defines the function prototype for logging errors.

var LogPrintf LogHandlerFunc = log.Printf

LogPrintf defines a log handler which uses log.Printf.

type Properties

type Properties struct {
	// Pre-/Postfix for property expansion.
	Prefix  string
	Postfix string

	// DisableExpansion controls the expansion of properties on Get()
	// and the check for circular references on Set(). When set to
	// true Properties behaves like a simple key/value store and does
	// not check for circular references on Get() or on Set().
	DisableExpansion bool
	// contains filtered or unexported fields
}

A Properties contains the key/value pairs from the properties input. All values are stored in unexpanded form and are expanded at runtime

func Load

func Load(buf []byte, enc Encoding) (*Properties, error)

Load reads a buffer into a Properties struct.

Example (Iso88591)

Code:

buf := []byte("key = ISO-8859-1 value with unicode literal \\u2318 and umlaut \xE4") // 0xE4 == ä
p, _ := Load(buf, ISO_8859_1)
v, ok := p.Get("key")
fmt.Println(ok)
fmt.Println(v)
true
ISO-8859-1 value with unicode literal ⌘ and umlaut ä
Example (Utf8)

Code:

p, _ := Load([]byte("key = UTF-8 value with unicode character ⌘ and umlaut ä"), UTF8)
v, ok := p.Get("key")
fmt.Println(ok)
fmt.Println(v)
true
UTF-8 value with unicode character ⌘ and umlaut ä

func LoadAll

func LoadAll(names []string, enc Encoding, ignoreMissing bool) (*Properties, error)

LoadAll reads the content of multiple URLs or files in the given order into a Properties struct. If 'ignoreMissing' is true then a 404 status code or missing file will not be reported as error. Encoding sets the encoding for files. For the URLs please see LoadURL for the Content-Type header and the encoding.

func LoadFile

func LoadFile(filename string, enc Encoding) (*Properties, error)

LoadFile reads a file into a Properties struct.

func LoadFiles

func LoadFiles(filenames []string, enc Encoding, ignoreMissing bool) (*Properties, error)

LoadFiles reads multiple files in the given order into a Properties struct. If 'ignoreMissing' is true then non-existent files will not be reported as error.

func LoadMap

func LoadMap(m map[string]string) *Properties

LoadMap creates a new Properties struct from a string map.

func LoadString

func LoadString(s string) (*Properties, error)

LoadString reads an UTF8 string into a properties struct.

func LoadURL

func LoadURL(url string) (*Properties, error)

LoadURL reads the content of the URL into a Properties struct. See Loader#LoadURL for details.

func LoadURLs

func LoadURLs(urls []string, ignoreMissing bool) (*Properties, error)

LoadURLs reads the content of multiple URLs in the given order into a Properties struct. If IgnoreMissing is true then a 404 status code will not be reported as error. See Loader#LoadURL for the Content-Type header and the encoding.

func MustLoadAll

func MustLoadAll(names []string, enc Encoding, ignoreMissing bool) *Properties

MustLoadAll reads the content of multiple URLs or files in the given order into a Properties struct. If 'ignoreMissing' is true then a 404 status code or missing file will not be reported as error. Encoding sets the encoding for files. For the URLs please see LoadURL for the Content-Type header and the encoding. It panics on error.

func MustLoadFile

func MustLoadFile(filename string, enc Encoding) *Properties

MustLoadFile reads a file into a Properties struct and panics on error.

func MustLoadFiles

func MustLoadFiles(filenames []string, enc Encoding, ignoreMissing bool) *Properties

MustLoadFiles reads multiple files in the given order into a Properties struct and panics on error. If 'ignoreMissing' is true then non-existent files will not be reported as error.

func MustLoadString

func MustLoadString(s string) *Properties

MustLoadString reads an UTF8 string into a Properties struct and panics on error.

func MustLoadURL

func MustLoadURL(url string) *Properties

MustLoadURL reads the content of a URL into a Properties struct and panics on error.

func MustLoadURLs

func MustLoadURLs(urls []string, ignoreMissing bool) *Properties

MustLoadURLs reads the content of multiple URLs in the given order into a Properties struct and panics on error. If 'ignoreMissing' is true then a 404 status code will not be reported as error.

func NewProperties

func NewProperties() *Properties

NewProperties creates a new Properties struct with the default configuration for "${key}" expressions.

func (*Properties) ClearComments

func (p *Properties) ClearComments()

ClearComments removes the comments for all keys.

func (*Properties) Decode

func (p *Properties) Decode(x interface{}) error

Decode assigns property values to exported fields of a struct.

Decode traverses v recursively and returns an error if a value cannot be converted to the field type or a required value is missing for a field.

The following type dependent decodings are used:

String, boolean, numeric fields have the value of the property key assigned. The property key name is the name of the field. A different key and a default value can be set in the field's tag. Fields without default value are required. If the value cannot be converted to the field type an error is returned.

time.Duration fields have the result of time.ParseDuration() assigned.

time.Time fields have the vaule of time.Parse() assigned. The default layout is time.RFC3339 but can be set in the field's tag.

Arrays and slices of string, boolean, numeric, time.Duration and time.Time fields have the value interpreted as a comma separated list of values. The individual values are trimmed of whitespace and empty values are ignored. A default value can be provided as a semicolon separated list in the field's tag.

Struct fields are decoded recursively using the field name plus "." as prefix. The prefix (without dot) can be overridden in the field's tag. Default values are not supported in the field's tag. Specify them on the fields of the inner struct instead.

Map fields must have a key of type string and are decoded recursively by using the field's name plus ".' as prefix and the next element of the key name as map key. The prefix (without dot) can be overridden in the field's tag. Default values are not supported.

Examples:

// Field is ignored.
Field int `properties:"-"`

// Field is assigned value of 'Field'.
Field int

// Field is assigned value of 'myName'.
Field int `properties:"myName"`

// Field is assigned value of key 'myName' and has a default
// value 15 if the key does not exist.
Field int `properties:"myName,default=15"`

// Field is assigned value of key 'Field' and has a default
// value 15 if the key does not exist.
Field int `properties:",default=15"`

// Field is assigned value of key 'date' and the date
// is in format 2006-01-02
Field time.Time `properties:"date,layout=2006-01-02"`

// Field is assigned the non-empty and whitespace trimmed
// values of key 'Field' split by commas.
Field []string

// Field is assigned the non-empty and whitespace trimmed
// values of key 'Field' split by commas and has a default
// value ["a", "b", "c"] if the key does not exist.
Field []string `properties:",default=a;b;c"`

// Field is decoded recursively with "Field." as key prefix.
Field SomeStruct

// Field is decoded recursively with "myName." as key prefix.
Field SomeStruct `properties:"myName"`

// Field is decoded recursively with "Field." as key prefix
// and the next dotted element of the key as map key.
Field map[string]string

// Field is decoded recursively with "myName." as key prefix
// and the next dotted element of the key as map key.
Field map[string]string `properties:"myName"`

func (*Properties) Delete

func (p *Properties) Delete(key string)

Delete removes the key and its comments.

func (*Properties) Filter

func (p *Properties) Filter(pattern string) (*Properties, error)

Filter returns a new properties object which contains all properties for which the key matches the pattern.

func (*Properties) FilterFunc

func (p *Properties) FilterFunc(filters ...func(k, v string) bool) *Properties

FilterFunc returns a copy of the properties which includes the values which passed all filters.

func (*Properties) FilterPrefix

func (p *Properties) FilterPrefix(prefix string) *Properties

FilterPrefix returns a new properties object with a subset of all keys with the given prefix.

func (*Properties) FilterRegexp

func (p *Properties) FilterRegexp(re *regexp.Regexp) *Properties

FilterRegexp returns a new properties object which contains all properties for which the key matches the regular expression.

func (*Properties) FilterStripPrefix

func (p *Properties) FilterStripPrefix(prefix string) *Properties

FilterStripPrefix returns a new properties object with a subset of all keys with the given prefix and the prefix removed from the keys.

func (*Properties) Get

func (p *Properties) Get(key string) (value string, ok bool)

Get returns the expanded value for the given key if exists. Otherwise, ok is false.

func (*Properties) GetBool

func (p *Properties) GetBool(key string, def bool) bool

GetBool checks if the expanded value is one of '1', 'yes', 'true' or 'on' if the key exists. The comparison is case-insensitive. If the key does not exist the default value is returned.

Example

Code:

var input = `
	key=1
	key2=On
	key3=YES
	key4=true`
p, _ := Load([]byte(input), ISO_8859_1)
fmt.Println(p.GetBool("key", false))
fmt.Println(p.GetBool("key2", false))
fmt.Println(p.GetBool("key3", false))
fmt.Println(p.GetBool("key4", false))
fmt.Println(p.GetBool("keyX", false))
true
true
true
true
false

func (*Properties) GetComment

func (p *Properties) GetComment(key string) string

GetComment returns the last comment before the given key or an empty string.

func (*Properties) GetComments

func (p *Properties) GetComments(key string) []string

GetComments returns all comments that appeared before the given key or nil.

func (*Properties) GetDuration

func (p *Properties) GetDuration(key string, def time.Duration) time.Duration

GetDuration parses the expanded value as an time.Duration (in ns) if the key exists. If key does not exist or the value cannot be parsed the default value is returned. In almost all cases you want to use GetParsedDuration().

func (*Properties) GetFloat64

func (p *Properties) GetFloat64(key string, def float64) float64

GetFloat64 parses the expanded value as a float64 if the key exists. If key does not exist or the value cannot be parsed the default value is returned.

func (*Properties) GetInt

func (p *Properties) GetInt(key string, def int) int

GetInt parses the expanded value as an int if the key exists. If key does not exist or the value cannot be parsed the default value is returned. If the value does not fit into an int the function panics with an out of range error.

func (*Properties) GetInt64

func (p *Properties) GetInt64(key string, def int64) int64

GetInt64 parses the expanded value as an int64 if the key exists. If key does not exist or the value cannot be parsed the default value is returned.

func (*Properties) GetParsedDuration

func (p *Properties) GetParsedDuration(key string, def time.Duration) time.Duration

GetParsedDuration parses the expanded value with time.ParseDuration() if the key exists. If key does not exist or the value cannot be parsed the default value is returned.

func (*Properties) GetString

func (p *Properties) GetString(key, def string) string

GetString returns the expanded value for the given key if exists or the default value otherwise.

Example

Code:

p, _ := Load([]byte("key=value"), ISO_8859_1)
v := p.GetString("another key", "default value")
fmt.Println(v)
default value

func (*Properties) GetUint

func (p *Properties) GetUint(key string, def uint) uint

GetUint parses the expanded value as an uint if the key exists. If key does not exist or the value cannot be parsed the default value is returned. If the value does not fit into an int the function panics with an out of range error.

func (*Properties) GetUint64

func (p *Properties) GetUint64(key string, def uint64) uint64

GetUint64 parses the expanded value as an uint64 if the key exists. If key does not exist or the value cannot be parsed the default value is returned.

func (*Properties) Keys

func (p *Properties) Keys() []string

Keys returns all keys in the same order as in the input.

func (*Properties) Len

func (p *Properties) Len() int

Len returns the number of keys.

func (*Properties) Load

func (p *Properties) Load(buf []byte, enc Encoding) error

Load reads a buffer into the given Properties struct.

func (*Properties) Map

func (p *Properties) Map() map[string]string

Map returns a copy of the properties as a map.

func (*Properties) Merge

func (p *Properties) Merge(other *Properties)

Merge merges properties, comments and keys from other *Properties into p

func (*Properties) MustFlag

func (p *Properties) MustFlag(dst *flag.FlagSet)

MustFlag sets flags that are skipped by dst.Parse when p contains the respective key for flag.Flag.Name.

It's use is recommended with command line arguments as in:

flag.Parse()
p.MustFlag(flag.CommandLine)
Example

Code:

x := flag.Int("x", 0, "demo customize")
y := flag.Int("y", 0, "demo override")

// Demo alternative for flag.Parse():
flag.CommandLine.Parse([]string{"-y", "10"})
fmt.Printf("flagged as x=%d, y=%d\n", *x, *y)

p := NewProperties()
p.MustSet("x", "7")
p.MustSet("y", "42") // note discard
p.MustFlag(flag.CommandLine)
fmt.Printf("configured to x=%d, y=%d\n", *x, *y)
flagged as x=0, y=10
configured to x=7, y=10

func (*Properties) MustGet

func (p *Properties) MustGet(key string) string

MustGet returns the expanded value for the given key if exists. Otherwise, it panics.

func (*Properties) MustGetBool

func (p *Properties) MustGetBool(key string) bool

MustGetBool checks if the expanded value is one of '1', 'yes', 'true' or 'on' if the key exists. The comparison is case-insensitive. If the key does not exist the function panics.

func (*Properties) MustGetDuration

func (p *Properties) MustGetDuration(key string) time.Duration

MustGetDuration parses the expanded value as an time.Duration (in ns) if the key exists. If key does not exist or the value cannot be parsed the function panics. In almost all cases you want to use MustGetParsedDuration().

func (*Properties) MustGetFloat64

func (p *Properties) MustGetFloat64(key string) float64

MustGetFloat64 parses the expanded value as a float64 if the key exists. If key does not exist or the value cannot be parsed the function panics.

func (*Properties) MustGetInt

func (p *Properties) MustGetInt(key string) int

MustGetInt parses the expanded value as an int if the key exists. If key does not exist or the value cannot be parsed the function panics. If the value does not fit into an int the function panics with an out of range error.

func (*Properties) MustGetInt64

func (p *Properties) MustGetInt64(key string) int64

MustGetInt64 parses the expanded value as an int if the key exists. If key does not exist or the value cannot be parsed the function panics.

func (*Properties) MustGetParsedDuration

func (p *Properties) MustGetParsedDuration(key string) time.Duration

MustGetParsedDuration parses the expanded value with time.ParseDuration() if the key exists. If key does not exist or the value cannot be parsed the function panics.

func (*Properties) MustGetString

func (p *Properties) MustGetString(key string) string

MustGetString returns the expanded value for the given key if exists or panics otherwise.

func (*Properties) MustGetUint

func (p *Properties) MustGetUint(key string) uint

MustGetUint parses the expanded value as an int if the key exists. If key does not exist or the value cannot be parsed the function panics. If the value does not fit into an int the function panics with an out of range error.

func (*Properties) MustGetUint64

func (p *Properties) MustGetUint64(key string) uint64

MustGetUint64 parses the expanded value as an int if the key exists. If key does not exist or the value cannot be parsed the function panics.

func (*Properties) MustSet

func (p *Properties) MustSet(key, value string) (prev string, ok bool)

MustSet sets the property key to the corresponding value. If a value for key existed before then ok is true and prev contains the previous value. An empty key is silently ignored.

func (*Properties) Set

func (p *Properties) Set(key, value string) (prev string, ok bool, err error)

Set sets the property key to the corresponding value. If a value for key existed before then ok is true and prev contains the previous value. If the value contains a circular reference or a malformed expression then an error is returned. An empty key is silently ignored.

func (*Properties) SetComment

func (p *Properties) SetComment(key, comment string)

SetComment sets the comment for the key.

func (*Properties) SetComments

func (p *Properties) SetComments(key string, comments []string)

SetComments sets the comments for the key. If the comments are nil then all comments for this key are deleted.

func (*Properties) SetValue

func (p *Properties) SetValue(key string, value interface{}) error

SetValue sets property key to the default string value as defined by fmt.Sprintf("%v").

func (*Properties) String

func (p *Properties) String() string

String returns a string of all expanded 'key = value' pairs.

func (*Properties) Write

func (p *Properties) Write(w io.Writer, enc Encoding) (n int, err error)

Write writes all unexpanded 'key = value' pairs to the given writer. Write returns the number of bytes written and any write error encountered.

func (*Properties) WriteComment

func (p *Properties) WriteComment(w io.Writer, prefix string, enc Encoding) (n int, err error)

WriteComment writes all unexpanced 'key = value' pairs to the given writer. If prefix is not empty then comments are written with a blank line and the given prefix. The prefix should be either "# " or "! " to be compatible with the properties file format. Otherwise, the properties parser will not be able to read the file back in. It returns the number of bytes written and any write error encountered.

Package Files

BUGs

  • Set() does not check for invalid unicode literals since this is currently handled by the lexer.

  • Write() does not allow to configure the newline character. Therefore, on Windows LF is used.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier