ext/config.bi

Summary
ext/config.bi
About this ModuleThis module provides a way to configure your program easily using the standard locations on each platform.
Code LicenseCopyright © 2007-2014, FreeBASIC Extended Library Development Group
ext.config
Functions
setAppNameThe Human-readable name of your application to be used when determining where to load/save the configuration file by default.
setPathSets the configuration file location to a non-standard location.
loadLoads the configuration from disk (if available).
saveSaves the current state of configuration to disk.
Basic Usage
Functions
getBool
getString
getInteger
getDouble
getBoolArray
getIntegerArray
getDoubleArray
getStringArray
setBool
setString
setInteger
setDouble
setBoolArray
setIntegerArray
setDoubleArray
setStringArray
existsCheck if the specified name exists in the configuration file.
removeRemove the specified key from the configuration file.
Advanced Usage
Functions
get_rawxmlThis function allows you to access the raw xml tree associated with a key in order to do things that are too advanced for the simple api above.

About this Module

This module provides a way to configure your program easily using the standard locations on each platform.  You do not need to distribute a config file either, as it will be generated the first time you run your application provided you set you default values in the getType calls.  This configuration file is saved in somewhat human-readable XML for advanced users to modify if they wish to do so at a standard location.

The Standard locations for each platform are

Windows%APPDATA%\appname\config.xml
Linux$HOME/.config/appname/config.xml
DOSEXEPATH/appname.cfg

The configuration file is treated as a name-value store.  Each named item can consist of a Boolean value, integer or double value and a String value.  If you wish to have more than one, you should make sure that you call getString first so the name is properly created.  Also, please note that integers and doubles are stored in the same location in name and will overwrite each other.

You should generally call the get* functions (with a default value) and only call the set* functions if you need to change something after loading the configuration, i.e. the user changes something or you are saving a new window position at exit.

You must ensure that you call setAppName before calling load else your application will have the default name of “UnnamedApp”.

Code License

Copyright © 2007-2014, FreeBASIC Extended Library Development Group

Distributed under the FreeBASIC Extended Library Group license.  See accompanying file LICENSE.txt or copy at http://code.google.com/p/fb-extended-lib/wiki/License

ext.config

Summary
Functions
setAppNameThe Human-readable name of your application to be used when determining where to load/save the configuration file by default.
setPathSets the configuration file location to a non-standard location.
loadLoads the configuration from disk (if available).
saveSaves the current state of configuration to disk.

Functions

setAppName

declare sub setAppName(byref appn as string)

The Human-readable name of your application to be used when determining where to load/save the configuration file by default.

Parameters

appnthe Name to use.

setPath

declare sub setPath(byref path as string)

Sets the configuration file location to a non-standard location.  Generally you should not use this without a good reason.

Parameters

pathwhere to save/load the configuration file from.

load

declare sub load()

Loads the configuration from disk (if available).

save

declare sub save()

Saves the current state of configuration to disk.

Functions

getBool

declare function getBool(byref name_ as string,  
byval default as bool =  false) as bool

Parameters

name_the name of the value to retrieve
defalutoptional the default value to return if the name_ is not set

Returns

The retrived value or the default if not set.

Example

Generates the following XML

<name_ enabled="false" />

getString

declare function getString(byref name_ as string,  
byref default as string =  "") as string

Parameters

name_the name of the value to retrieve
defalutoptional the default value to return if the name_ is not set

Returns

The retrived value or the default if not set.

Example

Generates the following XML

<name_>string</name_>

getInteger

declare function getInteger(byref name_ as string,  
byval default as integer =  0) as integer

Parameters

name_the name of the value to retrieve
defalutoptional the default value to return if the name_ is not set

Returns

The retrived value or the default if not set.

Example

Generates the following XML

<name_ value="0" />

getDouble

declare function getDouble(byref name_ as string,  
byval default as double =  0.0) as double

Parameters

name_the name of the value to retrieve
defalutoptional the default value to return if the name_ is not set

Returns

The retrived value or the default if not set.

Example

Generates the following XML

<name_ value="0.0" />

getBoolArray

declare sub getBoolArray(byref name_ as string,  
byref subname as string =  "item",
array() as bool  )

Parameters

name_the key to retrieve items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to put the results into

Example

XML output

<name_>
  <item enabled="true" />
  <item enabled="true" />
</name>

getIntegerArray

declare sub getIntegerArray(byref name_ as string,  
byref subname as string =  "item",
array() as integer  )

Parameters

name_the key to retrieve items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to put the results into

Example

XML output

<name_>
  <item value="0" />
  <item value="0" />
</name>

getDoubleArray

declare sub getDoubleArray(byref name_ as string,  
byref subname as string =  "item",
array() as double  )

Parameters

name_the key to retrieve items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to put the results into

Example

XML output

<name_>
  <item value="0.0" />
  <item value="0.0" />
</name>

getStringArray

declare sub getStringArray(byref name_ as string,  
byref subname as string =  "item",
array() as string  )

Parameters

name_the key to retrieve items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to put the results into

Example

XML output

<name_>
  <item>string</item>
  <item>string</item>
</name>

setBool

declare sub setBool(byref name_ as string,
byval v as bool)

Parameters

name_the key to set the value of
vthe value to assign to name_

Notes

Changes take effect immediately in memory but do not persist on disk until <save> is called.

setString

declare sub setString(byref name_ as string,
byref v as string)

Parameters

name_the key to set the value of
vthe value to assign to name_

Notes

Changes take effect immediately in memory but do not persist on disk until <save> is called.

setInteger

declare sub setInteger(byref name_ as string,
byval v as integer)

Parameters

name_the key to set the value of
vthe value to assign to name_

Notes

Changes take effect immediately in memory but do not persist on disk until <save> is called.

setDouble

declare sub setDouble(byref name_ as string,
byval v as double)

Parameters

name_the key to set the value of
vthe value to assign to name_

Notes

Changes take effect immediately in memory but do not persist on disk until <save> is called.

setBoolArray

declare sub setBoolArray(byref name_ as string,  
byref subname as string =  "item",
array() as bool  )

Parameters

name_the key to set items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to get the values from

setIntegerArray

declare sub setIntegerArray(byref name_ as string,  
byref subname as string =  "item",
array() as integer  )

Parameters

name_the key to set items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to get the values from

setDoubleArray

declare sub setDoubleArray(byref name_ as string,  
byref subname as string =  "item",
array() as double  )

Parameters

name_the key to set items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to get the values from

setStringArray

declare sub setStringArray(byref name_ as string,  
byref subname as string =  "item",
array() as string  )

Parameters

name_the key to set items for
subnameoptional the name of the subkey each item is listed as, default is “item” (see example)
array()the array to get the values from

exists

declare function exists(byref name_ as string) as bool

Check if the specified name exists in the configuration file.

Parameters

name_the key to check for.

Returns

TRUE if the key exists, FALSE otherwise.

remove

declare sub remove(byref name_ as string)

Remove the specified key from the configuration file.

Parameters

name_the key to remove.

Notes

This change will not take effect on disk until you call <save>.

Advanced Usage

Summary
Functions
get_rawxmlThis function allows you to access the raw xml tree associated with a key in order to do things that are too advanced for the simple api above.

Functions

get_rawxml

declare function get_rawxml(byref name_ as string) as ext.xml.node ptr

This function allows you to access the raw xml tree associated with a key in order to do things that are too advanced for the simple api above.

Parameters

name_the key to retrieve

Returns

<ext.xml.node> pointer or NULL if the key does not exist

declare sub setAppName(byref appn as string)
The Human-readable name of your application to be used when determining where to load/save the configuration file by default.
declare sub setPath(byref path as string)
Sets the configuration file location to a non-standard location.
declare sub load()
Loads the configuration from disk (if available).
declare sub save()
Saves the current state of configuration to disk.
declare function getBool(byref name_ as string,  
byval default as bool =  false) as bool
declare function getString(byref name_ as string,  
byref default as string =  "") as string
declare function getInteger(byref name_ as string,  
byval default as integer =  0) as integer
declare function getDouble(byref name_ as string,  
byval default as double =  0.0) as double
declare sub getBoolArray(byref name_ as string,  
byref subname as string =  "item",
array() as bool  )
declare sub getIntegerArray(byref name_ as string,  
byref subname as string =  "item",
array() as integer  )
declare sub getDoubleArray(byref name_ as string,  
byref subname as string =  "item",
array() as double  )
declare sub getStringArray(byref name_ as string,  
byref subname as string =  "item",
array() as string  )
declare sub setBool(byref name_ as string,
byval v as bool)
declare sub setString(byref name_ as string,
byref v as string)
declare sub setInteger(byref name_ as string,
byval v as integer)
declare sub setDouble(byref name_ as string,
byval v as double)
declare sub setBoolArray(byref name_ as string,  
byref subname as string =  "item",
array() as bool  )
declare sub setIntegerArray(byref name_ as string,  
byref subname as string =  "item",
array() as integer  )
declare sub setDoubleArray(byref name_ as string,  
byref subname as string =  "item",
array() as double  )
declare sub setStringArray(byref name_ as string,  
byref subname as string =  "item",
array() as string  )
declare function exists(byref name_ as string) as bool
Check if the specified name exists in the configuration file.
declare sub remove(byref name_ as string)
Remove the specified key from the configuration file.
declare function get_rawxml(byref name_ as string) as ext.xml.node ptr
This function allows you to access the raw xml tree associated with a key in order to do things that are too advanced for the simple api above.