jrf files now contain comments to make them more readable

README.adoc

@@ -536,4 +536,4 @@ See the separate document: link:FAQ.adoc[FAQ].
 
 
 
-The documents of this project are formatted as Asciidoc documents with Jamal meta markup.
+The documents of this project are formatted as Asciidoc documents with Jamal meta markup.

README.jrf

@@ -1 +1,4 @@
+# This is a Jama reference file containing serialized base64 encoded macros
+# id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters
+# TOC
 VE9D|eyU=|JX0=|0|0|0|Ci4gPDxJbnN0YWxsYXRpb24+PgouIDw8R1M+PgouIDw8Q29uZmlndXJhdGlvbj4+Ci4gPDxGZWF0dXJlcz4+Ci4gPDxDb250cmlidXRpbmc+PgouIDw8RG9jdW1lbnRhdGlvbj4+Ci4gPDxMaWNlbnNlPj4KLiA8PENoYW5nZWxvZz4+Ci4gPDxSb2FkbWFwPj4KLiA8PFN1cHBvcnQ+PgouIDw8RkFRPj4KLiA8PE1haW50ZW5hbmNlPj4=|

jamal-snippet/README.adoc

@@ -3339,7 +3339,7 @@ will result
 - ShellVar.java: 3,837 bytes
 - Locate.java: 5,965 bytes
 - XmlDocument.java: 5,671 bytes
-- References.java: 7,745 bytes
+- References.java: 9,022 bytes
 - Java.java: 11,623 bytes
 - ReplaceLines.java: 3,479 bytes
 - SkipLines.java: 2,801 bytes
@@ -3600,7 +3600,7 @@ will result in the output
 
 [source]
 ----
-2023-12-05 15:42:11
+2023-12-05 17:02:16
 ----
 
 

jamal-snippet/sample.jrf

@@ -1 +1,4 @@
+# This is a Jama reference file containing serialized base64 encoded macros
+# id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters
+# a
 YQ==|ew==|fQ==|0|0|0|VGhlIHZhbHVlIG9mIGE=|

jamal-snippet/src/main/java/javax0/jamal/snippet/References.java

@@ -57,7 +57,7 @@ public String evaluate(final Input in, final Processor processor) throws BadSynt
             closer.addSerializedLines(macrosSerialized);
             final var deserializer = getDeserializerMacroObject(processor);
             for (var macroSerialized : macrosSerialized) {
-                if (macroSerialized.length() > 0) {// empty lines are ignored
+                if (notComment(macroSerialized)) {// empty and comment lines are ignored
                     final var macro = deserializer.deserialize(macroSerialized);
                     processor.defineGlobal(macro);
                 }
@@ -70,6 +70,10 @@ public String evaluate(final Input in, final Processor processor) throws BadSynt
         return "";
     }
 
+    private static boolean notComment(String macroSerialized) {
+        return !macroSerialized.isEmpty() && macroSerialized.charAt(0) != '#';
+    }
+
     /**
      * Create a macro object that will be used to deserialize the strings into macro objects.
      * This deserializer macro object will (should) NOT be registered in the macro registry, hence the name is not
@@ -140,7 +144,8 @@ void addSerializedLines(final List<String> serialized) {
 
         @Override
         public void close() throws Exception {
-            final var sb = new StringBuilder();
+            final var sb = new StringBuilder("# This is a Jama reference file containing serialized base64 encoded macros\n"
+                    + "# id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters\n");
             final var missing = new ArrayList<String>();
             for (final var ref : holder.getObject()) {
                 final var serialized = processor.getRegister()
@@ -149,32 +154,50 @@ public void close() throws Exception {
                         .map(macro -> (UserDefinedMacro) macro)
                         .map(Serializing::serialize);
                 if (serialized.isPresent()) {
+                    sb.append("# ").append(ref).append('\n');
                     sb.append(serialized.get()).append('\n');
                 } else {
                     missing.add(ref);
                 }
             }
-            Files.writeString(Paths.get(file.toURI()), sb.toString(), StandardCharsets.UTF_8, StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.CREATE);
-            BadSyntax.when(missing.size() > 0, "The following references are missing: " + String.join(", ", missing));
+            Files.writeString(Paths.get(file.toURI()), sb.toString(), StandardCharsets.UTF_8,
+                    StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.CREATE);
+            BadSyntax.when(!missing.isEmpty(), "The following references are missing: " + String.join(", ", missing));
             if (macrosSerialized != null) {
                 final var diff = checkIdempotency(macrosSerialized, sb.toString().split("\n"));
-                IdempotencyFailed.when(diff.length() > 0, "The following references are not idempotent: " + diff);
+                IdempotencyFailed.when(!diff.isEmpty(), "The following references are not idempotent: " + diff);
             }
         }
 
+        /**
+         * Check if the two sets of serialized macros are idempotent. The first set is the old set, and the second set is
+         * the new set. The method returns a string that contains the list of the macros that are new, deleted or
+         * changed.
+         * <p>
+         * The serialization set may contain empty and comment lines. These are ignored.
+         *
+         * @param oldSet the old set of serialized macros as string
+         * @param newSet the new set of serialized macros as string
+         * @return the list of the macros that are new, deleted or changed, essentially a difference
+         * @throws BadSyntax if the deserialization of the serialized macro fails
+         */
         private String checkIdempotency(String[] oldSet, String[] newSet) throws BadSyntax {
             final var diffMap = new HashMap<String, String[]>();
             final var deserializer = getDeserializerMacroObject(processor);
             for (final var line : oldSet) {
-                final var id = deserializer.deserialize(line).getId();
-                diffMap.put(id, new String[]{line, null});
+                if (notComment(line)) {
+                    final var id = deserializer.deserialize(line).getId();
+                    diffMap.put(id, new String[]{line, null});
+                }
             }
             for (final var line : newSet) {
-                final var id = deserializer.deserialize(line).getId();
-                if (diffMap.containsKey(id)) {
-                    diffMap.get(id)[1] = line;
-                } else {
-                    diffMap.put(id, new String[]{null, line});
+                if (notComment(line)) {
+                    final var id = deserializer.deserialize(line).getId();
+                    if (diffMap.containsKey(id)) {
+                        diffMap.get(id)[1] = line;
+                    } else {
+                        diffMap.put(id, new String[]{null, line});
+                    }
                 }
             }
             final var err = new StringBuilder();