show_augmentation 0.1.0-8.dev

Shows augmentation code generated by macros for a given source file.

A command-line tool to show augmentation generated by Dart macros:

dart run show_augmentation --file=relative/path/to/file.dart

You can usually view augmentation in your IDE:

But currently only VSCode supports it. It's experimental and sometimes buggy. If the IDE does not work for you, use this tool.

Usage

1. Switch to Dart 3.5+ (currently experimental).

2. Make sure Dart 3.5+ is in your $PATH before any stable Dart location.

3. Add this package as dev_dependency to pubspec.yaml:

dev_dependency:
  show_augmentation: ^0.1.0-3.dev

4. Run dart pub get

5. Run in terminal:

dart run show_augmentation --file=relative/path/to/file.dart

It will print the augmentation for the file if it has macro applications. It will print nothing otherwise.

Full usage:

Usage: dart run show_augmentation --file=relative/path/to/file.dart [--line-numbers] [-v]
    --file=<FILE> (mandatory)    The file to show augmentation for, relative to the current directory.
    --help                       Show this help message.
    --line-numbers               Show line numbers.
-v, --verbose                    Show debug output.

Example

This package comes with an example file and macro. For this example, run:

cd example
dart run show_augmentation --file=lib/main.dart

The output:

augment library 'package:show_augmentation_example/main.dart';

import 'dart:core' as prefix0;

augment class User {
void hello() {prefix0.print('Hello! I am User. I have age, name, username.');}
}

How it Works

Most of the tips and navigation in most IDEs come not from the IDE but from Dart itself. Modern IDEs do not interpret the code themselves. Instead, Dart and most other languages now have so-called language servers shipped with them. An IDE starts such a server locally for a given language and tells it to analyze the entire project and tell it any intel for a given file that the user is currently viewing: errors, warnings, fix suggestions, "Go to Definition", etc. Language Server Protocol is used for communication between an IDE and servers, it's standard for all languages.

Viewing the augmentation in Dart works the same way. An IDE asks the Dart language server to show augmentation for a given file. It works one way, and that's why the augmentation in VSCode is read-only.

This tool does the same. It launches the Dart language server locally, tells it to analyze your project, and then requests the augmentation for the given file. That's why the result is the same as with viewing it in your IDE.

This tool uses my package lsp_client for this communication.