Jamal is a macro language (JAmal MAcro Language)

The simplest way to start Jamal is to use the JShell.

All you need to do is execute the following command:

It will start Jamal to process all files with .jam extension in the current directory and below. The output files will have the same name as the processed file without the .jam at the end. For example, pom.xml.jam will be processed to pom.xml.

You do not even need to install Jamal. If you have Java 11 or later installed, you can execute the above command. JShell will download and execute the script from the URL depicted above. The script will check if Jamal is installed on your machine. If it is not installed, it will automatically download the needed JAR. When the JAR files are downloaded, it will start Jamal in the current working directory using the default settings. You can alter the settings using the jamal.options file. If this file does not exist in the current working directory, then the JShell script will create one containing the default settings.

It is also straightforward to start Jamal using the Maven plugin version. To do that, you have to have Maven installed, but as a Java developer, you probably have. Then you can issue the command:

if you have a pom.xml file in your directory.

If you do not have, then read the documentation of the Jamal Maven plugin at https://github.com/verhas/jamal/blob/master/jamal-maven-plugin/README.md It is short and straightforward.

When something goes wrong, then Jamal will give you a detailed error message. The message will include the file name, line number, and character count where the error happened. Jamal may think it works fine in other cases, but the output is not exactly what you expected. Sorry, in this case, the issue, most probably, is with your expectations. Jamal converts the text following the rules defined in this document.

If you want to use Jamal macros to maintain your Maven POM files, you can do that. Edit the content of the POM XML in the file pom.xml.jam. This file should contain the POM XML possibly enhanced with Jamal macros. Create a .mvn directory with an extensions.xml file in your project root. About the content and how this Maven extension works read the extension’s documentation.

To start Jamal on the command line, you need a command:

It is not a user-friendly approach. You do not want to type all the paths, and the JARs every time you want to start Jamal. For this reason, there is a file, jamal.sh that has the following content:

The shell variable MODULES should list the Jamal modules you may need to use in your processing. The basic modules needed under every circumstance are listed in the example. The other modules available are snippet, scriptbasic, groovy, ruby, plantuml, and debug. The shell variable REPO must be set to point to the repository where your local JAR files are. VERSION has to be the latest version or the one you intend to use.

The invocation of the shell script is ./jamal.sh options where the options have the key=value format. If you use a simple option help, then Jamal will print out a short screen that looks something like this:

The command line can contain options and parameters. Most of the options have single character version and also multiple character versions. The option values have to be written after the option in case the option is single character and with a = is multiple-character.

The options you can use with the command line version of Jamal are the followings:

• --dry-dry-run will tell Jamal to perform a dry run without invoking the conversion. Use this opition to test the input and output pattern to see which files will Jamal process and what output files it will create.

• --dry-run is a dry run, but not so dry as --dry-dry-run. When this option is used the Jamal processing is performed, but the result is not saved into the out. Using this option you can see what files Jamal will process and you can also see if there is any error during the processing.

• -c or --close=<macroClose> specifies the macro closing string. The default macro closing string is }. When using this option mind that some characters need escape on the command line.

• -o or --open=<macroOpen> specifies the macro opening string. The default macro opening string is {. When using this option mind that some characters need escape on the command line.

• -f or --file instructs Jamal not to parse the directory for input files. When this option is used Jamal will process the command line parameter <inputFile> and it will write the output to <outputFile>.

• -s or --source=<sourceDirectory> specifies the source directory where Jamal will start looking for input files. The file listing is recursive going into subdirectories. The default value is the current directory.

• -d or --depth=<depth> limits the dept of directory recursion. The default value does not limit the depth.

• -e or --exclude=<exclude> exclude the files that match the pattern <exclude>. The pattern can be usualy file matching wild-card pattern or regular expression if the option -x, --regex is used. The default value is not to exclude any file.

• -i or --include=<include> ` include the files that match the pattern `<include>. The pattern can be usualy file matching wild-card pattern or regular expression if the option -x, --regex is used. The default value is *.jam.

• -r or --transform=<transform> [<transform>] define one or more transformation. When multiple files are processed this transformations are used to calculate the output file name from the input file name. The option must have two values. The first value is the regular expression, the second parameter is the replacement string. These are the parameters that will be used in the Java method inputFileName.replaceAll(a,b) to calculate the output file name. The default value is \.jam$ and an empty string. The default value will cause replaceAll to chop off the .jam extension from the end of the file. That way, for example pom.xml.jam will be converted to pom.xml.

• -t or --target=<targetDirectory> can specify the target directory where the output will be stored. If input files are under some subdirectories of the <sourceDirectory> then the same directory structure will be created for the output. The default value is the current directory.

• -x or --regex use regular expression for the <include> and for the <exclude> values. Transform is always interpreted as regular expression.

• -g or --debug=<debug> start the code in debug mode. To use this option the debugger module implementing the debugger must be on the classpath. This is automatically ensured when Jamal is started using jbang using the jbang jamal@verhas command. The parameter <debug> is the debugger configuration string. To use the web based debugger you can specify http:8080. With that parameter the debugger will start to listen on the port 8080 on the localhost ip. The client code that runs in the browser can also be downloaded from the same server from the http://localhost:8080 address. If you specify a different port, then from that port.

• -v or --verbose verbose output

• -h or --help help

• <inputFile> the input file in case the option -f or --file was used

• <outputFile> the output file in case the option -f or --file was used

JBang (https://www.jbang.dev) is a popular command line tool that eases the startup of Java applications. Jamal can be started using JBang.

This may be the choice for you if you want to use Jamal, but you do not even have Java installed. Installing JBang is extremely simple. When running Jamal using JBang, Jbang will install everything that is needed to execute Jamal is a clean and non-intrusive way.

To start Jamal when you have JBang installed on your machine the command line to start Jamal is

This command will invoke the command line version automatically caring about all the Jar files. The syntax and meaning of the options are the same as in case of the command line version. This startup also loads all the Jamal extensions, including snippet, scriptbasic, groovy, ruby, plantuml, and debug (1.7.3 and later) and some others. If you want to see the exact list of the modules this startup loads have a look at the starter file.

When something goes wrong, Jamal gives you a detailed error message. The message will include the file name, line number, and character count where the error happened. In other cases, Jamal may think it works fine, but the output is not exactly what you expected. Sorry, in this case, the issue, most probably, is with your expectations.

In cases like that, you can try to debug the execution of the macro engine. There are two possibilities:

1. use the trace functionality, or

2. use the debugger.

The trace functionality can create a detailed XML trace of the execution that can later be examined. The trace information is structured with nested structures. XML is a format that can accommodate such nested structures and has very extensive editor support.

The debugging functionality can execute the macro transformation step-by-step providing interactive debugger user interface. The tracing functionality was developed earlier and its importance lessens by the introduction of the debugger.

Tracing

-Djamal.trace=tracefile.xml

export JAMAL_TRACE=tracefile.xml

unset JAMAL_TRACE

Debugging

-Djamal.debug=http:8080

export JAMAL_DEBUG=http:8080

unset JAMAL_DEBUG

since 1.0.0 (core)

comment is used to insert comments to the input. It can also be used to enclose definitions without side effects, but this is not recommended. For that purpose, use the [block](#block) macro.

For more about definition scopes and exporting, read the section about export. In that section we discuss the evaluation order of the macros in great detail.

will generate

Note that this is important to use the @ character in front of the keyword comment to make it a real comment. If the macro character # is used, like {#comment comment_text} then the comment_text part will be evaluated. If there is some macro in the comment_text that modifies the evaluation state, then the modification will happen. For example, if the comment_text defines some global macro, then the defined macro can be used after the comment block.

It is safe to say always to use {@comment …​}. When the code needs the evaluation, then use the [block](#block) macro.

since 1.0.0 (core)

block is technically the same as comment. It is recommended to use the comment macro with the @ starting character. In that case the content of the comment is not interpreted by Jamal. Use the block with # to have the content interpreted. Block should be used to enclose definitions to a scope level. Note that the result of the macro {#block …​ } is an empty string.

For more about definition scopes and exporting, read the section about export. In that section we discuss the evaluation order of the macros in great detail.

since 1.0.0 (core)

The macros begin and end start and close a local definition scope. This is similar as using a {#ident …​ } macro to create a new scope for the evaluation of the macros inside it. The text between the {@begin} and {@end} will be evaluated in a new scope. Any user defined macro in this scope is going to be local, unless exported or has a : in the name.

It is recommended to use begin and end when the structure is complex, and it is more readable to use the begin, end macros than a simple block. To ensure that all begin has an end you can name the blocks. You can put an arbitrary string after the macro name begin and if you do then you have to repeat the same string after the macro name end. The spaces from the beginning, and the end of the parameter are trimmed.

will result

First Z is defined to be the string "1" (without the quotes). Then we start a new scope, named alma. Inside this new scope we redefine the macro Z to be 2. When we use Z writing {Z} then it will output 2 here. We also define S to be 2 and we also export it. Exporting means that the definition will get to the surrounding scope. After that we close the scope named alma. When closing the scope there is an extra space after the name, but it does not matter. Now S is 2, because it was exported and Z is 1, because it was defined to be 1 on this level and was not exported from the nested level.

For more about definition scopes and exporting, read the section about export. In that section we discuss the evaluation order of the macros in great detail.

Scopes are nested, stacked into each other any levels. Scopes are opened by many things, like macro start, or including a file. You can close a scope using the macro end that was opened with a matching begin. You cannot not close a scope using end that was opened by something else. For example, you cannot get into the scope of the including file putting a pair-less end macro into an included file. This will trigger a processing error. It is also an error if a {@begin…​} does not have its {@end…​} pair in the main file or in any included or imported file.

• since 1.0.0 (core)

• since 1.6.4 default as special macro

• since 1.7.4 default macro first argument, macro can be defined to evaluate verbatim

• since 1.7.6 optional and extra ignored arguments

Define basics

{@define id(arguments)=body}

{#define id(arguments)=body}

{@define id=body}

{#define id=body}

{@define id()=body}

{#define id()=body}

{@define fox(x)=The brown fox jumps over the high x}{fox fence}

The brown fofence jumps over the high fence

{@define z(*a,*b,*c,*d)=When a *a can *b then *c can *d}
{z /leopard and a *c/run/fish/fly}

When a leopard and a *c can run then fish can fly

Special User Defined Macros

Macro redefine

{@define a=1}{@define a=2}{a}

2

{@define a=1}{@define ? a=2}{a}

1

{@define a=1}{@try! {@define! a=2}}

The macro 'a' was already defined.

{@define x=1966}
{@define a={x}}
{a} evaluates first to the macro `x` and then that evaluates to 1966
{@verbatim a} stops before the evaluation of the result of the macro and this way it is the same as
{@define ~ a={x}}{a}

1966 evaluates first to the macro `x` and then that evaluates to 1966
{x} stops before the evaluation of the result of the macro and this way it is the same as
{x}

{@define x=1966}
{@define a={x}}{a} is the same as
{@define ~ a={x}}{!a}

1966 is the same as
1966

Global Macros

{@define A:Z=1}
{@begin alma}
{@define A:Z=2}{A:Z}
{@end alma }{A:Z}

2
2

{@define :Z=1}
{@begin alma}
{@define :Z=2}{Z}
{@end alma }{Z}

2
2

{@define :Z=1}
{@begin alma}
{@define Z=2}{Z}
{@end alma }{Z}

2
1

{@try! {undefinedMacro}}
this is empty string >>{?undefinedMacro}<<

User defined macro '{undefinedMacro ...' is not defined.
this is empty string >><<

{@options emptyUndef}>{?notDefined}<>{notDefined}<

><><

Default macro

>>{?hoppala}<<
{@define default=wupppss}{hoppala}
>>{?hoppala}<<

>><<
wupppss
>>wupppss<<

{@define default=wupppss}\
{#ident {@undefine default}>>{?hoppala}<<}>>{?hoppala}<<

>><<>>wupppss<<

{@define default=wupppss}\
{@options :noUndefault}>>{?hoppala}<<{@options ~:noUndefault}>>{?hoppala}<<

>><<>>wupppss<<

{@define default($x)=wupppss $x}{hoppala zumzum}
>>{?hoppala zumzum}<<

wupppss zumzum
>>wupppss zumzum<<

{@options :lenient}
{@define default($_,$x)={@if |$x|<$_>$x</$_>|<$_/>}}{hoppala}
{bikkala zz}

<hoppala/>
<bikkala>zz</bikkala>

{@define default(...)=DEFAULT}{huppala}{bumbala}{wopsydosy}

DEFAULTDEFAULTDEFAULT

{@define enclose(a)=<!!a!!>}
{enclose this text}

<!!this text!!>

{@define enclose(a)=<!!a!!>}
{enclose /-}

<!!-!!>

{enclose -}

<!!!!>

{@define enclose(a)=<!!a!!>}
{@define dash=-}
{enclose {dash}}

<!!-!!>

{enclose |+this text}
{enclose ||this text}
{enclose | this text}

<!!+this text!!>
<!!|this text!!>
<!! this text!!>

{@options ~lenient}
{@define x(a,b)= |a b|}
{@try!{x/s/h/t}}

Macro 'x' needs 2 arguments and got 3
>>>s
>>>h
>>>t

{@define x(a,b)= |a b|}{@options :lenient}
{x/s/h/t}

|s h|

{@define parameterless=this is a simple macro} macro defined
{parameterless}
{@define withparams(a,b,%66h)=this is a b %66h} macro defined
{withparams/A/more complex/macro}
{withparams/%66h/%66h/zazu} <- %66h is not replaced to zazu in the parameters
{@define? withparams(a,b,c)=abc}here 'withparams' is not redefined
{withparams|a|b|c}
{#comment {@define x=local}{@define :x=global} {#define :y=here we are {x}}}
{y}
here we are {x}

 macro defined
this is a simple macro
 macro defined
this is A more complex macro
this is %66h %66h zazu <- %66h is not replaced to zazu in the parameters
here 'withparams' is not redefined
this is a b c

here we are local
here we are global

Pure Macros

{@sep [ ]}[@define a=[z]{z}][@sep]{@define z=3}{a}
{@sep [ ]}[@define a():=[z]{z}][@sep]{@define z=3}{a}

3{z}
[z]3

Optional Arguments

{@options ~lenient}{@comment just to be sure}
{@define a(a,b,...c,d,e)=>a< .b. /c/ |d| (e)}
{a :1:2:3}

>1< .2. /3/ || ()

{@define a(...a,b,c,d,e)=>a< .b. /c/ |d| (e)}
{a :1:2:3:4:5}
{a :1:2:3:4}
{a :1:2:3}
{a :1:2}
{a :1}
{a}

>1< .2. /3/ |4| (5)
>1< .2. /3/ |4| ()
>1< .2. /3/ || ()
>1< .2. // || ()
>1< .. // || ()
>< .. // || ()

{@try! {a :1:2:3:4:5:6}}

Macro 'a' needs (0 ... 5) arguments and got 6
>>>1
>>>2
>>>3
>>>4
>>>5
>>>6

{@define a(...a,b,c,d,e...)=>a< .b. /c/ |d| (e)}
{a :1:2:3:4:5:6}

>1< .2. /3/ |4| (5)

• since 1.6.6

undefine can be used to undefine a macro. Undefining a macro works the same way as definition: in scope. When you undefine a macro it will be undefined only for the current scope and later for any lower newly opened scope. Undefining a macro does not affects the definition of the macro in any higher level.

You can undefine a macro on the global level the same way as you can define a macro on the global level.

Simple undefine on one single scope

{@define fruit=apple}{fruit}{@undefine fruit} |{?fruit}|

apple ||

Undefine an inherited macro in a local scope

{@define fruit=apple}{fruit} {#ident {@undefine fruit} |{?fruit}|}  |{?fruit}|

apple ||  |apple|

Being undefined can be exported

{@define fruit=apple} {fruit}\
{#ident {@undefine fruit} |{?fruit}| {@export fruit}}\
|{?fruit}|

apple|| ||

Undefine, export and redefine

{@define fruit=apple}\
global scope: {fruit}
 {@begin scope_1}\
   scope_1: {fruit}
   {@begin scope_2}\
     scope_2: {fruit}
     {@undefine fruit}{@export fruit}\
     scope_2: {?fruit}
     {@define fruit=pear}\
     scope_2: {fruit}
   {@end scope_2}\
   scope_1: {?fruit}
 {@end scope_1}\
global scope: {fruit}

global scope: apple
    scope_1: apple
        scope_2: apple
          scope_2:
          scope_2: pear
      scope_1:
 global scope: apple

since 1.0.0 (core)

eval interprets the content of the macro. The text written after the macro keyword eval is evaluated as a script. The scripting language can be defined following a / character. If there is no script type defined (or jamal is defined) then the content will be evaluated as normal Jamal macro text. Otherwise, the script engine named is used.

There are three ways to use the macro in one of the following formats:

If eval is followed by / character then the next identifier is the type of the script. White space characters before, and after the /, as well as after the script type name are ignored. You can use any scripting language that

• implements the Java scripting API and

• the interpreter is available on the classpath when Jamal is executed.

If the script type is jamal then it is the same as if there was no script type specified. You may need the explicit specification of jamal when the content of the macro to be evaluated starts with the / character.

If character following the keyword eval is * then the scripting type is jamal and the evaluation is repeated until all macros are resolved. The macro assumes that all the macros are resolved when the evaluation of the text does not change any more. This may lead to infinite loop, therefore there is a built-in limit. eval* evaluates the macro input at most 100 times. This limit can be changed with the option evaluateLoopLimit. This name can also be used as a user defined macro to set this option globally, for example:

This option has two aliases limit, and max. The aliases can be used interchanged between [ and ] characters following the \* character, for example:

The following two examples show how eval can be used to evaluate simple arithmetic expressions using the Java built-in JShell interpreter. Note that in the second example the macro eval is preceded with the character # therefore the body of the macro is parsed for other macros before eval itself is invoked. That way {a} and {b} are replaced with their defined values and eval itself sees 1+2.

will result

Starting with version 1.5.0 Jamal introduces the ! modification character. When this character is used in front of a macro, then the result of the macro will be evaluated like it was surrounded with {#eval …​ }. This can be used in the case of user-defined macros as well as in the case of built-in macros. Note, that in the case of user-defined macros the result of the macro will be evaluated by default. Using the ! in front of a user-defined macro will repeat the evaluation. You can use more than one ! characters in front of a macro. The macro result will be evaluated so many times as many ! characters there are. In case of a user-defined macro the "so many times" should be interpreted as one, by default plus N times.

For example:

and the output is

In this example the macro userDefined is {`c}. User defined macros values are evaluated after the evaluation of the macro itself, therefore when we use {userDefined} we get {c}. The back-tick character before the macro after the { is identical to the use of an ident macro: {@ident {c}}.

When there is a single ! in front of it, then the repeated evaluation results {b}, and so on. To get the final result, in this case we need three ! characters, meaning four post evaluation.

You can use this character together with the back-tick macro modifying character. They do not eliminate each other, because the back-tick prevents pre-evaluation and ! provides extra post evaluation. When using ! to evaluate the result of a macro you cannot specify any scripting language. The evaluation will be Jamal macros evaluation.

since 1.10.0

The macro defer evaluates its input only when the processing is finished. It can be used to execute some macros at the end of the execution, which have side effect, or to modify the final output using some macros.

At the place of the the macro the value of the macro is an empty string. The result of the evaluation, since it happens after the whole input was already processed and we have a final output, is also ignored. There is, however, a possibility for the content of the macro to read the final result and also to modify it.

When the input of the macro is executed the global macro $input contains the output of the processing. The naming may be strange at first, but consider that this string is the input for the deferred macro evaluation.

If this evaluation defines the global macro $output the value of the macro will be used instead of the original output.

The name of the input and output macros can be changed using options. The options

• $input with the aliases input, and inputName can specify the name of the input macro.

• $output with the aliases output, and outputName can specify the name of the output macro.

As usually the option name can be defined as a macro, like {@define $input=$INPUT}, the aliases can only be used as macro options, like

In the followings we will give some examples.

This example is the simplest. It defers an empty string.

When the empty string is evaluated nothing happens, the original output is retained:

The second example is a bit more complex:

This example defines a user defined macro that duplicates the input. In the deferred evaluation the macro $output is defined and it will be the same as the $input repeated.

The next example demonstrates that

• the name of the input and output macros can be redefined, and

• multiple defer macros are executed in the order as they were evaluated in the input during the Jamal processing.

Note that the definition of the macros $input and $output are local to the block and therefore they have no impact on the second defer. Since the {#define OUT=|{IN}|} is defind before {#define $output={$input}} the text Framed is enclosed first between | characters and only the result is enclosed between \*.

The output is:

The next example is almost the same as the previous. It uses macro options to set the input and output names for the first defer macro:

In this case there is no need for the block macro, since option setting is always local to the macro where it is set. The result is the same as in the previous case:

The next example shows that you do not need to use the input at all to set the output.

In this case the output is an empty string

The following sample shows that the macros used in the text of defer have to be defined only when it gets executed. In the example the macro doplikate is not defined when used in defer only at the end of the file.

The output is:

The following example is a bit more complex. In this case the code uses the escape* macro.

In this case there are two deferred operations. The first one is the unescaping of escape*. This is executed first, because the use of the first escape* macro precedes the macro defer. When this unescaping is finished the result of the processing will be {mememe}Mememe?. It contains a string that can be interpreted as a macro. For this reason the macro doplikate is defined as a "verbatim" macro. This is signalled by the ~ character after the define keyword. Verbatim user defined macros are not post evaluated. When doplikate is invoked in the defer then {mememe}Mememe? will be converted to {mememe}Mememe?{mememe}Mememe?. This result also will not be evaluated again.

However, when we set the macro $output in the line {#define $output={doplikate/{$input}}} why {mememe}Mememe? is not evaluated. The reason is that the user defined macro $input holding the final result of the Jamal processing is also a verbatim macro.

The output is:

Although $input is verbatim, $output does not need to be. This macro is used temporarily by the deferred action to change the output of Jamal processing. The following example shows that the value of $output is not available as input for defer. The macro $output can only be set by the input of defer and $output is undefined when the evaluation starts:

This example tries to use the value of the macro $output in the deferred code. The deferred code can rely on the macros defined during the Jamal processing. Note, however that only the top level macros are available as all other macros are out of scope and only those, which were defined at the end of the Jama processing.

The macro $output, however, is used in a special way. Because it serves to pass a modified output from the deferred code it is undefined before the deferred code start. The result of this evaluation is:

The macro $output gets undefined before the evaluation of each deferred code. If we extend the previous example and define the output in one deferred code and try to use that in the next one it will still be undefined.

The output is still:

The last example shows that other macros survive and can be used in subsequent deferred actions. If the macro doplikate is defined in a deferred action then the subsequent deferred actions can use the macro:

And the output is:

since 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.

is

on the machine where the original README.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. 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.

since 1.0.0 (core)

import opens a file and reads the content of the file and interprets it as Jamal macro file. Anything defined in that file will be imported into the scope of the current file. If the macro opening and closing strings are redefined using the sep macro it will change for the file that imported the other file. Any user-defined macros defined in the top-level scope of the file will be available in the importing file.

Note that the top-level scope of the file may not be the same as the global scope. If the importing happens

• from an included file, or

• from inside a block of from inside a macro, or

• in scope that was started with a begin macro

then the "top-level-scope of the file" is the one, that contains the import macro. If anything is defined into the global scope in the imported file then those macros will eventually be in the global scope and available to anyone later.

The output that the processing of the imported file generates is discarded.

The syntax of the command is

{@import file_name}

The name of the file can be absolute, or it can be relative to the file that imports the other file. Any file name starting with the letters res: are considered to be resource files in Java. This makes it possible to load macros that are provided with JAR libraries and are on the classpath. Any file name starting with the letters https: are downloaded from the net.

The option [top] can be used along with the import. In this case a relative file name is relative to the main file that imports the other files. It is not possible to to step one or a few levels up in the import hierarchy. The only two possibilities are to import as file relative to the current one or the top level one.

Note, however, that using the option [top] does not change the scope of the imports. The definitions will be exported to the importing scope. This option only changes the base directory for the file name calculation.

Use import to import user-defined macro definitions.

Because the textual output from the evaluation of the file is discarded feel free to use text in the file to be imported as documentation. There is no need to enclose such a text into a {@comment …​} macro.

Starting with version 1.5.0 the import macro looks into the file before evaluating it. If the very first two characters in the file are {@ then it evaluates the content using { as macro opening string and } as macro closing string. This way you can freely import resource files provided in JAR file or through the net even if you use different macro opening and closing strings. Such import files cannot redefine the macro opening and closing string unless file importing also uses { and }.

• since 1.0.0 (core)

• since 1.7.3 verbatim include

include reads a file similarly to import, but it starts a new scope for the processing of the included file, and it also results the content of the file included into the main file.

Use include to get the content of a file into the main output.

The file included can define user-defined macros. These macros are available only inside the included file unless they are exported. The included file may redefine the macro opening and closing string, but this works only in the included file only. The file that includes the other file is not affected by the redefinition of the macro opening and closing string.

The macro itself is replaced by the output generated by the processing of the included file.

The syntax of the command is

{@include file_name}

or (starting with 1.7.3)

{@include [verbatim] file_name}

If the option verbatim is specified then the file is inserted into the output as it is without processing. This option can also be used in the form

{@include [includeVerbatim] file_name}

This version of this option name can also used as an option set using {@options includeVerbatim}. In that case all includes will be executed without processing the read file where and when the option includeVerbatim is true.

Note that the macro include is NOT inner scope dependent. It means that {#include {@options includeVerbatim} …​} will not work. The options set inside the include macro have no effect when the include macro is executed.

The option set outside, like {@options includeVerbatim}{#include …​} will work. However it will change the behaviour of all include macros executing later, while the option is in effect.

The name of the file can be absolute, or it can be relative to the file that includes the other file. Any file name starting with the letters res: are considered to be resource files in Java. This makes it possible to load macros that are provided with JAR libraries and are on the classpath. Any file name starting with the letters https: are downloaded from the net.

The option [top] can be used along with the include. In this case a relative file name is relative to the main file that includes the other files. It is not possible to to step one or a few levels up in the include hierarchy. The only two possibilities are to include as file relative to the current one or the top level one.

The number of includes are limited to 100 in depth. A file can include another, which can again include another and so on, but only to the maximum depth of 100. This depth limit is set because an included file can be included many times. It is possible to implement recursion including of files. If the recursion does not end the include macros would drive the macro resolution into an infinite loop. This limit prevents this to happen.

The limit can be modified setting the environment variable JAMAL_INCLUDE_DEPTH.

since 1.0.0 since 1.7.4 can define an alias for an already loaded macro

use declares a Java class as a built-in macro or defines an alias name for an already loaded built-in macro.

How macros are loaded

Defining the use of a Java Class as a Macro

{@use global javax0.jamal.scriptbasic.Basic as scriptbasic}

{@use javax0.jamal.scriptbasic.Basic as scriptbasic}

{@use javax0.jamal.scriptbasic.Basic}

Defining the use of a Java Class as a Macro

since 1.0.0 (core)

The macro script defines a user-defined macro that is interpreted as a script. The syntax of the command is

If script is followed by / character then the next identifier is the type of the script. If this is missing the default, JShell is assumed. You can use any scripting language that implements the Java scripting API and the interpreter is available on the classpath.

The parameters are handled differently from the parameters of the user-defined macros defined using the define built-in macro. In that case, the parameter strings are replaced by the actual value strings during evaluation. In this case, the parameters are used as global variable names. Using these names, the actual values are injected into the context of the script before evaluation.

This also implies that you do not have the total freedom of parameter names. For define we can use any string as a parameter id so long as long it contains no , and no ). In this case, you should care about the syntax of the scripting language used. The parameter names have to be valid identifiers in the scripting language as they are used as such.

The value injection converts the actual value of the parameter to script values. Because the parameters are injected into global variables Jamal performs some conversions. Without this, all the scripts that use some integer or floating-point calculation were supposed to convert them first from the string.

Therefore, Jamal tries to convert the actual parameters.

• First it tries treating it as an integer. If it succeeds then the global variable having the name as the parameter will hold an integer value.

• If the conversion to an integer does not work then it tries the same with double.

• If that is also not feasible then it will check if the actual value is lower case true or false. In this case the global variable of the script will be a Boolean value.

• In any other case, the global variable will get the actual value as a string assigned to it.

The actual scripting implementation may not have Integer, Double or Boolean type but there will be some script type corresponding.

The following sample shows a simple script that implements a looping construct using JavaScript. The source Jamal file:

The output generated by the Jamal preprocessor:

Note that the JavaScript code itself contains the macro opening and closing strings. This does not do any harm so long as long these are in pairs. It is a better practice to change the separator characters to something that cannot appear in the body of the script macro.

Starting with version 1.3.0 Jamal support the JShell built-in scripting engine. You can define JShell as script type. In this case the content will be passed to the Java built-in JShell engine. When the script is invoked the result of the macro will be the string that is printed by the JShell script. If this is empty then the value of the last Java shell snippet will be used. The argument names have to be valid Java identifiers. When the script is invoked they will be defined as String, long, double or boolean variables. They will get the actual values of the parameters. The type depends on the actual value. If the value string can be interpreted as a long then it will be converted to long. If the string is not a long, but can be converted to double then the variable will be double. If the string is either true or false case insensitive then the variable will be boolean. In any other case the variable will be declared as String.

In short, the arguments to a script macro will be converted to the following types in this order, whichever first succeeds:

• int

• double

• boolean

• String

For more information and details see the section xiii. JShell

since 1.3.0 (core)

The Java built-in scripting engine JShell can be used to define macros. The macro script and the macro JShell can be used to define JShell scripts.

The macro JShell can be used to define methods, classes, variables and so on. The macro script is to define a script macro that later can be invoked like any other used defined script macro.

When the macro JShell or script is used the result is empty string. When the script is invoked the output of the macro will be what the script prints out to the standard output.

The following example defines a global method, a script using the method and then it invokes the script.

It simply prints

The macro JShell defines the method hello(). The macro script is a script macro that has one argument. Note that this argument is also the name of the global variable world. This global variable is used in the JShell snippet defined above but this is not an argument to the method. When we use the line

Jamal will invoke the JShell interpreter executing

first, and then

Since the method hello() prints out to the standard output Hello, My Dear this is the result of this macro.

If there is some error in the code of the snippet then Jamal will throw a BadSyntax exception. In this exception the causing exception is included if there is any. This causing exception should give some clue to find out what the issue is. If that does not help then using the interactive JShell program should help.

Creating a JShell execution environment is expensive. To do that the Java starts a new JVM process for the JShell. Many Jamal macro processing do not need the extra JShell. It would slow down Jamal if we created the JShell process for each and every processor even when it is not needed. The JShell environment is created only when it is unavoidable. It is when the processing uses the first time a JShell type script. It not when the script is defined. It is when the defined script is used. In the above example the JShell interpreter is created when the {hello …​} macro is evaluated. Only at that point all the prior definitions that were defined in any {@JShell } macro are fed into the JShell interpreter.

The consequence is that you do not need to worry about the performance when you design a macro library. The processed files can bravely import the macros even if they declare JShell usage. It will not slow down the processing creating a JShell engine, only when the JShell engine is needed.

Another important side effect of this optimization is that you will not get an error message for an erroneous {@JShell } macro until the JShell interpreter is used. When you design a macro library it is not enough to import the library to discover possible errors in the JShell scrips. The scripts have to be used to manifest the error.

• since 1.0.0 (core)

• since 1.5.0 multi-argument for

• since 1.6.3 backtick string separator value list

• since 1.7.3 options between [ and ]

• since 1.7.8 option evalist

The macro for can be used to repeat the same text many times. This macro has two forms. The syntax of the macro is either

or

The variable or the multiple variables can be used in the content and will be replaced for each iteration with the respective element on the comma-separated list. When there are multiple variables then the sub-list of the values is separated using the | character. Both the command and the | character can be modified to use something else instead of these characters.

The list of the values can also be separated by other strings. If the macro $forsep is defined, like in

then the arguments will be separated by one or more spaces. The string between the ( and the ) will be split using the string defined in $forsep as a regular expression.

Similarly, if the macro $forsubsep is defined, like in

then the values for the different variables will be separated by a semicolon.

Note that the macros $forsep and $forsubsep can also be defined inside the for macro body in case the macro is used with the # character at the start. In this case the definition of these macros is limited to the evaluation of this very for macro.

Starting with version 1.7.3 you can also define these options locally using the format

where the options can be

• $forsep, separator to specify the separator regular expression

• $forsubsep, subseparator to specify the sub separator regular expression

• trimForValues, trim to trim off the sapces from the values

• skipForEmpty, skipEmpty to skip empty parameter list (see below)

• lenient for lenient operation (see below)

• evaluateValueList, or evalist to instruct the loop that the list of the values between the ( and ) has to be evaluated.

For example the macros:

will result

In this case the value of the macro $forsep is effective inside the for, but it is undefined outside. Another example:

will result the same output:

The number of the actual values separated by | character should be the same as the number of the variables in the for loop. If this is not the case then the macro evaluation will throw a bad syntax exception. This can be suppressed with the option lenient. If the option lenient is used then extra values are ignored and missing values are presented as empty strings. Note that this same option controls how user defined macro arguments are paired to the parameters.

Starting with version 1.5.3 you can fine tune how a for loop treats the empty elements. By default, the empty elements in a for loop value list represent empty strings. The loop body will be rendered with these values replacing the loop variable with an empty string. In a situation like that the use of the option lenient is also a must if the loop has multiple variables. In that case the empty value will be split into a one, empty string value for the empty value in the loop and this has to be assigned to the multipled loop variables. For example

will not work, because the empty string cannot be split into two strings (it results one empty string when it is split). On the other hand the following code will work

and it will result

as both k and z are empty strings. Here, you can see two versions. The first one is declaring the lenient option inside the for macro, the second one is using the option, which is more coincise and shorter.

This default behaviour can be altered using the option skipForEmpty. If this option is used the for loop will skip the empty values. The previous example with this option:

will evaluate to an empty string. Also note that in this case there is no need to use the option lenient. That is because the empty value is skipped and there is no issue splitting it up into a less number of values than the number of the loop variables.

The example above contains one loop value and that loop value is an empty string. There can be more than one empty values in a for loop and empty and non-empty values can be mixed. The option skipForEmpty and the alias skipEmpty works in any of those cases. For example:

will also result an empty string and

will result

Sometimes the values for the for loop come from some macro. In that case the for macro should start with the # character, otherwise the macro will not be evaluated to the list of values. For example:

will result

That is because the content of the macro for is not evaluated before the for loop is executed because we used the @ character. The result of the for loop is not evaluated. We will have to attend to that, but first we have to solve the issue that the macro list is not evaluated. To do that we need to use the # character in front of the for loop.

will result an empty string:

The reason is that the content of the for macro is evaluated before executing the macro itself. That way the macro reference {list} will become x,y,z, but the same time the part, which is after the = is also evaluated. The evaluation will define the macro z to be zz, but this macro is within the scope of the for macro. As soon as the for macro execution is finished the definition of z is lost. What we want is to protect the body of the for macro from evaluation before for the macro is executed and we want it to execute after.

will result

The macro {@ident …​} is evaluated and its result is the content of the macro and it is not evaluated further before the evaluation of the macro for. The macro for gets evaluated and then the output is evaluated because the macro is preceeded with the back-tick character, which is a shorthand for the core built-in macro eval. This evaluation defines x, y and z.

Because the case that we want to evaluate the list part of the for loop but not the body part is so common there is an option that helps with this. The option evaluateValueList (alias evalist) instructs the macro for to evaluate the value list before iterating through it.

will result

We still need the ! character in front of the for but we could get rid of the ident macro and the extra level of nesting.

Sometimes you may need to do a for loop over values that contain the ) character. With the conventional form of the for macro it was not possible, because the first ) character terminates the list of the values. Jamal 1.6.3 introduced a new, backward compatible format for the for macro.

Instead of the ( and ) characters it is possible to use an arbitrary string to denote the end of the values. When the first character after the keyword in (after optional spaces) is the backtick character then the string till the next backtick character will be used to denote the end of the values. The starting and ending backtick should also be part of the string closing the values.

For example the following

will result

Note that this alternative format can only be used for the values list and not for the variables. The variables of the for loop should always be listed between ( and ) characters.

The if macro makes it possible to evaluate the content conditionally. The syntax of the macro is:

Here we use / as a separator character but this is not hardwired. The if macro uses the Standard Built-In Macro Argument Splitting to parse the body of the macro.

The result of the evaluated macro will be the then content when the test is true, and the else content otherwise.

When no options are specified the test is true, if

• it is the literal string true (case-insensitive),

• it is a signed or unsigned integer number, and the value is not zero,

• it is any other string that contains at least one non-space character, except

• when the test is the literal string false (case-insensitive).

The literal false is false using any combination of upper and lower case letters with or without surrounding spaces.

The evaluation of the test string can be modified using options. There are 8 options.

The first three options are "boolean" options. It is enough to use their keyword between the [ and ]. (See examples later.)

• blank will test true if the test string is blank, it is empty or contains spaces only.

• empty will test true if the test string is zero length and does not contain even spaces.

• not will negate the test result.

• or can be used with the numerical options when more than one test is needed. When you specify more than one equals, lessThan, or greaterThan option the test is true if any of the tests is true. This is the default behaviour, so this option is not needed. Setting or=false has no effect and is not the same as using the option and. This option is included only to add readability if needed.

• and after the evaluation of multiple tests. When this option is used the test is true if all of the tests are true. This option cannot be used together with the option or and is also needs multiple numeric options.

Note that the options and and or are simple boolean options. They can appear only once in the list of the macro options. You cannot write {@if [equals=3 or equals=4 or equals=6] /9/a/b}. It is recommended to use the or or the and option following the first numeric option. For example, {@if [lessThan=7 and greaterThan=2] /6/it is in (2,7)/out of range}`. If you feel it is more readable you can put these options at any place in the list.

The following options will do numerical comparison. When any of them are used then the test string is converted to a number. If the test string is not a number an error will happen. These options are integer options, which means that you have to specify a number following them like lessThan=55.

• lessThan (aliases less,smaller, smallerThan) is true if the number is less than the value.

• greaterThan (aliases greater, bigger, biggerThan, larger, largerThan) is true if the number is greater than the value.

• equals (aliases equal, equalsTo, equalTo) is true if the number is equal to the value.

There is no separately "less than or equal" and "greater or equal" option. If, for example, you want to test that a number is greater than or equal to a certain value then you can use the greaterThan and the equals options together. An alternative is to use the lessThan option along with the boolean not option.

The following examples show a few cases, as demonstrations:

since 1.0.0 (core)

ident is an extremely simple macro. It just returns the body of the macro. The name stands for identity. It is helpful in some complex cases when you need to fine-tune the macro evaluation order. It is the case when Jamal should not evaluate some macro while it should others in a local scope. For example:

When we define the macro c we do not want to evaluate {a}. There are two reasons for this. One is that at that point, a is not defined. The other is to use the actual definition of a whenever the macro c is used. On the other hand, we want to evaluate b. This way, c will become {a}92. When later c is used, and we already defined a as 14, then the final result will be 1492.

Note that c is defined using the # character before define. At the same time, we used @ in front of ident. Jamal evaluates the content of define. In this evaluation {@ident {a}} is evaluated and {b} is also evaluated. {@ident {a}} becomes {a}. {b} becomes '92`. This way c will become {a}92.

If we redefine later a to some different value then c will follow this change. If we redefine b the value of c will still remain 1492 assuming a is still 14.

You can also use this macro to enclose some text into a block where the definitions are local. For example, you may want to modify the macro start and end strings temporarily. In that case, you can use the sep macro at the start and use the sep macro without argument to reset the previous value. You can also enclose the setting of the macro start and end string into an ident block.

Specific use of ident is to insert a "null length separator" into the text. Imagine that the macro start and close strings should be and . We may want to use those because the curly braces are used in the text frequently, and so are the single ( and ) characters.

As an example, we may want to define a macro that creates a markdown image reference:

This example needs a space after the closing ) character at the end of the image url. If we did not have this space, the macro would be closed one ) sooner than needed. To avoid that, we insert an extra space after the image reference. Usually, it is not a problem. In some situations, however, we do not want to have that extra space there. It is possible using ident.

The macro @ident will prevent Jamal from interpreting the ) character after the .png as the first character of a macro closing string. At the same time @ident produces no character, not even a space in the output. You can also use the macros comment and block the same way.

Be aware that the macro ident consumes the white spaces (including newlines) that follow the ident keyword. It is to avoid extra white spaces when tabulation gives better readability. If you need the whitespace (e.g., newline) in the output, you can put those in the ident macro.

Starting with Jama 1.5.0, there is a built-in language syntax similar to ident. If a macro is preceded with a

backtick character, then the macro will not be evaluated. The above example, which is

can also be written as:

This built-in "ident" can be used many times if you want to postpone the macro evaluation multiple times. You can have

or

as many times as it makes sense. You can use this macro modification character together with the ! character. There is no restriction on ordering the ! and the backtick characters in case they are used together. If you use many of them in extreme cases, you can mix them. Note, if the macro does not get evaluated fully, Jamal may not preserve the order of these characters in the output.

since 1.0.0 (core)

verbatim is a special macro, which affects macro evaluation order and is used for advanced macro evaluation. To understand what it does, we have to discuss first how Jamal evaluates the different macros.

Jamal parses the input from the start towards the end and copies the characters from the input to the output. Whenever, when it sees a macro then it evaluates the macro, and the result of the evaluation is copied to the output. This evaluation is done in three steps, two of those are recursive. Let’s have a simple example:

The macro a is defined simply. It is this is it. Whenever a is evaluated it will result the string this is it.

The macro b has the value {a}. When macro b is defined the content {a} is not evaluated before the definition because there is a @ before the define. When b is evaluated it results {a} and then before using this output in place of the use of the macro b this result is evaluated by Jamal as a new input. This second recursive evaluation will result in the string this is it.

The macro c is defined using the # character before the keyword define, therefore Jamal will process the body of the macro before processing the built-in macro define itself. Essentially, it will evaluate {b} first. It will put the resulting characters after the = sign in the definition of c and then it will evaluate the define built-in macro.

As we discussed above when this time {b} is evaluated it results {a}, which also gets evaluated and then it results this is it. Therefore, the value of the macro c is this is it and that is what we see in the output:

This way the evaluation of a macro is done in three steps:

1. Evaluate the body of the macro unless the macro is built-in and starts with the character @. For this evaluation Jamal starts a new scope and evaluate the macros following these three steps.

2. Evaluate the macro itself. If it is a built-in macro then it calls the evaluate() method of the Java class that implements the macro. If the macro is user defined then it evaluates as described in the section define.

3. If the macro is user-defined or starts with a ! character then Jamal evaluates the output of the macro. If it contains macros then evaluate those using these three steps.

As you can see the first, and the last steps are recursive steps. The first step can be skipped using the @ character, but only in case of built-in macros. The second step cannot be skipped, and after all, there is no reason to do so. However, the third step can be

• skipped using the macro verbatim if the macro is user defined, or

• enforced using a ! in front of the @ or # character if the macro is built-in.

The use of the ! character in front of a built-in macro is similar to the use of the macro eval. For example

can be shortened as

The only difference is that the eval macro consumes the white-space characters at the start of its argument. In the example above the {#eval macro …​} before its evaluation is

The body starts with a new line. The macro eval deletes this new line, while using the ! in front of the macro does not.

The syntax of the verbatim macro is the following:

The verbatim macro has to be followed by a user defined macro use. If we modify the previous example to use verbatim we can do it the following way:

In this example {@verbatim b} is the same as {b} in the previous example. The only exception is that after b is evaluated the result is not processed further for macros. It is used directly as the value of the new macro c because of the verbatim keyword. The value of c will be {a}. Also, when we use {c} the result of c is scanned as a third step for further macros. In this case, there is one because the value of the macro c is {a}, that further evaluates to this is it. On the other hand when we use {@verbatim c} then the result {a} is not processed any further.

Note that the macro verbatim is a special one because it is hardwired into the evaluation logic of Jamal and it is not a "real" built-in macro. In other words, if there are user-defined macros and built-in macros then verbatim is one level deeper built-in than the other built-in macros. To understand this may be important if you want to write your own built-in macros as Java classes. You cannot "redefine" verbatim.

You cannot use verbatim together with the ! macro modifying character. Their meaning is exactly opposite.

Fine points of macro evaluation

since 1.0.0 (core)

This macro can be used to change the macro opening and closing string. In the examples, in this documentation, we use { as the opening string and } as the closing string. Jamal itself does not impose any such predefined setting.

The syntax of the command is

If both the start and end strings are a single character, for example [ and ] then you can use the simple form:

A two-character argument to the macro sep will use the first character as macro opening string and the second as macro closing string. You can also use three character. For example:

The separating character between the opening and closing string characters can be any character except any of the opening or closing string character. It is also possible to use the format

separating the opening and closing strings with spaces. This format is very readable and convenient in many cases. For example, you can specify

and other, similar opening and closing strings. There are some definitions that can be misleading. For example, the following declarations can be interpreted by humans in multiple ways.

Many human readers would tend to think the second. The syntax however matches the \S+\s+\S+ pattern. To avoid any such ambiguous situation Jamal does not allow the use of this form when

• the opening string

• starts and ends with the same character

• is at least three characters long, and

• it does not contain the first character inside

or

• the closing string

• starts with the same character as the opening string

• at least two character long

• does not contain this character after the first character.

These seem to be complex rules. They contain a bit of heuristics. They were designed to let the users use the most readable format of the sep macro. The same time they help avoid unreadable declarations and errors.

If in doubt then you can always use the last, definitive syntax that does not rely on any heuristics. This syntax is described in the followings.

If the syntax does not match and of the previous cases, Jamal will use the syntax that is defined with the following "regular expression" like line:

There can be whitespace characters after the macro name sep, and at the end, but these are optional. The first non-space character is used as a separator character that separates the macro opening string from the macro closing string. It is usually the / character, but it can be anything that does not appear in the opening string. Prior to 1.3.0 this character could appear in the closing string, although it is not recommended. Starting with 1.3.0 it is an error. It is possible to use spaces inside the macro opening and closing strings, but it is not recommended. Leading and trailing spaces of the opening and closing strings will be trimmed off. That way

are all the same. Note though that {@sep / [[ /]]} would be logical in the above list, but it is missing. There is only one space (\s+) separator between the / and /]] strings, and it matches the

format, and it will set the separators to / [[ and /]].

Note that the macro sep should be terminated with the original macro closing string. The macros after it already have to use the altered opening and closing strings. This makes it a bit tricky when you want to use a closing string that happens to contain the original closing string. Assume that the current opening string is { and the current closing string is }. You want to have {{ as an opening string and }} as a closing string. This is often the choice when using Jamal in a programming language environment that heavily uses { and`}` braces. In this case

will not work. It will set the closing string empty which is not valid and will raise an error. To overcome the situation you have to change the separator strings in two steps:

Also, do not forget that the end you should call sep without an argument twice:

unless you want this change till the end of the scope.

The change of the opening and the closing strings always happens in pairs. You cannot change only the closing or only the opening string. You can, however, redefined one of them to be something that is different from the current value, and the other one to be the same as the current value. To do that you will need two steps for the reason described above. Even in this case, the definitions should specify both strings.

The change of the opening and closing strings is valid only for the current scope. Returning from the scope the original value is restored even if the strings were set to different values multiple times.

Neither the opening nor the closing string can be empty. Trying to set it to an empty string will raise an error.

When the opening and the closing strings are set, the original values are stored in a list. It is possible to use the macro sep without any separator string specification. In this case the macro call is nothing more than the macro name, like {@sep}. In this case the last opening and closing strings are restored. The strings are stored in a stack, so you can define new strings and return to the previous one many times nesting the redefinitions.

The following sample is executed with { and } as opening and closing string at the beginning. After that, it sets the strings to [[ and ]]. This is used to define the macro apple. After this when the scope of the next macro, comment starts the opening and closing strings are still [[ and ]]. Starting a new scope does not change the macro opening and closing strings.

It would be an error to use [[@sep]] inside the scope of the macro comment at this point trying to restore the original macro opening and closing strings. In that scope at the start, there are no opening and closing strings to be restored. The opening and closing strings do not belong to this scope, they are simply inherited from the outer scope. On the other hand, the sample can change the strings, as it does to << and >>. Using these it defines the macro z. Note that z is not exported from this scope.

After that the <<@sep>> restores the opening and closing strings to the inherited one and with these, it defines a1 and a2 and exports them. Note, that a1 will have the actual value of the macro z evaluated inside the scope of the comment macro. The macro a2 starts with @ thus the body is not parsed during the macro definition and thus the value of a2 is unevaluated, as it is. Similarly, the macro a3 will have the value`{z}`.

All these macros are evaluated because the macro comment is started with the character #. It means that Jamal will evaluate the body of the macro before evaluating the macro itself.

After the comment macro the separators are set back to the original value { and } automatically. Then we have a simple macro definition that defines z and then this z is used, and the exported a1, a2, and a3.

z is now, as defined in the outer scope is SSS. a1 has the value that came from the macro z as it was defined inside the scope of the macro comment. Macro a2 has the value that has nothing special in the current scope. The macro a3 has the value {z} which is evaluated after the macro a3 is replaced with its value.

since 1.0.0 (core)

export moves the definition of one or more user-defined macros to a higher scope.

The syntax of the macro is

exporting one or more macros, comma separated.

When a macro is defined it is defined in the current scope (unless the name contains one or more :, or it starts with :).

The Jamal input file is one scope and if there is a macro defined in the file on the top-level then that macro can be used anywhere inside the file. However, when Jamal includes a file into another it opens a new scope. The macro include should include some text in the output. It can be used, for example, to split up a long document into chapters and then use Jamal to create the final output. In that case, the macros defined in the included files should not interfere with the definitions in the file that includes the other one. To accomplish this separation Jamal starts a new scope when it includes a file. Scopes are embedded into each other like a call stack in a programming languages. When a macro is defined in scope it is available in that scope and all other scopes that are opened from that scope. When a macro is redefined in a scope the redefined value is used until the scope is closed. In the case of an included file, the user-defined macros defined in the included file disappear as soon as the included file processing is finished.

The setting and resetting of the separator characters is also limited to the scope. You cannot reset the separator character to a value that was set in a lower, or higher scope.

Jamal opens a new scope in the following cases:

• When a file is processed with the include macro.

• When macros are evaluated inside another macro. This is the case of user-defined macros or in case of built-in macros when they are started with the character #.

• Other built-in macros that are not part of the core package may also open and close scopes. Built-in macros are provided in form of JAR files.

Note that the macro import does NOT open a new scope to process the imported file. This is because of the aim of import is to have the macros defined in the imported file available in the file that imports them.

In the following example, we define the macro Z in the scope of the macro comment. The {@define Z=13} is evaluated before the comment macro because we use the # in front of the comment macro. When the comment evaluation finishes the scope is closed and Z is not defined anymore. In the second case the macro Z is exported using the export macro. The export macro moves the definition of the macro from the scope of the comment to the enclosing scope.

The example:

will result:

You cannot export a macro defined in a higher scope. You can use those macros and you can reference them. It is just that you cannot export them to the enclosing scope because they do not belong to the current scope. You can export a macro that was defined in a lower scope and was exported to the current scope. However, you cannot export a macro that was defined in a lower scope but was not exported to the current scope, simply because they do not exist anymore when the export is executed. You cannot export macros from the top-level scope, because there is no enclosing scope above that.

since 1.0.3 (core)

The options macro can be used to alter the behavior of Jamal. The options can be listed | separated as an argument to the macro.

The macro does not check the option’s name. For example the option lenient is used by Jamal itself and by the for macro, however, if you type {@options lenuent} misspelled the options macro will not recognize it as an error. The option lenuent could be used by some other macros and the options macro just treats it as a new option. It stores the options specified, and they can be queried by any other built-in macros. Any extension can define and use any options it likes.

The scope of the options is local, or global the same way as the scope of user-defined macros.

An option can be switched off using the ~ character in front of the options name. There can be no space between the ~ character and the name of the option.

Similar to user defined macros, options containing a : are global. You can define a global value for an option using the : prefix in front of the name of the option. This character will be removed from the name, the same way as it is removed from the name of global user defined macros. If the : is inside the name then it remains part of the name, and it is not possible to have a local definition for the option.

The options implemented currently:

:lenient

omasalgotm (since 1.2.0 < 1.10.0)

nl (since 1.3.0)

{@define z=1}\n          <- new line will get into the output

{@define z=1}\\n         <- the \ and new-line will be skipped, it does not get into the output

{@define z=1}\ ... \n    <- there can be spaces between the \ and the \n, still the
                            \ and new-line characters will be skipped

{@define z=1} ... \\n    <- nothing is skipped, there are spaces before the \ character

failfast (since 1.7.8)

since 1.5.0 (core)

The macro try will evaluate its content and return the result. The evaluation does not open a new scope, just like in the case of the macro {@eval }. In case the evaluation results an error then the result will be empty string.

For example the following macro will produce an empty string.

The macro macro is not defined, but the error is caught with the macro try.

The macro try can also be used to include the error message into the output. If we use an ! character right after (no spaces) the try keyword the result will be the error message. If there is no error then the result is the result of the evaluated text inside the macro.

If we use a ? character right after (no spaces) the try keyword then the result will be the string true if there was no error and false is there was an error. This can be used to test the "computability" of the text.

The macro try should only be used to debug certain macro files. When an error happens, and the try macro catches the exception thrown the scopes may not be properly closed.

• since 1.5.4 (core)

• since 1.9.1 (escape*)

The built-in macro escape is a special one, like verbatim. It is implemented as Java a macro class, but the macro evaluation process takes the presence of an escape macro into account. The syntax of the macro is the following:

The part SEP between the back-tick characters can be any string, which does not appear inside the escaped string. This string has to be repeated at the end of the macro before the macro end string.

The result of the macro is the escaped string without any modification. The macro itself is very simple. The speciality of macro is that Jamal takes care of this macro when searching for macros in the text. When Jamal sees a macro opening string, then it checks way before the evaluation of the macro if the actual macro is an escape macro or not. It the macro is an escape macro, then it finds the SEP strings, and the macro end string after that. If there is any macro opening or macro closing string inside the escape macro they are ignored.

will result

It is recommended not to use this macro in your Jamal source. If you can solve your task without this macro, then you should do it without such a strong tool.

There is a special way to escape content from macro evaluation. In this special case you can write a * right after the escape keyword, as

In this case the escape not only escapes the macro opening and any other otherwise processable content but also results the protecting shell around the escaped string. The result in this case will be

This macro comes in handy when you want to protect something from evaluation that should never be interpreted as a macro text. For example you can have a Maven property in a pom.jam file, like ${project.build.sourceDirectory}. You can redefine at the start of the file the macro open and macro close strings, but it may be simpler to protect the one or few special strings. A normal escape, without the * after the keyword hides the content from evaluation only once. When the * character is used the content will be protected even when it is deep inside macros and target for many different evaluations. It should only be eliminated at the very end of the processing on the top level, which is done automatically.

The macro escape* will liberate the content. The liberation will happen after the whole content was already processed in a so called "closer". Built-in macros implemented in Java have the possibility to register an object to be executed after the processing of the whole content. Such an object is a closer and it can be used to close resources that were open by the macro during processing. During the execution of this closer the code can access and modify the final result.

The macro escape* registers a closer that will invoke the the Jamal processing again for the output with a flag that tells every escape* macro to release its content.

In some cases it may happen that you want the escape* closer run before some other closers, but the escape* happens later than the register of the other closer.

The different closers are invoked in the order they were registered. You may use a macro X, which also creates a closer. The use of the macro X precedes the first evaluation of an escape* macro. In this case the closer registered by X would be evaluated before the escape* closer. If you want the escape* closer to run first, you have to use the macro escape* before X. The simplest form is

It essentially escapes an empty string delimited by two backtick delimited empty strings. (Hence the four back ticks.) After the content liberation the result will be an empty string, thus there is no harm using this before any X macro.

The closer registered by escape* works very simple. It simply evaluates the result setting a flag that tells escape* that this time it should ignore the \* character.

since 1.6.4

Since Jamal has many different versions, there may be a need to stick to a specific version. To do that, the built-in macro introduced in version 1.6.4 require can be used. The syntax of the macro is

The evaluation of this built-in macro will check that the currently running version of Jamal is

• less-than

• greater-than

• lees-then or equal

• greater than or equal, or

• equal

to/than the version specified after the comparison sign. The use of the comparison sign is optional. The default comparison is greater than or equal.

If the comparison fails, the evaluation of the macro will result in an error. If the current version matches the requirement, then the result of the macro is an empty string.

For example:

will result

You can specify only one version in a require macro. If you want to specify a minimum and a maximum version, you should use two require macros.

Using a version before 1.6.4 in the require argument is an error.

This variable can define the connection timeout value for the web download in millisecond as unit.

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 appended 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 Jama into an infinite recursive call. During the macro evaluation {a} will result {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 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 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 file include nesting. The default value is 100.

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

The 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 |

This environment variable can define options for the Jama processor. The value of the variable is interpreted as a multi-part 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.

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.

When the file name starts with the characters res: it is a Java resource file. It means that the file is in a JAR file among the classes. The JAR file has to be on the classpath. When Jamal is started from the command line then the JAR file has to be added to the classpath. The classpath is usually after the -cp or -classpath argument of the Java command line. If Jamal is started as a Maven plugin then the configuration in the pom.xml file should include the dependency. For example to add the pomlib library JAR to the classpath you can use the following fragment in your pom.xml:

Web resources can be downloaded using the https: prefix. The only protocol supported is https. Jamal does not download any resource using the unencrypted HTTP protocol.

It is possible to cache the downloaded files. The environment variable JAMAL_HTTPS_CACHE can define a directory to store the web resources. In case the environment variable is not defined then the default value ~/.jamal/cache/ will be used. If the cache directory exists Jamal will store there the downloaded files. Jamal will create the subdirectories if needed, but Jamal will never create the cache directory itself. If you do not want to use the caching then do not create the cache directory.

Jamal will not cache a downloaded files that has SNAPSHOT in the URL (all capital letters). There is no cache eviction or expiration. You can find the files in the cache directory in subdirectories. You can also find there corresponding property files that contain information about the caching. These properties files are information purpose and Jamal does not use them at the moment.

The connection to the web can be configured if needed. The environment variables that can be used are the followings:

• JAMAL_CONNECT_TIMEOUT, and

• JAMAL_READ_TIMEOUT

can define two timeout values for the web download in millisecond as unit.

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.

file/line:column

file/line:column <<< file/line:column