diff --git a/packages/cross_file/CHANGELOG.md b/packages/cross_file/CHANGELOG.md index e4e29a8fbcf4..ac14e215177b 100644 --- a/packages/cross_file/CHANGELOG.md +++ b/packages/cross_file/CHANGELOG.md @@ -1,3 +1,8 @@ +## 0.3.5+4 + +* Adds a runnable `main` entry point and an additional `XFile.fromData` + demonstration to the example. + ## 0.3.5+3 * Clarifies native XFile.mimeType documentation. diff --git a/packages/cross_file/README.md b/packages/cross_file/README.md index df5a96044af0..726387910b57 100644 --- a/packages/cross_file/README.md +++ b/packages/cross_file/README.md @@ -10,17 +10,15 @@ access the file and its metadata. Example: - + ```dart final file = XFile('assets/hello.txt'); -print('File information:'); +print('XFile from disk:'); print('- Path: ${file.path}'); print('- Name: ${file.name}'); -print('- MIME type: ${file.mimeType}'); - -final String fileContent = await file.readAsString(); -print('Content of the file: $fileContent'); +print('- Length: ${await file.length()} bytes'); +print('- Content: ${await file.readAsString()}'); ``` You will find links to the API docs on the [pub page](https://pub.dev/packages/cross_file). diff --git a/packages/cross_file/example/lib/main.dart b/packages/cross_file/example/lib/main.dart new file mode 100644 index 000000000000..617a0a52eacf --- /dev/null +++ b/packages/cross_file/example/lib/main.dart @@ -0,0 +1,59 @@ +// Copyright 2013 The Flutter Authors +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +// ignore_for_file: avoid_print + +import 'dart:typed_data'; + +import 'package:cross_file/cross_file.dart'; + +// `dart:io` (used by the path-based XFile implementation) is not available on +// web, so the disk-based excerpt is only executed on non-web platforms. +const bool _kIsWeb = bool.fromEnvironment('dart.library.js_interop'); + +/// Demonstrate instantiating an XFile for the README. +Future instantiateXFile() async { + // #docregion Instantiate + final file = XFile('assets/hello.txt'); + + print('XFile from disk:'); + print('- Path: ${file.path}'); + print('- Name: ${file.name}'); + print('- Length: ${await file.length()} bytes'); + print('- Content: ${await file.readAsString()}'); + // #enddocregion Instantiate + + return file; +} + +/// Demonstrate constructing an XFile directly from in-memory bytes, which is +/// useful when the file contents are generated at runtime or received from a +/// network source rather than read from disk. +Future instantiateXFileFromData() async { + // #docregion InstantiateFromData + final bytes = Uint8List.fromList([ + 72, 101, 108, 108, 111, 33, // 'Hello!' + ]); + final file = XFile.fromData(bytes, mimeType: 'text/plain'); + + print('XFile from in-memory bytes:'); + print('- MIME type: ${file.mimeType}'); + print('- Length: ${await file.length()} bytes'); + print('- Content: ${await file.readAsString()}'); + // #enddocregion InstantiateFromData + + return file; +} + +/// Runs the example excerpts, demonstrating the [XFile] API. +Future main() async { + if (!_kIsWeb) { + print('=== Creating an XFile from disk ==='); + await instantiateXFile(); + print(''); + } + + print('=== Creating an XFile from in-memory bytes ==='); + await instantiateXFileFromData(); +} diff --git a/packages/cross_file/example/lib/readme_excerpts.dart b/packages/cross_file/example/lib/readme_excerpts.dart deleted file mode 100644 index 94e3c879b87c..000000000000 --- a/packages/cross_file/example/lib/readme_excerpts.dart +++ /dev/null @@ -1,24 +0,0 @@ -// Copyright 2013 The Flutter Authors -// Use of this source code is governed by a BSD-style license that can be -// found in the LICENSE file. - -// ignore_for_file: avoid_print - -import 'package:cross_file/cross_file.dart'; - -/// Demonstrate instantiating an XFile for the README. -Future instantiateXFile() async { - // #docregion Instantiate - final file = XFile('assets/hello.txt'); - - print('File information:'); - print('- Path: ${file.path}'); - print('- Name: ${file.name}'); - print('- MIME type: ${file.mimeType}'); - - final String fileContent = await file.readAsString(); - print('Content of the file: $fileContent'); - // #enddocregion Instantiate - - return file; -} diff --git a/packages/cross_file/example/test/readme_excerpts_test.dart b/packages/cross_file/example/test/main_test.dart similarity index 67% rename from packages/cross_file/example/test/readme_excerpts_test.dart rename to packages/cross_file/example/test/main_test.dart index f46576cc0fdb..2fa54889b7a4 100644 --- a/packages/cross_file/example/test/readme_excerpts_test.dart +++ b/packages/cross_file/example/test/main_test.dart @@ -3,7 +3,7 @@ // found in the LICENSE file. import 'package:cross_file/cross_file.dart'; -import 'package:cross_file_example/readme_excerpts.dart'; +import 'package:cross_file_example/main.dart'; import 'package:test/test.dart'; const bool kIsWeb = bool.fromEnvironment('dart.library.js_interop'); @@ -20,4 +20,12 @@ void main() { final String fileContent = await xFile.readAsString(); expect(fileContent, allOf(isNotNull, isNotEmpty)); }, skip: kIsWeb); + + test('instantiateXFileFromData constructs from bytes', () async { + // Ensure that the snippet code runs successfully on every platform. + final XFile xFile = await instantiateXFileFromData(); + expect(xFile.mimeType, 'text/plain'); + expect(await xFile.length(), 6); + expect(await xFile.readAsString(), 'Hello!'); + }); } diff --git a/packages/cross_file/pubspec.yaml b/packages/cross_file/pubspec.yaml index d0bb7119f1f2..099b57ae387c 100644 --- a/packages/cross_file/pubspec.yaml +++ b/packages/cross_file/pubspec.yaml @@ -2,7 +2,7 @@ name: cross_file description: An abstraction to allow working with files across multiple platforms. repository: https://github.com/flutter/packages/tree/main/packages/cross_file issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+cross_file%22 -version: 0.3.5+3 +version: 0.3.5+4 environment: sdk: ^3.10.0