import and include parop 'in'

snip:eval developed

README.adoc

@@ -225,18 +225,11 @@ They are documented along with the macro documentation.
 The environment variables and their meanings are documented in their
 link:./documentation/ENVIRONMENT_VARIABLES.adoc[documentation].
 
-Modules can contain each a `.jim` file that the processor will load when the module is loaded.
-The Jamal installation can also contain a `~/.jamal/.jim` file that is loaded when a Jamal processor is started.
-These files can contain macros and are treated like if they were imported from the source code.
-
-NOTE: While the `.jim` files in the modules may be part of the functionality that the modules deliver, the one in the `~/.jamal` directory is not.
-Putting any macro into this file makes Jamal execution installation specific.
-This feature is there to provide a way to set some options globally for a whole project temporary.
-The actual need igniting the implementation of this feature was to have a global `detectNoChange` option, while all the erroneous regular expressions were fixed in the different files.
 
 == Features [[Features]]
 
 
+
 Jamal is a meta markup language that extends existing markup languages in a transparent way.
 The language is designed so that it will not interfere with any existing or future markup.
 
@@ -543,4 +536,4 @@ See the separate document: link:FAQ.adoc[FAQ].
 
 
 
-The documents of this project are formatted as Asciidoc documents with Jamal meta markup.
+The documents of this project are formatted as Asciidoc documents with Jamal meta markup.

RELEASES.adoc.jam

@@ -26,6 +26,8 @@
 This helps to avoid situations when a snippet is heavily transformed to create documentation lines from source code and the source changes structurally and the transformation gets outdated.
 It is recommended to set the `detectNoChange` option to true globally at the start of the input file.
 * The argument splitting many built-in macro uses now looks at the macro `$REGEX` and uses it to split the arguments if defined.
+* `snip:eval` can evaluate snippets using the location of the snippet for relative files referenced inside the snippet
+* `import` and `include` macros have parop `in`.
 
 {%RELEASE IZMIR%}
 

documentation/ARGSPLIT.adoc

@@ -148,4 +148,5 @@ They enclose the string value of the parop in an `Input` object before calling `
 
 For the Kotlin support methods have look at the Kotlin file
 
-  ../jamal-kotlin/src/main/kotlin/javax0/jamal/kotlin/InputSupport.kt
+  ../jamal-kotlin/src/main/kotlin/javax0/jamal/kotlin/InputSupport.kt
+

documentation/FILE_NAMES.adoc

@@ -187,4 +187,7 @@ For more information read the link:../jamal-maven-input/README.adoc[documentatio
 Jamal can read files from JAR files.
 In this case the prefix has to be `jar:file:` and the file name has to be the name of the JAR file followed by the name of the file inside the JAR file following a `!` character.
 
-For more information read the link:../jamal-jar-input/README.adoc[documentation] of the module implementing the `jar:file:` prefix.
+For more information read the link:../jamal-jar-input/README.adoc[documentation] of the module implementing the `jar:file:` prefix.
+
+
+

documentation/HOWTO_DEBUG.adoc

@@ -118,4 +118,4 @@ If you do not want to trace anymore, do not forget to unset the environment vari
 unset JAMAL_TRACE
 ----
 
-to avoid an excessively large trace file growing on your disk.
+to avoid an excessively large trace file growing on your disk.

documentation/JAMAL_API.adoc

@@ -103,4 +103,4 @@ The two static methods `include()` and `exclude()` can be used to create these a
 
 The current and past versions of the JavaDoc can be read online at the address:
 
-link:https://javadoc.io/doc/com.javax0.jamal[`https://javadoc.io/doc/com.javax0.jamal`]
+link:https://javadoc.io/doc/com.javax0.jamal[`https://javadoc.io/doc/com.javax0.jamal`]

documentation/MODULES.adoc

@@ -264,4 +264,7 @@ The code in the directory `jamal-debug-ui` contains the REACT.js based ui for th
 
 
 This is not a module.
-The code in the directory `jamal-docker` contains a Dockerfile to build a Docker image with Jamal.
+The code in the directory `jamal-docker` contains a Dockerfile to build a Docker image with Jamal.
+
+
+

documentation/SAMPLE_README.adoc

@@ -4,4 +4,6 @@
 
 
 How to use Jamal in five minutes.
-This is a sample readme of the version `2.5.0-SNAPSHOT`.
+This is a sample readme of the version `2.5.0-SNAPSHOT`.
+
+

documentation/macros/import.adoc

@@ -9,7 +9,7 @@ since version `1.0.0`
 
 == Syntax
 
- {@import [top noCache isolate] impoted_file.jim}
+ {@import [top noCache isolate in] 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.
@@ -97,4 +97,15 @@ More precisely, it will download the resource from the network and update the ca
 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.
+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.

documentation/macros/import.adoc.jam

@@ -2,11 +2,11 @@
 {%@import macrodoc.jim%}
 {%MACRO name="import" since={%RELEASE:ZURICH%}%}
 
-{%@snip:check file=../../jamal-core/src/main/java/javax0/jamal/builtins/Import.java hash=57051a81 %}
+{%@snip:check file=../../jamal-core/src/main/java/javax0/jamal/builtins/Import.java hash=31239e9d %}
 
 == Syntax
 
- {@import [top noCache isolate] impoted_file.jim}
+ {@import [top noCache isolate in] 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.
@@ -82,4 +82,8 @@ Starting with version {%RELEASE:ZOLLIKOFEN%} the import macro has the option `no
 The release {%RELEASE:ROGACHEVO%} 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.
+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`
+
+{%PAROP_IN/import%}

documentation/macros/include.adoc

@@ -95,3 +95,13 @@ Starting with version 2.0.0 the include macro looks into the file before evaluat
 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.

documentation/macros/include.adoc.jam

@@ -1,6 +1,6 @@
 {%@import macrodoc.jim%}
 {%MACRO name="include" since={%RELEASE:ZURICH%}%}
-{%@snip:check file=../../jamal-core/src/main/java/javax0/jamal/builtins/Include.java hash=795ea0d6%}
+{%@snip:check file=../../jamal-core/src/main/java/javax0/jamal/builtins/Include.java hash=561c3a33%}
 {%@import ../../environmentvariables.jim%}
 == Syntax
 
@@ -70,3 +70,6 @@ The limit can be modified setting the environment variable {%JAMAL_INCLUDE_DEPTH
 
 {%DEFAULTOPEN/{%RELEASE:BUDAPEST%}/include%}
 
+== `in`
+
+{%PAROP_IN/include%}

documentation/macros/macrodoc.jim

@@ -75,3 +75,12 @@ code%}
 {%!#output {%lastCode%}%}%}%}
 ----
 %}
+
+{%@define PAROP_IN($x)=The release {%RELEASE:ROGACHEVO%} introduced the option `in`.
+The option can define multiple prefixes for the file name to be {%#if /{%@string:equals /$x/import%}/imported/included%}.
+These prefixes are separated by the `|` character.
+When performing the $x 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.%}

jamal-api/src/main/java/javax0/jamal/api/BadSyntax.java

@@ -24,6 +24,13 @@ public BadSyntax(String message, Throwable cause) {
         super(message, cause);
     }
 
+    public BadSyntax(String message, List<Throwable> suppressed) {
+        super(message);
+        for (final var s : suppressed) {
+            this.addSuppressed(s);
+        }
+    }
+
     final private List<String> parameters = new ArrayList<>();
 
     public List<String> getParameters() {

jamal-core/src/main/java/javax0/jamal/builtins/Import.java

@@ -78,18 +78,15 @@ public String evaluate(Input input, Processor processor) throws BadSyntax {
         final var top = scanner.bool(null, "top");
         final var noCache = scanner.bool(null, "noCache");
         final var isolate = scanner.bool(null, "isolate", "isolated");
+        final var inDirs = scanner.str(null, "in");
         scanner.done();
-        if (top.is()) {
-            while (position.parent != null) {
-                position = position.parent;
-            }
-        }
+        position = Include.repositionToTop(position, top);
+        final var prefixes = Include.getPrefixes(inDirs);
         skipWhiteSpaces(input);
-        var reference = position.file;
-        var fileName = absolute(reference, input.toString().trim());
+        var fileName =  input.toString().trim();
         if (wasNotImported(fileName)) {
             importedAlready.get(importedAlready.size() - 1).add(fileName);
-            final var in = getInput(fileName, position, noCache.is(), processor);
+            final var in = getInput(prefixes, fileName, position, noCache.is(), processor);
             final var weArePseudoDefault = processor.getRegister().open().equals("{") && processor.getRegister().close().equals("}");
             final var useDefaultSeparators = in.length() > 1 && in.charAt(0) == IMPORT_SHEBANG1 && in.charAt(1) == IMPORT_SHEBANG2 && !weArePseudoDefault;
             final Processor myProcessor;

jamal-core/src/main/java/javax0/jamal/builtins/Include.java

@@ -8,10 +8,10 @@
 import javax0.jamal.api.Position;
 import javax0.jamal.api.Processor;
 import javax0.jamal.tools.Marker;
-import javax0.jamal.tools.Params;
 import javax0.jamal.tools.Range;
 import javax0.jamal.tools.Scanner;
 import javax0.jamal.tools.param.BooleanParameter;
+import javax0.jamal.tools.param.StringParameter;
 
 import static javax0.jamal.api.SpecialCharacters.IMPORT_CLOSE;
 import static javax0.jamal.api.SpecialCharacters.IMPORT_OPEN;
@@ -43,23 +43,24 @@ private static int getDepth() {
     @Override
     public String evaluate(Input input, Processor processor) throws BadSyntax {
         var position = input.getPosition();
-        final var scanner = newScanner(input,processor);
+        final var scanner = newScanner(input, processor);
         final var top = scanner.bool(null, "top");
         final var verbatim = scanner.bool("includeVerbatim", "verbatim");
         final var lines = scanner.str(null, "lines");
         final var noCache = scanner.bool(null, "noCache");
+        final var inDirs = scanner.str(null, "in");
         scanner.done();
         position = repositionToTop(position, top);
+        final var prefixes = getPrefixes(inDirs);
 
         skipWhiteSpaces(input);
-        var reference = position.file;
-        var fileName = absolute(reference, input.toString().trim());
+        var fileName = input.toString().trim();
         if (depth-- == 0) {
             depth = getDepth(); // try macro may recover
             throw new BadSyntax("Include depth is too deep");
         }
         final String result;
-        final var in = getInput(fileName, position, noCache.is(), processor);
+        final var in = getInput(prefixes, fileName, position, noCache.is(), processor);
         final var weArePseudoDefault = processor.getRegister().open().equals("{") && processor.getRegister().close().equals("}");
         final var useDefaultSeparators = in.length() > 1 && in.charAt(0) == IMPORT_SHEBANG1 && in.charAt(1) == IMPORT_SHEBANG2 && !weArePseudoDefault;
         if (lines.isPresent()) {
@@ -83,6 +84,16 @@ public String evaluate(Input input, Processor processor) throws BadSyntax {
         return result;
     }
 
+    static String[] getPrefixes(StringParameter inDirs) throws BadSyntax {
+        final String[] prefixes;
+        if (inDirs.isPresent()) {
+            prefixes = inDirs.get().split("\\|");
+        } else {
+            prefixes = new String[]{""};
+        }
+        return prefixes;
+    }
+
 
     /**
      * Get the position of the 'include' from the input. When the 'top' parameter is true the position is the position
@@ -94,7 +105,7 @@ public String evaluate(Input input, Processor processor) throws BadSyntax {
      * relative file name
      * @throws BadSyntax if 'top' is erroneous and querying it throws exception
      */
-    private Position repositionToTop(Position position, final BooleanParameter top) throws BadSyntax {
+    static Position repositionToTop(Position position, final BooleanParameter top) throws BadSyntax {
         if (top.is()) {
             while (position.parent != null) {
                 position = position.parent;