// 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.

/// Matchers build up their error messages by appending to Description objects.
///
/// This interface is implemented by StringDescription.
///
/// This interface is unlikely to need other implementations, but could be
/// useful to replace in some cases - e.g. language conversion.
abstract class Description {
  int get length;

  /// Change the value of the description.
  Description replace(String text);

  /// This is used to add arbitrary text to the description.
  Description add(String text);

  /// This is used to add a meaningful description of a value.
  Description addDescriptionOf(value);

  /// This is used to add a description of an [Iterable] [list],
  /// with appropriate [start] and [end] markers and inter-element [separator].
  Description addAll(String start, String separator, String end, Iterable list);
}

/// The base class for all matchers.
///
/// [matches] and [describe] must be implemented by subclasses.
///
/// Subclasses can override [describeMismatch] if a more specific description is
/// required when the matcher fails.
abstract class Matcher {
  const Matcher();

  /// Does the matching of the actual vs expected values.
  ///
  /// [item] is the actual value. [matchState] can be supplied
  /// and may be used to add details about the mismatch that are too
  /// costly to determine in [describeMismatch].
  bool matches(item, Map matchState);

  /// Builds a textual description of the matcher.
  Description describe(Description description);

  /// Builds a textual description of a specific mismatch.
  ///
  /// [item] is the value that was tested by [matches]; [matchState] is
  /// the [Map] that was passed to and supplemented by [matches]
  /// with additional information about the mismatch, and [mismatchDescription]
  /// is the [Description] that is being built to describe the mismatch.
  ///
  /// A few matchers make use of the [verbose] flag to provide detailed
  /// information that is not typically included but can be of help in
  /// diagnosing failures, such as stack traces.
  Description describeMismatch(item, Description mismatchDescription,
          Map matchState, bool verbose) =>
      mismatchDescription;
}