commit	66d2d587f3313c68e32ca7a4cd1e969b4858a04a	[log] [tgz]
author	Simon Binder <oss@simonbinder.eu>	Sun Dec 27 19:12:02 2020 +0100
committer	Simon Binder <oss@simonbinder.eu>	Sun Dec 27 19:12:02 2020 +0100
tree	ec266f9983180fbed49e2e2b534b1763438b43fd
parent	7685edcaff5f6de08fcfdba483671a1200404cf9 [diff]

tree: ec266f9983180fbed49e2e2b534b1763438b43fd

README.md

tar

This package provides stream-based readers and writers for tar files.

When working with large tar files, this library consumes considerably less memory than package:archive, although it is slightly slower.

Reading

To read entries from a tar file, use

import 'dart:io';
import 'package:tar/tar.dart' as tar;

Future<void> main() async {
  final tarFile = File('file.tar')
       .openRead()
       .transform(tar.reader);

  await for (final entry in tarFile) {
    print(entry.name);
    print(await entry.transform(utf8.decoder).first);
  }
}

To read .tar.gz files, transform the stream with gzip.decoder first.

Writing

You can write tar files into a StreamSink<List<int>>, such as an IOSink:

import 'dart:io';
import 'package:tar/tar.dart' as tar;

Future<void> main() async {
  final output = File('test.tar').openWrite();

  await Stream<tar.Entry>.value(
    tar.MemoryEntry(
      tar.Header(
        name: 'hello.txt',
        mode: int.parse('644', radix: 8),
      ),
      utf8.encode('Hello world'),
    ),
  ).pipe(tar.WritingSink(output));
}

Note that tar files are always written in the pax format defined by the POSIX.1-2001 specification (--format=posix in GNU tar). When all entries have file names shorter than 100 chars and a size smaller than 8 GB, this is equivalent to the ustar format. This library won't write PAX headers when there is no reason to do so.

To write .tar.gz files, you can again transform the stream twice:

import 'dart:io';
import 'package:tar/tar.dart' as tar;

Future<void> write(Stream<tar.Entry> entries) {
  return entries
      .transform(tar.writer)
      .transform(gzip.encoder)
      .pipe(File('output.tar.gz').openWrite())
}

Features

Supports ustar archives
Supports extended pax headers for long file or link names
Supports long file and link names generated by GNU-tar
Hardened against denial-of-service attacks with invalid tar files