Merge branch 'topic/java_cleanups' into 'master'

Various cleanups in the Java bindings

Closes #767

See merge request eng/libadalang/langkit!1020

Author: HugoGGuerrier

langkit/templates/java_api/array.mako

@@ -102,10 +102,9 @@
             ${elem_ni_ref_type} toRead;
 
             // Iterate over all array elements
+            final int elemSize = SizeOf.get(${elem_ni_type}.class);
             for(int i = 0 ; i < size ; i++) {
-                nativeItem = nativeItems.add(
-                    i * SizeOf.get(${elem_ni_type}.class)
-                );
+                nativeItem = nativeItems.add(i * elemSize);
                 toRead = WordFactory.unsigned(nativeItem.rawValue());
                 content[i] = ${
                     api.ni_wrap(cls.element_type, "toRead", [])
@@ -166,10 +165,9 @@
             ${elem_ni_ref_type} toWrite;
 
             // Place all elements in the native array
+            final int elemSize = SizeOf.get(${elem_ni_type}.class);
             for(int i = 0 ; i < this.content.length ; i++) {
-                nativeItem = nativeItems.add(
-                    i * SizeOf.get(${elem_ni_type}.class)
-                );
+                nativeItem = nativeItems.add(i * elemSize);
                 toWrite = WordFactory.unsigned(
                     nativeItem.rawValue()
                 );

langkit/templates/java_api/jni_impl_c.mako

@@ -802,7 +802,7 @@ const char * to_c_string(
     return (*env)->GetStringUTFChars(env, j_string, NULL);
 }
 
-// Release the given C string assocaited with the given Java string
+// Release the given C string associated with the given Java string
 void release_c_string(
     JNIEnv *env,
     jstring j_string,
@@ -2530,7 +2530,7 @@ ${iterator.jni_c_impl(iterator_type)}
 % endfor
 
 // ==========
-// AST node functions
+// Node functions
 // ==========
 
 // Return whether the two given entities are equal
@@ -2720,7 +2720,7 @@ ${api.jni_func_sig("node_image", "jobject")}(
 }
 
 // ==========
-// AST node field accessors
+// Node field accessors
 // ==========
 
 % for astnode in ctx.astnode_types:

langkit/templates/java_api/main_class.mako

@@ -322,8 +322,6 @@ public final class ${ctx.lib_name.camel} {
 
     /**
      * Convert a C Langkit exception to the LangkitException class.
-
-     * @param
      */
     private static LangkitException wrapException(
         final LangkitExceptionNative exc
@@ -369,7 +367,7 @@ public final class ${ctx.lib_name.camel} {
     // ==========
 
     /**
-     * Interface to visit the AST.
+     * Interface to visit the parse tree.
      */
     public static interface BasicVisitor<T> {
         T visit(${root_node_type} node);
@@ -381,7 +379,7 @@ public final class ${ctx.lib_name.camel} {
     }
 
     /**
-     * Interface to visit the AST with a parameter.
+     * Interface to visit the parse tree with a parameter.
      */
     public static interface ParamVisitor<T, P> {
         T visit(${root_node_type} node, P param);
@@ -807,7 +805,7 @@ public final class ${ctx.lib_name.camel} {
         % endfor
         ;
 
-        // ----- Class attributes
+        // ----- Class attributes -----
 
         /** Singleton that represents the none expcetion kind. */
         public static final ExceptionKind NONE =
@@ -1820,7 +1818,7 @@ public final class ${ctx.lib_name.camel} {
 
         // ----- Class attributes -----
 
-        /** Singleton that represents the none diagnositc. */
+        /** Singleton that represents the none diagnostic. */
         public static final Diagnostic NONE = new Diagnostic(
             SourceLocationRange.NONE,
             Text.NONE
@@ -1873,8 +1871,8 @@ public final class ${ctx.lib_name.camel} {
         /**
          * Wrap a pointer to a native diagnostic.
          *
-         * @param pointer The pointer to the native diagnositc.
-         * @return The wrapped diagnositc.
+         * @param pointer The pointer to the native diagnostic.
+         * @return The wrapped diagnostic.
          */
         static Diagnostic wrap(
             final Pointer pointer
@@ -1886,7 +1884,7 @@ public final class ${ctx.lib_name.camel} {
          * Wrap a diagnostic native value in the Java class.
          *
          * @param diagnosticNative The diagnostic NI native value.
-         * @return The newly wrapped diagnositc.
+         * @return The newly wrapped diagnostic.
          */
         static Diagnostic wrap(
             final DiagnosticNative diagnosticNative
@@ -2049,7 +2047,7 @@ public final class ${ctx.lib_name.camel} {
 
     }
 
-    ${c_doc('langkit.unit_provider_type')}
+    ${java_doc('langkit.unit_provider_type', 4)}
     public static final class UnitProvider implements AutoCloseable {
 
         // ----- Class attributes -----
@@ -2141,7 +2139,7 @@ public final class ${ctx.lib_name.camel} {
 
     }
 
-    ${java_doc('langkit.event_handler_type')}
+    ${java_doc('langkit.event_handler_type', 4)}
     public static final class EventHandler implements AutoCloseable {
 
         // ----- Class attributes -----
@@ -2687,9 +2685,9 @@ public final class ${ctx.lib_name.camel} {
             if(o == this) return true;
             if(!(o instanceof Token)) return false;
             final Token other = (Token) o;
-            return other.tokenDataHandler.equals(this.tokenDataHandler) &&
-                    other.tokenIndex == this.tokenIndex &&
-                    other.triviaIndex == this.triviaIndex;
+            return this.tokenDataHandler.equals(other.tokenDataHandler) &&
+                    this.tokenIndex == other.tokenIndex &&
+                    this.triviaIndex == other.triviaIndex;
         }
 
         // ----- Inner classes -----
@@ -3071,6 +3069,26 @@ public final class ${ctx.lib_name.camel} {
             return this.eventHandler;
         }
 
+        // ----- Class methods -----
+
+        /**
+         * Increase the reference counter of the given context.
+         *
+         * @param context The context to increase the reference counter of.
+         */
+        private static void increaseRefCounter(
+            final AnalysisContext context
+        ) {
+            // Increase the context reference counter of the context if not null
+            if(!context.reference.isNull()) {
+                if(ImageInfo.inImageCode()) {
+                    NI_LIB.${nat("context_incref")}(context.reference.ni());
+                } else {
+                    JNI_LIB.${nat("context_incref")}(context.reference.jni());
+                }
+            }
+        }
+
         // ----- Instance methods -----
 
         /**
@@ -3260,24 +3278,6 @@ public final class ${ctx.lib_name.camel} {
         }
         % endif
 
-        /**
-         * Increase the reference counter of the given context.
-         *
-         * @param context The context to increase the reference counter of.
-         */
-        private static void increaseRefCounter(
-            final AnalysisContext context
-        ) {
-            // Increase the context reference counter of the context if not null
-            if(!context.reference.isNull()) {
-                if(ImageInfo.inImageCode()) {
-                    NI_LIB.${nat("context_incref")}(context.reference.ni());
-                } else {
-                    JNI_LIB.${nat("context_incref")}(context.reference.jni());
-                }
-            }
-        }
-
         /** @see java.lang.AutoCloseable#close() */
         @Override
         public void close() {
@@ -3551,9 +3551,9 @@ public final class ${ctx.lib_name.camel} {
         }
 
         /**
-         * Get the list of assiated diagnositcs. Those are parsing errors.
+         * Get the list of associated diagnostics. Those are parsing errors.
          *
-         * @return The diagnositcs of the unit.
+         * @return The diagnostics of the unit.
          */
         public List<Diagnostic> getDiagnostics() {
             final int diagnosticCount;
@@ -3605,7 +3605,7 @@ public final class ${ctx.lib_name.camel} {
             if(this == o) return true;
             if(!(o instanceof AnalysisUnit)) return false;
             final AnalysisUnit other = (AnalysisUnit) o;
-            return other.reference.equals(other.reference);
+            return this.reference.equals(other.reference);
         }
 
     }
@@ -4096,28 +4096,28 @@ public final class ${ctx.lib_name.camel} {
         // ----- Dumping methods -----
 
         /**
-         * Return the AST in a string.
+         * Return the parsing tree in a string.
          *
-         * @return The string containing the representation of the AST
+         * @return The string containing the representation of the parsing tree
          * from the node.
          */
         @CompilerDirectives.TruffleBoundary
-        public String dumpAST() {
+        public String dumpTree() {
             final StringBuilder builder = new StringBuilder();
-            this.dumpAST(builder);
+            this.dumpTree(builder);
             return builder.toString();
         }
 
         /**
-         * Dump the AST in the given string builder.
+         * Dump the parse tree in the given string builder.
          *
-         * @param builder The builder to dump the AST in.
+         * @param builder The builder to dump the parse tree in.
          */
         @CompilerDirectives.TruffleBoundary
-        public void dumpAST(
+        public void dumpTree(
             final StringBuilder builder
         ) {
-            this.dumpAST(builder, "");
+            this.dumpTree(builder, "");
         }
 
         /**
@@ -4137,17 +4137,18 @@ public final class ${ctx.lib_name.camel} {
             builder.append(indent)
                 .append(name)
                 .append(":\n");
-            value.dumpAST(builder, indent + "  ");
+            value.dumpTree(builder, indent + "  ");
         }
 
         /**
-         * Dump the AST in the given string builder with the indent level.
+         * Dump the parse tree in the given string builder with the indent
+         * level.
          *
-         * @param builder The builder to dump the AST in.
+         * @param builder The builder to dump the tree in.
          * @param indent The starting indent level.
          */
         @CompilerDirectives.TruffleBoundary
-        protected void dumpAST(
+        protected void dumpTree(
             final StringBuilder builder,
             String indent
         ) {
@@ -4271,7 +4272,7 @@ public final class ${ctx.lib_name.camel} {
 
     }
 
-    // ===== Generated AST node wrapping classes =====
+    // ===== Generated node wrapping classes =====
 
     % for astnode in ctx.astnode_types:
         % if astnode != T.root_node:

langkit/templates/java_api/readme_md.mako

@@ -41,7 +41,7 @@ public class Main {
             ${ctx.lib_name.camel}.AnalysisContext.create();
         ${ctx.lib_name.camel}.AnalysisUnit unit = ctx.getUnitFromFile(myFile);
 
-        // Dump the AST
+        // Dump the parsed tree
         System.out.println(unit.root().dump());
 
     }

testsuite/tests/java_api/general/common/BindingsTests.java

@@ -114,6 +114,20 @@ private static void testUnitFileName() {
         ) {
             // Get the unit for the foo.txt file
             AnalysisUnit unit = context.getUnitFromFile("foo.txt");
+            AnalysisUnit other = context.getUnitFromFile("foo.txt");
+            AnalysisUnit notSame =
+                context.getUnitFromBuffer("var identifier", "bar.txt");
+            System.out.println(
+                unit.toString() + " != " + other + " = " + (unit != other)
+            );
+            System.out.println(
+                unit.toString() + ".equals(" + other + ") = " +
+                unit.equals(other)
+            );
+            System.out.println(
+                unit.toString() + ".equals(" + notSame +
+                ") = " + unit.equals(notSame)
+            );
             System.out.println(
                 "Unit for the file " +
                 new File(unit.getFileName()).getName()
@@ -168,7 +182,7 @@ private static void testTokens() {
             System.out.println("Text range with a NO_TOKEN = " +
                 Token.textRange(first, none));
 
-            // Test the token equivalence
+            // Test the token equivalence and equality
             AnalysisUnit eqUnit = context.getUnitFromBuffer(
                 "null identifier example identifier example",
                 "foo.txt"
@@ -189,6 +203,20 @@ private static void testTokens() {
                 }
                 current = current.next();
             }
+
+            Token left = eqUnit.getFirstToken();
+            Token right = eqUnit.getFirstToken();
+            while(!(left.isNone() || right.isNone())) {
+                System.out.println(
+                    left.toString() + " != " + right + " = " + (left != right)
+                );
+                System.out.println(
+                    left.toString() + ".equals(" + right + ") = " +
+                    left.equals(right)
+                );
+                left = left.next();
+                right = right.next();
+            }
         }
 
         // Display the footer
@@ -219,7 +247,7 @@ private static void testNodes() {
                 "Unit root children = " + root.children().toString()
             );
             System.out.println(
-                "Unit root AST dump = " + root.dumpAST()
+                "Unit root tree dump = " + root.dumpTree()
             );
             System.out.println(
                 "Unit root is a list node = " + root.isListType()