Module trial.arsd.terminal

Note

on Posix, it traps SIGINT and translates it into an input event. You should keep your event loop moving and keep an eye open for this to exit cleanly; simply break your event loop upon receiving a UserInterruptionEvent. (Without the signal handler, ctrl+c can leave your terminal in a bizarre state.)

As a user, if you have to forcibly kill your program and the event doesn't work, there's still ctrl+\

On old Mac Terminal btw, a lot of hacks are needed and mouse support doesn't work on older versions. Most functions work now with newer Mac OS versions though.

Future Roadmap

* The CharacterEvent and NonCharacterKeyEvent types will be removed. Instead, use KeyboardEvent on new programs. * The ScrollbackBuffer will be expanded to be easier to use to partition your screen. It might even handle input events of some sort. Its API may change. * getline I want to be really easy to use both for code and end users. It will need multi-line support eventually. * I might add an expandable event loop and base level widget classes. This may be Linux-specific in places and may overlap with similar functionality in simpledisplay.d. If I can pull it off without a third module, I want them to be compatible with each other too so the two modules can be combined easily. (Currently, they are both compatible with my eventloop.d and can be easily combined through it, but that is a third module.) * More advanced terminal features as functions, where available, like cursor changing and full-color functions. * More documentation.

WHAT I WON'T DO: * support everything under the sun. If it isn't default-installed on an OS I or significant number of other people might actually use, and isn't written by me, I don't really care about it. This means the only supported terminals are: * xterm (and decently xterm compatible emulators like Konsole) * Windows console * rxvt (to a lesser extent) * Linux console * My terminal emulator family of applications https://github.com/adamdruppe/terminal-emulator Anything else is cool if it does work, but I don't want to go out of my way for it. * Use other libraries, unless strictly optional. terminal.d is a stand-alone module by default and always will be. * Do a full TUI widget set. I might do some basics and lay a little groundwork, but a full TUI is outside the scope of this module (unless I can do it really small.)

History

On December 29, 2020 the structs and their destructors got more protection against in-GC finalization errors and duplicate executions.

This should not affect your code.

Example

Get Line

This example will demonstrate the high-level [Terminal.getline] interface.

The user will be able to type a line and navigate around it with cursor keys and even the mouse on some systems, as well as perform editing as they expect (e.g. the backspace and delete keys work normally) until they press enter. Then, the final line will be returned to your program, which the example will simply print back to the user.

import trial.arsd.terminal;

void main() {
	auto terminal = Terminal(ConsoleOutputType.linear);
	string line = terminal.getline();
	terminal.writeln("You wrote: ", line);

	// new on October 11, 2021: you can change the echo char
	// for password masking now. Also pass `0` there to get unix-style
	// total silence.
	string pwd = terminal.getline("Password: ", '*');
	terminal.writeln("Your password is: ", pwd);
}

version(demos) main; // exclude from docs

Example

Color

This example demonstrates color output, using [Terminal.color] and the output functions like [Terminal.writeln].

import trial.arsd.terminal;

void main() {
	auto terminal = Terminal(ConsoleOutputType.linear);
	terminal.color(Color.green, Color.black);
	terminal.writeln("Hello world, in green on black!");
	terminal.color(Color.DEFAULT, Color.DEFAULT);
	terminal.writeln("And back to normal.");
}

version(demos) main; // exclude from docs

Example

Single Key

This shows how to get one single character press using the [RealTimeConsoleInput] structure. The return value is normally a character, but can also be a member of [KeyboardEvent.Key] for certain keys on the keyboard such as arrow keys.

For more advanced cases, you might consider looping on [RealTimeConsoleInput.nextEvent] which gives you full events including paste events, mouse activity, resizes, and more.

See Also

[KeyboardEvent], [KeyboardEvent.Key], [kbhit]

import trial.arsd.terminal;

void main() {
	auto terminal = Terminal(ConsoleOutputType.linear);
	auto input = RealTimeConsoleInput(&terminal, ConsoleInputFlags.raw);

	terminal.writeln("Press any key to continue...");
	auto ch = input.getch();
	terminal.writeln("You pressed ", ch);
}

version(demos) main; // exclude from docs

Example

ditto

import trial.arsd.terminal;

void main() {
	auto terminal = Terminal(ConsoleOutputType.linear);
	auto rtti = RealTimeConsoleInput(&terminal, ConsoleInputFlags.raw);
	loop: while(true) {
		switch(rtti.getch()) {
			case 'q': // other characters work as chars in the switch
				break loop;
			case KeyboardEvent.Key.F1: // also f-keys via that enum
				terminal.writeln("You pressed F1!");
			break;
			case KeyboardEvent.Key.LeftArrow: // arrow keys, etc.
				terminal.writeln("left");
			break;
			case KeyboardEvent.Key.RightArrow:
				terminal.writeln("right");
			break;
			default: {}
		}
	}
}

version(demos) main; // exclude from docs

Example

Full screen

This shows how to use the cellular (full screen) mode and pass terminal to functions.

import trial.arsd.terminal;

// passing terminals must be done by ref or by pointer
void helper(Terminal* terminal) {
	terminal.moveTo(0, 1);
	terminal.getline("Press enter to exit...");
}

void main() {
	// ask for cellular mode, it will go full screen
	auto terminal = Terminal(ConsoleOutputType.cellular);

	// it is automatically cleared upon entry
	terminal.write("Hello upper left corner");

	// pass it by pointer to other functions
	helper(&terminal);

	// since at the end of main, Terminal's destructor
	// resets the terminal to how it was before for the
	// user
}