hw1: update cases, manual

Author: NeverBehave

ConWaysGame/deps/junit-platform-console-standalone-1.7.0.jar

@@ -0,0 +1,122 @@
+# Manual
+
+This is the manual of Conway Game of Life simulator usage.
+
+## Inputs
+
+In this section, program usage will be presented, as well as input file format.
+
+### Command line
+
+Please refer to `readme.md`, looking for commands for your OS. Here we will explain each argument and its usage.
+
+#### `<input>`
+
+The path to the seed file. The file format is defined below.
+
+##### Input File format
+
+- The first line contains, in order, the number of rows, and the number of columns in the grid, separated by a comma and a space. E.g., 5, 7 means that there are 5 rows and 7 columns in the grid. There are no spaces after the number of columns.
+- All lines starting from the second one contain the state of one row in the grid, starting with row #0. The state of each cell is designated with either 0 (cell is dead) or 1 (cell is alive). The states of individual cells are separated by a comma followed by a space (there is no comma and/or space after the last 0 or 1 in the line). For example, if the third line of the file (the second line of the grid part of the file) is 0, 0, 0, 1, 0, 0, 0 it corresponds to the following cell states in row[1]: row[1][0], row[1][1], row[1][2], row[1][4], row[1][5], and row[1][6] are dead, and row[1][3] is alive.
+- All lines end with the new line character.
+
+###### Example
+
+```
+5, 7
+0, 0, 0, 0, 0, 0, 0
+0, 0, 0, 1, 0, 0, 0
+0, 0, 0, 1, 1, 1, 1
+1, 0, 0, 0, 1, 1, 1
+1, 1, 1, 1, 1, 1, 1
+```
+
+You may find more examples under `tests/` folder.
+
+#### `<output>`
+
+The path to the directory where results should be stored. If the directory does not exist, program will generate all necessary parent directories. Each file inside the directory will follow the following format: 
+
+```
+<seedFilename>.<currentStep>.txt
+```
+
+##### Output File Format
+
+The output file example may be found at `tests/result/`. The format of the file is the same as the input file.
+
+#### `<step>`
+
+The number of step the simulation should run. This should be a positive integer.
+
+## Errors
+
+Here we have listed some possible errors when using the program and what could you do when you have encountered them.
+We have also provided some good and bad examples in next section.
+
+### `Err: [io] Output path must be a directory`
+
+The specified `<output>` exists and is not a directory. Please specify another available location.
+
+### `Err: [io] Failed to create output directory`
+
+The specified `<output>` does not exist, but program failed to create corresponded parents directories. Sometimes it may be system error, but please ensure the path enter is valid for your current OS.
+
+### `Err: [input] step x is invalid`
+
+This happened when step is less than 0. Please specify a number equal to or larger than 0.
+
+### `An error occur while processing files: `
+
+An `IOException` occurs. Possibly due to non-existence of a specified file, or other system issue. Please read stack for more info.
+
+### `Err: [input] unable to parse "x" as integer`
+
+Either seed file row/col or step is not a valid integer representation. Please double check your input. 
+
+### `Err: [seedFile] unable to identify row/col of the map`
+
+The first line of the seed file doesn't follow the `row, col` format and can't be parsed.
+
+### `Err: [seedFile] Invalid row/col, must be positive integer larger than 2`
+
+Row or column integer representation in the seedFile is invalid.
+
+### `Err: [seedFile] Unexpected col length at row index x`
+
+When reading seed file, a row is missing some cell representation. Please check if your file is corrupted.
+
+### `Err: [seedFile] Unexpected cell type x`
+
+When reading a specific cell in the seed file, program cannot recognize its status. Please refer to file format section for the correct types.
+
+### `Cannot invoke "String.split(String)" because "<local1>" is null`
+
+Seed file is possibly empty. Please check if correct seed file is given.
+
+## Examples Args
+
+Please append the following with your OS command specify in `readme.md`
+
+```bash
+tests/example1.txt tests/result/example1 21
+tests/example2.txt tests/result/example2 5
+tests/example3.txt tests/result/example3 50
+```
+
+### Bad Examples
+
+```bash
+... tests/invalid1.txt tests/result/example1 1
+Err: [seedFile] Invalid row/col, must be positive integer larger than 2
+... tests/invalid2.txt tests/result/example1 1
+Err: [seedFile] Invalid row/col, must be positive integer larger than 2
+... tests/invalid3.txt tests/result/example1 1
+Err: [seedFile] Unexpected cell type 2
+... tests/invalid4.txt tests/result/example1 1
+Err: [seedFile] Unexpected col length at row index 1
+... tests/invalid5.txt tests/result/example1 1
+Cannot invoke "String.split(String)" because "<local1>" is null
+... tests/example3.txt tests/result/example1 -1
+Err: [input] step -1 is invalid
+```

ConWaysGame/manual.md

@@ -0,0 +1,84 @@
+# Tests
+
+The following methods are used when testing the program. 
+
+## United test
+
+A Java framework, JUnit5, has been used within the process. You may consult to `com.luox6.conway.test` for the test cases written.
+
+### Included sections
+
+- getters/setters
+- class constructor
+- `getCell` with wrapping
+- `neighbour` live cell counts with wrapping
+- `toString` format test
+
+The above have tested class's construction, mutation, and expected string representation.
+
+### Run Unit Test 
+
+You may use your favourite IDE integration with JUnit. Please consult [JUnit manual](https://junit.org/junit5/docs/current/user-guide/#running-tests)
+However, if you would like to use `ConsoleLauncher`, after compiling the program following the instruction in `readme.md`, try the following command for unit test result.
+
+```bash
+# The following bash command should run at project root directory
+$ java -jar deps/junit-platform-console-standalone-1.7.0.jar -cp ./src --scan-class-path
+```
+
+Success Output: 
+
+```
+Thanks for using JUnit! Support its development at https://junit.org/sponsoring
+
+╷
+├─ JUnit Jupiter ✔
+│  └─ ConwayMapTest ✔
+│     ├─ getMapRowLength() ✔
+│     ├─ isValidCoordinate() ✔
+│     ├─ getMapColLength() ✔
+│     ├─ testToString() ✔
+│     ├─ getCell() ✔
+│     └─ neighbours() ✔
+└─ JUnit Vintage ✔
+
+Test run finished after 89 ms
+[         3 containers found      ]
+[         0 containers skipped    ]
+[         3 containers started    ]
+[         0 containers aborted    ]
+[         3 containers successful ]
+[         0 containers failed     ]
+[         6 tests found           ]
+[         0 tests skipped         ]
+[         6 tests started         ]
+[         0 tests aborted         ]
+[         6 tests successful      ]
+[         0 tests failed          ]
+```
+
+## Manual Test
+
+However, the unit test cannot cover some corner cases, e.g.:
+
+- Seed file parsing
+- IO/Input validation
+- ...
+
+In order to test these cases, here we have some crafted files, which are also listed in `manual->Example Args` section.
+These cases have covered the following topics: 
+
+- example1.txt -> Given test file from homework description
+- example2.txt -> Wrapping, neighbour counts, simple, mostly static case
+- example3.txt -> Wrapping, neighbour counts, complex moving case
+- invalid1.txt -> Seed file with < 2 rows
+- invalid2.txt -> Seed file with < 2 columns
+- invalid3.txt -> Seed file with undefined char
+- invalid4.txt -> Seed file with inconsistent rows
+- invalid5.txt -> empty seed file
+
+Commands to run these examples have also listed in the manual. It is believed that these cases cover most of the common mistakes that users would make.
+
+Game rules are also tested at `example2.txt` and `example3.txt` by stepping through the generated files.
+
+Some examples inspired by [wikipedia](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life).

ConWaysGame/manuals/manual.md

@@ -1,3 +1,61 @@
+# Conway Game of Life
+
+## Environment
+
+Code and scripts are tested under with following settings.
+
+### Linux 
+
+#### Distribution
+
+NixOS https://nixos.org
+
+```bash
+$ uname -a
+Linux home-thinkcenter 5.4.90 #1-NixOS SMP Sun Jan 17 13:05:38 UTC 2021 x86_64 GNU/Linux
+```
+
+#### JDK
+
+```bash
+$ javac --version
+javac 15.0.1
+$ java --version
+openjdk 15.0.1 2020-10-20
+OpenJDK Runtime Environment (build 15.0.1+0-adhoc..jdk15u-jdk-15.0.1-ga)
+OpenJDK 64-Bit Server VM (build 15.0.1+0-adhoc..jdk15u-jdk-15.0.1-ga, mixed mode, sharing)
+```
+
+### Windows
+
+Virtualbox (Oracle VM VirtualBox VM Runner v6.1.16) used.
+
+https://modern.ie Image from https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/
+
+#### Distribution
+
+![](./windows.png)
+
+#### JDK
+
+```powershell
+PS C:\Users\IEUser> javac --version
+javac 15.0.2
+PS C:\Users\IEUser> java --version
+java 15.0.2 2021-01-19
+Java(TM) SE Runtime Environment (build 15.0.2+7-27)
+Java HotSpot(TM) 64-Bit Server VM (build 15.0.2+7-27, mixed mode, sharing)
+```
+
+#### Note for javadoc
+
+By default, installation from Java won't add javadoc to path. Please add Java bin path to `Control Panel -> System and Security -> System -> Advance System Setting -> Environment Variables -> Path` with your install path so the script can work properly.
+
+![](./windows_path.png)
+
+
+### 
+
 ## Usage
 
 The following command are happened under project root directory
@@ -18,14 +76,21 @@ sh scripts/run.sh <input> <output> <step>
 
 ### Windows
 
+Open the powershell and nevigate to the project root directory
+
 #### Compile
 
 ```cmd
-scripts/compile.cmd
+.\scripts\compile.cmd
 ```
 
 #### Run
 
 ```cmd
-scripts/run.cmd <input> <output> <step>
+.\scripts\run.cmd <input> <output> <step>
 ```
+
+
+## Others
+
+Please consult `manuals/` for more info

ConWaysGame/manuals/tests.md

@@ -1,7 +1,7 @@
 @ECHO OFF
 echo "====== GameOfLife Script on Windows ======"
 echo "Compiling..."
-javac -cp '.\deps\*' .\src\**\*.java
-echo "Compilaton success. Generating Javadoc..."
+javac -cp '.\deps\*' -sourcepath src src/com/luox6/conway/Main.java
+echo "Compilaton complete. Generating Javadoc..."
 cd .\src
-javadoc -encoding UTF-8 com.luox6.conway -d ..\doc
+javadoc -encoding UTF-8 com.luox6.conway -d ..\docs

ConWaysGame/readme.md

@@ -1,6 +1,6 @@
 echo "====== GameOfLife Script on Linux ======"
 echo "[MSG] Compiling..."
-javac -cp './deps/*' ./src/**/*.java
+javac -cp './deps/*' -sourcepath src src/com/luox6/conway/Main.java
 echo "[MSG] Compilaton success. Generating Javadoc..."
 cd ./src
 javadoc -encoding UTF-8 com.luox6.conway -d ../docs

ConWaysGame/scripts/compile.cmd

@@ -1,3 +1,2 @@
 @ECHO OFF
-echo "Start running..."
 java -classpath .\src com.luox6.conway.Main %1 %2 %3

ConWaysGame/scripts/compile.sh

@@ -1,2 +1 @@
-echo "Start running..."
 java -classpath ./src com.luox6.conway.Main "$@"

ConWaysGame/scripts/run.cmd

@@ -117,7 +117,7 @@ public Integer getCell(int row, int col) {
         // However, if it is less than 0, we need to have the reminder of our length and then
         // add the length back. Not the index.
         final BiFunction<Integer, Integer, Integer> wrapper =
-                (k, v) -> k < 0 ? k % v + v : k % (v - 1);
+                (k, v) -> k < 0 ? k % v + v : k % v;
         int realRow = wrapper.apply(row, this.row);
         int realCol = wrapper.apply(col, this.col);
 
@@ -177,7 +177,11 @@ private void step(int row, int col, int[][] changed) {
      * Move game forward by calculating each coordinates
      */
     public void tick() {
-        int[][] changed = map.clone();
+        // Clone the array for record
+        int[][] changed = new int[row][col];
+        for (int i = 0; i < row; i++) {
+            changed[i] = map[i].clone();
+        }
 
         for (int i = 0; i < row; i++) {
             for (int j = 0; j < col; j++) {
@@ -208,13 +212,17 @@ public static int charToInt(char cell) {
     @Override
     public String toString() {
         StringBuilder x = new StringBuilder();
-        x.append("ConwayGameOfLife with row " + row + ", col " + col + ", current tick " + tick + ".\n");
-        x.append("Map: \n");
+        x.append(row).append(", ").append(col).append("\n");
         for (int i = 0; i < row; i++) {
-            x.append(Arrays.toString(map[i]));
-            x.append("\n");
+            for (int j = 0; j < col - 1; j++) {
+                x.append(map[i][j]).append(", ");
+            }
+            x.append(map[i][col - 1]).append("\n");
         }
 
+        // Remove last newline
+        x.setLength(x.length() - 1);
+
         return x.toString();
     }
 }