Generalize cursor movement

Author: romge

pom.xml

@@ -318,7 +318,7 @@
     <dependencies>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
-            <artifactId>junit-jupiter-engine</artifactId>
+            <artifactId>junit-jupiter</artifactId>
             <version>5.7.0</version>
             <scope>test</scope>
         </dependency>

src/main/java/org/fusesource/jansi/Ansi.java

@@ -556,46 +556,112 @@ public Ansi a(Attribute attribute) {
      *
      * @param row row (1-based) from top
      * @param column column (1 based) from left
-     * @return Ansi
+     * @return this Ansi instance
      */
     public Ansi cursor(final int row, final int column) {
         return appendEscapeSequence('H', row, column);
     }
 
+    /**
+     * Moves the cursor to column n. If n is negative it is not moved.
+     *
+     * @param x the index of the column to move to
+     * @return this Ansi instance
+     */
     public Ansi cursorToColumn(final int x) {
         return x >= 0 ? appendEscapeSequence('G', x) : this;
     }
 
+    /**
+     * Moves the cursor up. If the parameter y is negative it moves the cursor down.
+     *
+     * @param y the number of lines to move up
+     * @return this Ansi instance
+     */
     public Ansi cursorUp(final int y) {
-        return appendEscapeSequence('A', y);
+        return y > 0 ? appendEscapeSequence('A', y) : y < 0 ? cursorDown(-y) : this;
     }
 
+    /**
+     * Moves the cursor down. If the parameter y is negative it moves the cursor up.
+     *
+     * @param y the number of lines to move down
+     * @return this Ansi instance
+     */
     public Ansi cursorDown(final int y) {
-        return y > 0 ? appendEscapeSequence('B', y) : this;
+        return y > 0 ? appendEscapeSequence('B', y) : y < 0 ? cursorUp(-y) : this;
     }
 
+    /**
+     * Moves the cursor right. If the parameter x is negative it moves the cursor left.
+     *
+     * @param x the number of characters to move right
+     * @return this Ansi instance
+     */
     public Ansi cursorRight(final int x) {
-        return x > 0 ? appendEscapeSequence('C', x) : this;
+        return x > 0 ? appendEscapeSequence('C', x) : x < 0 ? cursorLeft(-x) : this;
     }
 
+    /**
+     * Moves the cursor left. If the parameter x is negative it moves the cursor right.
+     *
+     * @param x the number of characters to move left
+     * @return this Ansi instance
+     */
     public Ansi cursorLeft(final int x) {
-        return x > 0 ? appendEscapeSequence('D', x) : this;
+        return x > 0 ? appendEscapeSequence('D', x) : x < 0 ? cursorRight(-x) : this;
+    }
+
+    /**
+     * Moves the cursor relative to the current position. The cursor is moved right if x is
+     * positive, left if negative and down if y is positive and up if negative.
+     *
+     * @param x the number of characters to move horizontally
+     * @param y the number of lines to move vertically
+     * @return this Ansi instance
+     */
+    public Ansi cursorMove(final int x, final int y) {
+        return cursorRight(x).cursorDown(y);
     }
 
+    /**
+     * Moves the cursor to the beginning of the line below.
+     *
+     * @return this Ansi instance
+     */
     public Ansi cursorDownLine() {
         return appendEscapeSequence('E');
     }
 
+    /**
+     * Moves the cursor to the beginning of the n-th line below. If the parameter n is negative it
+     * moves the cursor to the beginning of the n-th line above.
+     *
+     * @param n the number of lines to move the cursor
+     * @return this Ansi instance
+     */
     public Ansi cursorDownLine(final int n) {
-        return n > 0 ? appendEscapeSequence('E', n) : this;
+        return n > 0 ? appendEscapeSequence('E', n) : n < 0 ? cursorUpLine(-n) : this;
     }
 
+    /**
+     * Moves the cursor to the beginning of the line above.
+     *
+     * @return this Ansi instance
+     */
     public Ansi cursorUpLine() {
         return appendEscapeSequence('F');
     }
 
+    /**
+     * Moves the cursor to the beginning of the n-th line above. If the parameter n is negative it
+     * moves the cursor to the beginning of the n-th line below.
+     *
+     * @param n the number of lines to move the cursor
+     * @return this Ansi instance
+     */
     public Ansi cursorUpLine(final int n) {
-        return n > 0 ? appendEscapeSequence('F', n) : this;
+        return n > 0 ? appendEscapeSequence('F', n) : n < 0 ? cursorDownLine(-n) : this;
     }
 
     public Ansi eraseScreen() {

src/test/java/org/fusesource/jansi/AnsiTest.java

@@ -17,6 +17,8 @@
 
 import org.fusesource.jansi.Ansi.Color;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
@@ -52,4 +54,83 @@ public void testClone() throws CloneNotSupportedException {
 
         assertEquals(ansi.a("test").reset().toString(), clone.a("test").reset().toString());
     }
+
+    @ParameterizedTest
+    @CsvSource({
+        "-1,-1,ESC[-1;-1H", "-1,0,ESC[-1;0H", "-1,1,ESC[-1;1H", "-1,2,ESC[-1;2H",
+        "0,-1,ESC[0;-1H", "0,0,ESC[0;0H", "0,1,ESC[0;1H", "0,2,ESC[0;2H",
+        "1,-1,ESC[1;-1H", "1,0,ESC[1;0H", "1,1,ESC[1;1H", "1,2,ESC[1;2H",
+        "2,-1,ESC[2;-1H", "2,0,ESC[2;0H", "2,1,ESC[2;1H", "2,2,ESC[2;2H"
+    })
+    public void testCursor(int x, int y, String expected) {
+        assertAnsi(expected, new Ansi().cursor(x, y));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,''", "-1,''", "0,ESC[0G", "1,ESC[1G", "2,ESC[2G"})
+    public void testCursorToColumn(int x, String expected) {
+        assertAnsi(expected, new Ansi().cursorToColumn(x));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,ESC[2B", "-1,ESC[1B", "0,''", "1,ESC[1A", "2,ESC[2A"})
+    public void testCursorUp(int y, String expected) {
+        assertAnsi(expected, new Ansi().cursorUp(y));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,ESC[2A", "-1,ESC[1A", "0,''", "1,ESC[1B", "2,ESC[2B"})
+    public void testCursorDown(int y, String expected) {
+        assertAnsi(expected, new Ansi().cursorDown(y));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,ESC[2D", "-1,ESC[1D", "0,''", "1,ESC[1C", "2,ESC[2C"})
+    public void testCursorRight(int x, String expected) {
+        assertAnsi(expected, new Ansi().cursorRight(x));
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,ESC[2C", "-1,ESC[1C", "0,''", "1,ESC[1D", "2,ESC[2D"})
+    public void testCursorLeft(int x, String expected) {
+        assertAnsi(expected, new Ansi().cursorLeft(x));
+    }
+
+    @ParameterizedTest
+    @CsvSource({
+        "-2,-2,ESC[2DESC[2A", "-2,-1,ESC[2DESC[1A", "-2,0,ESC[2D", "-2,1,ESC[2DESC[1B", "-2,2,ESC[2DESC[2B",
+        "-1,-2,ESC[1DESC[2A", "-1,-1,ESC[1DESC[1A", "-1,0,ESC[1D", "-1,1,ESC[1DESC[1B", "-1,2,ESC[1DESC[2B",
+        "0,-2,ESC[2A", "0,-1,ESC[1A", "0,0,''", "0,1,ESC[1B", "0,2,ESC[2B",
+        "1,-2,ESC[1CESC[2A", "1,-1,ESC[1CESC[1A", "1,0,ESC[1C", "1,1,ESC[1CESC[1B", "1,2,ESC[1CESC[2B",
+        "2,-2,ESC[2CESC[2A", "2,-1,ESC[2CESC[1A", "2,0,ESC[2C", "2,1,ESC[2CESC[1B", "2,2,ESC[2CESC[2B"
+    })
+    public void testCursorMove(int x, int y, String expected) {
+        assertAnsi(expected, new Ansi().cursorMove(x, y));
+    }
+
+    @Test
+    public void testCursorDownLine() {
+        assertAnsi("ESC[E", new Ansi().cursorDownLine());
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,ESC[2F", "-1,ESC[1F", "0,''", "1,ESC[1E", "2,ESC[2E"})
+    public void testCursorDownLine(int n, String expected) {
+        assertAnsi(expected, new Ansi().cursorDownLine(n));
+    }
+
+    @Test
+    public void testCursorUpLine() {
+        assertAnsi("ESC[F", new Ansi().cursorUpLine());
+    }
+
+    @ParameterizedTest
+    @CsvSource({"-2,ESC[2E", "-1,ESC[1E", "0,''", "1,ESC[1F", "2,ESC[2F"})
+    public void testCursorUpLine(int n, String expected) {
+        assertAnsi(expected, new Ansi().cursorUpLine(n));
+    }
+
+    private static void assertAnsi(String expected, Ansi actual) {
+        assertEquals(expected.replace("ESC", "\033"), actual.toString());
+    }
 }