blob: 203f32fdb57c65768fc692dea813ca79bc0c9e74 [file] [log] [blame]
// Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
@Deprecated("Use the package_config.json based API")
library package_config.packages;
import "src/packages_impl.dart";
/// A package resolution strategy.
/// Allows converting a `package:` URI to a different kind of URI.
/// May also allow listing the available packages and converting
/// to a `Map<String, Uri>` that gives the base location of each available
/// package. In some cases there is no way to find the available packages,
/// in which case [packages] and [asMap] will throw if used.
/// One such case is if the packages are resolved relative to a
/// `packages/` directory available over HTTP.
@Deprecated("Use the package_config.json based API")
abstract class Packages {
/// A [Packages] resolver containing no packages.
/// This constant object is returned by [find] above if no
/// package resolution strategy is found.
static const Packages noPackages = NoPackages();
/// Resolve a package URI into a non-package URI.
/// Translates a `package:` URI, according to the package resolution
/// strategy, into a URI that can be loaded.
/// By default, only `file`, `http` and `https` URIs are returned.
/// Custom `Packages` objects may return other URIs.
/// If resolution fails because a package with the requested package name
/// is not available, the [notFound] function is called.
/// If no `notFound` function is provided, it defaults to throwing an error.
/// The [packageUri] must be a valid package URI.
Uri resolve(Uri packageUri, {Uri notFound(Uri packageUri)});
/// Return the names of the available packages.
/// Returns an iterable that allows iterating the names of available packages.
/// Some `Packages` objects are unable to find the package names,
/// and getting `packages` from such a `Packages` object will throw.
Iterable<String> get packages;
/// Retrieve metadata associated with a package.
/// Metadata have string keys and values, and are looked up by key.
/// Returns `null` if the argument is not a valid package name,
/// or if the package is not one of the packages configured by
/// this packages object, or if the package does not have associated
/// metadata with the provided [key].
/// Not all `Packages` objects can support metadata.
/// Those will always return `null`.
String packageMetadata(String packageName, String key);
/// Retrieve metadata associated with a library.
/// If [libraryUri] is a `package:` URI, the returned value
/// is the same that would be returned by [packageMetadata] with
/// the package's name and the same key.
/// If [libraryUri] is not a `package:` URI, and this [Packages]
/// object has a [defaultPackageName], then the [key] is looked
/// up on the default package instead.
/// Otherwise the result is `null`.
String libraryMetadata(Uri libraryUri, String key);
/// Return the names-to-base-URI mapping of the available packages.
/// Returns a map from package name to a base URI.
/// The [resolve] method will resolve a package URI with a specific package
/// name to a path extending the base URI that this map gives for that
/// package name.
/// Some `Packages` objects are unable to find the package names,
/// and calling `asMap` on such a `Packages` object will throw.
Map<String, Uri> asMap();
/// The name of the "default package".
/// A default package is a package that *non-package* libraries
/// may be considered part of for some purposes.
/// The value is `null` if there is no default package.
/// Not all implementations of [Packages] supports a default package,
/// and will always have a `null` value for those.
String get defaultPackageName;