Asciidoc preprocessor option writableOutput was added

doclet documentation was extended, adding Gradle use pseudo chapter

jamal-asciidoc/Jamal.xml.jam

@@ -1,3 +1,4 @@
+{%@comment writableOutput%}
 {%@import ../version.jim%}
 {%@define asciidoc:output=live-templates/templates/Jamal.xml%}
 {%@sep 〔 〕%}
@@ -310,9 +311,8 @@ $variables
 〕
 
 
-〔template |snip:check|snip:check ($O$) $C$|check snippet consistency|
+〔template |snip:check|snip:check $O$|check snippet consistency|
  〔variable |O|"hash= lines= id= file= message= warning error"〕
- 〔variable |C|"snippet_name"〕
 〕
 
 〔template |snip:file|snip:file $C$|get the file name of the snippet|

jamal-asciidoc/README.adoc

@@ -413,14 +413,14 @@ If an option is defined for something controllable by configuration, then the op
 
 [source]
 ----
-{@comment off noSave log external fromFile noDependencies keepFrontMatter dual}
+{@comment off noSave log external fromFile noDependencies keepFrontMatter dual writableOutput}
 ----
 
 or
 
 [source]
 ----
-{%@comment off noSave log external fromFile noDependencies keepFrontMatter dual%}
+{%@comment off noSave log external fromFile noDependencies keepFrontMatter dual writableOutput%}
 ----
 
 You can place any of the options listed in the above example separated by spaces in any order.
@@ -476,6 +476,12 @@ Feel free to delete the log file.
 In some cases, you may need to execute the rendering using an external process.
 This option instructs the extension to start Jamal as an external process, convert the input to the output and then read the lines of the generated file and return it for the Asciidoc plugin.
 
+==== writableOutput
+
+The output file is usually saved as a read-only file.
+This is to prevent accidental editing of the file.
+This option instructs the extension to save the output file as a writable file.
+
 ==== fromFile
 
 Will instruct Jamal to ignore the lines that the Asciidoctor plugin is providing and read the lines directly from the file.

jamal-asciidoc/README.adoc.jam

@@ -402,13 +402,13 @@ When running outside of the editor, the response will be retrieved synchronously
 NOTE: When the environment variable was introduced, I had no idea any use of it.
 
 === Options
-{%@snip:check id=OPTIONS hash=48c3323a%}\
+{%@snip:check id=OPTIONS hash=e9d7bf24%}\
 
 You can alter the auxiliary functions of the extension using options.
 You can place these options into the document's first line into a comment.
 If an option is defined for something controllable by configuration, then the option will take precedence.
 
-{%@define FIRST_LINE_OPTIONS=off noSave log external fromFile noDependencies keepFrontMatter dual%}
+{%@define FIRST_LINE_OPTIONS=off noSave log external fromFile noDependencies keepFrontMatter dual writableOutput%}
 
 [source]
 ----
@@ -475,6 +475,12 @@ Feel free to delete the log file.
 In some cases, you may need to execute the rendering using an external process.
 This option instructs the extension to start Jamal as an external process, convert the input to the output and then read the lines of the generated file and return it for the Asciidoc plugin.
 
+==== writableOutput
+
+The output file is usually saved as a read-only file.
+This is to prevent accidental editing of the file.
+This option instructs the extension to save the output file as a writable file.
+
 ==== fromFile
 
 Will instruct Jamal to ignore the lines that the Asciidoctor plugin is providing and read the lines directly from the file.

jamal-asciidoc/live-templates/templates/Jamal.xml

@@ -150,7 +150,7 @@
     </template>
     <template description="require a certain version of Jamal" name="jm-require" toReformat="false" toShortenFQNames="true" value="{%@require $R$ $V$%}">
         <variable alwaysStopAt="true" expression="enum(&quot;&lt;=&quot;,&quot;&lt;&quot;,&quot;=&quot;,&quot;&gt;=&quot;,&quot;&gt;&quot;)" name="R"/>
-        <variable alwaysStopAt="true" expression="&quot;2.3.1-SNAPSHOT&quot;" name="V"/>
+        <variable alwaysStopAt="true" expression="&quot;2.5.0-SNAPSHOT&quot;" name="V"/>
         <context>
             <option name="AsciiDoc" value="true"/>
         </context>
@@ -409,9 +409,8 @@
             <option name="AsciiDoc" value="true"/>
         </context>
     </template>
-    <template description="check snippet consistency" name="jm-snip:check" toReformat="false" toShortenFQNames="true" value="{%@snip:check ($O$) $C$%}">
+    <template description="check snippet consistency" name="jm-snip:check" toReformat="false" toShortenFQNames="true" value="{%@snip:check $O$%}">
         <variable alwaysStopAt="true" expression="&quot;hash= lines= id= file= message= warning error&quot;" name="O"/>
-        <variable alwaysStopAt="true" expression="&quot;snippet_name&quot;" name="C"/>
         <context>
             <option name="AsciiDoc" value="true"/>
         </context>
@@ -736,4 +735,4 @@
             <option name="AsciiDoc" value="true"/>
         </context>
     </template>
-</templateSet>
+</templateSet>

jamal-asciidoc/src/main/java/javax0/jamal/asciidoc/Configuration.java

@@ -13,6 +13,7 @@ public class Configuration {
     public final boolean noDependencies;
     public final String externalCommand;
     public boolean keepFrontMatter;
+    public boolean writableOutput;
 
     private Configuration() {
         // snipline ASCIIDOC_EXTENSION_OPEN filter="(\w+)"
@@ -33,5 +34,7 @@ private Configuration() {
         noDependencies = EnvironmentVariables.getenv("ASCIIDOC_EXTENSION_NO_DEPENDENCIES").map(Boolean::parseBoolean).orElse(false);
         // snipline ASCIIDOC_EXTENSION_KEEP_FRONT_MATTER filter="(\w+)"
         keepFrontMatter = EnvironmentVariables.getenv("ASCIIDOC_EXTENSION_KEEP_FRONT_MATTER").map(Boolean::parseBoolean).orElse(false);
+        // snipline ASCIIDOC_EXTENSION_WRITABLE_OUTPUT filter="(\w+)"
+        keepFrontMatter = EnvironmentVariables.getenv("ASCIIDOC_EXTENSION_WRITABLE_OUTPUT").map(Boolean::parseBoolean).orElse(false);
     }
 }

jamal-asciidoc/src/main/java/javax0/jamal/asciidoc/InFileOptions.java

@@ -18,13 +18,18 @@ class InFileOptions {
     boolean dual = false;
     boolean keepFrontMatter = Configuration.INSTANCE.keepFrontMatter;
 
+    boolean writableOutput = Configuration.INSTANCE.writableOutput;
+
     boolean prefixLog;
 
     InFileOptions(final String firstLine) {
         final var matcher = Pattern.compile("@comment\\s+([\\w\\s]*)").matcher(firstLine);
         final var options = matcher.find() ? List.of(matcher.group(1).split("\\s+")) : List.<String>of();
 
         // snippet OPTIONS
+        if (options.contains("writableOutput")) {
+            writableOutput = true;
+        }
         if (options.contains("dual")) {
             dual = true;
             save = false;
@@ -41,7 +46,7 @@ class InFileOptions {
         if (options.contains("log")) {
             log = true;
         }
-        if( options.contains("prefixLog")){
+        if (options.contains("prefixLog")) {
             prefixLog = true;
         }
         if (options.contains("external")) {

jamal-asciidoc/src/main/java/javax0/jamal/asciidoc/JamalPreprocessor.java

@@ -22,6 +22,8 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.io.PrintWriter;
+import java.io.StringWriter;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -216,7 +218,7 @@ public String toString() {
                 }
             }
             if (opts.save) {
-                writeOutputFile(outputFileName, log, cachingFileReader, newLines);
+                writeOutputFile(outputFileName, log, cachingFileReader, newLines, opts);
             }
         }
         restoreTheLinesIntoThePlugin(reader, fileName, log, newLines, opts);
@@ -300,15 +302,29 @@ private Result runJamalInProcess(final String fileName, final List<String> lines
      * @param log               the logger
      * @param cachingFileReader the file reader that contains the list of the files that were read. It is used to log.
      * @param newLines          the lines that are to be written to the output file
+     * @param opts
      */
-    private void writeOutputFile(final String outputFileName, final Log log, final CachingFileReader cachingFileReader, final List<String> newLines) {
+    private void writeOutputFile(final String outputFileName, final Log log, final CachingFileReader cachingFileReader, final List<String> newLines, InFileOptions opts) {
         try {
-            OutputFile.save(Path.of(outputFileName), String.join("\n", newLines));
+            Path output = Path.of(outputFileName);
+            OutputFile.save(output, String.join("\n", newLines));
+            if (opts.writableOutput) {
+                final var success = output.toFile().setWritable(true);
+                if (!success) {
+                    log.info("Failed to set writable the output file " + outputFileName);
+                }
+            }
+            log.info("saved");
+            log.info("dependencies\n" + cachingFileReader.list());
         } catch (Exception e) {
-            // there is not much we can do here
+            log.info("Failed to save the output file " + outputFileName);
+            try (StringWriter sw = new StringWriter();
+                 PrintWriter pw = new PrintWriter(sw)) {
+                e.printStackTrace(pw);
+                log.info("Exception was:\n" + sw);
+            } catch (IOException ignore) {
+            }
         }
-        log.info("saved");
-        log.info("dependencies\n" + cachingFileReader.list());
     }
 
     private static final List<Converter> converters = Converter.getInstances();

jamal-assertions/README.adoc

@@ -565,4 +565,7 @@ results
 7. ERROR:
 8. ERROR: 3.14 is not a not numeric
 9. ERROR: three is an int, not a not int, and thus a numeric
-----
+----
+
+
+

jamal-cmd/README.adoc

@@ -102,4 +102,8 @@ See also the option `-from`.
 
 * `-jamalize`   will install Jamal in the `.asciidoctor/lib` directory.
 It version of the installed Jamal is the same as the one installing it.
-It can also install a different version if the option `-version=xxx` is specifying a specific versions.
+It can also install a different version if the option `-version=xxx` is specifying a specific versions.
+
+
+
+