wfile

WFile

The well-tested package for reading and writing JSON, image, text, binary, and XML files across multiple platforms. Can detect MIME types. Independent of the various system delimiters. Feel free to use it in your awesome project.

Share some ❤️ and star repo to support the WFile.

If you write an article about WFile or any of these packages, let me know and I'll post the URL of the article in the README 🤝

🔥 Motivation

1. We need to keep the file paths consistent in live cross-platform projects. I mean the dividers for Linux and Windows. I used to use path extensively (thanks to the authors), but we got some boilerplate with it.

2. WFile contains some abstractions, for ex. Broker, and its implementation: text, image, xml for filesystem. It helps to share data.

3. Many JSON files are very simple. I often use repetitive code to read them. You can now replace Dart's idioms with this line: f.readAsJsonMap() or f.readAsJsonList().

4. Also when reading the image file, we can get the alpha channel guarantee if it is needed.

Additionally with WFile you can write just

f.writeAsImage(image, 'path/to.webp');

instead of

final encoder = findEncoderForNamedImage(p);
if (encoder == null) {
  throw Exception('Not found an encoder for file `$p`.');
}
final bytes = encoder.encode(image);
File(p).writeAsBytesSync(bytes);

Thanks s00prtr00pr.

🚀 Usage

Read Files

const sourcePath = 'path/prefix';
// const sourcePath = ['path', 'prefix'];
final f = WFile(sourcePath);

// get a varios content from files with respect to [sourcePath]
f.readAsText('text.txt');
f.readAsTextLines('lines.txt');            // <String>[...]
f.readAsBytes('bytes.bin');
f.readAsImage('images/1/happy.png');       // path/prefix/images/1/happy.png
f.readAsImage(['images', 1, 'happy.png']); // path/prefix/images/1/happy.png
f.readAsJsonMap('map.json');               // <- { ... }
f.readAsJsonList('list.json');             // <- [ ... ]
f.readAsXml('data.xml');                   // <- <data attr="...">...</data>

Write Files

const sourcePath = 'path/prefix';
// const sourcePath = ['path', 'prefix'];
final f = WFile(sourcePath);

// get a varios content from files with respect to [sourcePath]
f.writeAsText(content, 'text.txt');
f.writeAsBytes(content, 'bytes.bin');
f.writeAsImage(content, 'images/1/happy.png');       // path/prefix/images/1/happy.png
f.writeAsImage([content, 'images', 1, 'happy.png']); // path/prefix/images/1/happy.png
f.writeAsJsonMap(content, 'map.json');               // { ... }
f.writeAsJsonList(content, 'list.json');             // [ ... ]
f.writeAsXml(content, 'data.xml');                   // <data attr="...">...</data>

Copy Files

f.copy('path/source.file', 'path/destination.file');

You can use a relative path.

Identify a File Type

final f = WFile('image.webp');

f.application(); // false
f.audio();       // false
f.binary();      // true
f.font();        // false
f.image();       // true
f.text();        // false
f.video();       // false

Identify the MIME type

f.mime();  // image/webp

✨ What's New

Look at changelog.

👋 Welcome

If you encounter any problems, feel free to open an issue. If you feel the package is missing a feature, please raise a ticket on Github and I'll look into it. Requests and suggestions are warmly welcome. Danke!

Contributions are what make the open-source community such a great place to learn, create, take a new skills, and be inspired.

If this is your first contribution, I'll leave you with some of the best links I've found: they will help you get started or/and become even more efficient.

• Guide to Making a First Contribution. You will find the guide in your native language.
• How to Contribute to Open Source. Longread for deep diving for first-timers and for veterans.
• Summer Guide from Google.
• CodeTriangle. Free community tools for contributing to Open Source projects.

The package WFile is open-source, stable and well-tested. Development happens on GitHub. Feel free to report issues or create a pull-request there.

General questions are best asked on StackOverflow.

And here is a curated list of how you can help:

• Documenting the undocumented. Whenever you come across a class, property, or method within our codebase that you're familiar with and notice it lacks documentation, kindly spare a couple of minutes to jot down some helpful notes for your fellow developers.
• Refining the code. While I'm aware it's primarily my responsibility to refactor the code, I wholeheartedly welcome any contributions you're willing to make in this area. Your insights and improvements are appreciated!
• Constructive code reviews. Should you discover a more efficient approach to achieve something, I'm all ears. Your suggestions for enhancement are invaluable.
• Sharing your examples. If you've experimented with our use cases or have crafted some examples of your own, feel free to add them to the example directory. Your practical insights can enrich our resource pool.
• Fix typos/grammar mistakes.
• Report bugs and scenarios that are difficult to implement.
• Implement new features by making a pull-request.

✅ TODO (perhaps)

Once you start using the WFile, it will become easy to choose the functionality to contribute. But if you already get everything you need from this package but have some free time, let me write here what I have planned:

• Copy folders.
• All feautures for this package into README.
• Support Web platform.
• Examples with filesystem brokers.
• An example with creating own broker.

It's just a habit of mine: writing down ideas that come to mind while working on a project. I confess that I rarely return to these notes. But now, hopefully, even if you don't have an idea yet, the above notes will help you choose the suitable "feature" and become a contributor to the open-source community.

Ready for 🪙

Created with ❤️