[Console] Add Cursor class to control the cursor in the terminal

[pierredup]

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	N/A
License	MIT
Doc PR	TBD

Add a new Cursor class to the Console component, that allows to manipulate the cursor in the terminal.

Options to move the cursor include: moveUp, moveDown, moveLeft, moveRight, show, hide, save and restore position, get current position etc.

Example usage:

$cursor = new Cursor($output);

$parts = [
    ['x' => 9, 'y' => 5, 'string' => '#'],
    ['x' => 9, 'y' => 7, 'string' => '#'],
    ['x' => 2, 'y' => 7, 'string' => '#####'],
    ['x' => 9, 'y' => 1, 'string' => '#######'],
    ['x' => 7, 'y' => 6, 'string' => '#'],
    ['x' => 9, 'y' => 2, 'string' => '#'],
    ['x' => 9, 'y' => 6, 'string' => '#'],
    ['x' => 9, 'y' => 3, 'string' => '#'],
    ['x' => 2, 'y' => 1, 'string' => '#####'],
    ['x' => 7, 'y' => 2, 'string' => '#'],
    ['x' => 9, 'y' => 4, 'string' => '#####'],
    ['x' => 1, 'y' => 2, 'string' => '#'],
    ['x' => 1, 'y' => 6, 'string' => '#'],
    ['x' => 2, 'y' => 4, 'string' => '#####'],
    ['x' => 1, 'y' => 3, 'string' => '#'],
    ['x' => 7, 'y' => 5, 'string' => '#'],
];

foreach ($parts as $part) {
    $cursor->moveToPosition($part['x'], $part['y']);
    $output->write($part['string']);

    usleep(200000);
}

$cursor->moveToPosition(1, 8);

Result:

[javiereguiluz]

For reference purposes, I've look for the APIs for this feature in other projects:

1. Go libraries and .Net libraries have just a few methods:

https://godoc.org/github.com/nsf/termbox-go

func HideCursor()
func SetCursor(x, y int)

https://godoc.org/github.com/gdamore/tcell

func HideCursor()
func ShowCursor(x int, y int)

.Net (https://msdn.microsoft.com/en-us/library/system.console_methods(v=vs.110).aspx)

SetCursorPosition(Int32, Int32)

And some properties:

CursorLeft
CursorTop
CursorVisible
...

2. On the other hand, JS libraries define a ton of methods:

https://github.com/cronvel/terminal-kit/blob/master/doc/low-level.md#ref.movingCursor

.saveCursor()
.restoreCursor()
.up(int n)
.down(int n)
.right(int n)
.left(int n)
.nextLine(int n)
.previousLine(int n)
.column(int x)
.scrollUp(int n)
.scrollDown(int n)
.scrollingRegion(top, bottom)
.resetScrollingRegion()
.moveTo(int x, int y)
.move(int x, int y)
.hideCursor()
.tabSet()
.tabClear()
.tabClearAll()
.forwardTab(int n)
.backwardTab(int n)

---

So we need to think if we want a simple (but enough) API or a complex (but useful) API.

[ogizanagi]

Also see the HOA Project Console Cursor API: https://github.com/hoaproject/Console#cursor

[yceruto]

Thanks for this feature! I left two minor comments.

[nicolas-grekas]

@pierredup see test failures :) Also, any comment when comparing the proposed API with the linked ones? Do any of them provide any idea to borrow?

[pierredup]

I prefer having a few explicit methods (E.G moveUp, moveDown) instead of just a couple generic methods, so I would much rather go the route of the JS libraries (although not as many methods as they have).

[chalasr]

Can we update QuestionHelper to make it use this for autocompletion?
I'm fine with the current naming.

[pierredup]

Can we update QuestionHelper to make it use this for autocompletion?

@chalasr Done

[chalasr]

Can you add a CHANGELOG entry and rebase to see tests green?

[chalasr]

Does it really belong to the cursor?

[fabpot]

LGTM.

Can we also have methods to get the max x and max y of the console/cursor? I think we already have the code in Symfony, that would be good to have it here as well.

Maybe we can simplify the progress bar code as well.

[pierredup]

I've rebased from master, and updated the Progress bar to use the Cursor class as well.

Can we also have methods to get the max x and max y of the console

This is currently available in the Terminal class for this component, so I'm not sure if it should be in the Cursor class as well

[chalasr]

Agree about keeping the terminal size logic in the Terminal class.
@pierredup Some related tests are failing, can you have a look?

[chalasr]

LGTM :) Missing CHANGELOG entry

[fabpot]

Thanks @pierredup for working on this feature, this is much appreciated.