blob: 92eedbda5159f7e81168194e9e4875b8d9b84ddb [file] [log] [blame]
// 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]:
abstract class BooleanSelector {
/// A selector that accepts all inputs.
static const all = const All();
/// A selector that accepts no inputs.
static const none = const 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`. The
/// parameter can be either an `Iterable<String>` containing variables that
/// should evaluate to `true`, or a function `bool semantics(String variable)`
/// that returns a variable's value.
bool evaluate(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 isDefined(String variable));