| OLD | NEW |
| (Empty) |
| 1 when [](https://pub.dartlang
.org/packages/when) [](https://drone.io/github.com/seaneagan/when.dart/latest) [](https:/
/coveralls.io/r/seaneagan/when.dart?branch=master) | |
| 2 ==== | |
| 3 | |
| 4 It's often useful to provide sync (convenient) and async (concurrent) versions | |
| 5 of the same API. `dart:io` does this with many APIs including [Process.run][] | |
| 6 and [Process.runSync][]. Since the sync and async versions do the same thing, | |
| 7 much of the logic is the same, with just a few small bits differing in their | |
| 8 sync vs. async implementation. | |
| 9 | |
| 10 The `when` function allows for registering `onSuccess`, `onError`, and | |
| 11 `onComplete` callbacks on another callback which represents that sync/async | |
| 12 dependent part of the API. If the callback is sync (returns a non-`Future` or | |
| 13 throws), then the other callbacks are invoked synchronously, otherwise the | |
| 14 other callbacks are registered on the returned `Future`. | |
| 15 | |
| 16 For example, here's how it can be used to implement sync and async APIs for | |
| 17 reading a JSON data structure from the file system with file absence handling: | |
| 18 | |
| 19 ```dart | |
| 20 import 'dart:async'; | |
| 21 import 'dart:convert'; | |
| 22 import 'dart:io'; | |
| 23 | |
| 24 import 'package:when/when.dart'; | |
| 25 | |
| 26 /// Reads and decodes JSON from [path] asynchronously. | |
| 27 /// | |
| 28 /// If [path] does not exist, returns the result of calling [onAbsent]. | |
| 29 Future readJsonFile(String path, {onAbsent()}) => _readJsonFile( | |
| 30 path, onAbsent, (file) => file.exists(), (file) => file.readAsString()); | |
| 31 | |
| 32 /// Reads and decodes JSON from [path] synchronously. | |
| 33 /// | |
| 34 /// If [path] does not exist, returns the result of calling [onAbsent]. | |
| 35 readJsonFileSync(String path, {onAbsent()}) => _readJsonFile( | |
| 36 path, onAbsent, (file) => file.existsSync(), | |
| 37 (file) => file.readAsStringSync()); | |
| 38 | |
| 39 _readJsonFile(String path, onAbsent(), exists(File file), read(File file)) { | |
| 40 var file = new File(path); | |
| 41 return when( | |
| 42 () => exists(file), | |
| 43 onSuccess: (doesExist) => doesExist ? | |
| 44 when(() => read(file), onSuccess: JSON.decode) : | |
| 45 onAbsent()); | |
| 46 } | |
| 47 | |
| 48 main() { | |
| 49 var syncJson = readJsonFileSync('foo.json', onAbsent: () => {'foo': 'bar'}); | |
| 50 print('Sync json: $syncJson'); | |
| 51 readJsonFile('foo.json', onAbsent: () => {'foo': 'bar'}).then((asyncJson) { | |
| 52 print('Async json: $asyncJson'); | |
| 53 }); | |
| 54 } | |
| 55 ``` | |
| 56 | |
| 57 [Process.run]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/d
art:io.Process#id_run | |
| 58 [Process.runSync]: https://api.dartlang.org/apidocs/channels/stable/dartdoc-view
er/dart:io.Process#id_runSync | |
| OLD | NEW |