Skip to content

Latest commit

 

History

History
91 lines (61 loc) · 3.73 KB

use.adoc

File metadata and controls

91 lines (61 loc) · 3.73 KB
Raw

use

since version 1.0.0

Syntax

{@use  [global] com.package.name.MacroClass as alias}

or

{@use  [global] macro_name as alias}

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

History

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

How macros are loaded

Built-in macros are classes that implement the javax0.jamal.api.Macro interface. When they are registered as services, they are automatically loaded when any application embedding Jamal creates a new processor. In other words, the classes that implement some macros are automatically discovered if

  • they are in the module-info module descriptor provides directive and/or

  • the fully qualified name of the class is listed in the JAR file in the META-INF/services/javax0.jamal.api.Macro file.

Some libraries contain javax0.jamal.api.Macro implementations that are not loaded by the service loader. These classes are not advertised in the module-info file or in the META-INF directory. To use these classes as built-in macros the macro use has to be invoked.

Defining the use of a Java Class as a Macro

The use of the use macro (sic) is the following:

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

In this example, the class javax0.jamal.scriptbasic.Basic implements a macro. The class has to be on the classpath, and it has to implement the interface javax0.jamal.api.Macro. It will be defined and available as a globally available built-in macro under the alias scriptbasic.

The keyword global can be missing:

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

In this case, the macro will only be available in the current scope and will not be available as soon as the current scope is closed. Note that built-in macros cannot be exported. They can be declared either local for the current scope or global.

Usually, the alias part (the as scriptbasic in the example above) can also be omitted:

Jamal source
{@use javax0.jamal.scriptbasic.Basic}

In such a case the macro will be registered with the name that the macro provides by itself as an identifier. The interface Macro defines a method String getId() that should return the identifier of the macro. The interface also provides a default implementation that returns the lower-case version of the class name (w/o the packages). If there is no defined alias following the as keyword, then the one returned by the macro implementation will be used.

It is recommended to use the alias in the Jamal source file. That way there is no ambiguity when reading the code what the name of the built-in macro is.

Defining alias for an already loaded marco

The syntax of the command is the same to define an alias for an already loaded macro. If there is no . dot character in the "klass name", then the command will know that it cannot be a class name. In that case, it will look for an already loaded built-in macro with the given name and it will register it again with the new alias. Following this, both names can refer to the same macro.

The alias will refer to the built-in macro, which is the closest reachable in the current scope. If the evaluation leaves the current scope, and the global keyword was not used, then the alias will also go out of the scope. It is independent of the macro itself. The macro may be reachable via the original name.

The alias will refer to the built-in macro, which is the closest reachable in the current scope even if the global keyword is used. In this case the alias will be global, and the macro will be reachable via the alias even if the original name was not registered global and goes out of scope.