Merge pull request #79 from emustudio/feature-78

[#78] Refactor memory interface + add annotations

src/main/java/net/emustudio/emulib/plugins/compiler/Compiler.java

@@ -20,7 +20,9 @@
 
 import net.emustudio.emulib.plugins.Plugin;
 
+import java.nio.file.Path;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * Compiler plugin root interface.
@@ -53,12 +55,13 @@ public interface Compiler extends Plugin {
 
     /**
      * Compile an input file into the output file.
+     * If output file exists, it will be overwritten.
+     * Resets program start address.
      *
-     * @param inputFileName  name of the input file (source code)
-     * @param outputFileName name of the output file (compiled code)
-     * @return true if compile was successful, false otherwise
+     * @param inputFile  input file path (source code)
+     * @param outputFile output file path (compiled code). Can be null.
      */
-    boolean compile(String inputFileName, String outputFileName);
+    void compile(Path inputFile, Path outputFile);
 
     /**
      * Compile an input file into the output file.
@@ -67,10 +70,11 @@ public interface Compiler extends Plugin {
      * extension of the input file is replaced by another one, denoting
      * compiled file. It is compiler-specific.
      *
-     * @param inputFileName name of the input file (source code)
-     * @return true if compile was successful, false otherwise
+     * @param inputFile input file path (source code)
      */
-    boolean compile(String inputFileName);
+    default void compile(Path inputFile) {
+        compile(inputFile, null);
+    }
 
     /**
      * Creates a lexical analyzer.
@@ -86,6 +90,11 @@ public interface Compiler extends Plugin {
      */
     List<FileExtension> getSourceFileExtensions();
 
+    /**
+     * Determine if automation is supported.
+     *
+     * @return true by default
+     */
     @Override
     default boolean isAutomationSupported() {
         return true;

src/main/java/net/emustudio/emulib/plugins/compiler/CompilerMessage.java

@@ -24,8 +24,8 @@
  * Messages are passed to compiler listeners when the compiler wishes to say something.
  */
 public class CompilerMessage {
-    public static final String MSG_INFO =    "[INFO   ] ";
-    public static final String MSG_ERROR =   "[ERROR  ] ";
+    public static final String MSG_INFO = "[INFO   ] ";
+    public static final String MSG_ERROR = "[ERROR  ] ";
     public static final String MSG_WARNING = "[WARNING] ";
 
     public static final String POSITION_FORMAT = "(%3d,%3d) ";
@@ -35,67 +35,75 @@ public class CompilerMessage {
      */
     public enum MessageType {
         /**
-        * The message represents a warning.
-        */
+         * The message represents a warning.
+         */
         TYPE_WARNING,
         /**
-        * The message represents an error.
-        */
+         * The message represents an error.
+         */
         TYPE_ERROR,
         /**
-        * The message represents an information.
-        */
+         * The message represents an information.
+         */
         TYPE_INFO,
         /**
-        * The message is of unknown type.
-        */
+         * The message is of unknown type.
+         */
         TYPE_UNKNOWN
     }
 
     private final MessageType messageType;
     private final String message;
-    private final int line;
-    private final int column;
+    private final SourceCodePosition position;
 
     /**
      * This constructor creates the Message object. Messages are created by
      * compiler.
-     * @param messageType
-     *   Type of the message.
-     * @param message
-     *   Text of the message
-     * @param line
-     *   Line in the source code
-     * @param column
-     *   Column in the source code
+     *
+     * @param messageType Type of the message.
+     * @param message     Text of the message
+     * @param line        Line in the source code
+     * @param column      Column in the source code
      */
     public CompilerMessage(MessageType messageType, String message, int line, int column) {
         this.messageType = Objects.requireNonNull(messageType);
         this.message = Objects.requireNonNull(message);
-        this.line = line;
-        this.column = column;
+        this.position = new SourceCodePosition(line, column);
+    }
+
+    /**
+     * This constructor creates the Message object. Messages are created by
+     * compiler.
+     *
+     * @param messageType Type of the message
+     * @param message     Text of the message
+     * @param position    Source code position
+     */
+    public CompilerMessage(MessageType messageType, String message, SourceCodePosition position) {
+        this.messageType = Objects.requireNonNull(messageType);
+        this.message = Objects.requireNonNull(message);
+        this.position = Objects.requireNonNull(position);
     }
 
     /**
      * This constructor creates the Message object. Messages are created by
      * compiler.
-     * @param message
-     *   Text of the message
+     *
+     * @param message Text of the message
      */
     public CompilerMessage(String message) {
-        this(MessageType.TYPE_UNKNOWN, message,-1,-1);
+        this(MessageType.TYPE_UNKNOWN, message, -1, -1);
     }
 
     /**
      * This constructor creates the Message object. Messages are created by
      * compiler.
-     * @param type
-     *   Type of the message.
-     * @param message
-     *   Text of the message
+     *
+     * @param type    Type of the message.
+     * @param message Text of the message
      */
     public CompilerMessage(MessageType type, String message) {
-        this(type,message,-1,-1);
+        this(type, message, -1, -1);
     }
 
     /**
@@ -117,31 +125,20 @@ public String getFormattedMessage() {
                 break;
         }
 
-        if ((line >= 0) || (column >= 0)) {
-            mes.append(String.format(POSITION_FORMAT, line, column));
+        if ((position.line >= 0) || (position.column >= 0)) {
+            mes.append(String.format(POSITION_FORMAT, position.line, position.column));
         }
         mes.append(message);
         return mes.toString();
     }
 
     /**
-     * Get line of the source code that the message belongs to.
+     * Get source code position
      *
-     * @return the line, starting from 0. Negative values indicate that this
-     * value is not valid.
+     * @return position in the source code
      */
-    public int getLine() {
-        return line;
-    }
-
-    /**
-     * Get column of the source code that the message belongs to.
-     *
-     * @return the column, starting from 0. Negative values indicate that this
-     * value is not valid.
-     */
-    public int getColumn() {
-        return column;
+    public SourceCodePosition getPosition() {
+        return position;
     }
 
     /**
@@ -155,6 +152,7 @@ public String getMessage() {
 
     /**
      * Get the type of the message.
+     *
      * @return the message type
      */
     public MessageType getMessageType() {

src/main/java/net/emustudio/emulib/plugins/compiler/SourceCodePosition.java

@@ -0,0 +1,97 @@
+/*
+ * This file is part of emuLib.
+ *
+ * Copyright (C) 2006-2023  Peter Jakubčo
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package net.emustudio.emulib.plugins.compiler;
+
+import net.jcip.annotations.Immutable;
+
+import java.util.Objects;
+
+/**
+ * Position in the source code.
+ */
+@Immutable
+public class SourceCodePosition {
+
+    /**
+     * Line
+     */
+    public final int line;
+    /**
+     * Column
+     */
+    public final int column;
+
+    /**
+     * Gets line
+     *
+     * @return line
+     */
+    public int getLine() {
+        return line;
+    }
+
+    /**
+     * Gets column
+     *
+     * @return column
+     */
+    public int getColumn() {
+        return column;
+    }
+
+    /**
+     * Creates new SourceCodePosition object
+     *
+     * @param line   line
+     * @param column column
+     */
+    public SourceCodePosition(int line, int column) {
+        this.line = line;
+        this.column = column;
+    }
+
+    /**
+     * Creates new SourceCodePosition object
+     *
+     * @param line   line
+     * @param column column
+     * @return SourceCodePosition object
+     */
+    public static SourceCodePosition of(int line, int column) {
+        return new SourceCodePosition(line, column);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        SourceCodePosition that = (SourceCodePosition) o;
+        return line == that.line && column == that.column;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(line, column);
+    }
+
+    @Override
+    public String toString() {
+        return "[line=" + line + ", column=" + column + "]";
+    }
+}

src/main/java/net/emustudio/emulib/plugins/memory/AbstractMemory.java

@@ -28,6 +28,7 @@
 /**
  * Implements fundamental functionality useful for most of the memory plugins.
  */
+@SuppressWarnings("unused")
 public abstract class AbstractMemory implements Memory {
     /**
      * Plugin ID assigned by emuStudio