Merge pull request #75 from emustudio/development

Development

Author: vbmacher

README.md

@@ -14,19 +14,19 @@ For Maven, use:
     <dependency>
         <groupId>net.emustudio</groupId>
         <artifactId>emulib</artifactId>
-        <version>11.7.0</version>
+        <version>12.0.0</version>
     </dependency>
 ```
 
 For Gradle, use:
 
 ```
-    implementation 'net.emustudio:emulib:11.7.0'
+    implementation 'net.emustudio:emulib:12.0.0'
 ```
 
 ### Important changes
 
-Up to version 9.0.0 emuLib used different group (`net.sf.emustudio`) and artifactId (`emuLib`). From version 10.0.0
+Until version 9.0.0 emuLib used different group (`net.sf.emustudio`) and artifactId (`emuLib`). From version 10.0.0
 onwards it uses group `net.emustudio` and artifactId `emulib` (all lowercase).
 
 ## Deployment

build.gradle

@@ -25,7 +25,7 @@ plugins {
 }
 
 group 'net.emustudio'
-version '11.7.0'
+version '12.0.0'
 
 repositories {
   mavenCentral()

src/main/java/net/emustudio/emulib/plugins/Plugin.java

@@ -36,7 +36,7 @@
  * - the root class has to have single constructor with 3 parameters (see below).
  * <p>
  * The constructor signature has to look like this:
- *
+ * <p>
  * <code>
  * \@PluginRoot(...)
  * SamplePlugin(long pluginId, ApplicationApi emustudio, PluginSettings settings) {
@@ -116,9 +116,8 @@ public interface Plugin {
     /**
      * Get run-time title of this plugin.
      * <p>
-     * The title is a matter of change during runtime - for example there
-     * might be a device which might be used many times but it is called
-     * differently for each instance.
+     * The title is a matter of change during runtime - for example there might exist a device instantiated more than
+     * once, and each instance can have different title assigned at runtime.
      *
      * @return run-time title of the plugin
      */
@@ -144,5 +143,12 @@ public interface Plugin {
      * @return plugin description
      */
     String getDescription();
+
+    /**
+     * Determines if this plugin supports emulation automation
+     *
+     * @return true if the plugin supports emulation automation; false otherwise
+     */
+    boolean isAutomationSupported();
 }
 

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

@@ -75,26 +75,20 @@ public interface Compiler extends Plugin {
     /**
      * Creates a lexical analyzer.
      *
-     * @param input source code
      * @return new lexer object
      */
-    LexicalAnalyzer createLexer(String input);
-
-    /**
-     * Gets location of compiled program in memory.
-     * <p>
-     * Program location should be valid only after successful compilation.
-     * The location should point to the starting position of the program in memory, where the CPU can start emulating.
-     *
-     * @return location of compiled program in memory
-     */
-    int getProgramLocation();
+    LexicalAnalyzer createLexer();
 
     /**
      * Get the list of source file extensions supported by the compiler.
      *
      * @return list of supported source file extensions
      */
-    List<SourceFileExtension> getSourceFileExtensions();
+    List<FileExtension> getSourceFileExtensions();
+
+    @Override
+    default boolean isAutomationSupported() {
+        return true;
+    }
 }
 

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

@@ -23,7 +23,7 @@
 
 /**
  * Compiler context can be used to provide additional meta-information for runtime, which can be used by other plugins.
- *
+ * <p>
  * Plugins which need the specific compiler contexts, should declare a dependency on the compiler plugin.
  */
 @PluginContext

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

@@ -24,9 +24,9 @@
  * 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_WARNING = "[Warning] ";
+    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) ";
 

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

@@ -0,0 +1,104 @@
+/*
+ * 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;
+
+/**
+ * A file extension with description.
+ * A compiler provides list of supported source file extensions with a description, which is then used in
+ * emuStudio application when opening a file.
+ * <p>
+ * The file extension should be provided without the starting dot ("."), i.e. "asm" instead of ".asm".
+ * The extension is case-sensitive.
+ * <p>
+ * Instances of this class can be compared using .equals() method and also put to hashed collections like
+ * HashMap or HashSet. The comparison is performed by extension only.
+ */
+@Immutable
+public class FileExtension {
+    private final String extension;
+    private final String description;
+
+    /**
+     * Creates new instance of FileExtension.
+     *
+     * @param extension   Case-sensitive non-null file extension of the file, without the starting dot
+     *                    (example: "asm", but not ".asm").
+     * @param description Non-null description of the file extension.
+     * @throws NullPointerException if extension or description is null
+     */
+    public FileExtension(String extension, String description) {
+        this.extension = Objects.requireNonNull(extension);
+        this.description = Objects.requireNonNull(description);
+    }
+
+    /**
+     * Returns the file extension.
+     *
+     * @return File extension
+     */
+    public String getExtension() {
+        return extension;
+    }
+
+    /**
+     * Returns the file-extension description.
+     *
+     * @return file-extension description
+     */
+    public String getDescription() {
+        return description;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        FileExtension that = (FileExtension) o;
+        return extension.equals(that.extension);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(extension);
+    }
+
+    /**
+     * Strip file name extension if the extension belongs to known extensions.
+     * <p>
+     * The idea is that compilers should generate file with some "output" extension, so the source extension is replaced
+     * with it. However, if the source extension is unknown, it should be preserved.
+     *
+     * @param fileName        a file name
+     * @param knownExtensions known extensions
+     * @return given file name stripped from extension if it belongs to known ones
+     */
+    public static String stripKnownExtension(String fileName, Iterable<FileExtension> knownExtensions) {
+        for (FileExtension extension : knownExtensions) {
+            int i = fileName.lastIndexOf("." + extension.getExtension());
+            if (i >= 0) {
+                return fileName.substring(0, i);
+            }
+        }
+        return fileName;
+    }
+}

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

@@ -18,6 +18,8 @@
  */
 package net.emustudio.emulib.plugins.compiler;
 
+import net.jcip.annotations.NotThreadSafe;
+
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
@@ -26,38 +28,48 @@
 
 /**
  * Lexical analyzer.
+ * <p>
+ * It is not meant to be thread-safe.
+ * Before using, make sure the lexer is reset.
  */
 @SuppressWarnings("unused")
+@NotThreadSafe
 public interface LexicalAnalyzer extends Iterable<Token> {
 
     /**
-     * Get next token.
-     * <p>
-     * Tokens are retrieved as in "iterator" style - the actual position is a mutable state stored in the lexer.
+     * Parse next token.
      *
-     * @return next token
+     * @return next token, or Token.EOF if no token is available on the input
      */
-    Token nextToken();
+    Token next();
 
     /**
-     * Determines if this lexer is at EOF (at the end of parsing)
-     * @return true if the EOF was hit
+     * Determines if a next token is available on the input at the current lexer position.
+     *
+     * @return true if the lexer has a next token to be parsed
      */
-    boolean isAtEOF();
+    boolean hasNext();
 
     /**
      * Reset this lexical analyzer with new input.
-     * All state should be reset.
+     *
      * @param input new program source code
      * @throws IOException when input cannot be read
      */
     void reset(InputStream input) throws IOException;
 
+    /**
+     * Reset this lexical analyzer with new input.
+     *
+     * @param input new program source code
+     */
+    void reset(String input);
+
     @Override
     default Iterator<Token> iterator() {
         List<Token> tokens = new ArrayList<>();
-        while (!isAtEOF()) {
-            tokens.add(nextToken());
+        while (hasNext()) {
+            tokens.add(next());
         }
         return tokens.iterator();
     }

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

@@ -126,9 +126,9 @@ void requestStop() {
     /**
      * Creates new instance of CPU.
      *
-     * @param pluginID plugin ID
+     * @param pluginID       plugin ID
      * @param applicationApi emuStudio API
-     * @param settings plugin custom settings
+     * @param settings       plugin custom settings
      */
     public AbstractCPU(long pluginID, ApplicationApi applicationApi, PluginSettings settings) {
         this.pluginID = pluginID;
@@ -212,7 +212,9 @@ private void stopExecutor(ExecutorService executor) {
         Objects.requireNonNull(executor);
         executor.shutdown();
         try {
-            executor.awaitTermination(10, TimeUnit.SECONDS);
+            if (!executor.awaitTermination(10, TimeUnit.SECONDS)) {
+                executor.shutdownNow();
+            }
         } catch (InterruptedException e) {
             Thread.currentThread().interrupt();
         }
@@ -273,7 +275,7 @@ private void ensureCpuIsStopped() {
 
     @Override
     public void reset() {
-        reset(0);
+        reset(applicationApi.getProgramLocation());
     }
 
     @Override