configure: functions module for shellfire

This module provides a simple framework for managing configuration of a shellfire application. It is deliberately separate to the core module, which provides automatic loading of configuration for the command line at run time. Instead, it lets users define configuration in both files and directories of snippets, which can be overridden, defaulted, validated and restored.

An example user is the swaddle packaging tool.

Compatibility

• Tag release_2015.0117.1750-1 is compatible with shellfire release release_2015.0117.1750-1.

Overview

Configuration is organised into namespaces which are private to your program; specifying the same namespace in different programs will give different results.

To get going, first we need to register some settings:-

configure_register 'Value' 'Boolean' 'swaddle_web' 'use_index_name_in_directory_links' yes
configure_register 'Array' 'Any' 'swaddle_web pandoc_options'
configure_register 'Value' 'NotEmpty' 'swaddle_web' 'index_name' 'index.html'

Note that there's no need to register the namespace; this happens automatically. The framework supports Values and Arrays. A Value may have a default (for example, index_name above defaults to index.html). Arrays can not have defaults. By convention, namespaces are organised in a hierarchy using underscores, _, and names use lower case and underscores _. This makes them easy to set by administrative users. There is no need to quote the values, either; this is done above to take advantage of syntax highlighting.

Then we can use our configuration:-

configure_reset 'swaddle_web'
configure_source '/path/to/configuration/folder' "myconf"
configure_validate 'swaddle_web'

# Get index name
indexName="$(configure_getValue 'swaddle_web' 'index_name')"

# Call pandoc with options
configure_iterateOverArrayWithDefaultsIfEmpty 'swaddle_web' 'pandoc_options' pandoc

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/configure.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/configure.git" above if using a fork.

You will also need to add paths - include the module paths.d.

Namespace configure

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn configure

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn configure
	…
}

Functions

---

configure_register

Parameter	Value	Optional
kind	Namespace used to differentiate configuration setting from any other	No
configurationValidationFunction	Use the function called configure_validate_${configurationValidationFunction} to validate configuration	No
namespace	Namespace used to differentiate configuration setting from any other	No
configurationSettingName	Name of configuration setting	No
default	When kind is Value, may be specified if a default is wanted. Not permitted when kind is Array	Yes

The values of kind may be:-

Value	Description
Value	A single value
Array	An array of zero or more values

The values of configurationValidationFunction are not constrained; you may define your own. Those supplied in this module are:-

Value	Description
Any	Any value permitted
NotEmpty	Any value apart from empty permitted
Boolean	Value must be a boolean (eg yes, true, 1, on, Y, T, etc) as per core_variable_isBoolean
ReadableSearchableFolderPath	Value must be a readable, searchable folder path

See the swaddle project for more examples of validation functions.

A namespace must consist only of lower and upper case letters, digits and underscores, to be compatible with all POSIX shells. This is not enforced, however.

The default may be whitespace-separated without using quotes; all values are concatenated together with a single SP separator.

---

configure_reset

Parameter	Value	Optional
namespace	Namespace used to differentiate configuration setting from any other	No

This functions resets configuration. This is useful when, for example, you allow a configuration setting to be specified, say, per company and per project. Initially, you'd want to have it configured company wide, then allow overrides per project. Perhaps you iterate over the projects, and then do some additional company-level processing; you'd want to call configure_reset before iterating over each project and after iterating over the last one.

Additionally, calling it once before any configuration is sourced at all defends against contamination of the environment variable space.

---

configure_source

Parameter	Value	Optional
configurationPath	Folder path containing configuration	No
configurationName	Base name of configuration, eg swaddle	No

This functions sources (loads) configuration files. It looks for a file named ${configurationName}.conf in configurationPath, and then any (readable, non-empty) .conf files in a folder configurationPath/${configurationName}.conf.d. If either does not exist, no error is raised.

Configuration files consist of lines of the form:-

configure swaddle maintainer_name 'Raphael Cohn'

If the name is an Array, then the value specified is appended to the array. If it is a Value, then it is replaced. The value is validated at this time. Any whitespace between in a value is normalised if not quoted. Values may also be heredocs, although this is not recommended and may not be supported in future releases (it doesn't seem to work reliably).

Note that configuration files are actually shell code, and can so be used to override or provide functions.

---

configure_source

Parameter	Value	Optional
configurationPath	Folder path containing configuration	No
configurationName	Base name of configuration, eg swaddle	No

This functions sources (loads) configuration files. It looks for a file named ${configurationName}.conf in configurationPath, and then any (readable, non-empty) .conf files in a folder configurationPath/${configurationName}.conf.d. If either does not exist, no error is raised.

Configuration files consist of lines of the form:-

configure swaddle maintainer_name 'Raphael Cohn'

If the name is an Array, then the value specified is appended to the array. If it is a Value, then it is replaced. The value is validated at this time. Any whitespace between in a value is normalised if not quoted. Values may also be heredocs, although this is not recommended and may not be supported in future releases (it doesn't seem to work reliably).

Note that configuration files are actually shell code, and can so be used to override or provide functions.

---

configure_validate

Parameter	Value	Optional
namespace	Namespace used to differentiate configuration setting from any other	No

Use this function after all configure_source calls have been made to ensure that all values that need to be configured have been configured. This method does not validate individual values; instead, it ensures that all values are set for a particular namespace.

---

configure_getValue

Parameter	Value	Optional
namespace	Namespace used to differentiate configuration setting from any other	No
configurationSettingName	Name of configuration setting	No

Use this function to get a Value from configuration. Printed to standard out, so use captures, eg

local repositoryName="$(configure_getValue 'swaddle_github' 'repository_name')"

---

configure_iterateOverArrayWithDefaultsIfEmpty

Parameter	Value	Optional
namespace	Namespace used to differentiate configuration setting from any other	No
configurationSettingName	Name of configuration setting	No
callback	Name of a function (or program on the path)	No
...	Zero or more arguments to use as defaults to iterate over if the configuration setting is an empty array	Yes

Use this function to iterate over each value in an Array configuration setting, passing each value as the variable core_variable_array_element to the function callback. If nothing was configured, then a set of defaults can be supplied as additional arguments ....

For example,

some_callback()
{
	echo "architecture: $core_variable_array_element"
}

configure_iterateOverArrayWithDefaultsIfEmpty 'swaddle_apt' 'architectures' some_callback 'amd64' 'i386'

will iterate over whatever is in architectures, or, if, empty, the values amd64 and i386.

---

configure_callFunctionWithDefaultsIfEmpty

Parameter	Value	Optional
namespace	Namespace used to differentiate configuration setting from any other	No
configurationSettingName	Name of configuration setting	No
callback	Name of a function (or program on the path)	No
...	Zero or more arguments to use as defaults to iterate over if the configuration setting is an empty array	Yes

Use this function to pass all the values in an Array configuration setting to a callback. If nothing was configured, then a set of defaults can be supplied as additional arguments ....

For example,

some_callback()
{
	echo "number of elements in array: $#"
	echo "Values: $@"
}

configure_iterateOverArrayWithDefaultsIfEmpty 'swaddle_apt' 'architectures' some_callback 'amd64' 'i386'

will pass whatever is in architectures, or, if, empty, the values amd64 and i386 (and so $# is 2).

---

configure_isValueValid

Parameter	Value	Optional
snippetName	Name of a snippet	No
configurationSettingValue	Value that would be retrieved from configure_getValue	No

This is a helper function to call when defining your own configurationValidationFunction. It allows you to embed a list of values inside your code that might change. It uses the core snippet functions. For example:-

core_snippet_embed raw validate_rpm_licence
configure_validate_RpmLicence()
{
	configure_isValueValid validate_rpm_licence "$1"
}

where validate_rpm_licence is the file lib/shellfire/${_program_name}/validate_rpm_licence.snippet, and might contain a list such as:-

AGPLv1
Artistic 2.0
…

Each entry is terminated by a line feed, including the final entry. If the value specified by configuration is in this list, it's valid. If it's not, its invalid. You can use your new validation function when registering, eg

configure_register Value Licence swaddle licence