Support alternative terminal screens

[chshersh]

Most common terminal simulators support alternative terminal screens:

• https://terminalguide.namepad.de/mode/p47/

However, I haven't found any functions in ansi-terminal to support this. Here is a simple Haskell script that uses this feature:

#!/usr/bin/env cabal
{- cabal:
build-depends:
  , base ^>= 4.16
-}

{-# LANGUAGE NumericUnderscores #-}
{-# LANGUAGE ScopedTypeVariables #-}

module Main where

import Control.Concurrent
import Data.Foldable

main :: IO ()
main = do
    putStrLn "\ESC[?1049h\ESC[H"

    for_ [1 .. 5] $ \(i :: Int) -> do
        putStrLn $ "Going back in: " <> show i
        threadDelay 1_000_000

    putStrLn "\ESC[?1049l"

Would it be possible to introduce functions like enterAlternativeScreen and leaveAlternativeScreen in ansi-terminal?

[mpilgrem]

As ansi-terminal aims to be cross-platform, it tends to support things that might be classified as the 'common ground' on the most popular terminals for Linux, macOS and Windows. That does not rule out other features, but it does mean that, if they are added, the Haddock documentation should aim to help users understand the limitations.

The website you refer to above covers Linux and Windows supports these codes (https://learn.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences#alternate-screen-buffer). Do you know if the native terminal on macOS (Terminal) supports them?

[Bodigrim]

These are known as smcup (switch to the alternative buffer) and rmcup (switch back) capabilities. On UNIX systems escape codes for a local terminal can be queried from terminfo database: from ghci

> import System.Console.Terminfo
> t <- setupTermFromEnv
> getCapability t (tiGetOutput1 "smcup") :: Maybe String
Just "\ESC7\ESC[?47h"
> getCapability t (tiGetOutput1 "rmcup") :: Maybe String
Just "\ESC[2J\ESC[?47l\ESC8"

or alternatively from bash:

~$ echo "$(tput smcup)" | cat -e
^[7^[[?47h$
~$ echo "$(tput rmcup)" | cat -e
^[[2J^[[?47l^[8$

[Bodigrim]

I'm not sure which code is more portable, 47 or 1049. infocmp says

$ infocmp xterm-color | grep mcup
	ri=\EM, rmacs=^O, rmcup=\E[2J\E[?47l\E8, rmir=\E[4l,
	smcup=\E7\E[?47h, smir=\E[4h, smkx=\E[?1h\E=, smso=\E[7m,
$ infocmp xterm | grep mcup
	rin=\E[%p1%dT, rmacs=\E(B, rmam=\E[?7l, rmcup=\E[?1049l,
	sgr0=\E(B\E[m, smacs=\E(0, smam=\E[?7h, smcup=\E[?1049h,

[mpilgrem]

As Windows' documentation suggests it implements 1 0 4 9, and not 4 7, I would likely implement the former. I am also hoping that when Microsoft decided to look to XTerm, it made sensible choices... EDIT: the XTerm documentation describes 1 0 4 9 as 'newer'.

[Bodigrim]

Do you know if the native terminal on macOS (Terminal) supports them?

I can confirm that code 1049 works with Terminal.app and iTerm.app on macOS.

[mpilgrem]

On naming, XTerm (the origin of these codes, I think) describes the functions as use Alternative Screen Buffer and use Normal Screen Buffer. ansi-terminal does not shy away from long function names. How about useAlternativeScreenBuffer and useNormalScreenBuffer?

[mpilgrem]

@chshersh, @Bodigrim, I'm happy for these to be implemented and happy to implement them - but may not get to that before the coming weekend.

[chshersh]

I don't have capacity to work on this issue at the moment but I'm interested in having this feature in the library so if this issue is not resolved in the future, I'll try to work on it at some point.

I personally okay with long names for the functions 👌🏻 In my vision, the name useNormalScreenBuffer implies that the function is idempotent and it's okay to call it multiple times without worrying about entering an invalid state in the system. I'm not sure if this is true here but it might be so in that case the name is fine 🙂

[mpilgrem]

I've made a pull request that adds this. I was mistaken, in that XTerm actually calls it use Alternate Screen Buffer - so useAlternateScreenBuffer. Be aware that useNormalScreenBuffer always restores the saved cursor position. So, if you use it, move the cursor, and use it again, the cursor will be back where it was when you first used it.