GitLocker: The Coding Marketplace

Description:

interact

Interact #
A collection of customizable interactive command-line components.

Table of Contents #

Overview
Installation
API Documentation

Components

Confirm Component
Input Component
Password Component
Select Component
MultiSelect Component
Sort Component
Spinner and MultiSpinner Components
Progress and MultiProgress Components

Customizing Themes
Handling Exceptions

Acknowledgement
License

Overview #
The library contains a bunch of command-line components that are easy to use and customizable, including text and password inputs, radio or select inputs, checkbox or multiple select inputs, spinners, and progress bars. Examples for all the available components can be found in the example folder, and the API Documentation section will cover all about them.
As an overview, you can make a Select component like this.
final languages = ['Rust', 'Dart', 'TypeScript'];
final selection = Select(
prompt: 'Your favorite programming language',
options: languages,
).interact();

print('${languages[selection]}');
copied to clipboard
It will result in something like this,

Installation #
Install the latest version of interact as a dependency as shown in pub.dev.

API Documentation #
Components #
These are the snippets of components with their properties and arguments. Check the pub documentation to get to know more about them in detail.

Confirm Component
A confirm component asks the user for a simple yes or no and will return a boolean accordingly.
final answer = Confirm(
prompt: 'Does it work?',
defaultValue: true, // this is optional
waitForNewLine: true, // optional and will be false by default
).interact();
copied to clipboard
If waitForNewLine is true, the prompt will wait for an Enter key from the user regardless of the answer.

Input Component
An input component asks the user for a string that could be validated.
final email = Input(
prompt: 'Your email',
defaultValue: '', // optional, will provide the user as a hint
initialText: '', // optional, will be autofilled in the input
validator: (String x) { // optional
if (x.contains('@')) {
return true;
} else {
throw ValidationError('Not a valid email');
}
},
).interact();
copied to clipboard
The message passed in the ValidationError exception will be shown as an error until the validator returns true.

Password Component
A password component behaves pretty much the same as an input component, but the user input will be hidden and by default, it has a repeat password validator that checks if two password inputs are the same or not.
final password = Password(
prompt: 'Password',
confirmation: true, // optional and will be false by default
confirmPrompt: 'Repeat password', // optional
confirmError: 'Passwords do not match' // optional
).interact();
copied to clipboard

Select Component
A select component asks the user to choose between the options supplied and the index of the chosen option will be returned.
final languages = ['Rust', 'Dart', 'TypeScript'];

final selection = Select(
prompt: 'Your favorite programming language',
options: languages,
initialIndex: 2, // optional, will be 0 by default
).interact();
copied to clipboard

MultiSelect Component
A multi-select component asks the user for multiple options check by using the SpaceBar. Similarly, the multi-select component will return a list of selected indexes.
final answers = MultiSelect(
prompt: 'Let me know your answers',
options: ['A', 'B', 'C'],
defaults: [false, true, false], // optional, will be all false by default
).interact();
copied to clipboard

Sort Component
A sort component asks the user to sort the given list of options and returns the list ordered by the user.
final sorted = Sort(
prompt: 'Sort Tesla models from favorite to least',
options: ['S', '3', 'X', 'Y'],
showOutput: false, // optional, will be false by default
).interact();
copied to clipboard
Sometimes the list given can be massive, so setting the showOutput to false makes the list not be shown in the success prompt.

Spinner and MultiSpinner Components
A spinner will show a spinning indicator until the user calls it's done method. When it's done, it shows the icon given in place of the spinner.
final gift = Spinner(
icon: '🏆',
leftPrompt: (done) => '', // prompts are optional
rightPrompt: (done) => done
? 'here is a trophy for being patient'
: 'searching a thing for you',
).interact();

await Future.delayed(const Duration(seconds: 5));
gift.done();
copied to clipboard
Using multiple spinners at once is a common practice, but because of the way the library renders things, it's not possible to have multiple them normally. It will break the rendering process of all components.
final spinners = MultiSpinner();

final horse = spinners.add(Spinner(
icon: '🐴',
rightPrompt: (done) => done ? 'finished' : 'waiting',
)); // notice how you don't need to call the `.interact()` function

await Future.delayed(const Duration(seconds: 5));
horse.done();
copied to clipboard
Now you can have multiple of them without breaking things.

Progress and MultiProgress Components
A progress component shows a progress bar.
final progress = Progress(
length: 1000, // required, the length of the progress to use
size: 0.5, // optional, will be 1 by default
rightPrompt: (current) => ' ${current.toString().padLeft(3)}/$length',
).interact();

for (var i = 0; i < 500; i++) {
await Future.delayed(const Duration(milliseconds: 5));
progress.increase(2);
}

progress.done();
copied to clipboard
The size is the multiplier for the rendered progress bar and it will be 1 by default. 0.5 means the rendered progress bar will be half the width of the terminal.
A MultiProgress does pretty much the same as what MultiSpinner did for spinners.
final bars = MultiProgress();

final p1 = bars.add(Progress(
length: 100,
rightPrompt: (current) => ' ${current.toString().padLeft(3)}/$length',
)); // notice how you don't need to call the `.interact()` function

for (var i = 0; i < 500; i++) {
await Future.delayed(const Duration(milliseconds: 5));
p1.increase(2);
}

p1.done();
copied to clipboard

Customizing Themes #
Because most of the visually rendered parts come from the theme object which is available for all components, you can customize a lot of them by changing the theme. Changing a theme for a component can be done by using the withTheme constructor.
final progress = Progress.withTheme(
theme: Theme(),
length: length,
rightPrompt: (current) => ' ${current.toString().padLeft(3)}/$length',
).interact();
copied to clipboard
The components used the Theme.defaultTheme as the theme by default. The Theme object has two premade themes,

Theme.colorfulTheme which is made with colorful ASCII/emojis
Theme.basicTheme which is mostly text characters and without colors

and the Theme.defaultTheme is the colorful theme by default.
Because constructing a theme from scrap requires you to write a lot of properties, it might be easier to extend existing themes to create a new one which can be done using the copyWith method.
import 'package:tint/tint.dart'; // for extension methods
// ...
Theme customTheme = Theme.colorfulTheme.copyWith(
activeItemPrefix: '👉'
activeItemStyle: (x) => x.yellow().underline(),
);
copied to clipboard
Technically, you can also override Theme.defaultTheme as a shortcut.
Handling Exceptions #
If your program throw exceptions and exit midway, interact's components won't be able to finish their tasks and gracefully quit therefore causing certain problems like cursors not showing up, terminal colors got modified etc. To fix these problems you should always try to catch exceptions and reset to terminal defaults using reset function.
try {
Spinner(icon: '🚨').interact();
throw Exception(); // spinner couldn't finished
} catch (e) {
reset(); // Reset everything to terminal defaults
rethrow;
}
copied to clipboard

Acknowledgement #
This library is mostly inspired by dialouger library from Rust. The lack of a properly maintained library for Dart with a well-made API is what pushed me into making this library.