Skip to content

Latest commit

 

History

History
110 lines (74 loc) · 4.82 KB

include.adoc

File metadata and controls

110 lines (74 loc) · 4.82 KB
Raw

include

since version 1.0.0

Syntax

{@include [top noCache verbatim optional in="" lines=m..n] included_file.jam}

History

  • since 2.6.0 include can be optional to ignore missing files

  • since 1.7.3 verbatim include

  • since 1.11.0 lines

  • since 1.11.0 noCache

Description

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.

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 [options] file_name}

The options are between the [ and ] brackets. They are:

  • includeVerbatim (alias verbatim) - the file is inserted into the output as it is without processing.

  • top - the file is included relative to the top level file. This option cannot be defined as macro.

  • lines - the option can list ranges of lines to include. The individual ranges can be separated by , or ;. The ranges are specified as a range of numbers separated by .. (two dots). A one line range can be specified by a single number. The range start line number can be larger than the end line number. In that case that lines appear in reversed order from the start to the end. The lines are included in the order as the ranges specify. Using this option you can rearrange the order of the lines. When you want to specify a range lasting to the end of the lines you can write 13..inf or 5..infinity. Range numbering starts with 1.

    This option cannot be defined as macro.

  • optional or ifExists will return an empty string if the file does not exist. The normal operation is to result a BadSyntax exception if the file does not exist.

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

Note

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.

This type of use is not recommended and is included only for backward compatibility and may later be removed.

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

The number of includes is 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. This possibility does not mean that it is clever to do it. 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.

Starting with version 2.0.0 the include 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 include resource files provided in JAR file or through the net even if you use different macro opening and closing strings.

in

The release 2.5.0 introduced the option in. The option can define multiple prefixes for the file name to be included. These prefixes are separated by the | character. When performing the include 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.