dcli
Search…
Displaying information
DCli provides a number of methods to display information to a user:

print

Dart provides the built in function 'print' which prints a line of text including a new line.
1
print('hello world');
Copied!

printerr

The standard Dart 'print' function prints to stdout, DCli's 'printerr' function is identical except that it prints to stderr.
1
printerr('something bad happened.');
Copied!
You should use printerr when you are printing error messages.

echo

The echo function is provided to supplement the Dart print method. The 'echo' allows you to control whether a new line is output after the text. By default echo will NOT output a newline.
1
echo('hello', newline: false);
Copied!

Colour coding

DCli allows you colour code your text output.
1
print(orange('hello world'));
Copied!
You can also control the background colour:
1
print(orange('hello world', background: AnsiColor.white));
Copied!
The following colours are supported for both the foreground (text) and background colours.
  • red
  • black
  • green
  • blue
  • yellow
  • magenta
  • cyan
  • white
  • orange
  • grey
By default the bold attribute is attached to each of the above builtin colours. You can suppress the bold attribute:
1
print(red('a dark message', bold: false));
Copied!

Format().row

This method is considered experimental. Use at your own peril.
The row method allows you to output a row of fixed with columns width controlled alignment.
1
print(Format().row(['OS Version', '${Platform.operatingSystemVersion}'],
2
widths: [17, -1]));
Copied!
Outputs a row with two columns. The first is 17 characters wide, the second expands as needed.
1
print(Format().row([
2
'$label',
3
'${fstat.modeString()}',
4
'<user>:${(owner.group == owner.user ? '<user>' : owner.group)}',
5
'${privatePath(path)} '
6
], widths: [
7
17,
8
9,
9
16,
10
-1
11
], alignments: [
12
TableAlignment.left,
13
TableAlignment.left,
14
TableAlignment.middle,
15
TableAlignment.left
16
]));
Copied!
Outputs a row with four columns of widths 17, 9, 16 and infinite. The columns are aligned, left, right, middle and left.

Terminal

The Terminal class allows you to control an ANSI terminal.
Row and Column positions are zero based.
The Terminal class is a singleton.
Most of the terminal methods will not work if stdin is not attached to a terminal (e.g the script is running in the background).
You can detect if a terminal is attached by calling Terminal().hasTerminal.
The methods will also not work if the terminal doesn't support Ansi escape sequences. You can check for Ansi support by calling Ansi.isSupported.
We try to be a little clever by suppressing ansi escape chacters if a terminal isn't detected or ansi isn't supported. I should note that the underlying detection methods are not 100% reliable.

clearScreen

Clears the console.
1
Terminal().clearScreen();
Copied!
The clearScreen method takes an optional named argument 'mode'. By default mode is TerminalClearMode.all.
The available modes are:
1
all - clears the entire screen.
2
fromCursor - clears the screen from the current cursor location.
3
toCursor - clears the screen from the start to the cursor location.
Copied!

clearLinelears the current line.

1
Terminal().clearLine();
Copied!

startOfLine()

Moves the cursor to the start of the current line.
1
Terminal().startOfLine();
Copied!

cursorUp()

Moves the cursor up a row.
1
Terminal().cursorUp();
Copied!

cursorDown()

Moves the cursor down a row.
Terminal().cursorDown();

cursorLeft()

Moves the cursor one character to the left.
Terminal().cursorLeft()

cursorRight()

Moves the cursor one character to the right.
1
Terminal().cursorRight();
Copied!

column

The column property acts as both a getter and a setter.
The column position is zero based.
Retrieve the current column position:
final current = Terminal().column;
Set the current column position:
Terminal().column = 10;

columns

Return the width of the terminal in columns. As the user can resize the terminal this value may change over time.
1
Terminal().columns;
Copied!

hasTerminal

Returns true if the terminal is attached to stdin. Most of the functions in this class will not work as expected if your app is not attached to stdin.
The cursor actions are all suppressed if you are not attached or if the terminal doesnt' support Ansi characters.

home

Sets the cursor to the top left corner of the screen (0,0)
1
Terminal().home;
Copied!

void overwriteLine(String text)

Replaces the text on the current line with the passed [text].
Terminal().overwriteLine('Hello World');

row

The row property acts as both a getter and a setter.
The row position is zero based.
Retrieve the current row position:
final current = Terminal().row;
Set the current row position:
Terminal().row = 10;

rows

The height of the terminal in rows.
Where a row is one character high.
If no terminal is attached to stdout, a [StdoutException] is thrown.
This value can change if the users resizes the console window.
1
Terminal().rows;
Copied!

showCursor

Shows or hides the cursor.
1
Terminal().showCursor(show: true);
Copied!

write

Write text to the terminal at the current row/column position.
1
Terminal().write('Hi there');
Copied!

writeLine

Writes [text] to the console followed by a newline.
u can control the alignment of [text] by passing the optional [alignment] argument which defaults to left alignment.
The alignment is based on the current terminals width with spaces inserted to the left of the string to facilitate the alignment.
Make certain the current line is clear and the cursor is at column 0 before calling this method otherwise the alignment will not work as expected.
1
Terminal().write('Hi there', alignment: TextAlignment.right);
Copied!