Skip to content

Commit 17ac61d

Browse files
verhasverhas
committed
starting the git macro package
1 parent c96d646 commit 17ac61d

File tree

38 files changed

+858
-37
lines changed

38 files changed

+858
-37
lines changed

‎FAQ.adoc

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,14 +57,15 @@ unless the file starts with the characters `{@`.
5757
=== I installed the ASCIIDOC plugin, and it gives error for the Jamal documentation
5858

5959

60-
If you try to look at the git master HEAD version there is a possibility that the documentation has errors.
60+
61+
It can only happen if you use a non-release, development version.
62+
63+
If you try to look at the git master HEAD version, there is a possibility that the documentation has errors.
6164
Check on GitHub if the build is broken.
6265
It usually is not.
6366
After that check that you have the latest version of the plugin is installed.
6467
When you edit the git master HEAD version, you are editing a not released version.
6568
The current documentation of Jamal may use the newest features, which were not released yet.
6669
To edit these, you need to install the non-released version.
6770
To do that run `mvn install` in the Jamal project directory first.
68-
After that `cd jamal-asciidoc` and `sh ./install-asciidoc.sh`.
69-
70-
71+
After that `cd jamal-asciidoc` and `sh ./install-asciidoc.sh`.

‎FAQ.adoc.jam

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,10 @@ unless the file starts with the characters `{@escape*``{@``}`.
5151
}
5252

5353
{Q|I installed the ASCIIDOC plugin, and it gives error for the Jamal documentation|
54-
If you try to look at the git master HEAD version there is a possibility that the documentation has errors.
54+
55+
It can only happen if you use a non-release, development version.
56+
57+
If you try to look at the git master HEAD version, there is a possibility that the documentation has errors.
5558
Check on GitHub if the build is broken.
5659
It usually is not.
5760
After that check that you have the latest version of the plugin is installed.

‎README.jrf

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# This is a Jamal reference file containing serialized base64 encoded macros
2-
# Created: 2024-10-08 20:08:24 +0200
2+
# Created: 2024-10-25 00:14:29 +0200
33
# id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters
44
# TOC
55
VE9D|eyU=|JX0=|0|0|0|Ci4gPDxJbnN0YWxsYXRpb24+PgouIDw8R1M+PgouIDw8Q29uZmlndXJhdGlvbj4+Ci4gPDxGZWF0dXJlcz4+Ci4gPDxDb250cmlidXRpbmc+PgouIDw8RG9jdW1lbnRhdGlvbj4+Ci4gPDxMaWNlbnNlPj4KLiA8PENoYW5nZWxvZz4+Ci4gPDxSb2FkbWFwPj4KLiA8PFN1cHBvcnQ+PgouIDw8RkFRPj4KLiA8PE1haW50ZW5hbmNlPj4=|

‎documentation/MODULES.adoc

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -250,43 +250,45 @@ Using these macros, you can split up a Yaml file into smaller pieces and use mac
250250

251251
Macros implementing interface to OpenAI.
252252

253-
=== 35. link:https://github.com/verhas/jamal/blob/master/jamal-sql/README.adoc[SQL] ^_macro_^
253+
=== 35. link:https://github.com/verhas/jamal/blob/master/jamal-git/README.adoc[GIT] ^_macro_^
254+
255+
256+
Macros implementing interface to local git repository.
257+
258+
=== 36. link:https://github.com/verhas/jamal/blob/master/jamal-sql/README.adoc[SQL] ^_macro_^
254259

255260

256261
Macros implementing SQL interface.
257262

258-
=== 36. link:https://github.com/verhas/jamal/blob/master/jamal-xls/README.adoc[XLS] ^_macro_^
263+
=== 37. link:https://github.com/verhas/jamal/blob/master/jamal-xls/README.adoc[XLS] ^_macro_^
259264

260265

261266
Macros implementing Excel interface.
262267

263-
=== 37. link:https://github.com/verhas/jamal/blob/master/jamal-rest/README.adoc[REST] ^_macro_^
268+
=== 38. link:https://github.com/verhas/jamal/blob/master/jamal-rest/README.adoc[REST] ^_macro_^
264269

265270

266271
Macros implementing REST interface.
267272

268-
=== 38. link:https://github.com/verhas/jamal/blob/master/jamal-java/README.adoc[JAVA] ^_debugger_^
273+
=== 39. link:https://github.com/verhas/jamal/blob/master/jamal-java/README.adoc[JAVA] ^_debugger_^
269274

270275

271276
Experimental module integrating the Java compiler into Jamal as macros.
272277

273-
=== 39. link:https://github.com/verhas/jamal/blob/master/jamal-debug-ui/README.adoc[DEBUG-UI] ^_debugger_^
278+
=== 40. link:https://github.com/verhas/jamal/blob/master/jamal-debug-ui/README.adoc[DEBUG-UI] ^_debugger_^
274279

275280

276281
This is not a module.
277282
The code in the directory `jamal-debug-ui` contains the REACT.js based ui for the debugger.
278283

279-
=== 40. link:https://github.com/verhas/jamal/blob/master/jamal-docker/README.adoc[DOCKER] ^_embed_^
284+
=== 41. link:https://github.com/verhas/jamal/blob/master/jamal-docker/README.adoc[DOCKER] ^_embed_^
280285

281286

282287
This is not a module.
283288
The code in the directory `jamal-docker` contains a Dockerfile to build a Docker image with Jamal.
284289

285-
=== 41. link:https://github.com/verhas/jamal/blob/master/jamal-packaging/README.adoc[PACKAGING] ^_packaging_^
286-
287-
288-
289-
Contains the different packaging code in the subdirectories.
290+
=== 42. link:https://github.com/verhas/jamal/blob/master/jamal-packaging/README.adoc[PACKAGING] ^_packaging_^
290291

291292

292293

294+
Contains the different packaging code in the subdirectories.

‎documentation/MODULES.adoc.jam

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,9 @@ Using these macros, you can split up a Yaml file into smaller pieces and use mac
186186
{chapter :openai:macro}
187187
Macros implementing interface to OpenAI.
188188

189+
{chapter :git:macro}
190+
Macros implementing interface to local git repository.
191+
189192
{chapter :sql:macro}
190193
Macros implementing SQL interface.
191194

‎jamal-all/README.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ This will add the following dependencies to your project:
5454
5555
* `jamal-rest`
5656
57+
* `jamal-git`
58+
5759
* `jamal-groovy`
5860
5961
* `jamal-io`

‎jamal-all/pom.xml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,10 @@
9595
<groupId>com.javax0.jamal</groupId>
9696
<artifactId>jamal-rest</artifactId>
9797
</dependency>
98+
<dependency>
99+
<groupId>com.javax0.jamal</groupId>
100+
<artifactId>jamal-git</artifactId>
101+
</dependency>
98102
<dependency>
99103
<groupId>com.javax0.jamal</groupId>
100104
<artifactId>jamal-groovy</artifactId>

‎jamal-asciidoc/README.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -680,6 +680,8 @@ The ZIP file you extracted to the `.Asciidoctor/lib` folder contains the followi
680680

681681
* `jamal-rest`
682682

683+
* `jamal-git`
684+
683685
* `jamal-test`
684686

685687
* `jamal-debug`

‎jamal-asciidoc/pom.xml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,10 @@
120120
<groupId>com.javax0.jamal</groupId>
121121
<artifactId>jamal-rest</artifactId>
122122
</dependency>
123+
<dependency>
124+
<groupId>com.javax0.jamal</groupId>
125+
<artifactId>jamal-git</artifactId>
126+
</dependency>
123127
<dependency>
124128
<groupId>com.javax0.jamal</groupId>
125129
<artifactId>jamal-test</artifactId>

‎jamal-asciidoc258/pom.xml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,10 @@
101101
<groupId>com.javax0.jamal</groupId>
102102
<artifactId>jamal-rest</artifactId>
103103
</dependency>
104+
<dependency>
105+
<groupId>com.javax0.jamal</groupId>
106+
<artifactId>jamal-git</artifactId>
107+
</dependency>
104108
<dependency>
105109
<groupId>com.javax0.jamal</groupId>
106110
<artifactId>jamal-test</artifactId>

‎jamal-cmd/pom.xml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,10 @@
124124
<groupId>com.javax0.jamal</groupId>
125125
<artifactId>jamal-rest</artifactId>
126126
</dependency>
127+
<dependency>
128+
<groupId>com.javax0.jamal</groupId>
129+
<artifactId>jamal-git</artifactId>
130+
</dependency>
127131
<dependency>
128132
<groupId>com.javax0.jamal</groupId>
129133
<artifactId>jamal-maven-input</artifactId>

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
{@define CENTRAL=https://repo1.maven.org/maven2}\
77

88
CLASSPATH=""
9-
function download() {}
9+
download() {}
1010
DIR=${}1//\.//}
1111
if ! test -f {REPO}/$DIR/$2/$3/$2-$3.jar; then
1212
echo "downloading {CENTRAL}/$DIR/$2/$3/jamal-$2-$3.jar"

‎jamal-git/README.adoc

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
= Jamal Git Macros
2+
3+
4+
This macro package can fetch information from a local git repository.
5+
6+
To use this module, you have to add the dependency to your Maven project, as:
7+
8+
[source,xml]
9+
----
10+
<dependency>
11+
<groupId>com.javax0.jamal</groupId>
12+
<artifactId>jamal-git</artifactId>
13+
<version>2.8.2-SNAPSHOT</version>
14+
</dependency>
15+
----
16+
17+
This macro package is included in the prepackaged versions of Jamal.
18+
19+
== Macros Implemented
20+
21+
22+
=== `git`
23+
24+
This macro should be used to specify the directory of the git repository.
25+
For example
26+
27+
.Jamal source
28+
[source]
29+
----
30+
{@git location=../.git}
31+
----
32+
33+
will locate the repository and then subsequent macros can fetch information from the repository.
34+
The parameter option (parop) `location` is mandatory and it should point to the `.git` directory of the repository.
35+
36+
The parameters of the opened repository are stored in the user defined macro `$git`.
37+
You can reference this macro directly as `{$git}` and the value will always be an empty string.
38+
39+
If you want to handle multiple git repositories, you can use the parop `id` to give an identifier to the repository.
40+
If used, the name specified will be used as a user-defined macro name to store the preference to the git repository.
41+
In this case the parop `id` should be used in all later calls to the git macros using the specific git repository.
42+
43+
=== `git:tag(s)`, `got:branch(es)`
44+
45+
This macro can be called as
46+
47+
* `git:tag`,
48+
* `git:tags`,
49+
* `git:branch`, or
50+
* `git:branches`
51+
52+
The macro can collect tags or branches from the local git repository.
53+
The singular and plural forms behave the same, and they exist to help the readability.
54+
The macro names containing `tag` return a tag or tags, and the ones containing `branch` return a branch or branches.
55+
56+
The behavior of the macro can be controlled using parops.
57+
These are the following:
58+
59+
* `id`
60+
is the identifier of the opened git repository.
61+
The default value is `$git` which is also the default value of the `git:connect` macro.
62+
If you are not dealing with more than one git repositories you can omit this parameter.
63+
Use it only if you also used it in the `git:connect` macro.
64+
* `match`
65+
is a regular expression that the tag name should match.
66+
If this parameter is present, then only those tags are listed that match the regular expression.
67+
* `index`
68+
is the index of the tag to list.
69+
If this parameter is present, then only the tag at the index is listed.
70+
The index is 0-based.
71+
Negative index is also allowed.
72+
In this case, the index is counted from the end of the list.
73+
For example, -1 means the last tag.
74+
If the index is too large or too small, then an error is thrown.
75+
* `last`
76+
If this parameter is present, then only the last tag is listed.
77+
It is the same as `index=-1`.
78+
* `first`
79+
If this parameter is present, then only the first tag is listed.
80+
It is the same as `index=0`.
81+
* `single`
82+
If this parameter is present, then the result is a single tag.
83+
If this parameter is present and the result is more than one tag then an error is thrown.
84+
85+
* `orderByName` orders the tags by name.
86+
* `orderByDate` orders the tags by the commit date.
87+
+
88+
The default value is `orderByName`.
89+
`orderByName` and `orderByDate` are exclusive; you can use only one.
90+
91+
* `name` will return the name(s) of the tag(s) or branch(es).
92+
* `time` will return the time of the commit of the tag(s) or branch(es).
93+
* `hash` will return the hash of the commit of the tag(s) or branch(es).
94+
+
95+
The default value is `name`.
96+
`name`, `time`, and `hash` are exclusive; you can use only one.
97+
* `sep`
98+
is the separator between the tags.
99+
The default value is `,` (a comma).
100+
This string (not only a single character is possible) is used to separate the tags in the result.
101+
The list can be used as the value list for the `for` macro.
102+
In the very special case when some of the tag or branch names contains a comma, then you can use this parameter.
103+
104+
105+
Examples:
106+
107+
.Jamal source
108+
[source]
109+
----
110+
{@git location=../.git}
111+
The latest release of Jamal is {#string:substring (begin=1) {@git:tag last orderByName match=v.*}}.
112+
----
113+
114+
result in:
115+
116+
.output
117+
[source]
118+
----
119+
The latest release of Jamal is 2.8.1.
120+
----

‎jamal-git/README.adoc.jam

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
= Jamal Git Macros
2+
{%@import res:jamal.jim%}
3+
{%@snip:xml pom=pom.xml%}\
4+
{%#define VERSION={%pom /project/version/text()%}%}\
5+
6+
This macro package can fetch information from a local git repository.
7+
8+
To use this module, you have to add the dependency to your Maven project, as:
9+
10+
[source,xml]
11+
----
12+
<dependency>
13+
<groupId>com.javax0.jamal</groupId>
14+
<artifactId>{%pom /project/artifactId/text()%}</artifactId>
15+
<version>{%VERSION%}</version>
16+
</dependency>
17+
----
18+
19+
This macro package is included in the prepackaged versions of Jamal.
20+
21+
== Macros Implemented
22+
{%@snip:collect from=src/main/%}
23+
24+
=== `git`
25+
26+
This macro should be used to specify the directory of the git repository.
27+
For example
28+
29+
{%sample/{@git location=../.git}%}
30+
31+
will locate the repository and then subsequent macros can fetch information from the repository.
32+
The parameter option (parop) `location` is mandatory and it should point to the `.git` directory of the repository.
33+
34+
The parameters of the opened repository are stored in the user defined macro `$git`.
35+
You can reference this macro directly as `{$git}` and the value will always be an empty string.
36+
37+
If you want to handle multiple git repositories, you can use the parop `id` to give an identifier to the repository.
38+
If used, the name specified will be used as a user-defined macro name to store the preference to the git repository.
39+
In this case the parop `id` should be used in all later calls to the git macros using the specific git repository.
40+
41+
=== `git:tag(s)`, `got:branch(es)`
42+
43+
This macro can be called as
44+
45+
* `git:tag`,
46+
* `git:tags`,
47+
* `git:branch`, or
48+
* `git:branches`
49+
50+
The macro can collect tags or branches from the local git repository.
51+
The singular and plural forms behave the same, and they exist to help the readability.
52+
The macro names containing `tag` return a tag or tags, and the ones containing `branch` return a branch or branches.
53+
54+
The behavior of the macro can be controlled using parops.
55+
These are the following:
56+
57+
{%#replaceLines replace="/^.*?\"(.*?)\".*/* `$1`/" replace=~^\s*//\s*~~ replace="/.*enumeration.*/"
58+
{%@snip tag_parameters%}%}
59+
60+
Examples:
61+
62+
{%sample/{@git location=../.git}
63+
The latest release of Jamal is {#string:substring (begin=1) {@git:tag last orderByName match=v.*}}.
64+
%}
65+
66+
result in:
67+
68+
{%output%}
69+
70+

‎jamal-git/pom.jam

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{@import https://raw.githubusercontent.com/central7/pom/1/pom.jim}
2+
{@import ../version.jim}
3+
{project jamal maven input}
4+
{GAV ::jamal-git:{VERSION}}
5+
{parent :{GROUPID}:jamal-parent}
6+
{description :Jamal Git repo reading plugin}
7+
8+
{@define openForTests={opens/git/git}}
9+
{build|{plugins| {@include ../plugins.jim}}}
10+
11+
{dependencies#
12+
{#for MODULE in (engine,extensions,tools)=
13+
{dependency|{GROUPID}|jamal-MODULE}}
14+
{#for MODULE in (testsupport)=
15+
{dependency|{GROUPID}|jamal-MODULE||test}}
16+
{#for MODULE in (api,engine)=
17+
{dependency|org.junit.jupiter|junit-jupiter-MODULE}}
18+
{dependency|org.eclipse.jgit|org.eclipse.jgit|6.6.1.202309021850-r}
19+
}
20+
{end project}
21+
{@xmlFormat}

0 commit comments

Comments
 (0)