Merge pull request #678 from dart-lang/merge-boolean_selector-package

Merge `package:boolean_selector`

.github/ISSUE_TEMPLATE/boolean_selector.md

@@ -0,0 +1,5 @@
+---
+name: "package:boolean_selector"
+about: "Create a bug or file a feature request against package:boolean_selector."
+labels: "package:boolean_selector"
+---

.github/labeler.yml

@@ -4,6 +4,10 @@
   - changed-files:
       - any-glob-to-any-file: '.github/**'
 
+'package:boolean_selector':
+  - changed-files:
+      - any-glob-to-any-file: 'pkgs/boolean_selector/**'
+
 'package:cli_config':
   - changed-files:
       - any-glob-to-any-file: 'pkgs/cli_config/**'

.github/workflows/boolean_selector.yaml

@@ -0,0 +1,72 @@
+name: package:boolean_selector
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/boolean_selector.yml'
+      - 'pkgs/boolean_selector/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/boolean_selector.yml'
+      - 'pkgs/boolean_selector/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+
+defaults:
+  run:
+    working-directory: pkgs/boolean_selector/
+
+jobs:
+  # Check code formatting and static analysis on a single OS (linux)
+  # against Dart dev.
+  analyze:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [dev]
+    steps:
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Check formatting
+        run: dart format --output=none --set-exit-if-changed .
+        if: always() && steps.install.outcome == 'success'
+      - name: Analyze code
+        run: dart analyze --fatal-infos
+        if: always() && steps.install.outcome == 'success'
+
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add macos-latest and/or windows-latest if relevant for this package.
+        os: [ubuntu-latest]
+        sdk: [3.1, dev]
+    steps:
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Run VM tests
+        run: dart test --platform vm
+        if: always() && steps.install.outcome == 'success'
+      - name: Run Chrome tests
+        run: dart test --platform chrome
+        if: always() && steps.install.outcome == 'success'

README.md

@@ -14,6 +14,7 @@ don't naturally belong to other topic monorepos (like
 
 | Package | Description | Version |
 | --- | --- | --- |
+| [boolean_selector](pkgs/boolean_selector/) | A flexible syntax for boolean expressions, based on a simplified version of Dart's expression syntax. | [![pub package](https://img.shields.io/pub/v/boolean_selector.svg)](https://pub.dev/packages/boolean_selector) |
 | [cli_config](pkgs/cli_config/) | A library to take config values from configuration files, CLI arguments, and environment variables. | [![pub package](https://img.shields.io/pub/v/cli_config.svg)](https://pub.dev/packages/cli_config) |
 | [coverage](pkgs/coverage/) | Coverage data manipulation and formatting. | [![pub package](https://img.shields.io/pub/v/coverage.svg)](https://pub.dev/packages/coverage) |
 | [extension_discovery](pkgs/extension_discovery/) | A convention and utilities for package extension discovery. | [![pub package](https://img.shields.io/pub/v/extension_discovery.svg)](https://pub.dev/packages/extension_discovery) |

pkgs/boolean_selector/.gitignore

@@ -0,0 +1,3 @@
+.dart_tool/
+.packages
+pubspec.lock

pkgs/boolean_selector/AUTHORS

@@ -0,0 +1,6 @@
+# Below is a list of people and organizations that have contributed
+# to the project. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google Inc.

pkgs/boolean_selector/CHANGELOG.md

@@ -0,0 +1,44 @@
+## 2.1.2
+
+* Increase the SDK minimum to `3.1.0`.
+* Move to `dart-lang/tools` monorepo.
+
+## 2.1.1
+
+* Increase the SDK minimum to `2.17.0`.
+* Populate the pubspec `repository` field.
+
+## 2.1.0
+
+* Stable release for null safety.
+
+## 2.0.0
+
+* Breaking: `BooleanSelector.evaluate` always takes a `bool Function(String)`.
+  For use cases previously passing a `Set<String>`, tear off the `.contains`
+  method. For use cases passing an `Iterable<String>` it may be worthwhile to
+  first use `.toSet()` before tearing off `.contains`.
+
+## 1.0.5
+
+* Update package metadata & add `example/` folder
+
+## 1.0.4
+
+* Now requires Dart 2.
+
+## 1.0.3
+
+* Work around an inference bug in the new common front-end.
+
+## 1.0.2
+
+* Declare compatibility with `string_scanner` 1.0.0.
+
+## 1.0.1
+
+* Fix all strong mode warnings.
+
+## 1.0.0
+
+* Initial release.

pkgs/boolean_selector/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2016, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/boolean_selector/README.md

@@ -0,0 +1,42 @@
+[![Build Status](https://github.com/dart-lang/tools/actions/workflows/boolean_selector.yaml/badge.svg)](https://github.com/dart-lang/tools/actions/workflows/boolean_selector.yaml)
+[![Pub Package](https://img.shields.io/pub/v/boolean_selector.svg)](https://pub.dev/packages/boolean_selector)
+[![package publisher](https://img.shields.io/pub/publisher/boolean_selector.svg)](https://pub.dev/packages/boolean_selector/publisher)
+
+The `boolean_selector` package defines a simple and flexible syntax for boolean
+expressions. It can be used for filtering based on user-defined expressions. For
+example, the [`test`][test] package uses boolean selectors to allow users to
+define what platforms their tests support.
+
+[test]: https://github.com/dart-lang/test
+
+The boolean selector syntax is based on a simplified version of Dart's
+expression syntax. Selectors can contain identifiers, parentheses, and boolean
+operators, including `||`, `&&`, `!`, and `? :`. Any valid Dart identifier is
+allowed, and identifiers may also contain hyphens. For example, `chrome`,
+`chrome || content-shell`, and `js || (vm && linux)` are all valid boolean
+selectors.
+
+A boolean selector is parsed from a string using
+[`BooleanSelector.parse()`][parse], and evaluated against a set of variables
+using [`BooleanSelector.evaluate()`][evaluate]. The variables are supplied as
+a function that takes a variable name and returns its value. For example:
+
+[parse]: https://pub.dev/documentation/boolean_selector/latest/boolean_selector/BooleanSelector/BooleanSelector.parse.html
+
+[evaluate]: https://pub.dev/documentation/boolean_selector/latest/boolean_selector/BooleanSelector/evaluate.html
+
+```dart
+import 'package:boolean_selector/boolean_selector.dart';
+
+void main(List<String> args) {
+  var selector = BooleanSelector.parse("(x && y) || z");
+  print(selector.evaluate((variable) => args.contains(variable)));
+}
+```
+
+## Versioning
+
+If this package adds new features to the boolean selector syntax, it will
+increment its major version number. This ensures that packages that expose the
+syntax to their users will be able to update their own minor versions, so their
+users can indicate that they rely on the new syntax.

pkgs/boolean_selector/analysis_options.yaml

@@ -0,0 +1,7 @@
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+linter:
+  rules:
+    - avoid_unused_constructor_parameters
+    - cancel_subscriptions
+    - package_api_docs

pkgs/boolean_selector/example/example.dart

@@ -0,0 +1,6 @@
+import 'package:boolean_selector/boolean_selector.dart';
+
+void main(List<String> args) {
+  var selector = BooleanSelector.parse('(x && y) || z');
+  print(selector.evaluate((variable) => args.contains(variable)));
+}

pkgs/boolean_selector/lib/boolean_selector.dart

@@ -0,0 +1,56 @@
+// Copyright (c) 2016, 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.
+
+import 'package:source_span/source_span.dart';
+
+import 'src/all.dart';
+import 'src/impl.dart';
+import 'src/none.dart';
+
+/// A boolean expression that evaluates to `true` or `false` based on certain
+/// inputs.
+///
+/// The syntax is mostly Dart's expression syntax restricted to boolean
+/// operations. See [the README][] for full details.
+///
+/// [the README]: https://github.com/dart-lang/boolean_selector/blob/master/README.md
+///
+/// Boolean selectors support structural equality. Two selectors that have the
+/// same parsed structure are considered equal.
+abstract class BooleanSelector {
+  /// A selector that accepts all inputs.
+  static const all = All();
+
+  /// A selector that accepts no inputs.
+  static const none = None();
+
+  /// All the variables in this selector, in the order they appear.
+  Iterable<String> get variables;
+
+  /// Parses [selector].
+  ///
+  /// This will throw a [SourceSpanFormatException] if the selector is
+  /// malformed or if it uses an undefined variable.
+  factory BooleanSelector.parse(String selector) = BooleanSelectorImpl.parse;
+
+  /// Returns whether the selector matches the given [semantics].
+  ///
+  /// The [semantics] define which variables evaluate to `true` or `false`. When
+  /// passed a variable name it should return the value of that variable.
+  bool evaluate(bool Function(String variable) semantics);
+
+  /// Returns a new [BooleanSelector] that matches only inputs matched by both
+  /// `this` and [other].
+  BooleanSelector intersection(BooleanSelector other);
+
+  /// Returns a new [BooleanSelector] that matches all inputs matched by either
+  /// `this` or [other].
+  BooleanSelector union(BooleanSelector other);
+
+  /// Throws a [FormatException] if any variables are undefined.
+  ///
+  /// The [isDefined] function should return `true` for any variables that are
+  /// considered valid, and `false` for any invalid or undefined variables.
+  void validate(bool Function(String variable) isDefined);
+}

pkgs/boolean_selector/lib/src/all.dart

@@ -0,0 +1,30 @@
+// Copyright (c) 2016, 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.
+
+import '../boolean_selector.dart';
+
+/// A selector that matches all inputs.
+class All implements BooleanSelector {
+  // TODO(nweiz): Stop explicitly providing a type argument when sdk#32412 is
+  // fixed.
+  @override
+  final Iterable<String> variables = const <String>[];
+
+  const All();
+
+  @override
+  bool evaluate(bool Function(String variable) semantics) => true;
+
+  @override
+  BooleanSelector intersection(BooleanSelector other) => other;
+
+  @override
+  BooleanSelector union(BooleanSelector other) => this;
+
+  @override
+  void validate(bool Function(String variable) isDefined) {}
+
+  @override
+  String toString() => '<all>';
+}