dart_console_plus

A Dart library for building console applications. This is a temporary OpenCI fork of dart_console, maintained in its own repository until the native terminal fixes below are available in an upstream release.

This library contains a variety of useful functions for console application development, including:

• Reading the current window dimensions (height, width)
• Reading and setting the cursor location
• Setting foreground and background colors
• Manipulating the console into "raw mode", which allows more advanced keyboard input processing than the default dart:io library.
• Reading keys and control sequences from the keyboard
• Writing aligned text to the screen
• Tabular data display, including month calendar

The library has been used to implement a Dart version of the Kilo text editor; when compiled with Dart it results in a self-contained kilo executable. The library is sufficient for a reasonably complete set of usage, including readline-style CLI and basic text games.

The library assumes a terminal that recognizes and implements common ANSI escape sequences. The package has been tested on macOS, Linux and Windows 10. Note that Windows did not support ANSI escape sequences in earlier versions.

The library uses the win32 package for accessing the Win32 API through FFI. That package contains many examples of using Dart FFI for more complex examples.

Origin and fixes

This fork is based on upstream dart_console 5.1.0 and includes:

• PR #15, commit 862e0af21ceffeb9939083217eef7f469e18ad52, by Masahiro Aoki: correct the variadic ioctl binding on macOS ARM64.
• PR #16, commit bc9caf9aee724056bf63c18850c3d1287279a92b, by Brett Sutton: build on PR #15 with platform-specific Linux/macOS termios layouts, safe raw-mode restoration, native allocation cleanup, and JIT/AOT regression tests.

The upstream BSD license and copyright notices are retained in LICENSE and source files. The full console API, examples, and tests are preserved; package imports use dart_console_plus.

Install

dart pub add dart_console_plus

Usage

A simple example for the dart_console_plus package:

import 'package:dart_console_plus/dart_console_plus.dart';

main() {
  final console = Console();

  console.clearScreen();
  console.resetCursorPosition();

  console.writeLine(
    'Console size is ${console.windowWidth} cols and ${console.windowHeight} rows.',
    TextAlignment.center,
  );

  console.writeLine();

  return 0;
}

More comprehensive demos of the Console class are provided, as follows:

Example	Description
demo.dart	Suite of test demos that showcase various capabilities
main.dart	Basic demo of how to get started with the dart_console_plus
keys.dart	Demonstrates how dart_console_plus processes control characters
readline.dart	Sample command-line interface / REPL
kilo.dart	Rudimentary text editor
life.dart	Game of Life
table.dart	Demonstrates tabular data display
calendar.dart	Prints a monthly calendar on the screen

Acknowledgements

Special thanks to Matt Sullivan (@mjohnsullivan) and Samir Jindel (@sjindel-google) for their help in explaining FFI to me when it was first introduced and still undocumented.

Thanks to @erf for contributing the Game of Life example.

Features and bugs

Please file feature requests and bugs at the issue tracker.