RELEASES.adoc.jam

= Jamal Releases

{%@import RELEASES.jim%}
{%@snip:collect from=./jamal-core/src%}

{%@define RELEASE_N($x)=== https://github.com/verhas/jamal/tree/$x[$x]%}
{%@define RELEASE($x)={%RELEASE_N {%RELEASE:$x%}%}%}

NOTE: The known bugs sections in the releases are updated after the release.
Plese consult the latest SNAPSHOT version available online at https://github.com/verhas/jamal/blob/master/RELEASES.adoc[GitHub Jamal RELEASES.adoc]

{%RELEASE KOMLO%}

=== Known Bugs

__currently there are no known bugs in this release__

=== New Features

* Functions depending on environment variables also read possible values from `.env` files.
  This functionality can be achieved in prior versions using tools like `direnv`.
  From this release Jamal itself reads the `.env` files.

* `trimLines` is also aliased as `trim` in the snippet library.

{%RELEASE PECS%}

=== Known Bugs

__currently there are no known bugs in this release__

=== New Features

* The `prog` module implements floating-point calculations.

{%RELEASE PECSVARAD%}

=== Known Bugs

__currently there are no known bugs in this release__

=== New Features

* A new modul to handle REST requests.
* A new modul to read from Microsoft Excel files and also to write into them.
* Macro `for` has a new parameter option.
* Macro `def` in the snippet module to simplify defining parameter-less macros.

=== Bug Fixes

* This version can be used as a Maven extension. The earlier bug was fixed.


{%RELEASE OULU%}

=== Known Bugs

* This release does not work as a Maven Extension.
The maven extensions started to use the pre-release Maven core dependecies of `4.0.0`.
It was a mistake, but until `4.0.0-alpha-8` there was no compatibility issue.
The Jamal extension structure was drastically changed from Maven core `4.0.0-alpha-8` to `beta` releases.
It caused the Maven extension to fail silently.
The extension is not invoked.
Since the source of Jamal contains the `pom.xml` files along the source files the fact that the extension did not start was not discovered.
+
*Workaround:* (1) Use {%RELEASE:ROGACHEVO%} version of Jamal as a maven extension.
If you need the features from the release {%RELEASE:OULU%} then.
(2) Avoid using the extension and traspile the `pom.jam` files to `pom.xml` files using the `jamal` command-line tool or Maven plugin.

=== New Features

* `jrf` (reference) files now can contain comments to make them more readable.
* `import` has a new parop `global` that makes the import global and not imported again even if the file was imported from a local scope.
* `import` does not import a file again if it has the same content as an already imported file.
Until now, different files with the same content could be imported in parallel.
* Snippet library has a new macro `plural` that can be used to pluralize a word.
* Bugfix: invoking macro close for AutoCloseable macros that need a processor and output.
* Module plantUML was removed from development.
This module is not supported anymore.
Using plant UML diagrams should be available through Kroki either using the public service or using a local containerized Kroki server.
* Bug fixed in `kroki.jim` resource file.
* String macro `string` can perform `equals`, `startsWith`, and `endsWith` operations more readably and with an `ignoreCase` option.
* String macro `string:between` can be used to extract a substring between two strings.
* A macro Java code can query the ID used to invoke it via the processor's `getId()` method.
  It makes it possible to alter the behavior of a macro based on the ID used to invoke it.
* Macro `string:before` and `string:after`.
* Macro `dev:root` can be used to find the root directory of the project.
* Macro `snip:update` is removed after long deprecated.
* A bug fixed in the macro references that caused index out of range exception if the `.jrf` reference file was corrupt.
* The processor properly reports the syntax error even if there is a syntax error also in some of the closers (code that runs at the end of the processing).

{%RELEASE ROGACHEVO%}

* Macro `options` can also be used as `option` in singular.
* Macro `options` has the parops `push` and `pop`.
* Macro `define` parop `noRedefine` can also be used as an option, not only as a parop.
* Macro `repeat` was developed in the snippet library.
* Macro `import` has a new parop, `isolate`, that makes the import isolated.
* Generated files are set to be read-only, so that they are not accidentally edited.
* `output:writable` can override this behavior.
* Command-line option `-jamalize` can install the Jamal AsciiDoc extension into the current project.
* An experimental parser was developed to support editor plugins and LSE implementations in the future.
* `output:charset` can be used to specify the output charset.
* `units.jim` defines the Unicode metric units characters.
* There is support to run Jamal from Docker in the `jamal-docker` module.
* The core macro `for` with the parop `evalist` allows you to omit the macro opening and closing strings when the list is nothing but an argument-less macro invocation.
* The `jamal-prog` package contains a macro `decimal` to support `BigDecimal` calculation in BASIC code.
* The `replace` and `replaceLines` macros in the snippet package result in an error not only if the input was not changed, but also when some of the search/replace string-string or regular expression-string pairs made no effect on the input when the option `detectNoChange` is used.
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 macros use 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 the parop `in`.
* The macros `file` and `directory` in the snippet package have a new parop `relativeTo` that controls the formatting placeholder calculation `relativePath`.
* The new macro `file:locate` can locate files.
* Exceptions insert the macro locations at the top of the stack trace.
* Macro `variation` was developed.

{%RELEASE IZMIR%}

* Kotlin support to make Macro creation in Kotlin a breeze.
* Scan interface usage to parse parops was eliminated.
* Word `decorator` macro was developed due to popular demand.
* Macro `counter` was extended to support hierarchical counters and also other than Latin characters.
* User-defined macros can have default parops for better readability.
* New `$time`, `$atime`, and `$ctime` placeholders for the `file` macro.

{%RELEASE MANAUS%}

* Core macro supports the option `flat` (alias as `export`) to evaluate the content in the same scope as the surrounding macro.
* `references` macro runs an idempotency check at the end of the execution.
* Macro parops that do not need `(` and `)` can be specified with optional parentheses.
You do not need to remember not to use the parentheses.
* Asciidoctor's extension supports both 2.5.10 and 3.0.0-alpha.1 versions of Asciidoctor.
It is not integration tested for the 3.X.X versions because the IntelliJ plugin currently supports 2.X.X versions only.
* Asciidoctor integration defines `asciidoctorj:version` macro.
* Upon start and macro load, Jamal executes the `.jim` resource files.
* Macro `define` can create a user-defined macro being an instance of a given class.
* Macro `urlEncode` can encode a string to be used in a URL.
* More Kroki support with `kroki` macro.
* Built-in BASIC can call user-defined and built-in macros.

{%RELEASE MELBOURNE%}

* Support for JSR223 scripting API.
Now you can use Jamal in any application that can be scripted.
* New macro in the file module to test file existence, type (dir or plain file), readability, writable, executable, or hidden.
* New macro in the file module to copy binary files.
Useful to fetch ephemeral resources via HTTP to have them attached to the document.
* New macro in the snippet library to memoize certain operations.
* `snip_list` does not list erroneous snippets anymore.
* `java:insert` can fail with error if it updates the file.
* New environment variable `asciidocfx.asciidoctor.plugin` is usable, the same as `intellij.asciidoctor.plugin`.
* Jamal works in AsciidocFX as well.
This is not a feature of this release, but it was tested and documented in this release first.
It requires AsciidocFX 1.8.5 or later.
* Macro `download` in the snippet library can download files from the internet.
* New macro `UrlEncode` in the snippet library.
* Macros implement the `OptionControlled` interface to discover the option open and close characters.
* Macro `program` can be used with the alias `prog`, and macros can be invoked from the BASIC script as functions or methods.
* Define can define a user-defined class specifying the class.

{%RELEASE BERLIN%}

* `java:insert` macro can

 insert a macro result into a Java source file between

  <editor-fold id="">
  </editor-fold>
+
lines.

* Macro `java:sources` can load the sources and compile as well, as from the compiled classes so that other macros can reference.
Macros `java:classes`, `java:methods`, `java:fields` can be used to list the classes, methods, and the fields of a class.

* Jamal Maven plugin was rewritten and has new functionality.

* Jamalize can be used to install Asciidoctor library files for IntelliJ.

* `shell:var` can replace `$xxx` and `$pass:[{xxx}]` references.

* `io:exec` was extended to support multi-line command and arguments.

{%RELEASE SOROKSAR%}

Experimental feature with a snippet collection from Java sources without specifying snippets in the code.

{%RELEASE CSEPEL%}

Bug fix release.
A bug driving the `prog` macro into an infinite loop was fixed.

{%RELEASE BUDAPEST%}

* The 'extensions' plugin was removed from the Maven extension dependency and from the AsciiDoc extension.

* Macro `program` can also be used with `do` and `run` aliases.

* File handling can read from a JAR file.

* `maven:load` can load macros from the Maven repository.

* `jbim` macro package was developed that can compile and load Java code from the Jamal file.

* Jbang, Asciidoctor, and command-line versions do not package the scripting modules.
Any script needing those has to use the `maven:load` macro to load the modules.

* Core macro include also uses the `{` and `}` characters to delimit the macro when the included file starts with `{@`.

* When you specify a range, like in the macro `include` option `lines`, you can use `inf` or `infinity` to denote infinity as the start or end of a range (case-insensitive).

* Docker is used to support integration-level tests, especially the access control check of the configuration needed by the macro `maven:load`.

* The core macro `define` implements the parop `tail` to have the last parameter containing the rest of the input instead of getting an error.

* The snippet library implements Base64 encoding and decoding.
Using this macro, you can insert Kroki pictures into your document.
There is also a `res:kroki.jim` importable resource script.

{%RELEASE_N/1.12.6%}
There is a new macro library `prog` that implements a simple BASIC-like programming language.

Snippet library macro `directory` has the same formatting options as `file` macro.
There are two new macros in the snippet library: `unicode` and `numbers`.
The `snip:check` macro implements the options `warning` and `error`.
JShell handling improved.
When there is no JShell, it causes BadSyntax and thus can be handled using the macro `try`.

When closing, the processor exceptions are cleared not only when there are closers.
This was a bug causing the exceptions to reappear using the macros `sample` and `output`.

The handling of external files, like `res:`, and `https:` were moved to services found using the service loader mechanism.
Loading files from Maven artifacts was implementing this service.

The prog macro package is implemented, giving imperative simple BASIC-like programming capabilities.

The AsciiDoc preprocessor for the IntelliJ Asciidoctor plugin supports the `prefixLog` option.

{%RELEASE_N/1.12.5%}

* Asciidoctor extension works with any file and converts whatever it can to AsciiDoc.

* There is a converter for Markdown, XML, and general text.

* It is possible to write a general converter for any file, which is edited as text and can be converted to AsciiDoc.
The converter will be picked up by the Asciidoctor plugin's Jamal preprocessor.

* Asciidoctor preprocessor sets the classloader, and that way, Snakeyaml can load the Ref files, and processing works in the editor as well.

* There is a system property `intellij.asciidoctor.plugin` set only in the IntelliJ Asciidoctor plugin.

{%RELEASE_N/1.12.4%}

* Asciidoctor extension works on all `*.jam` files.
If the extension is not `.adoc.jam`, it formats the display as preformatted AsciiDoc text.
* Asciidoctor extension can read directly from the `.jam` file when the `fromFile` option is used.
* Bug fixed that sometimes resulted in undefined counters.
* Asciidoctor gracefully handles the front matter when working with Jekyll files.
* Asciidoctor preprocessor can save the output to a file denoted by the macro `AsciiDoc:output`.
* Core macro `if` has `isDefined`, `isLocal`, and `isGlobal` options.

{%RELEASE_N/1.12.3%}

* Various bug fixes and dependency version updates.

* Sorting macro is available in the snippet library, developed by Michael.

* The macro `define` has options for all the different "define" types, like pure, verbatim, etc.
Originally, these could be reached using special characters, which are less verbose but cryptic.
The old syntax is still usable but not recommended.

* `file` macro in the snippet package now has formatting placeholders `bareNaked` and `nakedN` as well as `extensions` and `extensionN` with the possible `N` values being 1,2,3,4, and 5.

* The macro `counter` can save its actual value using `->`.
This is a shortcut to a series of macros.

* The Asciidoctor preprocessor caches the result of the last run and executes Jamal only when the input changes.
It also takes the included and imported files into account.

* A bug in the core of the processing engine that caused, in some rare cases, an over-indexing exception.

* The environment variable `JAMAL_DEV_PATH` now can point to a file instead of containing the replacements directly.

* Macros reading and writing a file can go through a hook that the embedding application can provide.
It is used by the Asciidoctor implementation to list all the files read during the processing.

* Jamal mock library is implemented, which can be used to mock some macros for user-defined macro testing.

* A warning is given when a macro is defined in a scope, but it is not used.

* Macro `for` supports the aliases `sep` and `subsep`.

* In addition to the special characters in the macro `define`, the behavior can also be altered using options.

* The option `{%@snip RestrictedDefineParameters%}` is now available for the `define` macro, to restrict parameter names to be identifiers.

{%RELEASE_N/1.12.2%}

* Doclet is fixed.
It can use all modules.

* `snip` macro itself can transform; there is no need for an extra `snip:transform` macro around it.

{%RELEASE_N/1.12.1%}

* When the macro `for` was used with the option `evalist`, the list could not include files using a relative file name because the evaluation was done by the processor on an input that had no file reference.
This is a

 bugfix release.

{%RELEASE_N/1.12.0%}

* It is possible to include a Word doc file into another Word doc file using the `docx:include` macro.

* You can insert a picture into a Word document using a Jamal macro.
Since picture insertion is a basic function of Microsoft Word, this functionality is to be used for special purposes only.

* The macro `snip` can also check if a snippet has changed using the `hash` parop.
There is no need to invoke a separate `snip:check` macro.

* There is an Asciidoctor extension, which can be used in IntelliJ to edit Jamal extended AsciiDoc in a WYSIWYG way.

* The Asciidoctor extension emits a `sed` command at the end of the error report, just in case and to help the lazy.

{%RELEASE_N/1.11.3%}

__This is a technical release.
It must not be used.__

It is not present on GitHub, only in Maven central.

{%RELEASE_N/1.11.2%}

* Bug fix release.
The `jamal-word` module has now fixed a bug that caused an index out of range error in some cases.
The bug manifested if the Word document contained a 'run' that contained no text in it.

* Some experimental `docx:` macros are also included in this release to control the generated output docx file to be protected from editing and to force track changes.

{%RELEASE_N/1.11.1%}

* Fully reworked command-line interface.

* Jamal macros can be used in Microsoft Word documents.

* Io module implements `io:exec` and `io:waitFor` macros to start external processes.

* `extension.xml` generation in Maven extension runs in a separate thread, so it does not delay the build.

* `~/.jamal/settings.(properties|xml)` can be used to configure Jamal in addition to system properties and environment variables.

* Use of the external library picocli was eliminated.

* File input converts `\r\n` to `\n` on Windows.

* Graphviz example was added to the integration tests, runs only on properly configured systems; it needs Graphviz installed eventually.

{%RELEASE_N/1.11.0%}

* Jamal provides suggestions in case a macro name is misspelled.

* Macro parameter handling provides suggestions when the parameter name is misspelled.
The suggestions are based on the Levenshtein distance.

* Root directory finding and converting all Jamal files with exclude/include list is part of the API.
This API is supposed to be used during unit test execution, which creates the documentation from the Jamal files.
Finding the project root directory is also part of the API.

* Macro statelessness was NOT checked by default in prior versions due to a bug.
This bug is fixed, and the macro statelessness is now checked by default.
The macro statelessness check was also implemented when registering global macros.

* Macro `replaceLines` can have multiple `replace` parops.

* The macro `snip:transform` was developed.

* Built-in macros can query the actual name of a parop, a.k.a.
which alias was used.

* `file` macro formatting supports `$simpleName`.

* Template handling and Trie implementation was refactored to improve performance, and it did.

* Macro register export also exports built-in macros.

* New core macro named `macro` was added.

* New API class `JamalOutputStream` was added, which is a filtering output stream.

* Macro `include` has a parop `lines`, which can limit which lines to include.

* Error reporting was fixed, avoiding circular exception references when closers were running.
For the user, this means a cleaner error report.

* New macros `range`, and `untab` in the snippet library.
It is also supported by the `snip:transform` macro.

* Macro `snip:collect` can collect snippets that start and stop with the AsciiDoc tag notation: `tag::name[]` and `end::name[]`.

* Macro `snip` implements the `poly` option to concatenate snippets.

* Dependencies following the latest releases.

* `import` and `include` macros implement a new option `noCache`.

* Maven extension can keep its own `extensions.xml` automatically up-to-date.

* `https` include and import cache can be configured to evict entries.

* Macro `rot13`.

* Improved error reporting.

{%RELEASE_N/1.10.4%}

* A bug fix in handling thin XML.
* `thinXml` macro was added.

{%RELEASE_N/1.10.3%}

* Support for ThinXML was added.

{%RELEASE_N/1.10.2%}

* The position in error messages became hierarchical, showing the position not only where the error is but also where the actual file was imported, included from.
* Snippets can be collected from resources and from the web using file names that start with `res:` and `https://`.
* Snippet collection still fails when trying to collect snippets from binary files, but the error message is more readable.
* SnipCheck can be switched off using -Djamal.snippet.check=false.
* SnipLoad and SnipSave macros were developed, letting the macro save and/or load snippets from an XML file.
* `string:xxx` macros now properly handle their arguments and do not use the whole input as an argument.
It makes a difference in the case of leading spaces.
* XML formatting is fixed.
Former formatting deleted the new lines from the output, adversely affecting CDATA content.
The new format fixes this and also adds a trailing `\n` at the end of the XML file.

{%RELEASE_N/1.10.1%}

* The snippet library was extended with two new macros `xml:define` and `xml:insert`.
When an XML user-defined macro is used without an argument, then the whole XML formatted is returned.

{%RELEASE_N/1.10.0%}

* New macro `defer`, which evaluates its input after the whole input was processed in a closer.

* Due to a bug, the backslash character did not escape the following newline after an `escape` macro (ironic).
Fixed.

* The old-style macro evaluation is not available anymore.
This significantly sped up the processing.
* There were bug fixes for bugs that, in some situations, prevented the proper handling of `~/...` format file names.

* Some environment variables did not have the system property pair.
Fixed.

* The Maven plugin, when used to convert a project to a Jamalized project, does not create `.mvn/extensions.xml` in the subdirectories anymore.

* There is a new environment variable `JAMAL_DEV_PATH` and system property `jamal.dev.path`.
See the documentation.

* A bug prevented file `include` in Windows in some special cases.
Fixed.

`snipline NAME` can be used to define a single-line snippet without an end snippet.

* Options `noUndefault` and `emptyUndef` are handled by macro evaluation.

* `xmlFormat` works even in applications that embed Jamal in multi-thread.

* `snip:check` is reworked, extended, and improved.

* The core macro `if` now has several options, and it is possible to test numeric comparisons as well as string emptiness.

* JUNIT dependency upped to 5.2.0