ansi_modifier 0.1.4 ansi_modifier: ^0.1.4 copied to clipboard
Style strings for terminal output by adding, replacing, or removing ANSI modifiers. Provides support for moving the current cursor position.
Ansi Modifier #
Introduction #
The package provides the class Ansi
holding ANSI modifier codes and
the String extension methods style
and clearStyle
for adding, replacing, and removing ANSI modifiers.
It provides Ansi codes for changing the current cursor position.
Usage #
Include ansi_modifier
as a dependency
in your pubspec.yaml
file.
1. Changing the Font Style and Colour of Console Output #
Use the String extension function style
to add new modifiers or
to replace existing ones. Use the function clearStyle
to remove
all Ansi modifier from a string.
import 'package:ansi_modifier/src/ansi.dart';
void main(List<String> args) {
// Create colorized strings.
print('\nCreate colorized strings:');
final blue = 'blueberry'.style(Ansi.blue + Ansi.italic);
final green = 'green apple'.style(Ansi.green);
final blueGreen = blue +
' and ' +
green.style(
Ansi.bold,
method: Replace.none,
);
print('$blue, $green, $blueGreen');
// Modify a previously colorized string.
print('\nModify previously colorized strings:');
// Create custom Ansi modifier.
final customModifier = Ansi.combine({Ansi.yellow, Ansi.bold, Ansi.underline});
// Replace first modifier:
final yellowGreen = blueGreen.style(customModifier, method: Replace.first);
// Replace all modifiers.
final magenta =
yellowGreen.style(Ansi.magenta, method: Replace.clearPrevious);
// Strip all Ansi modifiers.
print('$yellowGreen, $magenta, ${magenta.clearStyle()}\n');
}
Runnig the program above produces the following output:
2. Moving the Current Cursor Position #
Ansi codes for moving the current cursor position can be constructed using the
constructors .cursorUp
, .cursorDown
,
.cursorForward
,
.cursorBack
,
.cursorNextLine
,
.cursorPreviousLine
, and
.cursorToColumn
.
The example below shows how to change the cursor position
using Dart's stdout
function write
in order to display a
progress indicator:
import 'dart:io';
import 'package:ansi_modifier/src/ansi.dart';
void main(List<String> args) async {
// Emit a periodic stream
final stream = Stream<String>.periodic(
const Duration(milliseconds: 500),
(i) =>
'Progress timer: '.style(Ansi.grey) +
((i * 500 / 1000).toString() + ' s').style(Ansi.green));
// Listen to the stream and output progress indicator
final subscription = stream.listen((event) {
// Place cursor to first column to overwrite previous string.
stdout.write(Ansi.cursorToColumn(1));
stdout.write(event);
});
/// Add delay ...
await Future.delayed(Duration(seconds: 5), () {
print('\n');
print('After 5 seconds.'.style(Ansi.green));
});
await subscription.cancel();
}
The program above produces the following console output:
Tips and Tricks #
-
The String extension method
style
supports different replacement modes that can be adjusted using the optional argumentmethod
. -
Ansi codes can be combined using the addition operator
Anis.red + Ansi.bold
, or by using the factory constructorAnsi.combine
. -
Ansi output can be globally disabled by setting
Ansi.status = AnsiOutput.disabled
or by using the option:$ dart --define=isMonochrome=true example/bin/color_example.dart
Features and bugs #
If some Ansi modifiers are missing please file an enhancement request at the issue tracker.