Add toMap / toMapOf / toList

pkg/analyzer/lib/task/model.dart

 // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file

[Brian Wilkerson, 2015/03/24 15:07:11]

This needs to be sorted.

[scheglov, 2015/03/24 17:16:39]

Done.

 // 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 analyzer.task.model;
 
 import 'dart:collection';
 
 import 'package:analyzer/src/generated/engine.dart' hide AnalysisTask;
 import 'package:analyzer/src/generated/java_engine.dart';
 import 'package:analyzer/src/generated/source.dart';
 import 'package:analyzer/src/task/model.dart';
 
 /**
  * A function that takes an analysis [context] and an analysis [target] and
  * returns an analysis task. Such functions are passed to a [TaskDescriptor] to
  * be used to create the described task.
  */
 typedef AnalysisTask BuildTask(AnalysisContext context, AnalysisTarget target);
 
 /**
  * A function that takes the target for which a task will produce results and
  * returns a map from input names to descriptions of the analysis results needed
  * by the task in order for the task to be performed. Such functions are passed
  * to a [TaskDescriptor] to be used to determine the inputs needed by the task.
  */
 typedef Map<String, TaskInput> CreateTaskInputs(AnalysisTarget target);
 
 /**
+ * A function that converts an object of the type [B] into a [TaskInput].
+ * This is used, for example, by a [ListTaskInput] to create task inputs
+ * for each value in a list of values.
+ */
+typedef TaskInput<E> MapTaskInput<B, E>(B object);

[Brian Wilkerson, 2015/03/24 15:07:11]

The name makes it sound like this function is mapping a TaskInput to something
else, but it isn't. Given the comments below, perhaps the best path is some
incredibly generic name, like UnaryFunction (or getting rid of it entirely).

[scheglov, 2015/03/24 17:16:39]

MapToTaskInput ?
ToTaskInput ?

UnaryFunction for now.

+
+/**
  * An [AnalysisTarget] wrapper for an [AnalysisContext].
  */
 class AnalysisContextTarget implements AnalysisTarget {
   static final AnalysisContextTarget request = new AnalysisContextTarget(null);
 
   final AnalysisContext context;
 
   AnalysisContextTarget(this.context);
 
   @override
@@ skipping 197 matching lines @@
   /**
    * Return a list containing the descriptors of the results that are unioned
    * together to compose the value of this result.
    *
    * Clients must not modify the returned list.
    */
   List<ResultDescriptor<V>> get contributors;
 }
 
 /**
+ * A description of a [List]-based analysis result that can be computed by an
+ * [AnalysisTask].
+ *
+ * Clients are not expected to subtype this class.
+ */
+abstract class ListResultDescriptor<E> implements ResultDescriptor<List<E>> {
+  /**
+   * Initialize a newly created analysis result to have the given [name]. If a
+   * composite result is specified, then this result will contribute to it.
+   */
+  factory ListResultDescriptor(String name, List<E> defaultValue,
+      {CompositeResultDescriptor<List<E>> contributesTo}) = ListResultDescriptorImpl<E>;
+
+  @override
+  ListTaskInput<E> of(AnalysisTarget target);
+}
+
+
+/**
+ * A description of an input to an [AnalysisTask] that can be used to compute
+ * that input.
+ *
+ * Clients are not expected to subtype this class.
+ */
+abstract class ListTaskInput<E> extends TaskInput<List<E>> {
+  /**
+   * Create and return a builder that can be used to build this task input.
+   */
+  TaskInputBuilder<List<E>> createBuilder();

[Brian Wilkerson, 2015/03/24 15:07:10]

We shouldn't need to override this method, but if we do we should mark it as
@override and remove the comment.

[scheglov, 2015/03/24 17:16:39]

Done.

+
+  /**
+   * Return a task input that can be used to compute a map of elements of
+   * this input into some other objects.

[Brian Wilkerson, 2015/03/24 15:07:11]

Perhaps:

Return a task input that can be used to compute a map whose keys are the
elements of this input and whose values are the result of passing the
corresponding key to the [mapper] function.

[scheglov, 2015/03/24 17:16:39]

Done.

+   */
+  TaskInput<Map<E, Object>> toMap(MapTaskInput mapper);

[Brian Wilkerson, 2015/03/24 15:07:11]

Given that MapTaskInput returns a TaskInput, shouldn't this be "TaskInput<Map<E,
TaskInput>>"?

But the bigger question is, why restrict clients to building a map whose values
are task inputs? Why not allow a Map<AnalysisTarget, SourceKind>, for example?
Perhaps MapTaskInput should be defined as

typedef R MapTaskInput<P, R>(P parameter);

and someday this method could be

TaskInput<Map<E, R>> toMap<R>(MapTaskInput<E, R> f);

[scheglov, 2015/03/24 17:16:39]

  Not quite.
  It's final result is Map<E, V>, where V is result of TaskInput<V>, which is
created be the mapper.
  Well, toMap() and toMapOf() are used to create specifically
ListToMapTaskInput, which expects "TaskInput<E> GenerateTaskInputs<B, E>(B
object)", so we need the mapper to return TaskInput.

  While it would be nice to have a general case mapping, it is not strongly
required be implementation.
  We can do other kinds of mappings in a task itself.
  But when we want values of a TaskInputs, this requiring looking into a
CacheEntry, so it should be done externally, and cannot be done inside of a
task.

  There is also no a good way (without using mirrors) to distinguish between
mappers returning TaskInput(s) or final values.

+
+  /**
+   * Return a task input that can be used to compute an object for each element
+   * of this input.

[Brian Wilkerson, 2015/03/24 15:07:11]

Perhaps:

Return a task input that can be used to compute a list whose elements are the
result of passing the elements of this input to the [mapper] function.

[scheglov, 2015/03/24 17:16:39]

Done.

+   */
+  TaskInput<List> toList(MapTaskInput mapper);

[Brian Wilkerson, 2015/03/24 15:07:11]

Return ListTaskInput, so that they can be chained?

[scheglov, 2015/03/24 17:16:39]

Later.

+
+  /**
+   * Return a task input that can be used to compute a map of elements of
+   * this input into [valueResult]s.

[Brian Wilkerson, 2015/03/24 15:07:11]

Perhaps:

Return a task input that can be used to compute a map whose keys are the
elements of this input and whose values are the [valueResult]'s associated with
those elements.

[scheglov, 2015/03/24 17:16:39]

Done.

+   */
+  TaskInput<Map<E, Object>> toMapOf(ResultDescriptor valueResult);
+}

[Brian Wilkerson, 2015/03/24 15:07:11]

Seems like a corresponding method would be good:

ListTaskInput/*<E>*/ toListOf/*<E>*/(ResultDescriptor/*<E>*/ result);

[scheglov, 2015/03/24 17:16:39]

Done.

+
+
+/**
  * A description of an analysis result that can be computed by an [AnalysisTask].
  *
  * Clients are not expected to subtype this class.
  */
 abstract class ResultDescriptor<V> {
   /**
    * Initialize a newly created analysis result to have the given [name]. If a
    * composite result is specified, then this result will contribute to it.
    */
   factory ResultDescriptor(String name, V defaultValue,
       {CompositeResultDescriptor<V> contributesTo}) = ResultDescriptorImpl;
 
   /**
    * Return the default value for results described by this descriptor.
    */
   V get defaultValue;
 
   /**
    * Return the name of this descriptor.
    */
   String get name;
 
   /**
    * Return a task input that can be used to compute this result for the given
    * [target].
    */
-  TaskInput<V> inputFor(AnalysisTarget target);
+  TaskInput<V> of(AnalysisTarget target);
 }
 
 /**
  * A description of an [AnalysisTask].
  */
 abstract class TaskDescriptor {
   /**
    * Initialize a newly created task descriptor to have the given [name] and to
    * describe a task that takes the inputs built using the given [inputBuilder],
    * and produces the given [results]. The [buildTask] will be used to create
@@ skipping 90 matching lines @@
    * be computed, or `false` if the inputs have been computed.
    *
    * It is safe to invoke [moveNext] after it has returned `false`. In this case
    * [moveNext] has no effect and will again return `false`.
    *
    * Throws a [StateError] if the value of the current result has not been
    * provided using [currentValue].
    */
   bool moveNext();
 }