props

README

props: Go (golang) library for handling Java-style property files

This library provides compatibility with Java property files for Go.

There are two main types provided:

• Properties - read and write property files in Java format
• Expander - replaces property references wrapped by '${}' at runtime (as found in Ant/Log4J/JSP EL/Spring)

The full Java property file format (including all comment types, line continuations, key-value separators, unicode escapes, etc.) is supported.

Documentation

Overview

Package props implements handling of property lists and files. It is intended to be compatible with the Java property file format.

Index

• func TestGet(t *testing.T)
• func TestNames(t *testing.T)
• func TestNewProps(t *testing.T)
• func TestReadComments(t *testing.T)
• func TestReadContinued(t *testing.T)
• func TestReadEscapes(t *testing.T)
• func TestReadKeys(t *testing.T)
• func TestReadSimple(t *testing.T)
• func TestSet(t *testing.T)
• func TestWrite(t *testing.T)
• type Expander
  • func NewExpander() *Expander
  • func (e *Expander) Get(key string) string
  • func (e *Expander) GetDefault(key, defVal string) string
• type Properties
  • func NewProperties() *Properties
  • func Read(r io.Reader) (*Properties, error)
  • func (p *Properties) Clear()
  • func (p *Properties) Get(key string) string
  • func (p *Properties) GetDefault(key, defVal string) string
  • func (p *Properties) Load(r io.Reader) error
  • func (p *Properties) Names() []string
  • func (p *Properties) Set(key, val string)
  • func (p *Properties) Write(w io.Writer) error

Functions

func TestGet

func TestGet(t *testing.T)

func TestNames

func TestNames(t *testing.T)

func TestNewProps

func TestNewProps(t *testing.T)

func TestReadComments

func TestReadComments(t *testing.T)

func TestReadContinued

func TestReadContinued(t *testing.T)

func TestReadEscapes

func TestReadEscapes(t *testing.T)

func TestReadKeys

func TestReadKeys(t *testing.T)

func TestReadSimple

func TestReadSimple(t *testing.T)

func TestSet

func TestSet(t *testing.T)

func TestWrite

func TestWrite(t *testing.T)

Types

type Expander

type Expander struct {
	// Prefix indicates the start of a property expansion.
	Prefix string
	// Suffix indicates the end of a property expansion.
	Suffix string
	*Properties
}

Expander represents a property set that interprets special character sequences in property values as references to other property values for replacement.

For example, the following properties:

color.alert = red
color.info = blue
color.text = black

css.alert = border: 1px solid ${color.alert}; color: ${color.text};
css.info = border: 1px solid ${color.info}; color: ${color.text};

Would result in the following values:

"css.alert": "border: 1px solid red; color: black;"
"css.info":  "border: 1px solid blue; color: black;"

Nested and recursive property expansions are permitted. If a property value does not exist, the property reference will be left unchanged.

func NewExpander

func NewExpander() *Expander

NewExpander creates an empty property set with the default expansion Prefix "${" and Suffix "}".

func (*Expander) Get

func (e *Expander) Get(key string) string

Get retrieves the value of a property with all property references expanded. If the property does not exist, an empty string will be returned.

func (*Expander) GetDefault

func (e *Expander) GetDefault(key, defVal string) string

GetDefault retrieves the value of a property with all property references expanded. If the property does not exist, the default value will be returned with all its property references expanded.

type Properties

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

Properties represents a set of key-value pairs.

func NewProperties

func NewProperties() *Properties

NewProperties creates a new, empty property set.

func Read

func Read(r io.Reader) (*Properties, error)

Read creates a new property set and fills it with the contents of a file. See Load for the supported file format.

func (*Properties) Clear

func (p *Properties) Clear()

Clear removes all key-value pairs.

func (*Properties) Get

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

Get retrieves the value of a property. If the property does not exist, an empty string will be returned.

func (*Properties) GetDefault

func (p *Properties) GetDefault(key, defVal string) string

GetDefault retrieves the value of a property. If the property does not exist, then the default value will be returned.

func (*Properties) Load

func (p *Properties) Load(r io.Reader) error

Load reads the contents of a property file. Existing properties will be retained. The contents of the file will override any existing properties with matching keys.

File Format

The supported property file format follows the Java conventions. Each line of the file represents a key-value pair. Keys and values may be separated by '=', ':', or whitespace. Comments are indicated by a leading '#' or '!' character.

Encoding

Java property files require an ISO 8859-1 encoding, but this package will also accept files encoded in UTF-8.

Escapes

The escape character is '\'; valid escapes are '\f', '\n', '\r', '\t', and UTF-16 escapes in the format "\uXXXX" where each "X" is a hexadecimal digit. Invalid escapes are replaced with the escaped character only, so '\A' will result in 'A'. (This is useful for escaping the key separator or comment characters.) Invalid UTF-16 escapes will be replaced with the Unicode replacement character U+FFFD.

Spanning Lines

To create a key or value that spans multiple lines, end the line with '\' followed by a newline. All leading whitespace on the next line will be ignored and not included in the key or value, allowing for indentation of continued lines.

Sample File

This is a sample property file:

# env.properties
! for dev environment
site.url = http://localhost:8180/

# database
db.host:localhost
db.port:5432
db.user:devdb

# email
email.from dev@example.com
email.to   me@example.org

email.welcome  Subject: Welcome! \
			  Thank you. Now: \
			  \t Feat 1 \
			  \t Feat 2 \
			  Enjoy!

# reporting
rpt\ newline=\u000a
rpt\ list\ bullet=\u2022

Loading this file would result in the following properties:

"site.url":        "http://localhost:8180/"
"db.host":         "localhost"
"db.port":         "5432"
"db.user":         "devdb"
"email.from":      "dev@example.com"
"email.to":        "me@example.org"
"email.welcome":   "Subject: Welcome! \nThank you. Now: \n\tFeat 1 \n..."
"rpt newline":     "\n"
"rpt list bullet": "•"

func (*Properties) Names

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

Names returns the keys for all properties in the set.

func (*Properties) Set

func (p *Properties) Set(key, val string)

Set adds or changes the value of a property.

func (*Properties) Write

func (p *Properties) Write(w io.Writer) error

Write saves the property set to a file. The output will be in "key=value" format, with appropriate characters escaped. See Load for more details on the file format.

Note: if the property set was loaded from a file, the formatting and comments from the original file will not be retained in the output file.