File handling Archives ZIP TAR TGZ

# Archive File Handling

The `klyn.io.archives` package creates and extracts archive files without shelling out to external tools. Use it for deployment bundles, generated reports, backups, and runtime packaging tasks that must stay inside the Klyn runtime contract.

Imports

    import klyn.io
    import klyn.io.archives

Supported Formats

`ArchiveFormat` selects the implementation returned by `Archiver.getInstance`. Current formats are `ZIP`, `TAR`, and `TGZ`.

Format | Implementation | Typical extension
--- | --- | ---
`ArchiveFormat.ZIP` | `ZipArchiver` | `.zip`
`ArchiveFormat.TAR` | `TarArchiver` | `.tar`
`ArchiveFormat.TGZ` | `TgzArchiver` | `.tgz` or `.tar.gz`

Create an Archive

`makeArchive` accepts a source file or directory, the target archive file, and a `FileAccessMode`. Use `FileAccessMode.OVERWRITE` for deterministic exports that may replace an existing archive.

    import klyn.io
    import klyn.io.archives

    archiver = Archiver.getInstance(ArchiveFormat.ZIP)
    archiver.makeArchive("docs", "docs.zip", FileAccessMode.OVERWRITE)

If the format is fixed and you do not need runtime selection, instantiate the implementation directly.

    import klyn.io
    import klyn.io.archives

    zip = ZipArchiver()
    zip.makeArchive("reports", "reports.zip", FileAccessMode.OVERWRITE)

Extract an Archive

`unpackArchive` extracts into a destination directory. The destination creation policy is controlled with the same `FileAccessMode` enum used by archive creation.

    import klyn.io
    import klyn.io.archives

    archiver = Archiver.getInstance(ArchiveFormat.TAR)
    archiver.unpackArchive("docs.tar", "build/unpacked-docs", FileAccessMode.OVERWRITE)

Choosing a Format

- Use `ZIP` for cross-platform application bundles and user-facing downloads.
- Use `TAR` when you want a Unix-style container without compression.
- Use `TGZ` when you want a tar container wrapped in gzip for distribution.

Keep archive logic inside Klyn

The standard archive implementations are part of the runtime API. Prefer them over spawning `zip`, `tar`, or platform-specific shell commands so the same Klyn code can run consistently across Linux and Windows builds.

Safe Extraction

Treat archives from external sources as untrusted input. Extract them into a controlled temporary or application-owned directory, validate the extracted files, and only then move data into final locations. Avoid extracting directly over application source or configuration folders unless the archive was produced by a trusted process.