Using environment variables in XML configurationΒΆ

New in version Imagination: 2.5

New enhancement :)

You can refer to any environment variables in the XML configuration file. Here is how you can do it.

Suppose we have this configuration.

    <entity id="parser" class="app.Server">
        <param type="str" name="run_as">data_service</param>
        <param type="str" name="storage_path">/storage</param>

However, we would like to be able to make the running user and the storage path configurable. What we can do now is to refer to configuration via environment blocks.

    <entity id="parser" class="app.Server">
        <param type="str" name="run_as">{ $USER }</param>
        <param type="str" name="storage_path">{ $STORAGE_PATH or "/" }storage</param>


The syntax is { $<environment_name> [or <default_value> ]} where:

  • <environment_name> can only contains A-Z,a-z,0-9,_,. (i.e., valid environment variable names),
  • <default_value> is JSON-encode-able only of type int, float, and str,
  • there may be any spaces after { and before },
  • there must be at least one space before and after or.

When Imagination parses the value of parameter or item, the assembler will replace the environment block with the environment variable or the default value (if defined) before evaluate the final value into any defined data type.


If the environment variable is undefined and the default value is not set, e.g., { $USER }, Imagination will raise imagination.exc.UnknownEnvironmentVariableError.