import.adoc

import

since version 1.0.0

Syntax

{@import [top noCache isolate in global] imported_file.jim}

import opens a file and reads the content of the file interpreting as Jamal macro file. Anything defined in that file will be imported into the scope of the current file. In other words, importing a file happens in the same scope where the import macro is used. As a consequence of that, if the macro opening and closing strings are redefined in the imported file, they will also change in the importing file. Any user-defined macros defined in the top-level scope of the file will also be available.

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,

• from inside a block,

• 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 generated by the imported file 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 on the classpath. Any file name starting with the letters https: are downloaded from the net. In addition to these Jamal comes with a JAR and a Maven reader that can read files from JAR files and from Maven repositories. In these cases the file name starts with jar:file: or maven:.

top

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 step one or a few levels up in the import hierarchy. The only two possibilities are to import relative to the current one or to 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.

Note

The option top makes it possible to create macro libraries that are local to a document. Documentation may consist of several files across multiple directories. There can be a global import file containing macros used by all different documents in the different directories. In addition, there can be an import file in each directory that contains macros used only in that directory. The documents in the directory can import the global import file and the local import file. The global file, however, can not import the local file using the top option eliminating the need for the second import in the documents.

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.

Note

If there is a need to change the macro opening and closing strings in the imported file, the recommendation is to reset these changes before the end of the file. This way the imported file will not affect the importing file. Also, when the imported file starts with the {@ characters the importing process changes the macro opening and closing strings to { and } before the import and resets them after the import. If there is a sep macro changing the macro opening and closing strings in the imported file, then the reset will go back one level only, essentially reversing the last sep macro use. Assume that you have a file that uses the [ and ] characters as macro opening and closing strings. This file imports a file that starts with the {@ characters. The imported file also uses {@sep <>} to change the macro opening and closing strings to < and >. At the end of the file this is reset and now the macro opening and closing strings are { and }. This only happens when the file importing the other file uses something other than the { and } characters as macro opening and closing strings. If the importing file uses the { and } characters, then the imported file will be evaluated using the { and } characters as macro opening and closing strings just the normal way without setting and resetting the macro opening and closing strings. In this case the {@sep <>} change the macro opening and closing strings and this change will be in effect in the importing file.

noCache

Starting with version 1.11.0 the import macro has the option noCache.

• noCache will ignore the cache when downloading resources using https: protocol. More precisely, it will download the resource from the network and update the cache file with the new content every time.

isolate (boolean)

The release 2.5.0 introduced the option isolate. Using this option will process the imported file in a new processor. It means that the macros defined in the importING file will not be available in the importED file. The macros defined in the imported file will be available in the importing file after the import the same way as if the isolate option was not used.

in

The release 2.5.0 introduced the option in. The option can define multiple prefixes for the file name to be imported. These prefixes are separated by the | character. When performing the import operation, the first prefix that matches the file name is used.

The prefix is used at the start of the file name without any extra separator.

This option can be used for relative file names, where the location of the file may be different depending on the context.

global (boolean)

This option signals that the import should be registered on the global level. It is useful when a file is imported in a local level, but it contains only global macro definitions. In that case, there is no need to import it even at higher levels.

force (boolean)

This option enables the forceful import of a file, even if a file with identical content has already been imported.

To prevent redundant imports, the import macro avoids executing the macros within the imported file if a file with the same hash code has been imported previously. This check is conducted at the same or higher levels than the current import. If the import occurs at a lower level, it has no impact because that level is already out of scope, along with any macros imported at that level, unless they are designated as global or exported. Utilizing hash codes for checks helps minimize memory usage by not storing the complete import files and effectively ensures that the same file is not imported more than once.

However, there are scenarios where importing a file with the same content is necessary. For example, consider a situation where there is a global import file within a complex directory structure, and a file in the directory above merely imports the same file. This pattern continues up to the top-level directory.

In such cases, to enforce the import, use the force, or forced parop. It can also be activated globally through the import$force option.