Implement and action for manually clearing the Terminal (and conpty) buffer

[zadjii-msft]

Summary of the Pull Request

This adds a new action, clearBuffer. It accepts 3 values for the clear type:

• "clear": "screen": Clear the terminal viewport content. Leaves the scrollback untouched. Moves the cursor row to the top of the viewport (unmodified).
• "clear": "scrollback": Clear the scrollback. Leaves the viewport untouched.
• "clear": "all": (default) Clear the scrollback and the visible viewport. Moves the cursor row to the top of the viewport (unmodified).

"Clear Buffer" has also been added to defaults.json.

References

• From "Terminal: Clear" not working as desired vscode#75141 originally

PR Checklist

• Closes Support manually clearing the conpty buffer #1193
• Closes Add a terminal-side shortcut for clearing the screen and/or scrollback #1882
• I work here
• Tests added/passed
• Requires documentation to be updated

Detailed Description of the Pull Request / Additional comments

This is a bit tricky, because we need to plumb it all the way through conpty to clear the buffer. If we don't, then conpty will immediately just redraw the screen. So this sends a signal to the attached conpty, and then waits for conpty to draw the updated, cleared, screen back to us.

Validation Steps Performed

• works for each of the three clear types as expected
• tests pass.
• works even with ping -t 8.8.8.8 as you'd hope.

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• emptry
• tpye

Previously acknowledged words that are now absent

SPACEBAR Unregister

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the git@github.com:microsoft/terminal.git repository
on the dev/migrie/fhl-2021/clear-buffer-action branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect/alphabet.txt
.github/actions/spelling/expect/expect.txt
.github/actions/spelling/expect/web.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect/d465a47bc5bdd6eca2620a67144d139226d1d617.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/microsoft/terminal/issues/comments/897625511" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

✏️ Contributor please read this

By default the command suggestion will generate a file named based on your commit. That's generally ok as long as you add the file to your commit. Someone can reorganize it later.

⚠️ The command is written for posix shells. You can copy the contents of each perl command excluding the outer ' marks and dropping any '"/"' quotation mark pairs into a file and then run perl file.pl from the root of the repository to run the code. Alternatively, you can manually insert the items...

If the listed items are:

• ... misspelled, then please correct them instead of using the command.
• ... names, please add them to .github/actions/spelling/allow/names.txt.
• ... APIs, you can add them to a file in .github/actions/spelling/allow/.
• ... just things you're using, please add them to an appropriate file in .github/actions/spelling/expect/.
• ... tokens you only need in one place and shouldn't generally be used, you can add an item in an appropriate file in .github/actions/spelling/patterns/.

See the README.md in each directory for more information.

🔬 You can test your commits without appending to a PR by creating a new branch with that extra change and pushing it to your fork. The check-spelling action will run in response to your push -- it doesn't require an open pull request. By using such a branch, you can limit the number of typos your peers see you make. 😉

🗜️ If you see a bunch of garbage

If it relates to a ...

well-formed pattern

See if there's a pattern that would match it.

If not, try writing one and adding it to a patterns/{file}.txt.

Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

Note that patterns can't match multiline strings.

binary-ish string

Please add a file path to the excludes.txt file instead of just accepting the garbage.

File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).

[carlos-zamora]

Pretty confident with the Terminal stuff (except maybe TermConnection). The rest looks good too, but I'm a lot less familiar with that area.

[carlos-zamora]

Suggested change

	{ "command": { "action": "clearBuffer", "clear": "all" } },
	{ "command": { "action": "clearBuffer", "clear": "all" } },
	{ "command": { "action": "clearBuffer", "clear": "screen" } },
	{ "command": { "action": "clearBuffer", "clear": "scrollback" } },

Should we just go ahead and add all three to the command palette? It's filterable anyways. It also has the added benefit of allowing you to bind it to a key chord via SUI (because actions w/ args are not supported unless they've already been defined).

[carlos-zamora]

Suggested change

	short delta = (sNewTop + _viewport.Height()) - (GetBufferSize().Height());
	const short delta = (sNewTop + _viewport.Height()) - (GetBufferSize().Height());

[carlos-zamora]

Suggested change

	auto fillPosition = COORD{ 0, _viewport.Top() + 1 };
	auto fillLength = gsl::narrow_cast<size_t>(_viewport.Height() * GetBufferSize().Width());
	auto fillData = OutputCellIterator{ fillAttributes, fillLength };
	const auto fillPosition = COORD{ 0, _viewport.Top() + 1 };
	const auto fillLength = gsl::narrow_cast<size_t>(_viewport.Height() * GetBufferSize().Width());
	const auto fillData = OutputCellIterator{ fillAttributes, fillLength };

Not sure if these can be const, but if they can, there ya go.

[miniksa]

Okay, gonna approve. It is what it is.

I don't really like that we have to add another signal. Signaling to do the equivalent of SIGWNCH is well known and is what 8 is for, but this clear thing seems like a new invention which I'm not totally happy with. However... it's a problem that Windows sort of ends up with thanks to our weird architecture so I guess having our own solution is what's in order. Also it's just code so if we're proven wrong, we can just change it.

I want it to be like a VT signal on one of the existing channels, but on the input channel it makes no sense. And to get to the output channel, the alternative of making the Windows Terminal take a client-side reference to the same console as the client-app hosted in the ConPTY just to call clear seems ridiculous.

I think this is going to become less relevant over time as we approach passthrough mode where ConPTY will be less integral to the rendering on the Windows Terminal. But for now... the code must flow.

[ghost]

Hello @zadjii-msft!

Because this pull request has the AutoMerge label, I will be glad to assist with helping to merge this pull request once all check-in policies pass.

p.s. you can customize the way I help with merging this pull request, such as holding this pull request until a specific person approves. Simply @mention me (@msftbot) and give me an instruction to get started! Learn more here.

[ghost]

🎉Windows Terminal Preview v1.12.2922.0 has been released which incorporates this pull request.:tada:

Handy links:

• Release Notes
• Store Download