GLOSSARY.adoc.jam

== Jamal Glossary

{%@comment This is the ASCIIDOC version of the GLOSSARY document.
The source of the file is the GLOSSARY.adoc.jam.
This file is processed by the test javax0.jamal.documentation.TestConvertReadme in the module jamal-snippet.

%}{%@import res:jamal.jim%}\
{%@snip:xml pom=pom.xml%}\
{%#define VERSION={%pom /project/version/text()%}%}\
{%@define classFormat=`$canonicalName`%}{%@define methodFormat=`$name()`%}\
{%#define UDM={%@java:class javax0.jamal.api.UserDefinedMacro%}%}
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 {%@java:class javax0.jamal.engine.UserDefinedMacro%}.
This class implements the interface {%UDM%}.
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 {%@java: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 {%UDM%} 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 {%@java:class javax0.jamal.api.InnerScopeDependent%}.
Inner scope dependent macros can define user-defined macros, but the scope of these macros ends when the method {%@java:method javax0.jamal.api.Macro::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 {%@java:method javax0.jamal.api.Processor#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 {%@java:class javax0.jamal.api.Closer$ProcessorAware%} or {%@java:class 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 {%@define TITMI=this is the macro input%}{%TITMI%}}` has the text `{%TITMI%}` 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 `pass:[`]` 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.