This document describes the environment variables that you may set to modify the behavior of Jamal. The documentation file is less than 20 lines, the real documentation is in the source. Jamal collects the documentation from the source files and generates the ascii doc file from the source comments.
The general rule is that you do not need to configure Jamal. But you can.
All environment variables start with the prefix “JAMAL_”.
For every environment variable, there is a corresponding system property.
The name of the system property is the same as the environment variable lower-case converted and replacing the _ to . characters.
For example, for the environment variable JAMAL_CHECKSTATE, the system property is jamal.checkstate.
JAMAL_CHECKSTATE --> jamal.checkstate
First, the system property is consulted, and the environment variable has only effect when the system property is not defined. The following sections describe the individual environment variables.
This variable can define the connection timeout value for the web download in millisecond as unit.
Jamal can download resources when the name of a file starts with the prefix https://.
The default value for the timeouts is 5000, meaning five seconds.
The proxy setting can be configured using standard Java system properties.
For more information, see the Javadoc documentation of the class java.net.HttpURLConnection in the JDK documentation.
This variable can define the read timeout value for the web download in millisecond as unit.
The default value for the timeouts is 5000, meaning five seconds.
This environment variable defines the name of the trace file. When a trace file is defined, the evaluation and all the partial evaluations are logged to this file during processing. This file can grow very fast, and it is not purged or deleted by Jamal.
sets the recursive call depth in macro evaluation.
Macros may be recursive, and in some cases it may create infinite recursive calls in Jamal.
Try a simple Jamal file that contains {@define a={a}}{a}.
This will drive Jamal into an infinite recursive call.
During the macro evaluation, {a} will result in {a} again, and this will be evaluated again and again.
Infinite recursive calls result StackOverflowError which should not be caught by any program.
To avoid this, Jamal limits the recursive calls to the maximum depth of 1000.
This is a reasonable limit.
-
Most Jamal sources are not complex and will not get above this limit recursively.
-
At the same time, most Java implementations can handle this dept.
This limit may be too much in your environment.
Jamal may still throw a StackOverflowError.
In this case, set this to a smaller value.
It may also happen that you deliberately create complex recursive macros.
In that case, this limit may be too small.
Set your value to a limit that fits your need.
This environment variable can switch off macro statefulness checking during macro registration.
It is generally recommended that the macros are stateless to support multi-thread evaluation when a single JVM runs multiple Jamal processors in one or more threads.
If a macro has to have a state, it must be annotated using the annotation Macro.Stateful.
The statelessness or annotation is checked during macro registering since Jamal version 1.8.0.
You can switch off the functionality setting this environment variable to false.
It may be needed if you want to use an older, prior 1.8.0 library or a library that does not follow this rule.
This environment variable can switch on debugging of Jamal.
To use the debugger, this variable has to set to a value, which is recognized by a debugger on the classpath.
The web-based debugger recognizes the http:port format variables.
Set this variable to http:8080, put the jamal-debug module on the classpath and after starting Jamal processing open your browser at http://localhost:8080.
The debugger and the use of it is detailed in a separate section.
This variable can set the maximum number of files include nesting. The default value is 100.
This variable can be set to point to a directory for cache files. When Jamal downloads web resources, it stores them in a cache directory if the directory exists. Jamal creates subdirectories under the cache directory, but the cache directory itself has to be created manually.
The default location for the cache files is ~/.jamal/cache/.
This environment variable can define replacements for files.
The aim of this feature is to use a local file during development, and still refer to it using the https:// URL, which will be the production URL.
You want to run tests without pushing the file to a repository, but at the same time you do not want your code to refer to a dev location to be changed before releasing.
Only absolute file names can be replaced.
For example, you include the file https://raw.githubusercontent.com/central7/pom/1/pom.jim in your Jamal file.
You want to replace it with a local file ~/projects/jamal/pom.jim.
In that case, you should set the environment variable
export JAMAL_DEV_PATH=\|https://raw.githubusercontent.com/central7/pom/main/pom.jim?SNAPSHOT=~/github/jamal/pom.jimThe environment value is a list of = separated pairs.
The list is parsed using the standard InputHandler.getParts(Input) method.
This is the reason why the first character in the example is the separator |
An alternative use is to specify an existing text file in this variable.
In that case, the file will be read by Jamal, and the individual lines will be interpreted as key=value pairs.
Comment lines starting with # and empty lines are ignored.
This environment variable can define options for the Jamal processor.
The value of the variable is interpreted as a multipart input.
The list is parsed using the standard InputHandler.getParts(Input) method.
If you just have one option, then you can define that with the name.
If there are multiple options, then you have to select a non-alphanumeric separator character and present it in front of the list.
|
Note
|
that the usual | character has a special meaning for the bash, and therefore you may need to escape.
Also note that using : as a separator character may work, but it may be misleading as it can also be part of an option name.
|
The options are set on the top level, there is no need to use a : prefix.
To set an option to false, you can use the ~ character, but please do not.
Every option default value is false when not set.
The typical use of this possibility is to set the option failfast.
This option alters the error processing, and it is more "bound" to the execution than to the document.
It may be a better option to include it in an environment variable, or system property than in the document itself.
Both approaches work.