Skip to content

Latest commit

 

History

History
79 lines (53 loc) · 2.51 KB

env.adoc

File metadata and controls

79 lines (53 loc) · 2.51 KB
Raw

env

since version 1.3.0

env returns the value of an environment variable. The macro can also be used to test that an environment variable exists or not. If the argument to the macro is the name of an environment variable, then the result will be the value of the variable. If the variable is not defined, then the macro will result empty string.

Jamal source
{@env JAVA_HOME}

is

output
/Users/verhasp/.sdkman/candidates/java/21.0.1-oracle

on the machine where the original env.adoc.jam file was converted to ASCIIDOC.

If there is a ? after the name of the variable name, then the macro will result either the true or false. This can be used to test that an environment variable exists or not. In principle

Jamal source
{#if|{@env JAVA_HOME}|Java installed|Java not installed}

also results

output
Java installed

as anything that is not empty string or the literal false is considered true in Jamal. It may happen that the value of the environment variable is false and in that case the code would think it is not defined, instead of defined to be false. Also the value of the environment variable may contain the macro separating character

Testing the value of the environment variable in an {@if …​ } macro may be misleading when the value is literal false or an empty string.

Starting with Jamal 1.9.0, it is possible to use ! after the name of the variable. In this case, the macro will throw exception when the environment variable is not defined.

The macro does not only check the environment variables when looking for a configuration value. It looks at

  • the Java system properties first,

  • then at the environment variables, and finally

  • tries to look up the configuration value from the ~/.jamal/setting.properties or ~/.jamal/setting.xml file.

When looking up a Java system property the algorithm

  • converts the name of the property to lowercase, and

  • replaces all _ characters with dot . characters.

When looking up a property from the ~/.jamal/setting.properties or ~/.jamal/setting.xml file the algorithm also removes any JAMAL_ or jamal. prefix from the property name.

Note

This search algorithm tries to follow the naming of the Java system properties, environment and properties. Also, it makes it possible to define something globally for the user, or only for the running shell or only for the running JVM. The more local configuration overrules the broader one using this algorithm.