Skip to content

Latest commit

 

History

History
498 lines (324 loc) · 23.7 KB

RELEASES.adoc

File metadata and controls

498 lines (324 loc) · 23.7 KB

Jamal Releases

Note
 The known bugs sections in the releases are updated after the release. Please consult the latest SNAPSHOT version available online at GitHub Jamal RELEASES.adoc

2.8.2

Known Bugs

currently there are no known bugs in this release

New Features

  • The installation kit installed command line version includes the debugger.

  • When starting the command line version using -debug without value it will start the HTTP debugger on the port 8080. If you need to start it on a different port use the -debug=http:port option. Here http: is a literal string, and port is the port number.

  • Error messages are more informative, including the macros in the stack trace that caused the error. If there are user-defined macros calling one another, their names are listed after the file name.

  • There is a macro module to read a local GIT repository, which is experimental in this release.

2.8.1

Known Bugs

The command line version of the application does not include the debugger. It is not a bug, per se. You can start the debugger from the command line, but you have to start the application editing some shell scripts adding the dependency. Because the jbang version does include the debugger, it was not considered a bug. Starting with the release 2.8.1 there is an installation kit. When using the Jamal command line installed with the installation kit, the debugger is not available.

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.

2.8.0

Known Bugs

currently there are no known bugs in this release

New Features

  • The prog module implements floating-point calculations.

2.7.0

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.

2.6.0

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 2.5.0 version of Jamal as a maven extension. If you need the features from the release 2.6.0 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).

2.5.0

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

2.4.0

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

2.3.0

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

2.2.0

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

2.1.0

  • 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 ${xxx} references.

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

2.0.2

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

2.0.1

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

2.0.0

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

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.

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.

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.

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 RestrictedDefineParameters is now available for the define macro, to restrict parameter names to be identifiers.

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.

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.

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.

1.11.3

This is a technical release. It must not be used.

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

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.

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.

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.

1.10.4

  • A bug fix in handling thin XML.

  • thinXml macro was added.

1.10.3

  • Support for ThinXML was added.

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.

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.

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