which function

Which which(
  1. String appname, {
  2. bool first = true,
  3. bool verbose = false,
  4. bool extensionSearch = true,
  5. void progress(
    1. WhichSearch
    )?,
})

Path search utilities for finding executable applications.

This module provides functionality similar to the Unix 'which' command, allowing you to locate executable files in the system PATH.

Example usage:

// Find the location of the 'dart' executable
final dartLocation = which('dart');
if (dartLocation.found) {
  print('Dart found at: ${dartLocation.path}');
}

// Find all occurrences of 'python'
final pythonLocations = which('python', first: false);
for (final path in pythonLocations.paths) {
  print('Python found at: $path');
}

Search the PATH for an executable application.

This function searches for the specified application in all directories listed in the PATH environment variable, from left to right.

Parameters:

  • appname: Name of the application to find
  • first: If true, stops after finding the first match (default: true)
  • verbose: If true, provides detailed search progress (default: false)
  • extensionSearch: If true, searches for Windows extensions (default: true)
  • progress: Optional callback for processing search progress

Returns a Which object containing search results and status.

The extensionSearch parameter is useful for cross-platform development. When true on Windows, it will search for 'dart.exe', 'dart.bat', etc. when you search for 'dart'.

Example:

// Find the first occurrence of 'ls'
final result = which('ls');
if (result.found) {
  print('Found at: ${result.path}');
}

// Find all occurrences with verbose output
which('python', first: false, verbose: true);

// Cross-platform executable search
which('dart'); // Finds 'dart' on Unix, 'dart.exe' on Windows

Implementation

/// Search the PATH for an executable application.
///
/// This function searches for the specified application in all directories
/// listed in the PATH environment variable, from left to right.
///
/// Parameters:
/// - [appname]: Name of the application to find
/// - [first]: If true, stops after finding the first match (default: true)
/// - [verbose]: If true, provides detailed search progress (default: false)
/// - [extensionSearch]: If true, searches for Windows extensions (default: true)
/// - [progress]: Optional callback for processing search progress
///
/// Returns a [Which] object containing search results and status.
///
/// The [extensionSearch] parameter is useful for cross-platform development.
/// When true on Windows, it will search for 'dart.exe', 'dart.bat', etc.
/// when you search for 'dart'.
///
/// Example:
/// ```dart
/// // Find the first occurrence of 'ls'
/// final result = which('ls');
/// if (result.found) {
///   print('Found at: ${result.path}');
/// }
///
/// // Find all occurrences with verbose output
/// which('python', first: false, verbose: true);
///
/// // Cross-platform executable search
/// which('dart'); // Finds 'dart' on Unix, 'dart.exe' on Windows
/// ```
Which which(
  String appname, {
  bool first = true,
  bool verbose = false,
  bool extensionSearch = true,
  void Function(WhichSearch)? progress,
}) =>
    _Which().which(
      appname,
      first: first,
      verbose: verbose,
      extensionSearch: extensionSearch,
      progress: progress,
    );