interactive 1.3.0

REPL (interactive shell) for Dart, supporting 3rd party packages, hot reload, and full grammar

dart_interactive

A lot of sibling languages have a REPL, and is quite helpful in everyday usage, while Dart did not have it (even though it was the 7th highest-voted request). So here it comes!

🚀 Features

A full-featured REPL (interactive shell), with:

• Use any third-party package freely
• Auto hot-reload code anywhere, with state preserved
• Supports full grammar in REPL
• Play with existing code side-by-side

📚 Demo

Demo 1: Demonstrate features

1. Use 3rd party package

>>> !dart pub add path // normal shell command
>>> import 'package:path/path.dart'; // normal import
>>> join('directory', 'file.txt') // use it (`join` is a function in 3rd party package `path`)
directory/file.txt

2. Auto hot-reload

>>> import 'a.dart';
>>> myFunc()
hello, tom
// ... change content of `a.dart` ...
>>> myFunc()
hello, alex

3. Support full grammar

>>> a = 10;
// support rich grammar
>>> int g() => a++; class A {} class B {}
... class C extends A implements B {
...   int b = 20;
...   int f() { int c = 30; a++; b++; c++; return a+b+c+g(); }
... }
>>> c = C()
>>> c.f()
74
// support redefine class/method/...
>>> class C extends A implements B { int b = 20; int f() => b; }
>>> c.f()
21

Demo 2: Sample workflow

Surely, you do not have to use it like this. It is just a workflow that I personally feel comfortable when working with IPython/Juypter.

Suppose we have my_app.dart with some code, probably edited inside an IDE:

class Counter {
  int count = 0;
  String greet() => 'Hi Tom, you have count $count!';
}

Play with it a bit:

$ interactive --directory path/to/my/package
>>> import 'my_app.dart';
>>> counter = Counter();
>>> counter.count = 10;
>>> counter.greet()
Hi Tom, you have count 10!
>>> counter.count = 20;
>>> counter.greet()
Hi Tom, you have count 20!

Then we realize something wrong and want to change it:

(change "Tom" to "Alex" inside `my_app.dart`)

Continue playing with it (auto hot reloaded, and state preserved):

>>> counter.greet()
Hi Alex, you have count 20!

We can also use all dependencies in the package as well, since the REPL code is just like a normal code file in this package.

>>> import 'package:whatever_package';
>>> functionInWhateverPackage();

🎼 Getting started

Install (just standard procedure of installing global dart packages):

dart pub global activate interactive

Use (just a normal binary):

interactive

And play with it :)

Detailed functionality list

Expressions

>>> a = 'Hello'; b = ' world!'; 
>>> '$a, $b'                   
Hello,  world!

Statements

>>> print(a)
Hello

(All methods, not only print)

Functions

Define and redefine

>>> String f() => 'old';
>>> f()
old
>>> String f() => 'new';
>>> f()
new

Use local and global variables

>>> a = 10;
>>> int f() { int b = 20; a++; b++; return a+b; }
>>> f() 
32
>>> f()
33

Classes

Define and redefine, preserving states

>>> class C { int a = 10; int f() => a * 2; }
>>> c = C(); print(c.f());
20
>>> class C { int a = 1000; int f() => a * 3; }
>>> c.f()
30

Remark: This follows the Dart hot reload semantics.

Extends and implements

>>> class A { int f() => 10; } class B extends A { int f() => 20; }
>>> A().f() + B().f()
30
>>> class B implements A { int f() => 30; }
>>> A().f() + B().f()
40

Use local variables, fields, and global variables

>>> a = 10;
>>> class C { int b = 20; int f() { int c = 30; a++; b++; c++; return a+b+c; } }
>>> c = C(); print(c.f()); print(c.f());
63
65

Add libraries as dependency

Use !dart pub add package_name, just like what is done in Python (Jupyter/IPython).

>>> join('directory', 'file.txt')
(...error, since have not added that dependency...)
>>> !dart pub add path
Resolving dependencies...

+ path 1.8.2

Changed 1 dependency!

>>> join('directory', 'file.txt')
(...error, since have imported it...)
>>> import 'package:path/path.dart';
>>> join('directory', 'file.txt')   
directory/file.txt

Imports

Built-in package

>>> Random().nextInt(100)
(some error outputs here, because it is not imported)
>>> import "dart:math";
>>> Random().nextInt(100)
9

Third party package

Note: If it has not been added to dependency, please follow instructions above and use !dart pub add path to add it.

>>> join('directory', 'file.txt')
(...error, since have imported it...)
>>> import 'package:path/path.dart';
>>> join('directory', 'file.txt')   
directory/file.txt

Multiple in one go

>>> int g() => 42; class C { int a = 10; int f() => a * 2; }
>>> C().f() + g()
62

Multi line if not ended

(The ..., instead of >>>, appears in the two lines, because the package detects it is not finished.)

>>> class C {
...   int a = 10;
... }
>>> 

Run commands

Use prefix !.

>>> !whoami
tom
>>> !date
2022-10-22 ...outputs...

Execute within environment of existing package

interactive --directory path/to/your/package

Implementation

General:

• Create a blank package and an isolate as execution workspace
• Extract imports/classes/functions/etc using analyzer, with replacing when it has the same name, and synthesize a dart file - thus supports rich Dart feature
• Trigger Dart's hot-reload after the dart file is updated
• Use analyzer to distinguish expressions/statements/compilation-units and do corresponding transformation
• The only thing to let Dart VM service to evaluate is generatedMethod(), and do not evaluate anything more
• Adding dependencies is as simple as running standard shell command

As for "global" variables:

• Indeed implemented by a field variable
• Statements: Make it inside extension on dynamic { Object? generatedMethod() { ...the statements... } } to access it seamlessly
• Functions: Convert functions to extension methods on dynamic to access it seamlessly
• Classes: Synthesize getters/setters in classes, and delegate to the field variables, whenever there is a potential access to global variable to access it seamlessly

TODO more implementation discussions if people are interested (above is so brief)

✨ Contributors

Thanks goes to these wonderful people (emoji key):

fzyzcjy 💻 📖 🤔	Vyacheslav Egorov 🤔	Andreas Kirsch 🤔	Maksim Lin 🤔	Keithcat1 💻	Sebastian Thomschke 💻	arcanemachine 💻
David Martos 💻

More specifically, thanks for all these contributions:

• @mraleph (Dart team): Pointing out Dart exposes hot reload and expression evaluation.
• @BlackHC: Prior proof of concept and article on the problem of creating a REPL.
• @maks: Prior prototype as an update-to-Dart-2 of @BlackHC's prototype.
• @davidmartos96: Fix package import bug. Fix windows hot reload bug. Update analyze.
• @Keithcat1: Partially fix printing object.
• @sebthom: Use unused TCP port.
• @arcanemachine: Pin dependency.