Skip to content

Commit 7b89e44

Browse files
lrhnlrhn
committed
New API with per-platform properties.
The `Platform.current` object exposes one (or potentially more) of a `NativePlatform` (based on `dart:io`) or `BrowserPlatform` (based on JS `window.navigator` or anything else relevant). Each has its own API, and the current platform determines whether a value of these types is available or not. On unsupported platforms, a value is just `null`. Provides a `testing.dart` library which exposes `FakeNativePlatform` and `FakeBrowserPlatform`, which are customizable classes that can be used for testing. It's possible to run code with such a fake value as the *current* platform (`Platform.current` is temporarily updated to a value which exposes the, fx, `FakeNativePlatform` as its `Platform.nativePlatform`). Still retains the legacy and deprecated API that makes native properties directly available on `Platform`. Code should migrate to the new API by doing: * `const LocalPlatform()` → `Platform.current.nativePlatform!` * `new FakePlatform()` → `new FakeNativePlatform()` It's currently not possible to have more than one non-`null` platform-value. Platforms are detected by the presence of the `dart:io` and `dart:js_interop` libraries, and no current platform has both. When such a platform exists, the code will need to be adapted to to produce *both* (possible using conditional imports or conditional parts and augmentations).
1 parent af37fe5 commit 7b89e44

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+5599
-549
lines changed

‎pkgs/platform/.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
.dart_tool/
55
.pub/
66
build/
7+
doc/
78
packages
89
.packages
910

@@ -15,3 +16,6 @@ pubspec.lock
1516
.settings
1617
.idea
1718
.c9
19+
20+
# Used internally for test files.
21+
tmp/

‎pkgs/platform/CHANGELOG.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1+
## 3.2.0-wip
2+
3+
* New non-backwards compatible API.
4+
Use `Platform.current` to access the current platform,
5+
and `Platform.current.native` to either get access to native
6+
platform information, or get a `null` on non-native platforms.
7+
Similarly `Platform.current.web` is only non-`null` on the web.
8+
9+
Mocking APIs are moved to a separate library to ensure they are
10+
only used for testing, and to allow better performance in production.
11+
12+
Legacy APIs are deprecated, but retained and emulated using the new API.
13+
114
## 3.1.6
215

316
* Move to `dart-lang/core` monorepo.

‎pkgs/platform/example/bin/example.dart

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎pkgs/platform/example/bin/platform.dart

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
import 'package:platform/platform.dart';
6+
7+
void main(List<String> arguments) {
8+
final platform = Platform.current.nativePlatform;
9+
if (platform == null) {
10+
print('This program only supports execution on native platforms.');
11+
} else {
12+
print('Operating System: ${platform.operatingSystem}.');
13+
print('Local Hostname: ${platform.localHostname}.');
14+
print('Number of Processors: ${platform.numberOfProcessors}.');
15+
print('Path Separator: ${platform.pathSeparator}.');
16+
print('Locale Name: ${platform.localeName}.');
17+
print('Stdin Supports ANSI: ${yn(platform.stdinSupportsAnsi)}.');
18+
print('Stdout Supports ANSI: ${yn(platform.stdoutSupportsAnsi)}.');
19+
print('Executable Arguments: ${platform.executableArguments}.');
20+
print('Dart Version: ${platform.version}.');
21+
}
22+
}
23+
24+
String yn(bool yesOrNo) => yesOrNo ? 'yes' : 'no';

‎pkgs/platform/example/bin/platform_using_switch.dart

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
import 'package:platform/platform.dart';
6+
7+
void main() {
8+
switch (Platform.current) {
9+
case Platform(:var browserPlatform?):
10+
print('Running in a browser');
11+
print('User-agent: ${browserPlatform.userAgent}');
12+
case Platform(nativePlatform: var platform?)
13+
when platform.isLinux | platform.isMacOS | platform.isWindows:
14+
print('Running on ${platform.operatingSystem}');
15+
print('Hostname: ${platform.localHostname}');
16+
default:
17+
print('Not running on supported platform');
18+
}
19+
}

‎pkgs/platform/example/bin/tree_shake.dart

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
// Compile this file for a specific platform, for example as:
6+
//
7+
// dart compile exe --target-os=linux tree_shake.dart
8+
// dart compile js -o tree_shake.js tree_shake.dart
9+
//
10+
// and check that the executable does not contain the strings for
11+
// other platforms. For example on Linux, use:
12+
//
13+
// strings tree_shake.{exe,js} | grep "RUNNING"
14+
//
15+
// and check that the only retained value is either `RUNNING ON LINUX` or
16+
// `RUNNING IN A BROWSER`.
17+
18+
import 'package:platform/platform.dart';
19+
20+
void main() {
21+
const expectedPlatform = bool.fromEnvironment('dart.library.js_interop')
22+
? 'browser'
23+
: bool.fromEnvironment('dart.library.io')
24+
? 'native'
25+
: 'unknown';
26+
print('Expected platform: $expectedPlatform');
27+
28+
if (Platform.current.isBrowser) {
29+
print('RUNNING IN A BROWSER');
30+
var browser = Platform.current.browserPlatform!;
31+
print(browser.userAgent);
32+
} else if (Platform.current.isNative) {
33+
var native = Platform.current.nativePlatform!;
34+
if (native.isLinux) {
35+
print('RUNNING ON LINUX');
36+
} else if (native.isMacOS) {
37+
print('RUNNING ON MACOS');
38+
} else if (native.isWindows) {
39+
print('RUNNING ON WINDOWS');
40+
}
41+
}
42+
}

‎pkgs/platform/example/bin/tree_shake_nullaware.dart

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
// Compile this file for a specific platform, for example as:
6+
//
7+
// dart compile exe --target-os=linux tree_shake_nullaware.dart
8+
// dart compile js -o tree_shake_nullaware.js tree_shake_nullaware.dart
9+
//
10+
// and check that the executable does not contain the strings for
11+
// other platforms. For example on Linux, use:
12+
//
13+
// strings tree_shake_nullaware.{exe,js} | grep "RUNNING"
14+
//
15+
// and check that the only retained value is either `RUNNING ON LINUX` or
16+
// `RUNNING IN A BROWSER`.
17+
18+
import 'package:platform/platform.dart';
19+
20+
void main() {
21+
const expectedPlatform = bool.fromEnvironment('dart.library.js_interop')
22+
? 'browser'
23+
: bool.fromEnvironment('dart.library.io')
24+
? 'native'
25+
: 'unknown';
26+
print('Expected platform: $expectedPlatform');
27+
28+
if (Platform.current.isBrowser) {
29+
print('RUNNING IN A BROWSER');
30+
} else if (Platform.current.nativePlatform?.isLinux ?? false) {
31+
print('RUNNING ON LINUX');
32+
} else if (Platform.current.nativePlatform?.isMacOS ?? false) {
33+
print('RUNNING ON MACOS');
34+
} else if (Platform.current.nativePlatform?.isWindows ?? false) {
35+
print('RUNNING ON WINDOWS');
36+
}
37+
}

‎pkgs/platform/example/bin/tree_shake_pattern_const.dart

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
// Compile this file for a specific platform, for example as:
6+
//
7+
// dart compile exe --target-os=linux tree_shake_pattern_const.dart
8+
// dart compile js -o tree_shake_pattern_const.js tree_shake_pattern_const.dart
9+
//
10+
// and check that the executable does not contain the strings for
11+
// other platforms. For example on Linux, use:
12+
//
13+
// strings tree_shake_pattern_const.{exe,js} | grep "RUNNING"
14+
//
15+
// and check that the only retained value is either `RUNNING ON LINUX` or
16+
// `RUNNING IN A BROWSER`.
17+
18+
import 'package:platform/platform.dart';
19+
20+
void main() {
21+
const expectedPlatform = bool.fromEnvironment('dart.library.js_interop')
22+
? 'browser'
23+
: bool.fromEnvironment('dart.library.io')
24+
? 'native'
25+
: 'unknown';
26+
print('Expected platform: $expectedPlatform');
27+
28+
switch (Platform.current) {
29+
case Platform(:var browserPlatform?):
30+
print('RUNNING IN A BROWSER');
31+
print('User-agent: ${browserPlatform.userAgent}');
32+
case Platform(
33+
nativePlatform: NativePlatform(operatingSystem: NativePlatform.linux)
34+
):
35+
print('RUNNING ON LINUX');
36+
case Platform(
37+
nativePlatform: NativePlatform(operatingSystem: NativePlatform.macOS)
38+
):
39+
print('RUNNING ON MACOS');
40+
case Platform(
41+
nativePlatform: NativePlatform(operatingSystem: NativePlatform.windows)
42+
):
43+
print('RUNNING ON WINDOWS');
44+
}
45+
}

‎pkgs/platform/example/bin/tree_shake_pattern_eq.dart

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
// Compile this file for a specific platform, for example as:
6+
//
7+
// dart compile exe --target-os=linux tree_shake_pattern_eq.dart
8+
// dart compile js -o tree_shake_pattern_eq.js tree_shake_pattern_eq.dart
9+
//
10+
// and check that the executable does not contain the strings for
11+
// other platforms. For example on Linux, use:
12+
//
13+
// strings tree_shake_pattern_eq.{exe,js} | grep "RUNNING"
14+
//
15+
// and check that the only retained value is either `RUNNING ON LINUX` or
16+
// `RUNNING IN A BROWSER`.
17+
18+
import 'package:platform/platform.dart';
19+
20+
void main() {
21+
const expectedPlatform = bool.fromEnvironment('dart.library.js_interop')
22+
? 'browser'
23+
: bool.fromEnvironment('dart.library.io')
24+
? 'native'
25+
: 'unknown';
26+
print('Expected platform: $expectedPlatform');
27+
28+
switch (Platform.current) {
29+
case Platform(:var browserPlatform?):
30+
print('RUNNING IN A BROWSER');
31+
print('User-agent: ${browserPlatform.userAgent}');
32+
case Platform(
33+
nativePlatform: NativePlatform(operatingSystem: == NativePlatform.linux)
34+
):
35+
print('RUNNING ON LINUX');
36+
case Platform(
37+
nativePlatform: NativePlatform(operatingSystem: == NativePlatform.macOS)
38+
):
39+
print('RUNNING ON MACOS');
40+
case Platform(
41+
nativePlatform: NativePlatform(
42+
operatingSystem: == NativePlatform.windows
43+
)
44+
):
45+
print('RUNNING ON WINDOWS');
46+
}
47+
}

‎pkgs/platform/example/bin/tree_shake_pattern_when.dart

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
// Compile this file for a specific platform, for example as:
6+
//
7+
// dart compile exe --target-os=linux tree_shake_pattern_when.dart
8+
// dart compile js -o tree_shake_pattern_when.js tree_shake_pattern_when.dart
9+
//
10+
// and check that the executable does not contain the strings for
11+
// other platforms. For example on Linux, use:
12+
//
13+
// strings tree_shake_pattern_when.{exe,js} | grep "RUNNING"
14+
//
15+
// and check that the only retained value is either `RUNNING ON LINUX` or
16+
// `RUNNING IN A BROWSER`.
17+
18+
import 'package:platform/platform.dart';
19+
20+
void main() {
21+
const expectedPlatform = bool.fromEnvironment('dart.library.js_interop')
22+
? 'browser'
23+
: bool.fromEnvironment('dart.library.io')
24+
? 'native'
25+
: 'unknown';
26+
print('Expected platform: $expectedPlatform');
27+
28+
switch (Platform.current) {
29+
case Platform(:var browserPlatform?):
30+
print('RUNNING IN A BROWSER');
31+
print('User-agent: ${browserPlatform.userAgent}');
32+
case Platform(:var nativePlatform?) when nativePlatform.isLinux:
33+
print('RUNNING ON LINUX');
34+
case Platform(:var nativePlatform?) when nativePlatform.isMacOS:
35+
print('RUNNING ON MACOS');
36+
case Platform(:var nativePlatform?) when nativePlatform.isWindows:
37+
print('RUNNING ON WINDOWS');
38+
}
39+
}

‎pkgs/platform/example/bin/tree_shake_shorthand.dart

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
5+
// Compile this file for a specific platform, for example as:
6+
//
7+
// dart compile exe --target-os=linux tree_shake_shorthand.dart
8+
// dart compile js -o tree_shake_shorthand.js tree_shake_shorthand.dart
9+
//
10+
// and check that the executable does not contain the strings for
11+
// other platforms. For example on Linux, use:
12+
//
13+
// strings tree_shake_shorthand.{exe,js} | grep "RUNNING"
14+
//
15+
// and check that the only retained value is either `RUNNING ON LINUX` or
16+
// `RUNNING IN A BROWSER`.
17+
18+
import 'package:platform/platform.dart';
19+
20+
void main() {
21+
const expectedPlatform = bool.fromEnvironment('dart.library.js_interop')
22+
? 'browser'
23+
: bool.fromEnvironment('dart.library.io')
24+
? 'native'
25+
: 'unknown';
26+
print('Expected platform: $expectedPlatform');
27+
28+
if (Platform.current.isBrowser) {
29+
print('RUNNING IN A BROWSER');
30+
} else if (Platform.current.isLinux) {
31+
print('RUNNING ON LINUX');
32+
} else if (Platform.current.isMacOS) {
33+
print('RUNNING ON MACOS');
34+
} else if (Platform.current.isWindows) {
35+
print('RUNNING ON WINDOWS');
36+
}
37+
}

‎pkgs/platform/example/pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ version: 1.0.0
44
publish_to: none
55

66
environment:
7-
sdk: ^3.2.0
7+
sdk: ^3.5.0
88

99
dependencies:
1010
platform:

0 commit comments

Comments
 (0)