where 3.0.0

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 67

Where.dart

Runtime Release License Coverage Build

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:
  file: *
  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:file/file.dart' show FileSystemException;
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:
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

Node.js support

This package supports the Node.js platform. A JavaScript executable can be generated using the following Grinder command:

$ grind

This command will build a where.js file in the bin folder of this package. The generated executable has the same features as the Dart command line:

$ node bin/where.js --help
$ node bin/where.js --all dart

See also

License

Where.dart is distributed under the MIT License.

Changelog

This file contains highlights of what changes on each version of the Where.dart project.

Version 3.0.0

  • Added support for Node.js virtual machine.
  • Breaking change: removed the FileStat.stat() method.
  • Breaking change: renamed the FileStat class to FileStats.
  • Added the fileSystem, platform and processManager constants.
  • Added the getFileStats() function.
  • Added the arguments and exitCode properties.

Version 2.2.0

  • Updated the package dependencies.

Version 2.1.1

  • Fixed a bug: the CLI script doesn't run when using the pub global run command.

Version 2.1.0

  • Changed the signature of the FileStat class constructor.

Version 2.0.0

  • Breaking change: changed the signature of the Finder class constructor.
  • Breaking change: removed the Application class.
  • Breaking change: the version property is now private.
  • Converted the constructor of the FileStat class to a constant one.
  • Updated the package dependencies.

Version 1.1.0

Version 1.0.0

  • Added a command line interface.
  • Added new unit tests.

Version 0.1.0

  • Initial release.

1. Depend on it

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


dependencies:
  where: "^3.0.0"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:where/where.dart';
        
Version Uploaded Documentation Archive
3.0.0 Dec 6, 2017 Go to the documentation of where 3.0.0 Download where 3.0.0 archive
2.2.0 Nov 3, 2017 Go to the documentation of where 2.2.0 Download where 2.2.0 archive
2.1.1 Sep 15, 2017 Go to the documentation of where 2.1.1 Download where 2.1.1 archive
2.1.0 Sep 11, 2017 Go to the documentation of where 2.1.0 Download where 2.1.0 archive
2.0.0 Sep 11, 2017 Go to the documentation of where 2.0.0 Download where 2.0.0 archive
1.1.0 Sep 8, 2017 Go to the documentation of where 1.1.0 Download where 1.1.0 archive
1.0.0 Aug 11, 2017 Go to the documentation of where 1.0.0 Download where 1.0.0 archive
0.1.0 Aug 9, 2017 Go to the documentation of where 0.1.0 Download where 0.1.0 archive

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • completed on Feb 3, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
36 / 100
Health:
Code health derived from static analysis. [more]
97 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
67

Platforms

Detected platforms: Flutter, other

Primary library: package:where/where.dart with components: io.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use where.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.24.0 <2.0.0
args >=0.13.7 <2.0.0 1.3.0
file ^2.3.4 2.3.5
nodejs_interop ^0.6.0 0.6.0 0.8.0
platform ^2.1.1 2.1.1
process ^2.0.6 2.0.7
yaml ^2.1.13 2.1.13
Transitive dependencies
async 2.0.3
barback 0.15.2+14
charcode 1.1.1
collection 1.14.5
intl 0.15.2
js 0.6.1
meta 1.1.2
path 1.5.1
pool 1.3.4
source_span 1.4.0
stack_trace 1.9.1
string_scanner 1.0.2
Dev dependencies
coverage ^0.9.3
grinder ^0.8.0
node_preamble ^1.4.0 1.4.0
test ^0.12.29