bool.hasEnvironment constructor - bool - dart:core library (original) (raw)

constbool.hasEnvironment(

1. String name )

Whether name is declared in the compilation configuration environment.

The compilation configuration environment is provided by the surrounding tools which are compiling or running the Dart program. The environment is a mapping from a set of string keys to their associated string value. The string value, or lack of a value, associated with a namemust be consistent across all calls to String.fromEnvironment,int.fromEnvironment, bool.fromEnvironment and bool.hasEnvironmentin a single program.

This constructor evaluates to true if name has an associated value in the compilation configuration environment, and to false if not. If there is an associated value, then the value can be accessed usingconst String.fromEnvironment(name). Otherwise,String.fromEnvironment(name, defaultValue: someString)is known to evaluate to the given defaultValue.

The String.fromEnvironment, int.fromEnvironment andbool.fromEnvironment constructors always produce a String, int, or bool, as required for a constructor. In most cases, the absence of a configuration environment association for a name simply means that the code should fall back on a default behavior, and a default value of the same type typically represents that perfectly.

In some cases, a value of different type, mostly null, may better represent the absence of a choice. In that case, this constructor can be used to first check whether there is a value, and only then use the other fromEnvironment constructors. Example:

const int? indentOverride = bool.hasEnvironment("indent-override")
    ? int.fromEnvironment("indent-override")
    : null;
void indentLines(List<String> lines, int indentation) {
  int actualIndentation = indentOverride ?? indentation;
  // ... Do something to lines.
}

This pattern allows a compilation configuration to provide an override value to the program, but also to not do so, and the program can tell the difference between an explicitly provided value and the absence of one.

Another use case is to only do something extra when a needed value is available. Example:

const Logger? logger = bool.hasEnvironment("logging-id")
    ? Logger(id: String.fromEnvironment("logging-id"))
    : null;

This constructor is only guaranteed to work when invoked as const. It may work as a non-constant invocation on some platforms which have access to compiler options at run-time, but most ahead-of-time compiled platforms will not have this information.

Implementation

external const factory bool.hasEnvironment(String name);