GLOSSARY.adoc

Jamal Glossary

This glossary collects the terminologies that we use in Jamal.

Macro Start String

The string that starts a macro. It is usually a single character {, but it can be any character length. When Jamal is embedded, it is defined when the Jamal processor is created. The string, along with the Macro Closing String can dynamically be redefined using the core built-in macro sep.

Macro End String

The string that ends a macro. It is a single character } usually, but it can be any character length. When Jamal is embedded, it must be defined when the Jamal processor is created. The string, along with the Macro Start String can dynamically be redefined using the core built-in macro sep.

Built-in Macro

A built-in macro is a macro implemented in Java. The built-in macro is the opposite of a user-defined macro. Built-in macros are defined in Jamal’s core package and other packages.

User-Defined Macro

A macro, (usually) defined using Jamal macro source. The most common user-defined macro is created using the built-in core (see Core) macro define. A user defined macro defined using define inside Jamal is an instance of the class javax0.jamal.engine.UserDefinedMacro. This class implements the interface javax0.jamal.api.UserDefinedMacro. Any class implementing this interface can be a user-defined macro. The significant difference between the implementation of built-in macros and user-defined macros is that built-in macros are service objects. User-defined macro classes are not. There is usually only one instance per processor for each built-in macro class, and these instances are supposed to be stateless. User-defined macro classes are instantiated many times and may contain a state. The instance of the class javax0.jamal.engine.UserDefinedMacro is created by the built-in macro define. Other built-in macros can create instances of different classes, so long as long they implement the javax0.jamal.api.UserDefinedMacro interface.

Identifier

In Jamal, macro names are identifiers. Identifiers in Jamal start with the letters a-z or A-Z, $, :, or underscore and can contain any of these on consecutive positions. The second and other positions can also contain digits. Identifiers in Jamal start with the letters a-z or A-Z, $, :, or underscore and can contain any of these on consecutive positions. The second and other positions can also contain digits.

Core

The core package defines built-in macros, which are essential for the use of Jamal. Some of these macros are directly tied to the source parsing process. For example, the macro verbatim cannot be redefined. verbatim is implemented in the engine itself, and that way, it only looks like a macro.

Engine

Engine is the Java module and program code that executes the Jamal processor.

Experimental Module

Experimental module is a macro library or module, which is provided as is without any guarantee of further compatibility. The module may later be discontinued, or the API may change.

Scope

When Jamal executes, macros have a specific scope of validity. For example, including a file into a Jamal macro source will process that file in a new scope. This new scope is inside the scope of the file that includes the other. The Jamal code can use the macro definitions in the current scope or an upper scope. When a scope ends, the definitions that belong to the scope become stale and not usable anymore. It is not possible to reopen a closed scope. When a scope ends, the following scope above it will become the actual scope. Scopes are stacked into each other. A scope can be

• active the scope that is currently active. All new macro definitions are created in this scope.

• locked when the macros in the scope are available, but new macros are already defined in the scope one level above. A scope gets into a locked state when the scope is created to evaluate the parameters of a user-defined macro. The macros defined here are also available for evaluating the macro itself, but any new macro definition will go to the scope above.

• ended when the scope has ended, the references to any macro are deleted and will be GC-ed.

In addition to these three states, we also use the terminology "export scope" and "global scope".

• export scope is one level above the current scope. When a macro defined in the active scope is exported, the macro is moved to this scope.

• global is the top-level scope. It is opened automatically when the processor starts. Global macros are defined in this scope.

.

Inner Scope Dependent

A built-in macro is "inner scope dependent" if it has to execute in the scope that was opened when the evaluation of the macro parameter started. Inner scope dependent built-in macros have to implement the interface javax0.jamal.api.InnerScopeDependent. Inner scope dependent macros can define user-defined macros, but the scope of these macros ends when the method evaluate() returns. To create longer living user defined macros, inner scope dependent build-in macros can programmatically export the user defined macros they create. If an inner scope dependent built-in macro wants to define a macro usable in the scope where the macro is used, it has to export the user-defined macro.

Closer

Is an instance of a class implementing the AutoCloseable interface and registered in the processor calling deferredClose(). This object has to be registered into the processor object during the execution of Jamal. Some built-in macros create closer objects and register them. The processor invokes the method close() when the processing of the Jamal input has finished. The closer class may also implement javax0.jamal.api.Closer.ProcessorAware or javax0.jamal.api.Closer.OutputAware interfaces. It will make the processor inject the processor object or the result into the closer object before invoking close(). This way, a closer can modify the final output after all the Jamal macro processing has finished.

The core built-in macro defer uses this functionality. It stores the input of the macro in a new closer object and the closer object evaluates it at the end.

Accidental Snippet

An Accidental Snippet is a snippet in some file that starts in a line containing the characters snippet followed by an identifier, but which was not meant to be a snippet. For example, some comments may mention something like a snippet is…​. In this case, the snippet collection will recognize the snippet start, and the identifier will be is. Accidental snippets are better avoided, and it is almost always possible. If you cannot avoid it, then you should use different snippet start and end regular expressions. You can define these as the snip:collect macro parameters.

Maco Input

The input of a macro is the text that follows the macro name and lasts to the macro closing. For example, the {@trimLine this is the macro input} has the text this is the macro input as macro input.

Macro Prefix

The macro prefix means the characters between the macro opening string and the macro name in the case of a user defined macro, or between the macro opening string and the # ot @ character in the case of a built-in macro. Currently, these can be ` and ! characters. Spaces are ignored.

Parops

Macro parameter options. This terminology was invented in a later version to distinguish the macro options you use between [ anf ] or between ( anf ) in the macro use and options defined using the macro options. These are also mentioned as "macro options" or "macro parameters" in the documentation.

Macro Option, Macro Parameter

These two things have the same meaning, and both are used in the documentation. Built-in macros can use the option parsing routines for the syntax analysis of the input of the macro. In that case options can be defined at the start of the input between ( and ) (or some other) characters. The options usually have the format name=value. Core macros use [ and ] as option start and end characters.

Macro parameters are not the same as macro arguments. User defined macros have arguments. Built-in macros have options/parameters.

Macro Arguments

The actual values passed to a user-defined macro when it is used. User defined macros have name, optionally arguments, and a body. The arguments have symbolic names listed between ( and ) comma separated. The macro actual values are provided at the use, and the names are replaced by the actual values.

Macro Body

Is the text of a user-defined macro containing literal text and macro argument

Standard Built-In Parameter/Option Parsing

It means parsing the Macro Options. There is API support for the options' parsing.

Standard Built-In Macro Argument Splitting

The standard way a built-in macro can parse the Macro Input in case it does not intend to implement its syntax analysis. Using the standard way makes the macros more uniform. The core macro if uses the Standard Built-In Macro Argument Splitting. In other macro packages several macros use the built-in splitting.