utils.dart 15.7 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:async';
6
import 'dart:math' as math;
Devon Carew's avatar
Devon Carew committed
7

8
import 'package:intl/intl.dart';
9
import 'package:file/file.dart';
10
import 'package:path/path.dart' as path; // flutter_ignore: package_path_import
Devon Carew's avatar
Devon Carew committed
11

12
import '../convert.dart';
13

14 15 16
/// A path jointer for URL paths.
final path.Context urlContext = path.url;

17 18 19 20 21 22 23 24 25 26 27 28
/// Convert `foo_bar` to `fooBar`.
String camelCase(String str) {
  int index = str.indexOf('_');
  while (index != -1 && index < str.length - 2) {
    str = str.substring(0, index) +
      str.substring(index + 1, index + 2).toUpperCase() +
      str.substring(index + 2);
    index = str.indexOf('_');
  }
  return str;
}

29
final RegExp _upperRegex = RegExp(r'[A-Z]');
30 31

/// Convert `fooBar` to `foo_bar`.
32
String snakeCase(String str, [ String sep = '_' ]) {
33
  return str.replaceAllMapped(_upperRegex,
34
      (Match m) => '${m.start == 0 ? '' : sep}${m[0]!.toLowerCase()}');
35 36
}

37
String toTitleCase(String str) {
38
  if (str.isEmpty) {
39
    return str;
40
  }
41 42 43
  return str.substring(0, 1).toUpperCase() + str.substring(1);
}

44 45 46
/// Return the plural of the given word (`cat(s)`).
String pluralize(String word, int count) => count == 1 ? word : word + 's';

47 48
/// Return the name of an enum item.
String getEnumName(dynamic enumItem) {
49 50
  final String name = '$enumItem';
  final int index = name.indexOf('.');
51 52 53
  return index == -1 ? name : name.substring(index + 1);
}

54
String toPrettyJson(Object jsonable) {
55
  return const JsonEncoder.withIndent('  ').convert(jsonable) + '\n';
56 57
}

58 59
final NumberFormat kSecondsFormat = NumberFormat('0.0');
final NumberFormat kMillisecondsFormat = NumberFormat.decimalPattern();
60 61

String getElapsedAsSeconds(Duration duration) {
62
  final double seconds = duration.inMilliseconds / Duration.millisecondsPerSecond;
63 64 65 66 67 68
  return '${kSecondsFormat.format(seconds)}s';
}

String getElapsedAsMilliseconds(Duration duration) {
  return '${kMillisecondsFormat.format(duration.inMilliseconds)}ms';
}
69

70 71 72
/// Return a String - with units - for the size in MB of the given number of bytes.
String getSizeAsMB(int bytesLength) {
  return '${(bytesLength / (1024 * 1024)).toStringAsFixed(1)}MB';
73 74
}

75 76 77 78
/// A class to maintain a list of items, fire events when items are added or
/// removed, and calculate a diff of changes when a new list of items is
/// available.
class ItemListNotifier<T> {
79
  ItemListNotifier(): _items = <T>{};
80

81
  ItemListNotifier.from(List<T> items) : _items = Set<T>.of(items);
82 83 84

  Set<T> _items;

85 86
  final StreamController<T> _addedController = StreamController<T>.broadcast();
  final StreamController<T> _removedController = StreamController<T>.broadcast();
87 88 89 90 91 92 93

  Stream<T> get onAdded => _addedController.stream;
  Stream<T> get onRemoved => _removedController.stream;

  List<T> get items => _items.toList();

  void updateWithNewList(List<T> updatedList) {
94
    final Set<T> updatedSet = Set<T>.of(updatedList);
95

96 97
    final Set<T> addedItems = updatedSet.difference(_items);
    final Set<T> removedItems = _items.difference(updatedSet);
98 99 100

    _items = updatedSet;

101 102
    addedItems.forEach(_addedController.add);
    removedItems.forEach(_removedController.add);
103 104
  }

105 106 107 108 109 110
  void removeItem(T item) {
    if (_items.remove(item)) {
      _removedController.add(item);
    }
  }

111 112 113 114 115 116
  /// Close the streams.
  void dispose() {
    _addedController.close();
    _removedController.close();
  }
}
117 118

class SettingsFile {
119 120
  SettingsFile();

121 122 123
  SettingsFile.parse(String contents) {
    for (String line in contents.split('\n')) {
      line = line.trim();
124
      if (line.startsWith('#') || line.isEmpty) {
125
        continue;
126
      }
127
      final int index = line.indexOf('=');
128
      if (index != -1) {
129
        values[line.substring(0, index)] = line.substring(index + 1);
130
      }
131 132 133 134
    }
  }

  factory SettingsFile.parseFromFile(File file) {
135
    return SettingsFile.parse(file.readAsStringSync());
136 137 138 139 140
  }

  final Map<String, String> values = <String, String>{};

  void writeContents(File file) {
141
    file.parent.createSync(recursive: true);
142
    file.writeAsStringSync(values.keys.map<String>((String key) {
143 144 145 146
      return '$key=${values[key]}';
    }).join('\n'));
  }
}
147

148 149
/// Given a data structure which is a Map of String to dynamic values, return
/// the same structure (`Map<String, dynamic>`) with the correct runtime types.
150 151
Map<String, dynamic>? castStringKeyedMap(dynamic untyped) {
  final Map<dynamic, dynamic>? map = untyped as Map<dynamic, dynamic>?;
152
  return map?.cast<String, dynamic>();
153 154
}

155 156 157 158 159 160
/// Smallest column that will be used for text wrapping. If the requested column
/// width is smaller than this, then this is what will be used.
const int kMinColumnWidth = 10;

/// Wraps a block of text into lines no longer than [columnWidth].
///
161 162 163 164
/// Tries to split at whitespace, but if that's not good enough to keep it under
/// the limit, then it splits in the middle of a word. If [columnWidth] (minus
/// any indent) is smaller than [kMinColumnWidth], the text is wrapped at that
/// [kMinColumnWidth] instead.
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
///
/// Preserves indentation (leading whitespace) for each line (delimited by '\n')
/// in the input, and will indent wrapped lines that same amount, adding
/// [indent] spaces in addition to any existing indent.
///
/// If [hangingIndent] is supplied, then that many additional spaces will be
/// added to each line, except for the first line. The [hangingIndent] is added
/// to the specified [indent], if any. This is useful for wrapping
/// text with a heading prefix (e.g. "Usage: "):
///
/// ```dart
/// String prefix = "Usage: ";
/// print(prefix + wrapText(invocation, indent: 2, hangingIndent: prefix.length, columnWidth: 40));
/// ```
///
/// yields:
/// ```
///   Usage: app main_command <subcommand>
///          [arguments]
/// ```
///
/// If [columnWidth] is not specified, then the column width will be the
/// [outputPreferences.wrapColumn], which is set with the --wrap-column option.
///
/// If [outputPreferences.wrapText] is false, then the text will be returned
190 191
/// unchanged. If [shouldWrap] is specified, then it overrides the
/// [outputPreferences.wrapText] setting.
192
///
193 194 195
/// If the amount of indentation (from the text, [indent], and [hangingIndent])
/// is such that less than [kMinColumnWidth] characters can fit in the
/// [columnWidth], then the indent is truncated to allow the text to fit.
196
String wrapText(String text, {
197 198 199 200
  required int columnWidth,
  required bool shouldWrap,
  int? hangingIndent,
  int? indent,
201
}) {
202
  assert(columnWidth >= 0);
203 204 205 206 207 208 209
  if (text == null || text.isEmpty) {
    return '';
  }
  indent ??= 0;
  hangingIndent ??= 0;
  final List<String> splitText = text.split('\n');
  final List<String> result = <String>[];
210
  for (final String line in splitText) {
211 212 213 214 215 216 217 218 219
    String trimmedText = line.trimLeft();
    final String leadingWhitespace = line.substring(0, line.length - trimmedText.length);
    List<String> notIndented;
    if (hangingIndent != 0) {
      // When we have a hanging indent, we want to wrap the first line at one
      // width, and the rest at another (offset by hangingIndent), so we wrap
      // them twice and recombine.
      final List<String> firstLineWrap = _wrapTextAsLines(
        trimmedText,
220
        columnWidth: columnWidth - leadingWhitespace.length - indent,
221
        shouldWrap: shouldWrap,
222 223 224
      );
      notIndented = <String>[firstLineWrap.removeAt(0)];
      trimmedText = trimmedText.substring(notIndented[0].length).trimLeft();
225
      if (trimmedText.isNotEmpty) {
226 227
        notIndented.addAll(_wrapTextAsLines(
          trimmedText,
228
          columnWidth: columnWidth - leadingWhitespace.length - indent - hangingIndent,
229
          shouldWrap: shouldWrap,
230 231 232 233 234
        ));
      }
    } else {
      notIndented = _wrapTextAsLines(
        trimmedText,
235
        columnWidth: columnWidth - leadingWhitespace.length - indent,
236
        shouldWrap: shouldWrap,
237 238
      );
    }
239
    String? hangingIndentString;
240
    final String indentString = ' ' * indent;
241
    result.addAll(notIndented.map<String>(
242 243 244 245 246
      (String line) {
        // Don't return any lines with just whitespace on them.
        if (line.isEmpty) {
          return '';
        }
247 248 249 250 251
        String truncatedIndent = '$indentString${hangingIndentString ?? ''}$leadingWhitespace';
        if (truncatedIndent.length > columnWidth - kMinColumnWidth) {
          truncatedIndent = truncatedIndent.substring(0, math.max(columnWidth - kMinColumnWidth, 0));
        }
        final String result = '$truncatedIndent$line';
252
        hangingIndentString ??= ' ' * hangingIndent!;
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
        return result;
      },
    ));
  }
  return result.join('\n');
}

// Used to represent a run of ANSI control sequences next to a visible
// character.
class _AnsiRun {
  _AnsiRun(this.original, this.character);

  String original;
  String character;
}

/// Wraps a block of text into lines no longer than [columnWidth], starting at the
/// [start] column, and returning the result as a list of strings.
///
/// Tries to split at whitespace, but if that's not good enough to keep it
/// under the limit, then splits in the middle of a word. Preserves embedded
/// newlines, but not indentation (it trims whitespace from each line).
///
/// If [columnWidth] is not specified, then the column width will be the width of the
/// terminal window by default. If the stdout is not a terminal window, then the
/// default will be [outputPreferences.wrapColumn].
///
280 281 282
/// The [columnWidth] is clamped to [kMinColumnWidth] at minimum (so passing negative
/// widths is fine, for instance).
///
283
/// If [outputPreferences.wrapText] is false, then the text will be returned
284 285
/// simply split at the newlines, but not wrapped. If [shouldWrap] is specified,
/// then it overrides the [outputPreferences.wrapText] setting.
286 287
List<String> _wrapTextAsLines(String text, {
  int start = 0,
288 289
  required int columnWidth,
  required bool shouldWrap,
290
}) {
291 292 293 294 295 296 297 298 299 300 301
  if (text == null || text.isEmpty) {
    return <String>[''];
  }
  assert(start >= 0);

  // Splits a string so that the resulting list has the same number of elements
  // as there are visible characters in the string, but elements may include one
  // or more adjacent ANSI sequences. Joining the list elements again will
  // reconstitute the original string. This is useful for manipulating "visible"
  // characters in the presence of ANSI control codes.
  List<_AnsiRun> splitWithCodes(String input) {
302
    final RegExp characterOrCode = RegExp('(\u001b\\[[0-9;]*m|.)', multiLine: true);
303 304
    List<_AnsiRun> result = <_AnsiRun>[];
    final StringBuffer current = StringBuffer();
305
    for (final Match match in characterOrCode.allMatches(input)) {
306
      current.write(match[0]);
307
      if (match[0]!.length < 4) {
308
        // This is a regular character, write it out.
309
        result.add(_AnsiRun(current.toString(), match[0]!));
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
        current.clear();
      }
    }
    // If there's something accumulated, then it must be an ANSI sequence, so
    // add it to the end of the last entry so that we don't lose it.
    if (current.isNotEmpty) {
      if (result.isNotEmpty) {
        result.last.original += current.toString();
      } else {
        // If there is nothing in the string besides control codes, then just
        // return them as the only entry.
        result = <_AnsiRun>[_AnsiRun(current.toString(), '')];
      }
    }
    return result;
  }

327
  String joinRun(List<_AnsiRun> list, int start, [ int? end ]) {
328 329 330 331
    return list.sublist(start, end).map<String>((_AnsiRun run) => run.original).join().trim();
  }

  final List<String> result = <String>[];
332
  final int effectiveLength = math.max(columnWidth - start, kMinColumnWidth);
333
  for (final String line in text.split('\n')) {
334 335
    // If the line is short enough, even with ANSI codes, then we can just add
    // add it and move on.
336
    if (line.length <= effectiveLength || !shouldWrap) {
337 338 339 340 341 342 343 344 345 346
      result.add(line);
      continue;
    }
    final List<_AnsiRun> splitLine = splitWithCodes(line);
    if (splitLine.length <= effectiveLength) {
      result.add(line);
      continue;
    }

    int currentLineStart = 0;
347
    int? lastWhitespace;
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
    // Find the start of the current line.
    for (int index = 0; index < splitLine.length; ++index) {
      if (splitLine[index].character.isNotEmpty && isWhitespace(splitLine[index])) {
        lastWhitespace = index;
      }

      if (index - currentLineStart >= effectiveLength) {
        // Back up to the last whitespace, unless there wasn't any, in which
        // case we just split where we are.
        if (lastWhitespace != null) {
          index = lastWhitespace;
        }

        result.add(joinRun(splitLine, currentLineStart, index));

        // Skip any intervening whitespace.
364
        while (index < splitLine.length && isWhitespace(splitLine[index])) {
365 366 367 368 369 370 371 372 373 374 375
          index++;
        }

        currentLineStart = index;
        lastWhitespace = null;
      }
    }
    result.add(joinRun(splitLine, currentLineStart));
  }
  return result;
}
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395

/// Returns true if the code unit at [index] in [text] is a whitespace
/// character.
///
/// Based on: https://en.wikipedia.org/wiki/Whitespace_character#Unicode
bool isWhitespace(_AnsiRun run) {
  final int rune = run.character.isNotEmpty ? run.character.codeUnitAt(0) : 0x0;
  return rune >= 0x0009 && rune <= 0x000D ||
      rune == 0x0020 ||
      rune == 0x0085 ||
      rune == 0x1680 ||
      rune == 0x180E ||
      rune >= 0x2000 && rune <= 0x200A ||
      rune == 0x2028 ||
      rune == 0x2029 ||
      rune == 0x202F ||
      rune == 0x205F ||
      rune == 0x3000 ||
      rune == 0xFEFF;
}
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447

final RegExp _interpolationRegex = RegExp(r'\$\{([^}]*)\}');

/// Given a string that possibly contains string interpolation sequences
/// (so for example, something like `ping -n 1 ${host}`), replace all those
/// interpolation sequences with the matching value given in [replacementValues].
///
/// If the value could not be found inside [replacementValues], an empty
/// string will be substituted instead.
///
/// However, if the dollar sign inside the string is preceded with a backslash,
/// the sequences won't be substituted at all.
///
/// Example:
/// ```dart
/// final interpolated = _interpolateString(r'ping -n 1 ${host}', {'host': 'raspberrypi'});
/// print(interpolated);  // will print 'ping -n 1 raspberrypi'
///
/// final interpolated2 = _interpolateString(r'ping -n 1 ${_host}', {'host': 'raspberrypi'});
/// print(interpolated2); // will print 'ping -n 1 '
/// ```
String interpolateString(String toInterpolate, Map<String, String> replacementValues) {
  return toInterpolate.replaceAllMapped(_interpolationRegex, (Match match) {
    /// The name of the variable to be inserted into the string.
    /// Example: If the source string is 'ping -n 1 ${host}',
    ///   `name` would be 'host'
    final String name = match.group(1)!;
    return replacementValues.containsKey(name) ? replacementValues[name]! : '';
  });
}

/// Given a list of strings possibly containing string interpolation sequences
/// (so for example, something like `['ping', '-n', '1', '${host}']`), replace
/// all those interpolation sequences with the matching value given in [replacementValues].
///
/// If the value could not be found inside [replacementValues], an empty
/// string will be substituted instead.
///
/// However, if the dollar sign inside the string is preceded with a backslash,
/// the sequences won't be substituted at all.
///
/// Example:
/// ```dart
/// final interpolated = _interpolateString(['ping', '-n', '1', r'${host}'], {'host': 'raspberrypi'});
/// print(interpolated);  // will print '[ping, -n, 1, raspberrypi]'
///
/// final interpolated2 = _interpolateString(['ping', '-n', '1', r'${_host}'], {'host': 'raspberrypi'});
/// print(interpolated2); // will print '[ping, -n, 1, ]'
/// ```
List<String> interpolateStringList(List<String> toInterpolate, Map<String, String> replacementValues) {
  return toInterpolate.map((String s) => interpolateString(s, replacementValues)).toList();
}