Buffer API

[Tyriar]

This exposes the primary parts of the buffer to APIs, see changes to xterm.d.ts for the actual public API. It works by having a "view" object in public/ that owns the actual object and exposes friendly aliases for the properties, for example viewportY instead of ydisp, cursorX over x, getLine over lines.get(x), etc.

The first usage of this will be moving the search addon into the new addon API #2065, built 100% on stable API! The buffer API is currently marked experimental to make sure it meets the needs of the search addon, we can remove experimental at or before v4 #2075

Fixes #1994

[jerch]

Very nice 👍 , just two concerns from my side.

[jerch]

@Tyriar
The way you currently create the BufferView by referencing is not "stable" for buffer lines between data updates of the terminal due to recycling and line movements. Not sure yet if thats a drawback/issue at all, still it means that every action from an addon will have to re-request the view to see the real terminal buffer state with the correct buffer line order.

I think this is not an issue if we clearly document that ppl should avoid holding refs to members on nonlocal scope (rule of thumb - no event loop in between), instead always refer to them by the full descent like terminal.buffer().getLine(y).getCell(x)..... If they really have to hold stuff, they will have to copy the parts over to some own container. Local refs are not affected by this, so doing this to avoid recreating the intermediate objects is perfectly doable:

function someFunc() {
    const line = terminal.buffer().getLine(y);
    // iterate over cells
    for (let x=0; 0 < line.length; ++x) {
        someAction(line.getCell(x));
    }
}

While this might lead to unexpected results:

function someFunc() {
    const line = terminal.buffer().getLine(y);
    // iterate over cells
    for (let x=0; 0 < line.length; ++x) {
        // by the time doSomethingWithCell is called
        // line does not point to buffer[y] anymore
        setTimeout(() => someAction(line.getCell(x)), timeout);
    }
}

The latter can be fixed like this (but leads to the intermediate object overhead):

function someFunc() {
    // iterate over cells
    for (let x=0; 0 < terminal.cols; ++x) {
        setTimeout(() => someAction(terminal.buffer().getLine(y).getCell(x)), timeout);
    }
}

[Tyriar]

@jerch I think this is fine if it's called out in the documentation as you mention, I'll add some more details to the jsdoc

Fixed