PropertyFileAPI

::InstallAPI::PropertyFileAPI

This API provides the necessary functions for reading, manipulating and writing common properties files. A properties file follows the standard convention for Java properties files, but it basically matches an almost universal format for simple properties within a file.

Supported Platforms

All

Returns

See options

Options

-array <arrayName> (required)

The name of an array to store the values in.

-do (required)

Specifies the action the API should take. Possible values are:

append	Add a line to the given array that should be written to the properties file as-is.
data	Return a string of data that will be written to a file if written. This data is the current contents of the properties file.
keys	Return a list of keys in the properties array.
read	Read a given properties file into the array.
set	Set the value of a given key to a value. If the key already exists, it will be overwritten, and when it is saved to a file, it will replace the original line that set the key in the same place within the file.
unset	Unset the value of a given key. This will remove the key from the array as well as delete any reference to the value when the file is written out.
write	Write the property array to a file.

-file

If the do action is read or write, this property specifies the name of the file to read from or write to.

-key

If the do action is set or unset, this property specifies the key in the array to operate on.

-line

If the do action is append, this property specifies a line (or multiline) string to append directly to the given array.

-separator

Specifies the separator character to use between keys and values. The default is =.

-value

If the do action is set or unset, this property specifies the value to set for the given key.

Example

The following example shows a sample properties file and how the API uses it.

## Sample .properties file.

## Set foo

foo=bar

## Set bar

bar=foo

::InstallAPI::PropertyFileAPI -do read sample.properties -array props

::InstallAPI::PropertyFileAPI -do set -array props -key foo -value "NEW FOO"

::InstallAPI::PropertyFileAPI -do append -array props -line "\n## New value"

::InstallAPI::PropertyFileAPI -do set -array props -key newvalue -value "NEW VALUE"

The new properties file will look like this

## Sample .properties file.

## Set foo

foo=NEW FOO

## Set bar

bar=foo

## New value

newvalue=NEW VALUE