cli_dialog 0.2.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 53

cli_dialog #

Build Status

A Dart package which allows you to use Inquirer.js prompts with some additional features.

This package does not have any direct dependencies. The following GIF shows a CLI dialog which was created using this library. You can also visit the library page on pub.dev.

Demo of cli_dialog

You can find the source for this example here

Usage #

Basic Usage #

import 'package:cli_dialog/cli_dialog.dart';

void main() {
  final dialog = CLI_Dialog(questions: [
    ['What is your name?', 'name']
  ]);
  final name = dialog.ask()['name'];
}

Whenever you want to create a CLI dialog you create a CLI_Dialog() instance.

The CLI_Dialog class supports multiple keyword arguments amongst which questions is the most basic one. questions is a list of questions and corresponding keys to retreive the answers.

Thus, each list entry for questions has the following syntax: [<question>, <key<].

Then you will want to call the ask() method. It performs the CLI dialog and returns a map with the keys you provided and the values it received from the user.

Boolean questions #

import 'package:cli_dialog/cli_dialog.dart';

void main() {
  final dialog = CLI_Dialog(booleanQuestions: [
    ['Are you happy with this package?', 'isHappy']
  ]);
  final answer = dialog.ask()['isHappy'];
}

As the name suggests, boolean questions just asks the user for (y/N) answers and always returns bool values.

The N in (y/N) indicates that the default answer is no. You can change this by passing trueByDefault: true to the constructor.

List questions #

import 'package:cli_dialog/cli_dialog.dart';

void main() {
  const listQuestions = [
    [
      {
        'question': 'What is your favourite colour?',
        'options': ['Red', 'Blue', 'Green']
      },
      'colour'
    ]
  ];

  final dialog = CLI_Dialog(listQuestions: listQuestions);
  final answer = dialog.ask();
  final colour = answer['colour'];
}

List questions allow the user to make a selection amongst several strings. 'question' is the question that will be printed before the selection. 'options' are the options from which the user chooses exactly one. 'colour' is the key used to retreive the answer.

Messages #

Messages were added in 0.2.0. They are used to display information to users without prompting them for an answer.

You can use them like any other question using the messages keyword parameter or addQuestion(message, is_message: true). It is only optional to include a key if you are not using order.

Order #

import 'package:cli_dialog/cli_dialog.dart';

void main() {
  const listQuestions = [
    [
      {
        'question': 'Where are you from?',
        'options': ['Africa', 'Asia', 'Europe', 'North America', 'South Africa']
      },
      'origin'
    ]
  ];

  const booleanQuestions = [
    ['Do you want to continue?', 'continue']
  ];

  final dialog = CLI_Dialog(
      booleanQuestions: booleanQuestions,
      listQuestions: listQuestions,
      order: ['origin', 'continue']);

  dialog.ask();
}

The optional keyword parameter order for the constructor allows you to set a custom order for your questions in the dialog by passing a list with keys in your required order.

If you do not indicate any order then the standard order is applied:

  1. All messages are displayed to the user.
  2. All regular questions.
  3. All boolean questions.
  4. All list questions.

We used the order parameter in this example because otherwise the question 'Do you want to continue' would be asked before 'Where are you from?' according to standard order.

Navigation mode was added in 0.2.0. It allows users to freely navigate through the prompt and repeadetly answer questions if the want to. For the developer it is a matter of setting navigationMode to true:

final dialog = CLI_Dialog(navigationMode: true);

In navigation mode, each question is prepended by an index which shows the user which question he currently answers. The user can then prepend a colon to his answer and use these indices to jump to another question, even those he has not answered yet. For instance, answering :2 makes the user jump to the second question. After answering it, the user will be prompted with the third question (again) etc. Entering a question number which is out of scope finishes the CLI_Dialog and makes it return the answer map.

Testing #

This package also provides a small infrastructure for testing your dialogs.

For this purpose, there is the named constructor CLI_Dialog.std() which has two required arguments:

  • std_input = a StdinService
  • std_output = a StdoutService

StdinService and StdoutService are classes which are provided with this library. There are always used internally for i/o. If you explicitly use these classes then you will probably want to set the mock parameter to true which will make these services mock objects.

Furtermore, it is mostly advised to pass std_output to std_input using the informStdout and isTest parameter to inform the StdoutService about standard input in echo mode. Details can be checked out in the tests I have written (test/).

How it works #

This library uses ANSI/XTerm escape sequences and regular escape sequences. You can take a look at them in this file

Contributing #

Of course you are welcome to contribute to this project by issuing a pull request on Github.

Please write unit tests (test/) for new functionality and make sure that test.sh and lint.sh (tool/) run succesfully before submitting.

Please format your code using dartfmt -w . (this is also covered by lint.sh).

Windows #

cli_dialog supports Windows. However, there are some minor caveats:

  • You have to use 'W' and 'S' keys to navigate instead of arrow up and arrow down
  • Colors look a bit different in command prompt
  • The UTF-16 right indicator is replaced by a simple >

Acknowledgements and Alternatives #

This library is more a less a Dart port of Inquirer.js.

There is dart_inquirer which is not developed any more (even the Github repository was deleted by the author). It works fine but it has less features than this package (no colors, no navigation, no resume, no question mark etc.).

  • 0.0.1: Initial version (experimental).
  • 0.1.0: Bump to 0.1.0 to increase score.
  • 0.1.1: Small health improvement.
  • 0.1.2: Compatible update to the addQuestion(s) methods and add documentation.
  • 0.1.3: Finish documentation for API reference.
  • 0.1.4: Add support for Windows (with caveats).
  • 0.1.5: Fix addQuestion() and create example for it. Fix tests and enable Travis CI for Windows.
  • 0.2.0: Add navigation mode and messages.

example/lib/main.dart

import 'package:cli_dialog/cli_dialog.dart';

dynamic runExample([stdin_service, stdout_service]) {
  if (stdin_service == null) {
    stdin_service = StdinService();
  }
  if (stdout_service == null) {
    stdout_service = StdoutService();
  }

  const questions = [
    ['What name would you like to use for the project?', 'project_name']
  ];
  const booleanQuestions = [
    ['Would you like to add AngularDart routing?', 'routing']
  ];

  const listQuestions = [
    [
      {
        'question': 'Which stylesheet format would you like to use?',
        'options': [
          'CSS',
          'SCSS   [ https://sass-lang.com/documentation/syntax#scss                ]',
          'Sass   [ https://sass-lang.com/documentation/syntax#the-indented-syntax ]',
          'Less   [ http://lesscss.org                                             ]',
          'Stylus [ http://stylus-lang.com                                         ]'
        ]
      },
      'stylesheet'
    ]
  ];

  CLI_Dialog dialog = CLI_Dialog.std(stdin_service, stdout_service,
      questions: questions,
      booleanQuestions: booleanQuestions,
      listQuestions: listQuestions);

  return dialog.ask();
}

String report(answers, {do_print: true}) {
  var output = StringBuffer();
  output.writeln('');
  output.writeln('Your project name is ${answers["project_name"]}.');
  output.writeln(
      'You ' + (answers['routing'] ? '' : 'do not ') + 'want to use routing.');
  output.writeln(
      'Your preferred stylesheet format is ${answers["stylesheet"].split(' ')[0]}.');
  if (do_print) {
    print(output);
  }
  return output.toString();
}

void main() {
  report(runExample());
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  cli_dialog: ^0.2.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:cli_dialog/cli_dialog.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
7
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
53
Learn more about scoring.

We analyzed this package on Jul 14, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.15

Analysis suggestions

Package not compatible with runtime flutter-web on Web

Because:

  • package:cli_dialog/cli_dialog.dart that imports:
  • package:cli_dialog/src/xterm.dart that imports:
  • dart:io

Package not compatible with runtime js

Because:

  • package:cli_dialog/cli_dialog.dart that imports:
  • package:cli_dialog/src/xterm.dart that imports:
  • dart:io

Health suggestions

Fix lib/src/dialog.dart. (-0.50 points)

Analysis of lib/src/dialog.dart reported 1 hint:

line 264 col 7: DO use curly braces for all flow control structures.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.3.0 <3.0.0
Dev dependencies
example
test ^1.14.2