Tilde Expansion for Dart

Pub Version Documentation CI Status License: GPL

Expand ~ and ~/ in paths like a shell – cross-platform, lightweight, and zero-dependency.

Tired of manually replacing ~ with the user’s home directory in your Dart/Flutter apps? tilde_expansion does it for you, just like your shell.

Key Features:

  • Simple Usage: Easily expand tilde paths with a single method call.
  • Works with ~/ and ~user paths, note that no verification of that user existence is done
  • Cross-Platform Compatibility: Works seamlessly across different operating systems.
  • Flexible Configuration: Customize expansion behavior with optional parameters.
  • Efficient Implementation: Optimized for performance and clarity.

Why?

  • No built-in solution in Dart: The official path package ignores Unix user needs (yes, really).
  • Cross-platform: Works everywhere, from CLI tools to Flutter apps.
  • Tiny and fast: Zero dependencies, minimal overhead.

Installation

Add to your pubspec.yaml:

dependencies:
  tilde_expansion: ^latest_version

Or install via CLI:

dart pub add tilde_expansion

Usage

Basic Expansion

import 'package:tilde_expansion/tilde_expansion.dart';

void main() {
print("Expand path from ~/Documents/test.txt to   ${'~/Documents/test.txt'.expandUser()}");
}

Custom User Paths or to canonicalize the path

import 'package:tilde_expansion/tilde_expansion.dart';
void main() {
print("Hello to convert ~/Documents/test.txt to   ${'~/Documents/test.txt'.expandUser(canonicalize: true)}");
print("Hello to convert ~toto/Documents/test.txt to   ${'~toto/Documents/test.txt'.expandUser(canonicalize: true)}");
}

Features

  • ✅ Shell-like behavior: Mimics bash/zsh expansion rules.
  • ✅ No dependencies: Pure Dart, < 100 lines of code.
  • ✅ Error-resistant: Gracefully handles invalid paths.

Who Needs This?

  • CLI tools: Stop hardcoding /home/user/ – use ~ like in scripts!
  • Flutter apps: Save user paths (e.g., ~/Downloads) without platform-specific code.
  • Cross-platform projects: Write once, expand everywhere.

Running Tests

dart test ## to run the validation tests
dart run ## to run a minimal example

Additional Notes:

  • Error Handling: The package handles cases where the HOME environment variable is not set.
  • Performance: The implementation is optimized for efficiency, especially when dealing with large numbers of path expansions.

License

released under the GPLv3

Libraries

tilde_expansion