<commit_before>// Copyright (c) 2012, 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.

#library('source');

#import('io.dart');
#import('package.dart');
#import('pubspec.dart');
#import('system_cache.dart');
#import('version.dart');

/**
 * A source from which to install packages.
 *
 * Each source has many packages that it looks up using [PackageId]s. The source
 * is responsible for installing these packages to the package cache.
 */
class Source {
  /**
   * The name of the source. Should be lower-case, suitable for use in a
   * filename, and unique accross all sources.
   */
  abstract String get name;

  /**
   * Whether this source's packages should be cached in Pub's global cache
   * directory.
   *
   * A source should be cached if it requires network access to retrieve
   * packages. It doesn't need to be cached if all packages are available
   * locally.
   */
  abstract bool get shouldCache;

  /**
   * The system cache with which this source is registered.
   */
  SystemCache get systemCache {
    assert(_systemCache != null);
    return _systemCache;
  }

  /**
   * The system cache variable. Set by [_bind].
   */
  SystemCache _systemCache;

  /**
   * The root directory of this source's cache within the system cache.
   *
   * This shouldn't be overridden by subclasses.
   */
  String get systemCacheRoot => join(systemCache.rootDir, name);

  /**
   * Records the system cache to which this source belongs.
   *
   * This should only be called once for each source, by [SystemCache.register].
   * It should not be overridden by base classes.
   */
  void bind(SystemCache systemCache) {
    assert(_systemCache == null);
    this._systemCache = systemCache;
  }

  /**
   * Get the list of all versions that exist for the package described by
   * [description].
   *
   * Note that this does *not* require the packages to be installed, which is
   * the point. This is used during version resolution to determine which
   * package versions are available to be installed (or already installed).
   *
   * By default, this assumes that each description has a single version and
   * uses [describe] to get that version.
   */
  Future<List<Version>> getVersions(description) {
    return describe(new PackageId(this, Version.none, description))
      .transform((pubspec) => [pubspec.version]);
  }

  /**
   * Loads the (possibly remote) pubspec for the package version identified by
   * [id]. This may be called for packages that have not yet been installed
   * during the version resolution process.
   *
   * For cached sources, by default this uses [installToSystemCache] to get the
   * pubspec. There is no default implementation for non-cached sources; they
   * must implement it manually.
   */
  Future<Pubspec> describe(PackageId id) {
    if (!shouldCache) throw "Source $name must implement describe(id).";
    return installToSystemCache(id).transform((package) => package.pubspec);
  }

  /**
   * Installs the package identified by [id] to [path]. Returns a [Future] that
   * completes when the installation was finished. The [Future] should resolve
   * to true if the package was found in the source and false if it wasn't. For
   * all other error conditions, it should complete with an exception.
   *
   * [path] is guaranteed not to exist, and its parent directory is guaranteed
   * to exist.
   *
   * This doesn't need to be implemented if [installToSystemCache] is
   * implemented.
   */
  Future<bool> install(PackageId id, String path) {<commit_msg>Add a note to Source#install explaining that it should be very light-weight.<commit_after>// Copyright (c) 2012, 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.

#library('source');

#import('io.dart');
#import('package.dart');
#import('pubspec.dart');
#import('system_cache.dart');
#import('version.dart');

/**
 * A source from which to install packages.
 *
 * Each source has many packages that it looks up using [PackageId]s. The source
 * is responsible for installing these packages to the package cache.
 */
class Source {
  /**
   * The name of the source. Should be lower-case, suitable for use in a
   * filename, and unique accross all sources.
   */
  abstract String get name;

  /**
   * Whether this source's packages should be cached in Pub's global cache
   * directory.
   *
   * A source should be cached if it requires network access to retrieve
   * packages. It doesn't need to be cached if all packages are available
   * locally.
   */
  abstract bool get shouldCache;

  /**
   * The system cache with which this source is registered.
   */
  SystemCache get systemCache {
    assert(_systemCache != null);
    return _systemCache;
  }

  /**
   * The system cache variable. Set by [_bind].
   */
  SystemCache _systemCache;

  /**
   * The root directory of this source's cache within the system cache.
   *
   * This shouldn't be overridden by subclasses.
   */
  String get systemCacheRoot => join(systemCache.rootDir, name);

  /**
   * Records the system cache to which this source belongs.
   *
   * This should only be called once for each source, by [SystemCache.register].
   * It should not be overridden by base classes.
   */
  void bind(SystemCache systemCache) {
    assert(_systemCache == null);
    this._systemCache = systemCache;
  }

  /**
   * Get the list of all versions that exist for the package described by
   * [description].
   *
   * Note that this does *not* require the packages to be installed, which is
   * the point. This is used during version resolution to determine which
   * package versions are available to be installed (or already installed).
   *
   * By default, this assumes that each description has a single version and
   * uses [describe] to get that version.
   */
  Future<List<Version>> getVersions(description) {
    return describe(new PackageId(this, Version.none, description))
      .transform((pubspec) => [pubspec.version]);
  }

  /**
   * Loads the (possibly remote) pubspec for the package version identified by
   * [id]. This may be called for packages that have not yet been installed
   * during the version resolution process.
   *
   * For cached sources, by default this uses [installToSystemCache] to get the
   * pubspec. There is no default implementation for non-cached sources; they
   * must implement it manually.
   */
  Future<Pubspec> describe(PackageId id) {
    if (!shouldCache) throw "Source $name must implement describe(id).";
    return installToSystemCache(id).transform((package) => package.pubspec);
  }

  /**
   * Installs the package identified by [id] to [path]. Returns a [Future] that
   * completes when the installation was finished. The [Future] should resolve
   * to true if the package was found in the source and false if it wasn't. For
   * all other error conditions, it should complete with an exception.
   *
   * [path] is guaranteed not to exist, and its parent directory is guaranteed
   * to exist.
   *
   * Note that [path] may be deleted. If re-installing a package that has
   * already been installed would be costly or impossible,
   * [installToSystemCache] should be implemented instead of [install].
   *
   * This doesn't need to be implemented if [installToSystemCache] is
   * implemented.
   */
  Future<bool> install(PackageId id, String path) {
{'fraction_non_alphanumeric': 0.0879453135270146, 'fraction_numerical': 0.0010516629420270803, 'mean_word_length': 3.3080407701019254, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3350509', 'n_tokens_mistral': 2070, 'n_tokens_neox': 2014, 'n_words': 920}