[unified_analytics] Add Dash ENV var utils

Author: pq

pkgs/unified_analytics/lib/src/enums.dart

@@ -6,6 +6,18 @@
 List<String> get validDashTools =>
     DashTool.values.map((e) => e.label).toList()..sort();
 
+/// Environment variables used by the unified analytics package.
+enum DashEnvVar {
+  /// Environment variable used to suppress analytics.
+  suppressAnalytics('DASH__SUPPRESS_ANALYTICS'),
+
+  /// Environment variable used to specify the top-level tool.
+  tool('DASH__TOOL');
+
+  final String name;
+  const DashEnvVar(this.name);
+}
+
 /// Values for the event name to be sent to Google Analytics.
 ///
 /// The [label] for each enum value is what will be logged, the [description]

pkgs/unified_analytics/lib/src/utils.dart

@@ -35,6 +35,35 @@ bool checkDirectoryForWritePermissions(Directory directory) {
   return fileStat.modeString()[1] == 'w';
 }
 
+/// Compute whether to suppress analytics based on the environment variable
+/// `DASH__SUPPRESS_ANALYTICS`.
+///
+/// If the environment variable is set and not "false", return the
+/// corresponding boolean value. Otherwise, return the [defaultValue].
+bool computeSuppressAnalytics({bool defaultValue = false}) =>
+    bool.fromEnvironment(
+      DashEnvVar.suppressAnalytics.name,
+      defaultValue: defaultValue,
+    );
+
+/// Compute the top-level tool from the environment variable `DASH__TOOL`.
+///
+/// If the environment variable is set and valid, return the corresponding
+/// [DashTool]. Otherwise, return the [current] tool.
+DashTool computeTopLevelTool(DashTool current) {
+  final toolValue = io.Platform.environment[DashEnvVar.tool.name];
+  if (toolValue != null) {
+    try {
+      return DashTool.fromLabel(toolValue);
+    } on Exception {
+      // Fallback to `current` if the value in ENV is invalid.
+      // todo(pq): do we need better error handling here?
+    }
+  }
+
+  return current;
+}
+
 /// Format time as 'yyyy-MM-dd HH:mm:ss Z' where Z is the difference between the
 /// timezone of t and UTC formatted according to RFC 822.
 String formatDateTime(DateTime t) {

pkgs/unified_analytics/lib/unified_analytics.dart

@@ -4,8 +4,9 @@
 
 export 'src/analytics.dart' show Analytics, FakeAnalytics, NoOpAnalytics;
 export 'src/config_handler.dart' show ToolInfo;
-export 'src/enums.dart' show DashTool;
+export 'src/enums.dart' show DashEnvVar, DashTool;
 export 'src/event.dart' show CustomMetrics, Event;
 export 'src/log_handler.dart' show LogFileStats;
 export 'src/survey_handler.dart' show Survey, SurveyButton, SurveyHandler;
-export 'src/utils.dart' show parseDartSDKVersion;
+export 'src/utils.dart'
+    show computeSuppressAnalytics, computeTopLevelTool, parseDartSDKVersion;