[lang] Enablement of the automatic generation of the equality test fu…

…nctions.

In order to enable or disable the compiler's feature that automatically
generates the equality test functions (equals and hashCode) from the
declared fields, the following elements are added into the SARL
compiler:

* Configuration option for enabling or disabling the feature;
* Update of the bactch compiler with a new command-line option;
* Addition of a UI component within the Eclipse preferences; and
* Addition of the `@NoEqualityTestFunctionsGeneration` for disabling the
generation from the SARL source code.

Signed-off-by: Stéphane Galland <galland@arakhne.org>

docs/io.sarl.docs.markdown/src/main/documentation/reference/general/ActiveAnnotations.md

@@ -272,6 +272,47 @@ The previous code is equivalent to:
 		[:End:]
 
 
+## @NoEqualityTestFunctionsGeneration
+
+The [:noeqtestannon:] annotation disables the generation the equality test functions, i.e. `equals()` and `hashCode()` from
+the field declarations.
+
+By default, the SARL compiler generates the equality test functions from the type's fields. In several cases, this automatic
+behavior should be avoiding because the standard equality test that is provided by the Java run-time environment should be used.
+In this case, [:noeqtestannon:] annotation may be used to mark a type or a field for being excluded of the equality test generation. 
+
+The annotation may mark a type, as in the following example.
+In this case, no equality test function is generated within the marked type and all its subtypes.
+
+		[:Success:]
+			import io.sarl.lang.annotation.NoEqualityTestFunctionsGeneration
+			[:On]
+			[:noeqtestannon](@NoEqualityTestFunctionsGeneration)
+			class MyClass {
+			  var field1 : int
+			  var field2 : String
+			}
+			[:Off]
+		[:End:]
+
+The annotation may mark a specific field in order to exclude it from the equality test generation.
+In the following example, the [:noeqtestfield2:] field is marked with the annotation. Consequently, it
+is not included within the equality test within the `equals()` function, and the hash code replied
+by the `hashCode()` function does not include the hash code of the [:noeqtestfield2:] field.
+
+		[:Success:]
+			import io.sarl.lang.annotation.NoEqualityTestFunctionsGeneration
+			[:On]
+			class MyClass {
+			  var field1 : int
+			  [:noeqtestannon!]
+			  var [:noeqtestfield2](field2) : String
+			}
+			[:Off]
+		[:End:]
+
+
+
 ## @ToString
 
 The [:tostringannon:] annotation enables to generate the function that replies the string representation

main/coreplugins/io.sarl.lang.core/src/io/sarl/lang/annotation/NoEqualityTestFunctionsGeneration.java

@@ -0,0 +1,45 @@
+/*
+ * $Id$
+ *
+ * SARL is an general-purpose agent programming language.
+ * More details on http://www.sarl.io
+ *
+ * Copyright (C) 2014-2018 the original authors or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.sarl.lang.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Annotation for avoiding the automatic generation of the equality test functions.
+ *
+ * <p>The SARL compiler may be configured for generating the code of the equality test functions, i.e.
+ * {@code equals()} and {@code hashCode()}, based on the type's fields. This annotation avoids the
+ * generation of these functions in order to use the default Java definitions.
+ *
+ * @author $Author: sgalland$
+ * @version $FullVersion$
+ * @mavengroupid $GroupId$
+ * @mavenartifactid $ArtifactId$
+ * @since 0.8
+ */
+@Target({ElementType.TYPE, ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface NoEqualityTestFunctionsGeneration {
+	//
+}

main/coreplugins/io.sarl.lang.ui/src/io/sarl/lang/ui/preferences/Messages.java

@@ -44,6 +44,7 @@ private Messages() {
 	public static String SARLBuilderConfigurationBlock_0;
 	public static String SARLBuilderConfigurationBlock_1;
 	public static String SARLBuilderConfigurationBlock_2;
+	public static String SARLBuilderConfigurationBlock_3;
 	public static String SARLValidatorConfigurationBlock_0;
 	public static String SARLValidatorConfigurationBlock_2;
 	public static String SARLValidatorConfigurationBlock_3;

main/coreplugins/io.sarl.lang.ui/src/io/sarl/lang/ui/preferences/SARLBuilderConfigurationBlock.java

@@ -21,6 +21,7 @@
 
 package io.sarl.lang.ui.preferences;
 
+import static io.sarl.lang.ui.preferences.SARLBuilderPreferenceAccess.PREF_GENERATE_EQUALITY_TEST_FUNCTIONS;
 import static io.sarl.lang.ui.preferences.SARLBuilderPreferenceAccess.PREF_GENERATE_INLINE;
 import static io.sarl.lang.ui.preferences.SARLBuilderPreferenceAccess.PREF_GENERATE_PURE;
 import static io.sarl.lang.ui.preferences.SARLBuilderPreferenceAccess.PREF_USE_EXPRESSION_INTERPRETER;
@@ -72,6 +73,9 @@ protected void createGeneralSectionItems(Composite composite) {
 		addCheckBox(composite, Messages.SARLBuilderConfigurationBlock_2,
 				PREF_GENERATE_PURE, BOOLEAN_VALUES, 0);
 
+		addCheckBox(composite, Messages.SARLBuilderConfigurationBlock_3,
+				PREF_GENERATE_EQUALITY_TEST_FUNCTIONS, BOOLEAN_VALUES, 0);
+
 		this.generateInlineButton.addSelectionListener(new SelectionAdapter() {
 			@SuppressWarnings("synthetic-access")
 			@Override

main/coreplugins/io.sarl.lang.ui/src/io/sarl/lang/ui/preferences/SARLBuilderPreferenceAccess.java

@@ -53,6 +53,11 @@ public class SARLBuilderPreferenceAccess {
 	 */
 	public static final String PREF_GENERATE_PURE = "io.sarl.builder.generatePureAnnotation"; //$NON-NLS-1$
 
+	/**
+	 * Preference identifier for generating the equality test functions.
+	 */
+	public static final String PREF_GENERATE_EQUALITY_TEST_FUNCTIONS = "io.sarl.builder.generateEqualityTestFunctions"; //$NON-NLS-1$
+
 	/** Load the generator configuration from the preferences.
 	 *
 	 * @param generatorConfig the configuration to set up.
@@ -73,6 +78,9 @@ public void loadBuilderPreferences(GeneratorConfig2 generatorConfig, IProject co
 			if (preferenceStore.contains(PREF_GENERATE_PURE)) {
 				generatorConfig.setGeneratePureAnnotation(preferenceStore.getBoolean(PREF_GENERATE_PURE));
 			}
+			if (preferenceStore.contains(PREF_GENERATE_EQUALITY_TEST_FUNCTIONS)) {
+				generatorConfig.setGenerateEqualityTestFunctions(preferenceStore.getBoolean(PREF_GENERATE_EQUALITY_TEST_FUNCTIONS));
+			}
 		}
 	}
 
@@ -91,6 +99,7 @@ public void initialize(IPreferenceStoreAccess preferenceStoreAccess) {
 			store.setDefault(PREF_GENERATE_INLINE, GeneratorConfig2.DEFAULT_GENERATE_INLINE_ANNOTATION);
 			store.setDefault(PREF_USE_EXPRESSION_INTERPRETER, GeneratorConfig2.DEFAULT_USE_EXPRESSION_INTERPRETER_FOR_INLINE_ANNOTATION);
 			store.setDefault(PREF_GENERATE_PURE, GeneratorConfig2.DEFAULT_GENERATE_PURE_ANNOTATION);
+			store.setDefault(PREF_GENERATE_EQUALITY_TEST_FUNCTIONS, GeneratorConfig2.DEFAULT_GENERATE_EQUALITY_TEST_FUNCTIONS);
 		}
 
 	}

main/coreplugins/io.sarl.lang.ui/src/io/sarl/lang/ui/preferences/messages.properties

@@ -1,6 +1,7 @@
 SARLBuilderConfigurationBlock_0=Generate @Inline annotations (experimental)
 SARLBuilderConfigurationBlock_1=Simplify constant expressions
 SARLBuilderConfigurationBlock_2=Generate @Pure annotations
+SARLBuilderConfigurationBlock_3=Generate equality test functions (equals, hashCode)
 SARLValidatorConfigurationBlock_0=Redundant implementation of interface:
 SARLValidatorConfigurationBlock_2=Variable name shadowing:
 SARLValidatorConfigurationBlock_3=Discouraged boolean expression:

main/coreplugins/io.sarl.lang/src/io/sarl/lang/compiler/GeneratorConfig2.java

@@ -47,12 +47,18 @@ public class GeneratorConfig2 {
 	 */
 	public static final boolean DEFAULT_USE_EXPRESSION_INTERPRETER_FOR_INLINE_ANNOTATION = true;
 
-	/** Default value for the generation of the pure annotation flag.
+	/** Default value for the generation flag of the pure annotations.
 	 *
 	 * @since 0.8
 	 */
 	public static final boolean DEFAULT_GENERATE_PURE_ANNOTATION = true;
 
+	/** Default value for the generation flag of the equality test functions.
+	 *
+	 * @since 0.8
+	 */
+	public static final boolean DEFAULT_GENERATE_EQUALITY_TEST_FUNCTIONS = true;
+
 	/**
 	 * Whether <code>@Inline</code> shall be generated.
 	 */
@@ -68,6 +74,11 @@ public class GeneratorConfig2 {
 	 */
 	private boolean generatePureAnnotation = DEFAULT_GENERATE_PURE_ANNOTATION;
 
+	/**
+	 * Whether the equality test functions shall be generated.
+	 */
+	private boolean generateEqualityTestFunctions = DEFAULT_GENERATE_EQUALITY_TEST_FUNCTIONS;
+
 	/** Replies if the <code>@Inline</code> shall be generated.
 	 *
 	 * @return <code>true</code> if annotation shall be generated.
@@ -119,4 +130,23 @@ public void setGeneratePureAnnotation(final boolean generatePureAnnotation) {
 		this.generatePureAnnotation = generatePureAnnotation;
 	}
 
+	/** Replies if the equality test functions shall be generated.
+	 *
+	 * @return <code>true</code> if the functions shall be generated.
+	 * @since 0.8
+	 */
+	@Pure
+	public boolean isGenerateEqualityTestFunctions() {
+		return this.generateEqualityTestFunctions;
+	}
+
+	/** Set if the equality test functions shall be generated.
+	 *
+	 * @param generateFunctions <code>true</code> if functions shall be generated.
+	 * @since 0.8
+	 */
+	public void setGenerateEqualityTestFunctions(final boolean generateFunctions) {
+		this.generateEqualityTestFunctions = generateFunctions;
+	}
+
 }

main/coreplugins/io.sarl.lang/src/io/sarl/lang/compiler/batch/Main.java

@@ -109,6 +109,8 @@ public final class Main {
 
 	private static final String CLI_OPTION_GENERATE_PURES = "pures"; //$NON-NLS-1$
 
+	private static final String CLI_OPTION_GENERATE_EQUALITY_TEST_FUNCTIONS = "equalsFunctions"; //$NON-NLS-1$
+
 	private static final String CLI_OPTION_NOWARNING = "nowarn"; //$NON-NLS-1$
 
 	private static final String CLI_OPTION_WARNINGISERROR = "werror"; //$NON-NLS-1$
@@ -275,6 +277,9 @@ public static void parseCommandLine(String[] args, SarlBatchCompiler compiler) {
 				case CLI_OPTION_GENERATE_PURES:
 					compiler.setGeneratePureAnnotation(getBooleanValue(opt));
 					break;
+				case CLI_OPTION_GENERATE_EQUALITY_TEST_FUNCTIONS:
+					compiler.setGenerateEqualityTestFunctions(getBooleanValue(opt));
+					break;
 				case CLI_OPTION_NOWARNING:
 					compiler.setAllWarningSeverities(Severity.IGNORE);
 					break;

main/coreplugins/io.sarl.lang/src/io/sarl/lang/compiler/batch/SarlBatchCompiler.java

@@ -881,6 +881,25 @@ public void setGeneratePureAnnotation(final boolean generatePureAnnotation) {
 		getGeneratorConfig2().setGeneratePureAnnotation(generatePureAnnotation);
 	}
 
+	/** Replies if the equality test functions shall be generated.
+	 *
+	 * @return <code>true</code> if the functions shall be generated.
+	 * @since 0.8
+	 */
+	@Pure
+	public boolean isGenerateEqualityTestFunctions() {
+		return getGeneratorConfig2().isGenerateEqualityTestFunctions();
+	}
+
+	/** Set if the equality test functions shall be generated.
+	 *
+	 * @param generateFunctions <code>true</code> if the functions shall be generated.
+	 * @since 0.8
+	 */
+	public void setGenerateEqualityTestFunctions(final boolean generateFunctions) {
+		getGeneratorConfig2().setGenerateEqualityTestFunctions(generateFunctions);
+	}
+
 	/** Change the source path.
 	 *
 	 * <p>The source path is a list the names of folders that are separated by {@link File#pathSeparator}.