dart/pkg/mock/lib/src/log_entry_list.dart - external/dart - Git at Google

 // Copyright (c) 2014, 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 mock.log_entry_list;

 import 'package:matcher/matcher.dart';

 import 'call_matcher.dart';
 import 'log_entry.dart';
 import 'util.dart';

 /**
 * [StepValidator]s are used by [stepwiseValidate] in [LogEntryList], which
 * iterates through the list and call the [StepValidator] function with the
 * log [List] and position. The [StepValidator] should return the number of
 * positions to advance upon success, or zero upon failure. When zero is
 * returned an error is reported.
 */
 typedef int StepValidator(List<LogEntry> logs, int pos);

 /**
  * We do verification on a list of [LogEntry]s. To allow chaining
  * of calls to verify, we encapsulate such a list in the [LogEntryList]
  * class.
  */
 class LogEntryList {
   String filter;
   List<LogEntry> logs;
   LogEntryList([this.filter]) {
     logs = new List<LogEntry>();
   }

   /** Add a [LogEntry] to the log. */
   add(LogEntry entry) => logs.add(entry);

   /** Get the first entry, or null if no entries. */
   get first => (logs == null || logs.length == 0) ? null : logs[0];

   /** Get the last entry, or null if no entries. */
   get last => (logs == null || logs.length == 0) ? null : logs.last;

   /** Creates a LogEntry predicate function from the argument. */
   Function _makePredicate(arg) {
     if (arg == null) {
       return (e) => true;
     } else if (arg is CallMatcher) {
       return (e) => arg.matches(e.methodName, e.args);
     } else if (arg is Function) {
       return arg;
     } else {
       throw new Exception("Invalid argument to _makePredicate.");
     }
   }

   /**
    * Create a new [LogEntryList] consisting of [LogEntry]s from
    * this list that match the specified [mockNameFilter] and [logFilter].
    * [mockNameFilter] can be null, a [String], a predicate [Function],
    * or a [Matcher]. If [mockNameFilter] is null, this is the same as
    * [anything].
    * If [logFilter] is null, all entries in the log will be returned.
    * Otherwise [logFilter] should be a [CallMatcher] or  predicate function
    * that takes a [LogEntry] and returns a bool.
    * If [destructive] is true, the log entries are removed from the
    * original list.
    */
   LogEntryList getMatches([mockNameFilter,
                           logFilter,
                           Matcher actionMatcher,
                           bool destructive = false]) {
     if (mockNameFilter == null) {
       mockNameFilter = anything;
     } else {
       mockNameFilter = wrapMatcher(mockNameFilter);
     }
     Function entryFilter = _makePredicate(logFilter);
     String filterName = qualifiedName(mockNameFilter, logFilter.toString());
     LogEntryList rtn = new LogEntryList(filterName);
     var matchState = {};
     for (var i = 0; i < logs.length; i++) {
       LogEntry entry = logs[i];
       if (mockNameFilter.matches(entry.mockName, matchState) &&
           entryFilter(entry)) {
         if (actionMatcher == null ||
             actionMatcher.matches(entry, matchState)) {
           rtn.add(entry);
           if (destructive) {
             int startIndex = i--;
             logs.removeRange(startIndex, startIndex + 1);
           }
         }
       }
     }
     return rtn;
   }

   /** Apply a unit test [Matcher] to the [LogEntryList]. */
   LogEntryList verify(Matcher matcher) {
     if (_mockFailureHandler == null) {
       _mockFailureHandler =
           new _MockFailureHandler(getOrCreateExpectFailureHandler());
     }
     expect(logs, matcher, reason: filter, failureHandler: _mockFailureHandler);
     return this;
   }

   /**
    * Iterate through the list and call the [validator] function with the
    * log [List] and position. The [validator] should return the number of
    * positions to advance upon success, or zero upon failure. When zero is
    * returned an error is reported. [reason] can be used to provide a
    * more descriptive failure message. If a failure occurred false will be
    * returned (unless the failure handler itself threw an exception);
    * otherwise true is returned.
    * The use case here is to perform more complex validations; for example
    * we may want to assert that the return value from some function is
    * later used as a parameter to a following function. If we filter the logs
    * to include just these two functions we can write a simple validator to
    * do this check.
    */
   bool stepwiseValidate(StepValidator validator, [String reason = '']) {
     if (_mockFailureHandler == null) {
       _mockFailureHandler =
           new _MockFailureHandler(getOrCreateExpectFailureHandler());
     }
     var i = 0;
     while (i < logs.length) {
       var n = validator(logs, i);
       if (n == 0) {
         if (reason.length > 0) {
           reason = ': $reason';
         }
         _mockFailureHandler.fail("Stepwise validation failed at $filter "
                                  "position $i$reason");
         return false;
       } else {
         i += n;
       }
     }
     return true;
   }

   /**
    * Turn the logs into human-readable text. If [baseTime] is specified
    * then each entry is prefixed with the offset from that time in
    * milliseconds; otherwise the time of day is used.
    */
   String toString([DateTime baseTime]) {
     String s = '';
     for (var e in logs) {
       s = '$s${e.toString(baseTime)}\n';
     }
     return s;
   }

   /**
    *  Find the first log entry that satisfies [logFilter] and
    *  return its position. A search [start] position can be provided
    *  to allow for repeated searches. [logFilter] can be a [CallMatcher],
    *  or a predicate function that takes a [LogEntry] argument and returns
    *  a bool. If [logFilter] is null, it will match any [LogEntry].
    *  If no entry is found, then [failureReturnValue] is returned.
    *  After each check the position is updated by [skip], so using
    *  [skip] of -1 allows backward searches, using a [skip] of 2 can
    *  be used to check pairs of adjacent entries, and so on.
    */
   int findLogEntry(logFilter, [int start = 0, int failureReturnValue = -1,
       skip = 1]) {
     logFilter = _makePredicate(logFilter);
     int pos = start;
     while (pos >= 0 && pos < logs.length) {
       if (logFilter(logs[pos])) {
         return pos;
       }
       pos += skip;
     }
     return failureReturnValue;
   }

   /**
    * Returns log events that happened up to the first one that
    * satisfies [logFilter]. If [inPlace] is true, then returns
    * this LogEntryList after removing the from the first satisfier;
    * onwards otherwise a new list is created. [description]
    * is used to create a new name for the resulting list.
    * [defaultPosition] is used as the index of the matching item in
    * the case that no match is found.
    */
   LogEntryList _head(logFilter, bool inPlace,
                      String description, int defaultPosition) {
     if (filter != null) {
       description = '$filter $description';
     }
     int pos = findLogEntry(logFilter, 0, defaultPosition);
     if (inPlace) {
       if (pos < logs.length) {
         logs.removeRange(pos, logs.length);
       }
       filter = description;
       return this;
     } else {
       LogEntryList newList = new LogEntryList(description);
       for (var i = 0; i < pos; i++) {
         newList.logs.add(logs[i]);
       }
       return newList;
     }
   }

   /**
    * Returns log events that happened from the first one that
    * satisfies [logFilter]. If [inPlace] is true, then returns
    * this LogEntryList after removing the entries up to the first
    * satisfier; otherwise a new list is created. [description]
    * is used to create a new name for the resulting list.
    * [defaultPosition] is used as the index of the matching item in
    * the case that no match is found.
    */
   LogEntryList _tail(logFilter, bool inPlace,
                      String description, int defaultPosition) {
     if (filter != null) {
       description = '$filter $description';
     }
     int pos = findLogEntry(logFilter, 0, defaultPosition);
     if (inPlace) {
       if (pos > 0) {
         logs.removeRange(0, pos);
       }
       filter = description;
       return this;
     } else {
       LogEntryList newList = new LogEntryList(description);
       while (pos < logs.length) {
         newList.logs.add(logs[pos++]);
       }
       return newList;
     }
   }

   /**
    * Returns log events that happened after [when]. If [inPlace]
    * is true, then it returns this LogEntryList after removing
    * the entries that happened up to [when]; otherwise a new
    * list is created.
    */
   LogEntryList after(DateTime when, [bool inPlace = false]) =>
       _tail((e) => e.time.isAfter(when), inPlace, 'after $when', logs.length);

   /**
    * Returns log events that happened from [when] onwards. If
    * [inPlace] is true, then it returns this LogEntryList after
    * removing the entries that happened before [when]; otherwise
    * a new list is created.
    */
   LogEntryList from(DateTime when, [bool inPlace = false]) =>
       _tail((e) => !e.time.isBefore(when), inPlace, 'from $when', logs.length);

   /**
    * Returns log events that happened until [when]. If [inPlace]
    * is true, then it returns this LogEntryList after removing
    * the entries that happened after [when]; otherwise a new
    * list is created.
    */
   LogEntryList until(DateTime when, [bool inPlace = false]) =>
       _head((e) => e.time.isAfter(when), inPlace, 'until $when', logs.length);

   /**
    * Returns log events that happened before [when]. If [inPlace]
    * is true, then it returns this LogEntryList after removing
    * the entries that happened from [when] onwards; otherwise a new
    * list is created.
    */
   LogEntryList before(DateTime when, [bool inPlace = false]) =>
       _head((e) => !e.time.isBefore(when),
             inPlace,
             'before $when',
             logs.length);

   /**
    * Returns log events that happened after [logEntry]'s time.
    * If [inPlace] is true, then it returns this LogEntryList after
    * removing the entries that happened up to [when]; otherwise a new
    * list is created. If [logEntry] is null the current time is used.
    */
   LogEntryList afterEntry(LogEntry logEntry, [bool inPlace = false]) =>
       after(logEntry == null ? new DateTime.now() : logEntry.time);

   /**
    * Returns log events that happened from [logEntry]'s time onwards.
    * If [inPlace] is true, then it returns this LogEntryList after
    * removing the entries that happened before [when]; otherwise
    * a new list is created. If [logEntry] is null the current time is used.
    */
   LogEntryList fromEntry(LogEntry logEntry, [bool inPlace = false]) =>
       from(logEntry == null ? new DateTime.now() : logEntry.time);

   /**
    * Returns log events that happened until [logEntry]'s time. If
    * [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened after [when]; otherwise a new
    * list is created. If [logEntry] is null the epoch time is used.
    */
   LogEntryList untilEntry(LogEntry logEntry, [bool inPlace = false]) =>
       until(logEntry == null ?
           new DateTime.fromMillisecondsSinceEpoch(0) : logEntry.time);

   /**
    * Returns log events that happened before [logEntry]'s time. If
    * [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened from [when] onwards; otherwise a new
    * list is created. If [logEntry] is null the epoch time is used.
    */
   LogEntryList beforeEntry(LogEntry logEntry, [bool inPlace = false]) =>
       before(logEntry == null ?
           new DateTime.fromMillisecondsSinceEpoch(0) : logEntry.time);

   /**
    * Returns log events that happened after the first event in [segment].
    * If [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened earlier; otherwise a new list is created.
    */
   LogEntryList afterFirst(LogEntryList segment, [bool inPlace = false]) =>
       afterEntry(segment.first, inPlace);

   /**
    * Returns log events that happened after the last event in [segment].
    * If [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened earlier; otherwise a new list is created.
    */
   LogEntryList afterLast(LogEntryList segment, [bool inPlace = false]) =>
       afterEntry(segment.last, inPlace);

   /**
    * Returns log events that happened from the time of the first event in
    * [segment] onwards. If [inPlace] is true, then it returns this
    * LogEntryList after removing the earlier entries; otherwise a new list
    * is created.
    */
   LogEntryList fromFirst(LogEntryList segment, [bool inPlace = false]) =>
       fromEntry(segment.first, inPlace);

   /**
    * Returns log events that happened from the time of the last event in
    * [segment] onwards. If [inPlace] is true, then it returns this
    * LogEntryList after removing the earlier entries; otherwise a new list
    * is created.
    */
   LogEntryList fromLast(LogEntryList segment, [bool inPlace = false]) =>
       fromEntry(segment.last, inPlace);

   /**
    * Returns log events that happened until the first event in [segment].
    * If [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened later; otherwise a new list is created.
    */
   LogEntryList untilFirst(LogEntryList segment, [bool inPlace = false]) =>
       untilEntry(segment.first, inPlace);

   /**
    * Returns log events that happened until the last event in [segment].
    * If [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened later; otherwise a new list is created.
    */
   LogEntryList untilLast(LogEntryList segment, [bool inPlace = false]) =>
       untilEntry(segment.last, inPlace);

   /**
    * Returns log events that happened before the first event in [segment].
    * If [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened later; otherwise a new list is created.
    */
   LogEntryList beforeFirst(LogEntryList segment, [bool inPlace = false]) =>
       beforeEntry(segment.first, inPlace);

   /**
    * Returns log events that happened before the last event in [segment].
    * If [inPlace] is true, then it returns this LogEntryList after removing
    * the entries that happened later; otherwise a new list is created.
    */
   LogEntryList beforeLast(LogEntryList segment, [bool inPlace = false]) =>
       beforeEntry(segment.last, inPlace);

   /**
    * Iterate through the LogEntryList looking for matches to the entries
    * in [keys]; for each match found the closest [distance] neighboring log
    * entries that match [mockNameFilter] and [logFilter] will be included in
    * the result. If [isPreceding] is true we use the neighbors that precede
    * the matched entry; else we use the neighbors that followed.
    * If [includeKeys] is true then the entries in [keys] that resulted in
    * entries in the output list are themselves included in the output list. If
    * [distance] is zero then all matches are included.
    */
   LogEntryList _neighboring(bool isPreceding,
                             LogEntryList keys,
                             mockNameFilter,
                             logFilter,
                             int distance,
                             bool includeKeys) {
     String filterName = 'Calls to '
         '${qualifiedName(mockNameFilter, logFilter.toString())} '
         '${isPreceding?"preceding":"following"} ${keys.filter}';

     LogEntryList rtn = new LogEntryList(filterName);

     // Deal with the trivial case.
     if (logs.length == 0 || keys.logs.length == 0) {
       return rtn;
     }

     // Normalize the mockNameFilter and logFilter values.
     if (mockNameFilter == null) {
       mockNameFilter = anything;
     } else {
       mockNameFilter = wrapMatcher(mockNameFilter);
     }
     logFilter = _makePredicate(logFilter);

     // The scratch list is used to hold matching entries when we
     // are doing preceding neighbors. The remainingCount is used to
     // keep track of how many matching entries we can still add in the
     // current segment (0 if we are doing doing following neighbors, until
     // we get our first key match).
     List scratch = null;
     int remainingCount = 0;
     if (isPreceding) {
       scratch = new List();
       remainingCount = logs.length;
     }

     var keyIterator = keys.logs.iterator;
     keyIterator.moveNext();
     LogEntry keyEntry = keyIterator.current;
     Map matchState = {};

     for (LogEntry logEntry in logs) {
       // If we have a log entry match, copy the saved matches from the
       // scratch buffer into the return list, as well as the matching entry,
       // if appropriate, and reset the scratch buffer. Continue processing
       // from the next key entry.
       if (keyEntry == logEntry) {
         if (scratch != null) {
           int numToCopy = scratch.length;
           if (distance > 0 && distance < numToCopy) {
             numToCopy = distance;
           }
           for (var i = scratch.length - numToCopy; i < scratch.length; i++) {
             rtn.logs.add(scratch[i]);
           }
           scratch.clear();
         } else {
           remainingCount = distance > 0 ? distance : logs.length;
         }
         if (includeKeys) {
           rtn.logs.add(keyEntry);
         }
         if (keyIterator.moveNext()) {
           keyEntry = keyIterator.current;
         } else if (isPreceding) { // We're done.
           break;
         }
       } else if (remainingCount > 0 &&
                  mockNameFilter.matches(logEntry.mockName, matchState) &&
                  logFilter(logEntry)) {
         if (scratch != null) {
           scratch.add(logEntry);
         } else {
           rtn.logs.add(logEntry);
           --remainingCount;
         }
       }
     }
     return rtn;
   }

   /**
    * Iterate through the LogEntryList looking for matches to the entries
    * in [keys]; for each match found the closest [distance] prior log entries
    * that match [mocknameFilter] and [logFilter] will be included in the result.
    * If [includeKeys] is true then the entries in [keys] that resulted in
    * entries in the output list are themselves included in the output list. If
    * [distance] is zero then all matches are included.
    *
    * The idea here is that you could find log entries that are related to
    * other logs entries in some temporal sense. For example, say we have a
    * method commit() that returns -1 on failure. Before commit() gets called
    * the value being committed is created by process(). We may want to find
    * the calls to process() that preceded calls to commit() that failed.
    * We could do this with:
    *
    *      print(log.preceding(log.getLogs(callsTo('commit'), returning(-1)),
    *          logFilter: callsTo('process')).toString());
    *
    * We might want to include the details of the failing calls to commit()
    * to see what parameters were passed in, in which case we would set
    * [includeKeys].
    *
    * As another simple example, say we wanted to know the three method
    * calls that immediately preceded each failing call to commit():
    *
    *     print(log.preceding(log.getLogs(callsTo('commit'), returning(-1)),
    *         distance: 3).toString());
    */
   LogEntryList preceding(LogEntryList keys,
                          {mockNameFilter: null,
                          logFilter: null,
                          int distance: 1,
                          bool includeKeys: false}) =>
       _neighboring(true, keys, mockNameFilter, logFilter,
           distance, includeKeys);

   /**
    * Iterate through the LogEntryList looking for matches to the entries
    * in [keys]; for each match found the closest [distance] subsequent log
    * entries that match [mocknameFilter] and [logFilter] will be included in
    * the result. If [includeKeys] is true then the entries in [keys] that
    * resulted in entries in the output list are themselves included in the
    * output list. If [distance] is zero then all matches are included.
    * See [preceding] for a usage example.
    */
   LogEntryList following(LogEntryList keys,
                          {mockNameFilter: null,
                          logFilter: null,
                          int distance: 1,
                          bool includeKeys: false}) =>
       _neighboring(false, keys, mockNameFilter, logFilter,
           distance, includeKeys);
 }

 _MockFailureHandler _mockFailureHandler = null;

 /**
  * The failure handler for the [expect()] calls that occur in [verify()]
  * methods in the mock objects. This calls the real failure handler used
  * by the unit test library after formatting the error message with
  * the custom formatter.
  */
 class _MockFailureHandler implements FailureHandler {
   FailureHandler proxy;
   _MockFailureHandler(this.proxy);
   void fail(String reason) {
     proxy.fail(reason);
   }
   void failMatch(actual, Matcher matcher, String reason,
                  Map matchState, bool verbose) {
     proxy.fail(_mockingErrorFormatter(actual, matcher, reason,
         matchState, verbose));
   }
 }

 /**
  * The error formatter for mocking is a bit different from the default one
  * for unit testing; instead of the third argument being a 'reason'
  * it is instead a [signature] describing the method signature filter
  * that was used to select the logs that were verified.
  */
 String _mockingErrorFormatter(actual, Matcher matcher, String signature,
                               Map matchState, bool verbose) {
   var description = new StringDescription();
   description.add('Expected ${signature} ').addDescriptionOf(matcher).
       add('\n     but: ');
   matcher.describeMismatch(actual, description, matchState, verbose).add('.');
   return description.toString();
 }
	// Copyright (c) 2014, 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 mock.log_entry_list;

	import 'package:matcher/matcher.dart';

	import 'call_matcher.dart';
	import 'log_entry.dart';
	import 'util.dart';

	/**
	* [StepValidator]s are used by [stepwiseValidate] in [LogEntryList], which
	* iterates through the list and call the [StepValidator] function with the
	* log [List] and position. The [StepValidator] should return the number of
	* positions to advance upon success, or zero upon failure. When zero is
	* returned an error is reported.
	*/
	typedef int StepValidator(List<LogEntry> logs, int pos);

	/**
	* We do verification on a list of [LogEntry]s. To allow chaining
	* of calls to verify, we encapsulate such a list in the [LogEntryList]
	* class.
	*/
	class LogEntryList {
	String filter;
	List<LogEntry> logs;
	LogEntryList([this.filter]) {
	logs = new List<LogEntry>();
	}

	/** Add a [LogEntry] to the log. */
	add(LogEntry entry) => logs.add(entry);

	/** Get the first entry, or null if no entries. */
	get first => (logs == null \|\| logs.length == 0) ? null : logs[0];

	/** Get the last entry, or null if no entries. */
	get last => (logs == null \|\| logs.length == 0) ? null : logs.last;

	/** Creates a LogEntry predicate function from the argument. */
	Function _makePredicate(arg) {
	if (arg == null) {
	return (e) => true;
	} else if (arg is CallMatcher) {
	return (e) => arg.matches(e.methodName, e.args);
	} else if (arg is Function) {
	return arg;
	} else {
	throw new Exception("Invalid argument to _makePredicate.");
	}
	}

	/**
	* Create a new [LogEntryList] consisting of [LogEntry]s from
	* this list that match the specified [mockNameFilter] and [logFilter].
	* [mockNameFilter] can be null, a [String], a predicate [Function],
	* or a [Matcher]. If [mockNameFilter] is null, this is the same as
	* [anything].
	* If [logFilter] is null, all entries in the log will be returned.
	* Otherwise [logFilter] should be a [CallMatcher] or predicate function
	* that takes a [LogEntry] and returns a bool.
	* If [destructive] is true, the log entries are removed from the
	* original list.
	*/
	LogEntryList getMatches([mockNameFilter,
	logFilter,
	Matcher actionMatcher,
	bool destructive = false]) {
	if (mockNameFilter == null) {
	mockNameFilter = anything;
	} else {
	mockNameFilter = wrapMatcher(mockNameFilter);
	}
	Function entryFilter = _makePredicate(logFilter);
	String filterName = qualifiedName(mockNameFilter, logFilter.toString());
	LogEntryList rtn = new LogEntryList(filterName);
	var matchState = {};
	for (var i = 0; i < logs.length; i++) {
	LogEntry entry = logs[i];
	if (mockNameFilter.matches(entry.mockName, matchState) &&
	entryFilter(entry)) {
	if (actionMatcher == null \|\|
	actionMatcher.matches(entry, matchState)) {
	rtn.add(entry);
	if (destructive) {
	int startIndex = i--;
	logs.removeRange(startIndex, startIndex + 1);
	}
	}
	}
	}
	return rtn;
	}

	/** Apply a unit test [Matcher] to the [LogEntryList]. */
	LogEntryList verify(Matcher matcher) {
	if (_mockFailureHandler == null) {
	_mockFailureHandler =
	new _MockFailureHandler(getOrCreateExpectFailureHandler());
	}
	expect(logs, matcher, reason: filter, failureHandler: _mockFailureHandler);
	return this;
	}

	/**
	* Iterate through the list and call the [validator] function with the
	* log [List] and position. The [validator] should return the number of
	* positions to advance upon success, or zero upon failure. When zero is
	* returned an error is reported. [reason] can be used to provide a
	* more descriptive failure message. If a failure occurred false will be
	* returned (unless the failure handler itself threw an exception);
	* otherwise true is returned.
	* The use case here is to perform more complex validations; for example
	* we may want to assert that the return value from some function is
	* later used as a parameter to a following function. If we filter the logs
	* to include just these two functions we can write a simple validator to
	* do this check.
	*/
	bool stepwiseValidate(StepValidator validator, [String reason = '']) {
	if (_mockFailureHandler == null) {
	_mockFailureHandler =
	new _MockFailureHandler(getOrCreateExpectFailureHandler());
	}
	var i = 0;
	while (i < logs.length) {
	var n = validator(logs, i);
	if (n == 0) {
	if (reason.length > 0) {
	reason = ': $reason';
	}
	_mockFailureHandler.fail("Stepwise validation failed at $filter "
	"position $i$reason");
	return false;
	} else {
	i += n;
	}
	}
	return true;
	}

	/**
	* Turn the logs into human-readable text. If [baseTime] is specified
	* then each entry is prefixed with the offset from that time in
	* milliseconds; otherwise the time of day is used.
	*/
	String toString([DateTime baseTime]) {
	String s = '';
	for (var e in logs) {
	s = '$s${e.toString(baseTime)}\n';
	}
	return s;
	}

	/**
	* Find the first log entry that satisfies [logFilter] and
	* return its position. A search [start] position can be provided
	* to allow for repeated searches. [logFilter] can be a [CallMatcher],
	* or a predicate function that takes a [LogEntry] argument and returns
	* a bool. If [logFilter] is null, it will match any [LogEntry].
	* If no entry is found, then [failureReturnValue] is returned.
	* After each check the position is updated by [skip], so using
	* [skip] of -1 allows backward searches, using a [skip] of 2 can
	* be used to check pairs of adjacent entries, and so on.
	*/
	int findLogEntry(logFilter, [int start = 0, int failureReturnValue = -1,
	skip = 1]) {
	logFilter = _makePredicate(logFilter);
	int pos = start;
	while (pos >= 0 && pos < logs.length) {
	if (logFilter(logs[pos])) {
	return pos;
	}
	pos += skip;
	}
	return failureReturnValue;
	}

	/**
	* Returns log events that happened up to the first one that
	* satisfies [logFilter]. If [inPlace] is true, then returns
	* this LogEntryList after removing the from the first satisfier;
	* onwards otherwise a new list is created. [description]
	* is used to create a new name for the resulting list.
	* [defaultPosition] is used as the index of the matching item in
	* the case that no match is found.
	*/
	LogEntryList _head(logFilter, bool inPlace,
	String description, int defaultPosition) {
	if (filter != null) {
	description = '$filter $description';
	}
	int pos = findLogEntry(logFilter, 0, defaultPosition);
	if (inPlace) {
	if (pos < logs.length) {
	logs.removeRange(pos, logs.length);
	}
	filter = description;
	return this;
	} else {
	LogEntryList newList = new LogEntryList(description);
	for (var i = 0; i < pos; i++) {
	newList.logs.add(logs[i]);
	}
	return newList;
	}
	}

	/**
	* Returns log events that happened from the first one that
	* satisfies [logFilter]. If [inPlace] is true, then returns
	* this LogEntryList after removing the entries up to the first
	* satisfier; otherwise a new list is created. [description]
	* is used to create a new name for the resulting list.
	* [defaultPosition] is used as the index of the matching item in
	* the case that no match is found.
	*/
	LogEntryList _tail(logFilter, bool inPlace,
	String description, int defaultPosition) {
	if (filter != null) {
	description = '$filter $description';
	}
	int pos = findLogEntry(logFilter, 0, defaultPosition);
	if (inPlace) {
	if (pos > 0) {
	logs.removeRange(0, pos);
	}
	filter = description;
	return this;
	} else {
	LogEntryList newList = new LogEntryList(description);
	while (pos < logs.length) {
	newList.logs.add(logs[pos++]);
	}
	return newList;
	}
	}

	/**
	* Returns log events that happened after [when]. If [inPlace]
	* is true, then it returns this LogEntryList after removing
	* the entries that happened up to [when]; otherwise a new
	* list is created.
	*/
	LogEntryList after(DateTime when, [bool inPlace = false]) =>
	_tail((e) => e.time.isAfter(when), inPlace, 'after $when', logs.length);

	/**
	* Returns log events that happened from [when] onwards. If
	* [inPlace] is true, then it returns this LogEntryList after
	* removing the entries that happened before [when]; otherwise
	* a new list is created.
	*/
	LogEntryList from(DateTime when, [bool inPlace = false]) =>
	_tail((e) => !e.time.isBefore(when), inPlace, 'from $when', logs.length);

	/**
	* Returns log events that happened until [when]. If [inPlace]
	* is true, then it returns this LogEntryList after removing
	* the entries that happened after [when]; otherwise a new
	* list is created.
	*/
	LogEntryList until(DateTime when, [bool inPlace = false]) =>
	_head((e) => e.time.isAfter(when), inPlace, 'until $when', logs.length);

	/**
	* Returns log events that happened before [when]. If [inPlace]
	* is true, then it returns this LogEntryList after removing
	* the entries that happened from [when] onwards; otherwise a new
	* list is created.
	*/
	LogEntryList before(DateTime when, [bool inPlace = false]) =>
	_head((e) => !e.time.isBefore(when),
	inPlace,
	'before $when',
	logs.length);

	/**
	* Returns log events that happened after [logEntry]'s time.
	* If [inPlace] is true, then it returns this LogEntryList after
	* removing the entries that happened up to [when]; otherwise a new
	* list is created. If [logEntry] is null the current time is used.
	*/
	LogEntryList afterEntry(LogEntry logEntry, [bool inPlace = false]) =>
	after(logEntry == null ? new DateTime.now() : logEntry.time);

	/**
	* Returns log events that happened from [logEntry]'s time onwards.
	* If [inPlace] is true, then it returns this LogEntryList after
	* removing the entries that happened before [when]; otherwise
	* a new list is created. If [logEntry] is null the current time is used.
	*/
	LogEntryList fromEntry(LogEntry logEntry, [bool inPlace = false]) =>
	from(logEntry == null ? new DateTime.now() : logEntry.time);

	/**
	* Returns log events that happened until [logEntry]'s time. If
	* [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened after [when]; otherwise a new
	* list is created. If [logEntry] is null the epoch time is used.
	*/
	LogEntryList untilEntry(LogEntry logEntry, [bool inPlace = false]) =>
	until(logEntry == null ?
	new DateTime.fromMillisecondsSinceEpoch(0) : logEntry.time);

	/**
	* Returns log events that happened before [logEntry]'s time. If
	* [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened from [when] onwards; otherwise a new
	* list is created. If [logEntry] is null the epoch time is used.
	*/
	LogEntryList beforeEntry(LogEntry logEntry, [bool inPlace = false]) =>
	before(logEntry == null ?
	new DateTime.fromMillisecondsSinceEpoch(0) : logEntry.time);

	/**
	* Returns log events that happened after the first event in [segment].
	* If [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened earlier; otherwise a new list is created.
	*/
	LogEntryList afterFirst(LogEntryList segment, [bool inPlace = false]) =>
	afterEntry(segment.first, inPlace);

	/**
	* Returns log events that happened after the last event in [segment].
	* If [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened earlier; otherwise a new list is created.
	*/
	LogEntryList afterLast(LogEntryList segment, [bool inPlace = false]) =>
	afterEntry(segment.last, inPlace);

	/**
	* Returns log events that happened from the time of the first event in
	* [segment] onwards. If [inPlace] is true, then it returns this
	* LogEntryList after removing the earlier entries; otherwise a new list
	* is created.
	*/
	LogEntryList fromFirst(LogEntryList segment, [bool inPlace = false]) =>
	fromEntry(segment.first, inPlace);

	/**
	* Returns log events that happened from the time of the last event in
	* [segment] onwards. If [inPlace] is true, then it returns this
	* LogEntryList after removing the earlier entries; otherwise a new list
	* is created.
	*/
	LogEntryList fromLast(LogEntryList segment, [bool inPlace = false]) =>
	fromEntry(segment.last, inPlace);

	/**
	* Returns log events that happened until the first event in [segment].
	* If [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened later; otherwise a new list is created.
	*/
	LogEntryList untilFirst(LogEntryList segment, [bool inPlace = false]) =>
	untilEntry(segment.first, inPlace);

	/**
	* Returns log events that happened until the last event in [segment].
	* If [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened later; otherwise a new list is created.
	*/
	LogEntryList untilLast(LogEntryList segment, [bool inPlace = false]) =>
	untilEntry(segment.last, inPlace);

	/**
	* Returns log events that happened before the first event in [segment].
	* If [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened later; otherwise a new list is created.
	*/
	LogEntryList beforeFirst(LogEntryList segment, [bool inPlace = false]) =>
	beforeEntry(segment.first, inPlace);

	/**
	* Returns log events that happened before the last event in [segment].
	* If [inPlace] is true, then it returns this LogEntryList after removing
	* the entries that happened later; otherwise a new list is created.
	*/
	LogEntryList beforeLast(LogEntryList segment, [bool inPlace = false]) =>
	beforeEntry(segment.last, inPlace);

	/**
	* Iterate through the LogEntryList looking for matches to the entries
	* in [keys]; for each match found the closest [distance] neighboring log
	* entries that match [mockNameFilter] and [logFilter] will be included in
	* the result. If [isPreceding] is true we use the neighbors that precede
	* the matched entry; else we use the neighbors that followed.
	* If [includeKeys] is true then the entries in [keys] that resulted in
	* entries in the output list are themselves included in the output list. If
	* [distance] is zero then all matches are included.
	*/
	LogEntryList _neighboring(bool isPreceding,
	LogEntryList keys,
	mockNameFilter,
	logFilter,
	int distance,
	bool includeKeys) {
	String filterName = 'Calls to '
	'${qualifiedName(mockNameFilter, logFilter.toString())} '
	'${isPreceding?"preceding":"following"} ${keys.filter}';

	LogEntryList rtn = new LogEntryList(filterName);

	// Deal with the trivial case.
	if (logs.length == 0 \|\| keys.logs.length == 0) {
	return rtn;
	}

	// Normalize the mockNameFilter and logFilter values.
	if (mockNameFilter == null) {
	mockNameFilter = anything;
	} else {
	mockNameFilter = wrapMatcher(mockNameFilter);
	}
	logFilter = _makePredicate(logFilter);

	// The scratch list is used to hold matching entries when we
	// are doing preceding neighbors. The remainingCount is used to
	// keep track of how many matching entries we can still add in the
	// current segment (0 if we are doing doing following neighbors, until
	// we get our first key match).
	List scratch = null;
	int remainingCount = 0;
	if (isPreceding) {
	scratch = new List();
	remainingCount = logs.length;
	}

	var keyIterator = keys.logs.iterator;
	keyIterator.moveNext();
	LogEntry keyEntry = keyIterator.current;
	Map matchState = {};

	for (LogEntry logEntry in logs) {
	// If we have a log entry match, copy the saved matches from the
	// scratch buffer into the return list, as well as the matching entry,
	// if appropriate, and reset the scratch buffer. Continue processing
	// from the next key entry.
	if (keyEntry == logEntry) {
	if (scratch != null) {
	int numToCopy = scratch.length;
	if (distance > 0 && distance < numToCopy) {
	numToCopy = distance;
	}
	for (var i = scratch.length - numToCopy; i < scratch.length; i++) {
	rtn.logs.add(scratch[i]);
	}
	scratch.clear();
	} else {
	remainingCount = distance > 0 ? distance : logs.length;
	}
	if (includeKeys) {
	rtn.logs.add(keyEntry);
	}
	if (keyIterator.moveNext()) {
	keyEntry = keyIterator.current;
	} else if (isPreceding) { // We're done.
	break;
	}
	} else if (remainingCount > 0 &&
	mockNameFilter.matches(logEntry.mockName, matchState) &&
	logFilter(logEntry)) {
	if (scratch != null) {
	scratch.add(logEntry);
	} else {
	rtn.logs.add(logEntry);
	--remainingCount;
	}
	}
	}
	return rtn;
	}

	/**
	* Iterate through the LogEntryList looking for matches to the entries
	* in [keys]; for each match found the closest [distance] prior log entries
	* that match [mocknameFilter] and [logFilter] will be included in the result.
	* If [includeKeys] is true then the entries in [keys] that resulted in
	* entries in the output list are themselves included in the output list. If
	* [distance] is zero then all matches are included.
	*
	* The idea here is that you could find log entries that are related to
	* other logs entries in some temporal sense. For example, say we have a
	* method commit() that returns -1 on failure. Before commit() gets called
	* the value being committed is created by process(). We may want to find
	* the calls to process() that preceded calls to commit() that failed.
	* We could do this with:
	*
	* print(log.preceding(log.getLogs(callsTo('commit'), returning(-1)),
	* logFilter: callsTo('process')).toString());
	*
	* We might want to include the details of the failing calls to commit()
	* to see what parameters were passed in, in which case we would set
	* [includeKeys].
	*
	* As another simple example, say we wanted to know the three method
	* calls that immediately preceded each failing call to commit():
	*
	* print(log.preceding(log.getLogs(callsTo('commit'), returning(-1)),
	* distance: 3).toString());
	*/
	LogEntryList preceding(LogEntryList keys,
	{mockNameFilter: null,
	logFilter: null,
	int distance: 1,
	bool includeKeys: false}) =>
	_neighboring(true, keys, mockNameFilter, logFilter,
	distance, includeKeys);

	/**
	* Iterate through the LogEntryList looking for matches to the entries
	* in [keys]; for each match found the closest [distance] subsequent log
	* entries that match [mocknameFilter] and [logFilter] will be included in
	* the result. If [includeKeys] is true then the entries in [keys] that
	* resulted in entries in the output list are themselves included in the
	* output list. If [distance] is zero then all matches are included.
	* See [preceding] for a usage example.
	*/
	LogEntryList following(LogEntryList keys,
	{mockNameFilter: null,
	logFilter: null,
	int distance: 1,
	bool includeKeys: false}) =>
	_neighboring(false, keys, mockNameFilter, logFilter,
	distance, includeKeys);
	}

	_MockFailureHandler _mockFailureHandler = null;

	/**
	* The failure handler for the [expect()] calls that occur in [verify()]
	* methods in the mock objects. This calls the real failure handler used
	* by the unit test library after formatting the error message with
	* the custom formatter.
	*/
	class _MockFailureHandler implements FailureHandler {
	FailureHandler proxy;
	_MockFailureHandler(this.proxy);
	void fail(String reason) {
	proxy.fail(reason);
	}
	void failMatch(actual, Matcher matcher, String reason,
	Map matchState, bool verbose) {
	proxy.fail(_mockingErrorFormatter(actual, matcher, reason,
	matchState, verbose));
	}
	}

	/**
	* The error formatter for mocking is a bit different from the default one
	* for unit testing; instead of the third argument being a 'reason'
	* it is instead a [signature] describing the method signature filter
	* that was used to select the logs that were verified.
	*/
	String _mockingErrorFormatter(actual, Matcher matcher, String signature,
	Map matchState, bool verbose) {
	var description = new StringDescription();
	description.add('Expected ${signature} ').addDescriptionOf(matcher).
	add('\n but: ');
	matcher.describeMismatch(actual, description, matchState, verbose).add('.');
	return description.toString();
	}