starting the git macro package

FAQ.adoc

@@ -57,14 +57,15 @@ unless the file starts with the characters  `{@`.
 === I installed the ASCIIDOC plugin, and it gives error for the Jamal documentation
 
 
-If you try to look at the git master HEAD version there is a possibility that the documentation has errors.
+
+It can only happen if you use a non-release, development version.
+
+If you try to look at the git master HEAD version, there is a possibility that the documentation has errors.
 Check on GitHub if the build is broken.
 It usually is not.
 After that check that you have the latest version of the plugin is installed.
 When you edit the git master HEAD version, you are editing a not released version.
 The current documentation of Jamal may use the newest features, which were not released yet.
 To edit these, you need to install the non-released version.
 To do that run `mvn install` in the Jamal project directory first.
-After that `cd jamal-asciidoc` and `sh ./install-asciidoc.sh`.
-
-
+After that `cd jamal-asciidoc` and `sh ./install-asciidoc.sh`.

FAQ.adoc.jam

@@ -51,7 +51,10 @@ unless the file starts with the characters  `{@escape*``{@``}`.
 }
 
 {Q|I installed the ASCIIDOC plugin, and it gives error for the Jamal documentation|
-If you try to look at the git master HEAD version there is a possibility that the documentation has errors.
+
+It can only happen if you use a non-release, development version.
+
+If you try to look at the git master HEAD version, there is a possibility that the documentation has errors.
 Check on GitHub if the build is broken.
 It usually is not.
 After that check that you have the latest version of the plugin is installed.

README.jrf

@@ -1,5 +1,5 @@
 # This is a Jamal reference file containing serialized base64 encoded macros
-# Created: 2024-10-08 20:08:24 +0200
+# Created: 2024-10-25 00:14:29 +0200
 # id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters
 # TOC
 VE9D|eyU=|JX0=|0|0|0|Ci4gPDxJbnN0YWxsYXRpb24+PgouIDw8R1M+PgouIDw8Q29uZmlndXJhdGlvbj4+Ci4gPDxGZWF0dXJlcz4+Ci4gPDxDb250cmlidXRpbmc+PgouIDw8RG9jdW1lbnRhdGlvbj4+Ci4gPDxMaWNlbnNlPj4KLiA8PENoYW5nZWxvZz4+Ci4gPDxSb2FkbWFwPj4KLiA8PFN1cHBvcnQ+PgouIDw8RkFRPj4KLiA8PE1haW50ZW5hbmNlPj4=|

documentation/MODULES.adoc

@@ -250,43 +250,45 @@ Using these macros, you can split up a Yaml file into smaller pieces and use mac
 
 Macros implementing interface to OpenAI.
 
-=== 35. link:https://github.com/verhas/jamal/blob/master/jamal-sql/README.adoc[SQL] ^_macro_^
+=== 35. link:https://github.com/verhas/jamal/blob/master/jamal-git/README.adoc[GIT] ^_macro_^
+
+
+Macros implementing interface to local git repository.
+
+=== 36. link:https://github.com/verhas/jamal/blob/master/jamal-sql/README.adoc[SQL] ^_macro_^
 
 
 Macros implementing SQL interface.
 
-=== 36. link:https://github.com/verhas/jamal/blob/master/jamal-xls/README.adoc[XLS] ^_macro_^
+=== 37. link:https://github.com/verhas/jamal/blob/master/jamal-xls/README.adoc[XLS] ^_macro_^
 
 
 Macros implementing Excel interface.
 
-=== 37. link:https://github.com/verhas/jamal/blob/master/jamal-rest/README.adoc[REST] ^_macro_^
+=== 38. link:https://github.com/verhas/jamal/blob/master/jamal-rest/README.adoc[REST] ^_macro_^
 
 
 Macros implementing REST interface.
 
-=== 38. link:https://github.com/verhas/jamal/blob/master/jamal-java/README.adoc[JAVA] ^_debugger_^
+=== 39. link:https://github.com/verhas/jamal/blob/master/jamal-java/README.adoc[JAVA] ^_debugger_^
 
 
 Experimental module integrating the Java compiler into Jamal as macros.
 
-=== 39. link:https://github.com/verhas/jamal/blob/master/jamal-debug-ui/README.adoc[DEBUG-UI] ^_debugger_^
+=== 40. link:https://github.com/verhas/jamal/blob/master/jamal-debug-ui/README.adoc[DEBUG-UI] ^_debugger_^
 
 
 This is not a module.
 The code in the directory `jamal-debug-ui` contains the REACT.js based ui for the debugger.
 
-=== 40. link:https://github.com/verhas/jamal/blob/master/jamal-docker/README.adoc[DOCKER] ^_embed_^
+=== 41. link:https://github.com/verhas/jamal/blob/master/jamal-docker/README.adoc[DOCKER] ^_embed_^
 
 
 This is not a module.
 The code in the directory `jamal-docker` contains a Dockerfile to build a Docker image with Jamal.
 
-=== 41. link:https://github.com/verhas/jamal/blob/master/jamal-packaging/README.adoc[PACKAGING] ^_packaging_^
-
-
-
-Contains the different packaging code in the subdirectories.
+=== 42. link:https://github.com/verhas/jamal/blob/master/jamal-packaging/README.adoc[PACKAGING] ^_packaging_^
 
 
 
+Contains the different packaging code in the subdirectories.

documentation/MODULES.adoc.jam

@@ -186,6 +186,9 @@ Using these macros, you can split up a Yaml file into smaller pieces and use mac
 {chapter :openai:macro}
 Macros implementing interface to OpenAI.
 
+{chapter :git:macro}
+Macros implementing interface to local git repository.
+
 {chapter :sql:macro}
 Macros implementing SQL interface.
 

jamal-all/README.adoc

@@ -54,6 +54,8 @@ This will add the following dependencies to your project:
 
 * `jamal-rest`
 
+* `jamal-git`
+
 * `jamal-groovy`
 
 * `jamal-io`

jamal-all/pom.xml

@@ -95,6 +95,10 @@
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-rest</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.javax0.jamal</groupId>
+            <artifactId>jamal-git</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-groovy</artifactId>

jamal-asciidoc/README.adoc

@@ -680,6 +680,8 @@ The ZIP file you extracted to the `.Asciidoctor/lib` folder contains the followi
 
 * `jamal-rest`
 
+* `jamal-git`
+
 * `jamal-test`
 
 * `jamal-debug`

jamal-asciidoc/pom.xml

@@ -120,6 +120,10 @@
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-rest</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.javax0.jamal</groupId>
+            <artifactId>jamal-git</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-test</artifactId>

jamal-asciidoc258/pom.xml

@@ -101,6 +101,10 @@
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-rest</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.javax0.jamal</groupId>
+            <artifactId>jamal-git</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-test</artifactId>

jamal-cmd/pom.xml

@@ -124,6 +124,10 @@
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-rest</artifactId>
         </dependency>
+        <dependency>
+            <groupId>com.javax0.jamal</groupId>
+            <artifactId>jamal-git</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.javax0.jamal</groupId>
             <artifactId>jamal-maven-input</artifactId>

jamal-cmd/src/test/resources/jamal.sh.template.jam

@@ -6,7 +6,7 @@
 {@define CENTRAL=https://repo1.maven.org/maven2}\
 
 CLASSPATH=""
-function download() {}
+download() {}
   DIR=${}1//\.//}
   if ! test -f {REPO}/$DIR/$2/$3/$2-$3.jar; then
     echo "downloading {CENTRAL}/$DIR/$2/$3/jamal-$2-$3.jar"

jamal-git/README.adoc

@@ -0,0 +1,120 @@
+= Jamal Git Macros
+
+
+This macro package can fetch information from a local git repository.
+
+To use this module, you have to add the dependency to your Maven project, as:
+
+[source,xml]
+----
+<dependency>
+    <groupId>com.javax0.jamal</groupId>
+    <artifactId>jamal-git</artifactId>
+    <version>2.8.2-SNAPSHOT</version>
+</dependency>
+----
+
+This macro package is included in the prepackaged versions of Jamal.
+
+== Macros Implemented
+
+
+=== `git`
+
+This macro should be used to specify the directory of the git repository.
+For example
+
+.Jamal source
+[source]
+----
+{@git location=../.git}
+----
+
+will locate the repository and then subsequent macros can fetch information from the repository.
+The parameter option (parop) `location` is mandatory and it should point to the `.git` directory of the repository.
+
+The parameters of the opened repository are stored in the user defined macro `$git`.
+You can reference this macro directly as `{$git}` and the value will always be an empty string.
+
+If you want to handle multiple git repositories, you can use the parop `id` to give an identifier to the repository.
+If used, the name specified will be used as a user-defined macro name to store the preference to the git repository.
+In this case the parop `id` should be used in all later calls to the git macros using the specific git repository.
+
+=== `git:tag(s)`, `got:branch(es)`
+
+This macro can be called as
+
+* `git:tag`,
+* `git:tags`,
+* `git:branch`, or
+* `git:branches`
+
+The macro can collect tags or branches from the local git repository.
+The singular and plural forms behave the same, and they exist to help the readability.
+The macro names containing `tag` return a tag  or tags, and the ones containing `branch` return a branch or branches.
+
+The behavior of the macro can be controlled using parops.
+These are the following:
+
+* `id`
+is the identifier of the opened git repository.
+The default value is `$git` which is also the default value of the `git:connect` macro.
+If you are not dealing with more than one git repositories you can omit this parameter.
+Use it only if you also used it in the `git:connect` macro.
+* `match`
+is a regular expression that the tag name should match.
+If this parameter is present, then only those tags are listed that match the regular expression.
+* `index`
+is the index of the tag to list.
+If this parameter is present, then only the tag at the index is listed.
+The index is 0-based.
+Negative index is also allowed.
+In this case, the index is counted from the end of the list.
+For example, -1 means the last tag.
+If the index is too large or too small, then an error is thrown.
+* `last`
+If this parameter is present, then only the last tag is listed.
+It is the same as `index=-1`.
+* `first`
+If this parameter is present, then only the first tag is listed.
+It is the same as `index=0`.
+* `single`
+If this parameter is present, then the result is a single tag.
+If this parameter is present and the result is more than one tag then an error is thrown.
+
+* `orderByName` orders the tags by name.
+* `orderByDate` orders the tags by the commit date.
++
+The default value is `orderByName`.
+`orderByName` and `orderByDate` are exclusive; you can use only one.
+
+* `name` will return the name(s) of the tag(s) or branch(es).
+* `time` will return the time of the commit of the tag(s) or branch(es).
+* `hash` will return the hash of the commit of the tag(s) or branch(es).
++
+The default value is `name`.
+`name`, `time`, and `hash` are exclusive; you can use only one.
+* `sep`
+is the separator between the tags.
+The default value is `,` (a comma).
+This string (not only a single character is possible) is used to separate the tags in the result.
+The list can be used as the value list for the `for` macro.
+In the very special case when some of the tag or branch names contains a comma, then you can use this parameter.
+
+
+Examples:
+
+.Jamal source
+[source]
+----
+{@git location=../.git}
+The latest release of Jamal is {#string:substring (begin=1) {@git:tag last orderByName match=v.*}}.
+----
+
+result in:
+
+.output
+[source]
+----
+The latest release of Jamal is 2.8.1.
+----

jamal-git/README.adoc.jam

@@ -0,0 +1,70 @@
+= Jamal Git Macros
+{%@import res:jamal.jim%}
+{%@snip:xml pom=pom.xml%}\
+{%#define VERSION={%pom /project/version/text()%}%}\
+
+This macro package can fetch information from a local git repository.
+
+To use this module, you have to add the dependency to your Maven project, as:
+
+[source,xml]
+----
+<dependency>
+    <groupId>com.javax0.jamal</groupId>
+    <artifactId>{%pom /project/artifactId/text()%}</artifactId>
+    <version>{%VERSION%}</version>
+</dependency>
+----
+
+This macro package is included in the prepackaged versions of Jamal.
+
+== Macros Implemented
+{%@snip:collect from=src/main/%}
+
+=== `git`
+
+This macro should be used to specify the directory of the git repository.
+For example
+
+{%sample/{@git location=../.git}%}
+
+will locate the repository and then subsequent macros can fetch information from the repository.
+The parameter option (parop) `location` is mandatory and it should point to the `.git` directory of the repository.
+
+The parameters of the opened repository are stored in the user defined macro `$git`.
+You can reference this macro directly as `{$git}` and the value will always be an empty string.
+
+If you want to handle multiple git repositories, you can use the parop `id` to give an identifier to the repository.
+If used, the name specified will be used as a user-defined macro name to store the preference to the git repository.
+In this case the parop `id` should be used in all later calls to the git macros using the specific git repository.
+
+=== `git:tag(s)`, `got:branch(es)`
+
+This macro can be called as
+
+* `git:tag`,
+* `git:tags`,
+* `git:branch`, or
+* `git:branches`
+
+The macro can collect tags or branches from the local git repository.
+The singular and plural forms behave the same, and they exist to help the readability.
+The macro names containing `tag` return a tag  or tags, and the ones containing `branch` return a branch or branches.
+
+The behavior of the macro can be controlled using parops.
+These are the following:
+
+{%#replaceLines replace="/^.*?\"(.*?)\".*/* `$1`/" replace=~^\s*//\s*~~ replace="/.*enumeration.*/"
+{%@snip tag_parameters%}%}
+
+Examples:
+
+{%sample/{@git location=../.git}
+The latest release of Jamal is {#string:substring (begin=1) {@git:tag last orderByName match=v.*}}.
+%}
+
+result in:
+
+{%output%}
+
+

jamal-git/pom.jam

@@ -0,0 +1,21 @@
+{@import https://raw.githubusercontent.com/central7/pom/1/pom.jim}
+{@import ../version.jim}
+{project jamal maven input}
+    {GAV ::jamal-git:{VERSION}}
+    {parent :{GROUPID}:jamal-parent}
+    {description :Jamal Git repo reading plugin}
+
+    {@define openForTests={opens/git/git}}
+    {build|{plugins| {@include ../plugins.jim}}}
+
+    {dependencies#
+        {#for MODULE in (engine,extensions,tools)=
+            {dependency|{GROUPID}|jamal-MODULE}}
+        {#for MODULE in (testsupport)=
+            {dependency|{GROUPID}|jamal-MODULE||test}}
+        {#for MODULE in (api,engine)=
+            {dependency|org.junit.jupiter|junit-jupiter-MODULE}}
+        {dependency|org.eclipse.jgit|org.eclipse.jgit|6.6.1.202309021850-r}
+    }
+{end project}
+{@xmlFormat}