where 2.1.0

Find the instances of an executable in the system path.

Where.dart

Find the instances of an executable in the system path, implemented in in Dart.

Requirements

The latest Dart SDK and Pub versions. If you plan to play with the sources, you will also need the latest Grinder version.

Installing via Pub

1. Depend on it

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

dependencies:
  where: *

2. Install it

Install this package and its dependencies from a command prompt:

$ pub get

3. Import it

Now in your Dart code, you can use:

import 'package:where/where.dart' show where;

Usage

This package provides a single function, where(), allowing to locate a command in the system path:

try {
  // "path" is the absolute path to the executable.
  var path = await where('foobar');
  print('The "foobar" command is located at: $path');
}

on FileSystemException {
  // The command was not found on the system path.
  print('The "foobar" command is not found.');
}

The function returns a Future<String> specifying the path of the first instance of the executables found. If the command could not be located, a FileSystemException is thrown.

Options

The behavior of the where() function can be customized using the following optional named parameters.

bool all = false

A value indicating whether to return all executables found, instead of just the first one.

If you pass true as parameter value, the function will return a Future<List<String>> providing all paths found, instead of a Future<String>:

var paths = await where('foobar', all: true);

print('The "foobar" command was found at these locations:');
for (var path in paths) print(path);

String|List<String> extensions = ""

The executable file extensions, provided as a string or a list of file extensions. Defaults to the list of extensions provided by the PATHEXT environment variable.

The extensions option is only meaningful on the Windows platform, where the executability of a file is determined from its extension:

where('foobar', extensions: '.FOO;.EXE;.CMD');

dynamic onError(String command)

By default, when the specified command cannot be located, a FileSystemException is thrown. You can disable this exception by providing your own error handler:

var path = await where('foobar', onError: (_) => '');

if (path.isEmpty) print('The "foobar" command is not found.');
else print('The "foobar" command is located at: $path');

When an onError handler is provided, it is called with the command as argument, and its return value is used instead. This is preferable to throwing and then immediately catching the FileSystemException.

String|List<String> path = ""

The system path, provided as a string or a list of directories. Defaults to the list of paths provided by the PATH environment variable.

where('foobar', path: ['/usr/local/bin', '/usr/bin']);

String pathSeparator = ""

The character used to separate paths in the system path. Defaults to the platform path separator (e.g. ";" on Windows, ":" on other platforms).

where('foobar', pathSeparator: '#');

Command line interface

From a command prompt, install the where executable:

$ pub global activate where

Consider adding the pub global executables directory to your system path.

Then use it to find the instances of an executable:

$ where --help

Find the instances of an executable in the system path.

Usage:
pub global run where [options] <command>

Options:
-a, --all        list all instances of executables found (instead of just the first one)
-s, --silent     silence the output, just return the exit code (0 if any executable is found, otherwise 1)
-h, --help       output usage information
-v, --version    output the version number

For example:

$ where --all dart

See also

• API reference
• Code coverage
• Continuous integration

License

Where.dart is distributed under the MIT License.