Merge pull request #18 from NamiUni/feat/sort-bundle-keys

Ensure that the order of resource bundle keys matches the order of methods

Author: NamiUni

build-logic/src/main/kotlin/kotonoha.base.gradle.kts

@@ -6,7 +6,7 @@ plugins {
 
 java {
     toolchain {
-        languageVersion.set(JavaLanguageVersion.of(21))
+        languageVersion.set(JavaLanguageVersion.of(25))
     }
 }
 

gradle.properties

@@ -1,5 +1,5 @@
 # Project Properties
-projectVersion=0.2.0
+projectVersion=0.2.1
 group=io.github.namiuni
 description = An Adventure-focused library for Internationalization (i18n).
 

resourcebundle-generator-processor/src/main/java/io/github/namiuni/kotonoha/resourcebundle/generator/processor/ResourceBundleGeneratorProcessor.java

@@ -30,14 +30,10 @@
 import io.github.namiuni.kotonoha.annotations.ResourceBundle;
 import java.io.IOException;
 import java.io.Writer;
-import java.util.Comparator;
-import java.util.HashMap;
-import java.util.LinkedHashSet;
+import java.util.LinkedHashMap;
 import java.util.Map;
-import java.util.Properties;
+import java.util.Objects;
 import java.util.Set;
-import java.util.function.Supplier;
-import java.util.stream.Collectors;
 import javax.annotation.processing.AbstractProcessor;
 import javax.annotation.processing.Filer;
 import javax.annotation.processing.Messager;
@@ -53,41 +49,34 @@
 import javax.lang.model.element.TypeElement;
 import javax.tools.Diagnostic;
 import javax.tools.StandardLocation;
-import org.jspecify.annotations.NonNull;
-
-/**
- * An annotation processor that generates Java {@link java.util.ResourceBundle} property files
- * from interfaces annotated with {@link ResourceBundle}.
- *
- * <p>This processor scans methods within annotated interfaces for {@link Key}, {@link ResourceBundle}, {@link Message},
- * {@link Messages} annotations
- * to construct translation keys and messages. It then writes these into standard
- * `.properties` files, grouped by locale.</p>
- *
- * @since 0.1.0
- */
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/// An annotation processor that generates Java [java.util.ResourceBundle] property files
+/// from interfaces annotated with [ResourceBundle].
+///
+/// This processor scans methods within annotated interfaces for [Key], [ResourceBundle], [Message],
+/// [Messages] annotations
+/// to construct translation keys and messages. It then writes these into standard
+/// `.properties` files, grouped by locale.
+///
+/// Keys in the generated files are written in the same order as the method declarations
+/// in the source interface, because [javax.lang.model.element.TypeElement#getEnclosedElements()]
+/// preserves source declaration order per the `javax.lang.model` specification.
+///
+/// @since 0.1.0
+@NullMarked
 @SupportedAnnotationTypes({
         "io.github.namiuni.kotonoha.annotations.Key",
         "io.github.namiuni.kotonoha.annotations.ResourceBundle",
         "io.github.namiuni.kotonoha.annotations.Message",
         "io.github.namiuni.kotonoha.annotations.Messages"
 })
-@SupportedSourceVersion(SourceVersion.RELEASE_21)
+@SupportedSourceVersion(SourceVersion.RELEASE_25)
 public final class ResourceBundleGeneratorProcessor extends AbstractProcessor {
 
-    private static final Supplier<Properties> SORTED_PROPERTIES = () -> new Properties() {
-        @Override
-        public synchronized @NonNull Set<Map.Entry<Object, Object>> entrySet() {
-            return Set.copyOf(
-                    (Set<? extends Map.Entry<Object, Object>>) super.entrySet()
-                            .stream()
-                            .sorted(Comparator.comparing(entry -> entry.getKey().toString()))
-                            .collect(Collectors.toCollection(LinkedHashSet::new)));
-        }
-    };
-
-    private Filer filer;
-    private Messager messager;
+    private @Nullable Filer filer;
+    private @Nullable Messager messager;
 
     /**
      * Creates a new {@code ResourceBundleGeneratorProcessor} instance.
@@ -114,8 +103,7 @@ public boolean process(final Set<? extends TypeElement> annotations, final Round
 
         for (final Element element : resourceBundleElements) {
             if (element.getKind() != ElementKind.INTERFACE) {
-                final String message = "@ResourceBundle can only be applied to interfaces";
-                this.messager.printMessage(Diagnostic.Kind.ERROR, message, element);
+                Objects.requireNonNull(this.messager).printMessage(Diagnostic.Kind.ERROR, "@ResourceBundle can only be applied to interfaces", element);
                 continue;
             }
 
@@ -132,41 +120,44 @@ private void processResourceBundleInterface(final TypeElement typeElement) {
         }
 
         final String baseName = resourceBundleAnnotation.baseName();
-        final Map<String, Properties> localeProperties = new HashMap<>();
 
-        // Process all methods in the interface
+        // LinkedHashMap preserves locale insertion order.
+        // The inner LinkedHashMap preserves key insertion order, which corresponds
+        // to method declaration order because getEnclosedElements() is ordered by
+        // source position per the javax.lang.model specification.
+        final Map<String, Map<String, String>> localeEntries = new LinkedHashMap<>();
+
         for (final Element enclosedElement : typeElement.getEnclosedElements()) {
             if (enclosedElement.getKind() == ElementKind.METHOD) {
-                this.processMethod((ExecutableElement) enclosedElement, localeProperties);
+                this.processMethod((ExecutableElement) enclosedElement, localeEntries);
             }
         }
 
-        // Write properties files for each locale
-        this.writePropertiesFiles(baseName, localeProperties);
+        this.writePropertiesFiles(baseName, localeEntries);
     }
 
-    private void processMethod(final ExecutableElement method, final Map<String, Properties> localeProperties) {
+    private void processMethod(
+            final ExecutableElement method,
+            final Map<String, Map<String, String>> localeEntries
+    ) {
         if (method.isDefault() || method.getModifiers().contains(Modifier.STATIC)) {
             return;
         }
 
         final Key keyAnnotation = method.getAnnotation(Key.class);
         if (keyAnnotation == null) {
             final String message = "Method missing @Key annotation: %s";
-            this.messager.printMessage(Diagnostic.Kind.WARNING, message.formatted(method.getSimpleName()), method);
+            Objects.requireNonNull(this.messager).printMessage(Diagnostic.Kind.WARNING, message.formatted(method.getSimpleName()), method);
             return;
         }
 
         final String key = keyAnnotation.value();
-
-        // Process @Message annotations (both single and repeatable)
         final Message[] messageAnnotations = this.getMessageAnnotations(method);
 
         for (final Message messageAnnotation : messageAnnotations) {
             final String localeKey = this.getLocaleKey(messageAnnotation.locale());
-            final String content = messageAnnotation.content();
-
-            localeProperties.computeIfAbsent(localeKey, k -> SORTED_PROPERTIES.get()).setProperty(key, content);
+            localeEntries.computeIfAbsent(localeKey, _ -> new LinkedHashMap<>())
+                    .put(key, messageAnnotation.content());
         }
     }
 
@@ -191,20 +182,72 @@ private String getLocaleKey(final Locales locale) {
         return "_" + locale.asLocale();
     }
 
-    private void writePropertiesFiles(final String baseName, final Map<String, Properties> localeProperties) {
-        for (final Map.Entry<String, Properties> entry : localeProperties.entrySet()) {
+    private void writePropertiesFiles(
+            final String baseName,
+            final Map<String, Map<String, String>> localeEntries
+    ) {
+        for (final Map.Entry<String, Map<String, String>> entry : localeEntries.entrySet()) {
             final String localeKey = entry.getKey();
-            final Properties properties = entry.getValue();
-
+            final Map<String, String> entries = entry.getValue();
             final String fileName = baseName + localeKey + ".properties";
-            try (Writer writer = this.filer.createResource(StandardLocation.CLASS_OUTPUT, "", fileName).openWriter()) {
-                properties.store(writer, "Generated by ResourceBundleGeneratorProcessor");
-                this.messager.printMessage(Diagnostic.Kind.NOTE, "Generated resource bundle: " + fileName);
 
+            try (Writer writer = Objects.requireNonNull(this.filer).createResource(StandardLocation.CLASS_OUTPUT, "", fileName).openWriter()) {
+                writer.write("# Generated by ResourceBundleGeneratorProcessor\n");
+                for (final Map.Entry<String, String> prop : entries.entrySet()) {
+                    writer.write(escapeKey(prop.getKey()));
+                    writer.write('=');
+                    writer.write(escapeValue(prop.getValue()));
+                    writer.write('\n');
+                }
+                Objects.requireNonNull(this.messager).printMessage(Diagnostic.Kind.NOTE, "Generated resource bundle: " + fileName);
             } catch (final IOException exception) {
                 final String message = "Failed to write properties file: %s - %s";
-                this.messager.printMessage(Diagnostic.Kind.ERROR, message.formatted(fileName, exception.getMessage()));
+                Objects.requireNonNull(this.messager).printMessage(Diagnostic.Kind.ERROR, message.formatted(fileName, exception.getMessage()));
             }
         }
     }
+
+    private static String escapeKey(final String key) {
+        return escape(key, true);
+    }
+
+    private static String escapeValue(final String value) {
+        return escape(value, false);
+    }
+
+    private static String escape(final String input, final boolean escapeSpace) {
+        final int length = input.length();
+        final StringBuilder builder = new StringBuilder(length);
+
+        for (int i = 0; i < length; i++) {
+            final char ch = input.charAt(i);
+            switch (ch) {
+                case '\\' -> builder.append("\\\\");
+                case '\n' -> builder.append("\\n");
+                case '\r' -> builder.append("\\r");
+                case '\t' -> builder.append("\\t");
+                case '\f' -> builder.append("\\f");
+                case ' ' -> {
+                    if (escapeSpace || i == 0) {
+                        builder.append("\\ ");
+                    } else {
+                        builder.append(ch);
+                    }
+                }
+                case '=', ':', '#', '!' -> {
+                    builder.append('\\');
+                    builder.append(ch);
+                }
+                default -> {
+                    if (ch < 0x0020 || ch > 0x007e) {
+                        builder.append(String.format("\\u%04x", (int) ch));
+                    } else {
+                        builder.append(ch);
+                    }
+                }
+            }
+        }
+
+        return builder.toString();
+    }
 }

resourcebundle-generator-processor/src/test/java/io/github/namiuni/kotonoha/resourcebundle/generator/processor/ResourceBundleGeneratorProcessorTest.java

@@ -67,7 +67,7 @@ void testGetSupportedAnnotationTypes() {
         @DisplayName("Verify that supported Java source version is correct")
         void testGetSupportedSourceVersion() {
             final ResourceBundleGeneratorProcessor processor = new ResourceBundleGeneratorProcessor();
-            assertEquals(SourceVersion.RELEASE_21, processor.getSupportedSourceVersion());
+            assertEquals(SourceVersion.RELEASE_25, processor.getSupportedSourceVersion());
         }
     }