[cross_file] Add runnable example with main()

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.

packages/cross_file/README.md

@@ -10,17 +10,15 @@ access the file and its metadata.
 
 Example:
 
-<?code-excerpt "example/lib/readme_excerpts.dart (Instantiate)"?>
+<?code-excerpt "example/lib/main.dart (Instantiate)"?>
 ```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).

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<XFile> 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<XFile> 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<void> main() async {
+  if (!_kIsWeb) {
+    print('=== Creating an XFile from disk ===');
+    await instantiateXFile();
+    print('');
+  }
+
+  print('=== Creating an XFile from in-memory bytes ===');
+  await instantiateXFileFromData();
+}

packages/cross_file/example/test/readme_excerpts_test.dart → 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!');
+  });
 }

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