Added the option to specify a result file with --move VIEW

README.md

@@ -83,54 +83,84 @@ When using the subcommand, language-specific arguments can be set. A list of lan
 ```
 Parameter descriptions: 
       [root-dirs[,root-dirs...]...]
-                        Root-directory with submissions to check for plagiarism.
+                        Root-directory with submissions to check for
+                          plagiarism. If mode is set to VIEW, this parameter
+                          can be used to specify a file to open. In that case
+                          only a single file may be specified.
       -bc, --bc, --base-code=<baseCode>
-                        Path to the base code directory (common framework used in all submissions).
-  -l, --language=<language>
-                        Select the language of the submissions (default: java). See subcommands below.
-  -M, --mode=<{RUN, VIEW, RUN_AND_VIEW}>
-                        The mode of JPlag: either only run analysis, only open the viewer, or do both (default: null)
-  -n, --shown-comparisons=<shownComparisons>
-                        The maximum number of comparisons that will be shown in the generated report, if set to -1 all comparisons will be shown (default: 500)
+                        Path to the base code directory (common framework used
+                          in all submissions).
+      -l, --language=<language>
+                        Select the language of the submissions (default: java).
+                          See subcommands below.
+      -M, --mode=<{RUN, VIEW, RUN_AND_VIEW}>
+                        The mode of JPlag. If VIEW is chosen, you can specify a
+                          result file to display. One of: RUN, VIEW,
+                          RUN_AND_VIEW (default: null)
+      -n, --shown-comparisons=<shownComparisons>
+                        The maximum number of comparisons that will be shown in
+                          the generated report, if set to -1 all comparisons
+                          will be shown (default: 2500)
       -new, --new=<newDirectories>[,<newDirectories>...]
-                        Root-directories with submissions to check for plagiarism (same as root).
-      --normalize       Activate the normalization of tokens. Supported for languages: Java, C++.
+                        Root-directories with submissions to check for
+                          plagiarism (same as root).
+      --normalize       Activate the normalization of tokens. Supported for
+                          languages: Java, C++.
       -old, --old=<oldDirectories>[,<oldDirectories>...]
-                        Root-directories with prior submissions to compare against.
-  -r, --result-file=<resultFile>
-                        Name of the file in which the comparison results will be stored (default: results). Missing .zip endings will be automatically added.
-  -t, --min-tokens=<minTokenMatch>
-                        Tunes the comparison sensitivity by adjusting the minimum token required to be counted as a matching section. A smaller value increases the sensitivity but might lead to more
-                          false-positives.
+                        Root-directories with prior submissions to compare
+                          against.
+      -r, --result-file=<resultFile>
+                        Name of the file in which the comparison results will
+                          be stored (default: results). Missing .zip endings
+                          will be automatically added.
+      -t, --min-tokens=<minTokenMatch>
+                        Tunes the comparison sensitivity by adjusting the
+                          minimum token required to be counted as a matching
+                          section. A smaller value increases the sensitivity
+                          but might lead to more false-positives.
 
 Advanced
       --csv-export      Export pairwise similarity values as a CSV file.
-  -d, --debug           Store on-parsable files in error folder.
-  -m, --similarity-threshold=<similarityThreshold>
-                        Comparison similarity threshold [0.0-1.0]: All comparisons above this threshold will be saved (default: 0.0).
+      -d, --debug           Store on-parsable files in error folder.
+      --log-level=<{ERROR, WARN, INFO, DEBUG, TRACE}>
+                        Set the log level for the cli.
+      -m, --similarity-threshold=<similarityThreshold>
+                        Comparison similarity threshold [0.0-1.0]: All
+                          comparisons above this threshold will be saved
+                          (default: 0.0).
       --overwrite       Existing result files will be overwritten.
-  -p, --suffixes=<suffixes>[,<suffixes>...]
-                        comma-separated list of all filename suffixes that are included.
-  -P, --port=<port>     The port used for the internal report viewer (default: 1996).
-  -s, --subdirectory=<subdirectory>
+      -p, --suffixes=<suffixes>[,<suffixes>...]
+                        comma-separated list of all filename suffixes that are
+                          included.
+      -P, --port=<port>     The port used for the internal report viewer (default:
+                          1996).
+      -s, --subdirectory=<subdirectory>
                         Look in directories <root-dir>/*/<dir> for programs.
-  -x, --exclusion-file=<exclusionFileName>
-                        All files named in this file will be ignored in the comparison (line-separated list).
+      -x, --exclusion-file=<exclusionFileName>
+                        All files named in this file will be ignored in the
+                          comparison (line-separated list).
 
 Clustering
       --cluster-alg, --cluster-algorithm=<{AGGLOMERATIVE, SPECTRAL}>
-                        Specifies the clustering algorithm (default: spectral).
+                        Specifies the clustering algorithm. Available
+                          algorithms: agglomerative, spectral (default:
+                          spectral).
       --cluster-metric=<{AVG, MIN, MAX, INTERSECTION}>
-                        The similarity metric used for clustering (default: average similarity).
+                        The similarity metric used for clustering. Available
+                          metrics: average similarity, minimum similarity,
+                          maximal similarity, matched tokens (default: average
+                          similarity).
       --cluster-skip    Skips the cluster calculation.
 
 Subsequence Match Merging
       --gap-size=<maximumGapSize>
-                        Maximal gap between neighboring matches to be merged (between 1 and minTokenMatch, default: 6).
-      --match-merging   Enables merging of neighboring matches to counteract obfuscation attempts.
+                        Maximal gap between neighboring matches to be merged
+                          (between 1 and minTokenMatch, default: 6).
+      --match-merging   Enables merging of neighboring matches to counteract
+                          obfuscation attempts.
       --neighbor-length=<minimumNeighborLength>
-                        Minimal length of neighboring matches to be merged (between 1 and minTokenMatch, default: 2).
-
+                        Minimal length of neighboring matches to be merged
+                          (between 1 and minTokenMatch, default: 2).
 Languages:
   c
   cpp

cli/src/main/java/de/jplag/cli/CLI.java

@@ -57,7 +57,7 @@ public void executeCli() throws ExitException, IOException {
 
             switch (this.inputHandler.getCliOptions().mode) {
                 case RUN -> runJPlag();
-                case VIEW -> runViewer(null);
+                case VIEW -> runViewer(this.inputHandler.getFileForViewMode());
                 case RUN_AND_VIEW -> runViewer(runJPlag());
             }
         }

cli/src/main/java/de/jplag/cli/options/CliOptions.java

@@ -22,7 +22,7 @@
 public class CliOptions implements Runnable {
     public static final Language defaultLanguage = new JavaLanguage();
 
-    @Parameters(paramLabel = "root-dirs", description = "Root-directory with submissions to check for plagiarism.", split = ",")
+    @Parameters(paramLabel = "root-dirs", description = "Root-directory with submissions to check for plagiarism. If mode is set to VIEW, this parameter can be used to specify a file to open. In that case only a single file may be specified.", split = ",")
     public File[] rootDirectory = new File[0];
 
     @Option(names = {"--new", "-new"}, split = ",", description = "Root-directories with submissions to check for plagiarism (same as root).")
@@ -53,7 +53,8 @@ public class CliOptions implements Runnable {
             "--result-file"}, description = "Name of the file in which the comparison results will be stored (default: ${DEFAULT-VALUE}). Missing .zip endings will be automatically added.")
     public String resultFile = "results";
 
-    @Option(names = {"-M", "--mode"}, description = "The mode of JPlag. One of: ${COMPLETION-CANDIDATES} (default: ${DEFAULT_VALUE})")
+    @Option(names = {"-M",
+            "--mode"}, description = "The mode of JPlag. If VIEW is chosen, you can specify a result file to display. One of: ${COMPLETION-CANDIDATES} (default: ${DEFAULT_VALUE})")
     public JPlagMode mode = JPlagMode.RUN_AND_VIEW;
 
     @Option(names = {"--normalize"}, description = "Activate the normalization of tokens. Supported for languages: Java, C++.")

cli/src/main/java/de/jplag/cli/picocli/CliInputHandler.java

@@ -7,6 +7,7 @@
 
 import java.io.File;
 import java.security.SecureRandom;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
@@ -29,6 +30,7 @@
 public class CliInputHandler {
     private static final String OPTION_LIST_HEADING = "Parameter descriptions: ";
 
+    private static final String AMBIGUOUS_VIEW_FILE = "There are multiple files specified for '--mode VIEW', please make sure only to specify one.";
     private static final String UNKNOWN_LANGUAGE_EXCEPTION = "Language %s does not exists. Available languages are: %s";
     private static final String IMPOSSIBLE_EXCEPTION = "This should not have happened."
             + " Please create an issue on github (https://github.com/jplag/JPlag/issues) with the entire output.";
@@ -43,6 +45,8 @@ public class CliInputHandler {
     private static final String PARAMETER_SHORT_PREFIX = "  -";
     private static final String PARAMETER_SHORT_ADDITIONAL_INDENT = "    ";
 
+    private static final char RESULT_FILE_OPTION_NAME = 'r';
+
     private static final Random RANDOM = new SecureRandom();
 
     private final String[] args;
@@ -169,4 +173,26 @@ private String generateDescription() {
         var randomDescription = DESCRIPTIONS[RANDOM.nextInt(DESCRIPTIONS.length)];
         return String.format(DESCRIPTION_PATTERN, randomDescription, CREDITS);
     }
+
+    /**
+     * Returns the file to display when using --move VIEW. The result can be null, if no file was selected
+     * @return The file to show
+     * @throws CliException If multiple options would be valid
+     */
+    public File getFileForViewMode() throws CliException {
+        List<File> validOptions = new ArrayList<>(List.of(this.options.rootDirectory));
+
+        validOptions.addAll(List.of(this.options.newDirectories));
+        validOptions.addAll(List.of(this.options.oldDirectories));
+
+        if (this.parseResult.hasMatchedOption(RESULT_FILE_OPTION_NAME)) {
+            validOptions.add(new File(this.options.resultFile));
+        }
+
+        return switch (validOptions.size()) {
+            case 0 -> null;
+            case 1 -> validOptions.getFirst();
+            default -> throw new CliException(AMBIGUOUS_VIEW_FILE);
+        };
+    }
 }

cli/src/test/java/de/jplag/cli/ModeTest.java

@@ -0,0 +1,60 @@
+package de.jplag.cli;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrowsExactly;
+
+import java.io.File;
+import java.io.IOException;
+
+import org.junit.jupiter.api.Test;
+
+import de.jplag.cli.picocli.CliInputHandler;
+import de.jplag.cli.test.CliArgument;
+import de.jplag.cli.test.CliTest;
+import de.jplag.exceptions.ExitException;
+
+class ModeTest extends CliTest {
+    @Test
+    void testViewWithPositionalFile() throws IOException, ExitException {
+        CliInputHandler inputHandler = this
+                .runCli(args -> args.with(CliArgument.MODE, "view").with(CliArgument.SUBMISSION_DIRECTORIES, new String[] {"result.zip"}))
+                .inputHandler();
+        assertEquals(new File("result.zip"), inputHandler.getFileForViewMode());
+    }
+
+    @Test
+    void testViewWithOldFile() throws IOException, ExitException {
+        CliInputHandler inputHandler = this
+                .runCli(args -> args.with(CliArgument.MODE, "view").with(CliArgument.OLD_SUBMISSION_DIRECTORIES, new String[] {"result.zip"}))
+                .inputHandler();
+        assertEquals(new File("result.zip"), inputHandler.getFileForViewMode());
+    }
+
+    @Test
+    void testViewWithNewFile() throws IOException, ExitException {
+        CliInputHandler inputHandler = this
+                .runCli(args -> args.with(CliArgument.MODE, "view").with(CliArgument.NEW_SUBMISSION_DIRECTORIES, new String[] {"result.zip"}))
+                .inputHandler();
+        assertEquals(new File("result.zip"), inputHandler.getFileForViewMode());
+    }
+
+    @Test
+    void testViewWithResultFile() throws IOException, ExitException {
+        CliInputHandler inputHandler = this.runCli(args -> args.with(CliArgument.MODE, "view").with(CliArgument.RESULT_FILE, "result.zip"))
+                .inputHandler();
+        assertEquals(new File("result.zip"), inputHandler.getFileForViewMode());
+    }
+
+    @Test
+    void testViewWithMultipleFiles() {
+        assertThrowsExactly(CliException.class, () -> {
+            this.runCli(args -> args.with(CliArgument.MODE, "view").with(CliArgument.RESULT_FILE, "result.zip")
+                    .with(CliArgument.NEW_SUBMISSION_DIRECTORIES, new String[] {"test.zip"})).inputHandler();
+        });
+    }
+
+    @Override
+    public void addDefaultParameters() {
+        // prevents the submission directory from being added to the parameters automatically
+    }
+}

cli/src/test/java/de/jplag/cli/test/CliArgument.java

@@ -34,4 +34,6 @@ public record CliArgument<T>(String name, boolean isPositional) {
 
     public static CliArgument<String> SUBDIRECTORY = new CliArgument<>("subdirectory", false);
     public static CliArgument<String> EXCLUDE_FILES = new CliArgument<>("x", false);
+
+    public static CliArgument<String> MODE = new CliArgument<>("mode", false);
 }

cli/src/test/java/de/jplag/cli/test/CliResult.java

@@ -2,7 +2,8 @@
 
 import org.slf4j.event.Level;
 
+import de.jplag.cli.picocli.CliInputHandler;
 import de.jplag.options.JPlagOptions;
 
-public record CliResult(JPlagOptions jPlagOptions, String targetPath, Level logLevel) {
+public record CliResult(JPlagOptions jPlagOptions, String targetPath, Level logLevel, CliInputHandler inputHandler) {
 }

cli/src/test/java/de/jplag/cli/test/CliTest.java

@@ -154,7 +154,7 @@ protected CliResult runCli(Consumer<CliArgumentBuilder> additionalOptionsBuilder
 
             String targetPath = (String) getWritableFileMethod.invoke(cli);
 
-            return new CliResult(optionsBuilder.buildOptions(), targetPath, CollectedLogger.getLogLevel());
+            return new CliResult(optionsBuilder.buildOptions(), targetPath, CollectedLogger.getLogLevel(), inputHandler);
         } catch (IllegalAccessException | InvocationTargetException e) {
             Assumptions.abort("Could not access private field in CLI for test.");
             return null; // will not be executed