Module zip

Le module zip permet de manipuler des archives Zip depuis un script YScript : ouvrir une archive existante ou en créer une nouvelle, lister son contenu, ajouter/remplacer/supprimer des entrées, et compresser/décompresser un dossier entier.

require("io")
local zip = require("zip")

local ar = zip.open("package.zip", "a")
for _, e in ipairs(ar:entries()) do
    print(e.name, e.size, e.isdirectory)
end
ar:add("readme.txt", "hello")
ar:close()

Prérequis : la bibliothèque io

zip n'a aucune fonctionnalité qui ne touche pas au système de fichiers : une archive est un fichier, ajouter une entrée depuis un dossier lit des fichiers, compresser un dossier les parcourt. La bibliothèque io est donc une dépendance obligatoire de tout le module (contrairement à des modules comme http, où io n'est nécessaire qu'à certaines fonctions).

io doit être chargée avant zip :

require("io")          -- ou l'hôte a déjà appelé OpenIOLib()
local zip = require("zip")

Si io n'est pas chargée, require("zip") échoue (l'erreur remonte comme n'importe quel loader qui échoue — utilisez pcall(require, "zip") si vous voulez récupérer nil, message plutôt que de laisser l'erreur se propager) :

local ok, err = pcall(require, "zip")
if not ok then
    print("zip indisponible : " .. tostring(err))
end

Vue d'ensemble

L'objet archive

zip.open retourne un objet archive (un userdata avec ses propres méthodes, dans le même esprit qu'un FILE* retourné par io.open). Il doit être refermé explicitement par archive:close(), implicitement via l'attribut <close>, ou en dernier recours par le ramasse-miettes :

local ar <close> = zip.open("package.zip", "r")
-- ar:close() est appelé automatiquement en sortie de bloc

Utiliser une méthode sur une archive déjà fermée lève une erreur.

zip.open(path [, mode])

Ouvre une archive existante ou en crée une nouvelle. mode (chaîne, défaut "r") :

En cas d'échec (fichier absent en "r", contenu invalide, erreur disque...), zip.open retourne nil suivi d'un message d'erreur — comme io.open — plutôt que de lever une erreur script :

local ar, err = zip.open("introuvable.zip", "r")
if not ar then
    print("échec : " .. err)
    return
end

Un mode autre que "r"/"w"/"a" est en revanche une erreur de programmation et lève une erreur script immédiate (mauvais argument), pas un nil, message.

zip.type(obj)

Miroir de io.type : retourne "archive" si obj est une archive ouverte, "closed archive" si elle est fermée, ou nil si obj n'est pas une archive de ce module.

local ar = zip.open("a.zip", "w")
print(zip.type(ar))    --> archive
ar:close()
print(zip.type(ar))    --> closed archive
print(zip.type("x"))   --> nil

archive:entries()

Retourne un tableau (indices 1..n) décrivant chaque entrée de l'archive :

local ar = zip.open("package.zip", "r")
for _, e in ipairs(ar:entries()) do
    print(string.format("%-30s %8d -> %8d octets", e.name, e.size, e.compressedsize))
end
ar:close()

archive:exists(name)

Retourne true/false selon la présence d'une entrée name (fichier ou dossier) dans l'archive. Utile avant :add/:replace/:remove, qui sont volontairement stricts (voir plus bas) :

if ar:exists("config.json") then
    ar:replace("config.json", newContent)
else
    ar:add("config.json", newContent)
end

archive:read(name)

Retourne le contenu entier de l'entrée name sous forme de chaîne binaire (un caractère = un octet, même convention que le mode binaire de io) — pratique pour les petits fichiers texte/JSON, mais charge tout le contenu en mémoire de script. Pour un gros fichier, préférez :extract qui passe par un flux sans tout charger.

Erreurs : entrée absente, ou entrée désignant un dossier.

local ar = zip.open("package.zip", "r")
local manifest = ar:read("package.json")
ar:close()

archive:add(name, content) / archive:addfile(name, filepath)

Créent une nouvelle entrée name. Une entrée déjà présente sous ce nom est une erreur (pas d'écrasement implicite — utilisez :replace, ou testez :exists au préalable si vous voulez un comportement « upsert »).

• :add(name, content) — le contenu vient d'une chaîne de script (binaire, comme :read).
• :addfile(name, filepath) — le contenu vient d'un fichier du disque, copié en flux vers l'entrée sans être chargé intégralement en mémoire de script. Préférable pour les gros fichiers. Erreur si filepath n'existe pas sur le disque.

local ar = zip.open("package.zip", "a")
ar:add("VERSION", "1.0.0\n")
ar:addfile("dist/app.dll", "bin/Release/app.dll")
ar:close()

archive:replace(name, content)

Remplace le contenu d'une entrée déjà présente. Le format Zip ne permettant pas de modifier une entrée en place, ceci équivaut en interne à une suppression suivie d'un ajout — transparent pour le script, mais à garder en tête si vous inspectez le flux de l'archive par un autre moyen pendant l'opération. Erreur si name est absente (symétrique de :add).

ar:replace("VERSION", "1.0.1\n")

archive:remove(name)

Supprime l'entrée name. Erreur si elle est absente.

ar:remove("old-file.txt")

archive:extract(name, destpath [, overwrite])

Extrait l'entrée name directement vers le fichier destpath du disque, en flux (sans charger le contenu en mémoire de script — pendant symétrique de :addfile).

overwrite (booléen, défaut false) : si destpath existe déjà et overwrite n'est pas true, c'est une erreur — pas d'écrasement silencieux d'un fichier existant.

Erreur si l'entrée est absente, ou si elle désigne un dossier (utilisez :extractall ou io.mkdir pour un dossier).

local ar = zip.open("package.zip", "r")
ar:extract("bin/app.dll", "install/app.dll", true)  -- true = écrase si déjà présent
ar:close()

archive:extractall(destdir [, overwrite])

Extrait toutes les entrées vers destdir, en recréant la structure de dossiers automatiquement (sous-dossiers créés au besoin). overwrite a la même sémantique que pour :extract, appliquée à chaque fichier extrait.

local ar = zip.open("package.zip", "r")
ar:extractall("installed/mypackage", true)
ar:close()

archive:close()

Referme l'archive : persiste les modifications en attente (pour une archive ouverte en "w"/"a") et referme le fichier sous-jacent. Idempotent — un second :close() ne fait rien.

zip.extractall(zippath, destdir [, overwrite])

Raccourci équivalent à zip.open(zippath, "r"):extractall(destdir, overwrite) suivi d'un :close() automatique. Pratique pour un cas d'usage en un seul appel, par exemple installer un paquet téléchargé :

zip.extractall("mypackage-1.0.0.zip", "installed/mypackage", true)

zip.compressdir(srcdir, destzippath [, options])

Crée une nouvelle archive à destzippath et y ajoute récursivement tout le contenu de srcdir, avec des chemins d'entrée relatifs à srcdir (séparateur /, y compris depuis un hôte Windows). Une erreur est levée si srcdir n'existe pas.

options (table optionnelle) :

-- Sans includebase : les entrées sont "fichier.txt", "sub/nested.txt", ...
zip.compressdir("dist/mypackage", "mypackage-1.0.0.zip", { overwrite = true })

-- Avec includebase : les entrées sont "mypackage/fichier.txt", "mypackage/sub/nested.txt", ...
zip.compressdir("dist/mypackage", "mypackage-1.0.0.zip", { includebase = true })

Erreurs

Les erreurs de programmation (mauvais type/valeur d'argument, mode invalide, méthode appelée sur une archive fermée, opération incohérente comme ajouter une entrée déjà présente) sont levées comme des erreurs script classiques — à capturer avec pcall si nécessaire. Seul zip.open fait exception pour les échecs liés au système de fichiers (archive absente en lecture, contenu invalide, erreur disque) : il retourne nil, message, comme io.open.

Exemple complet

require("io")
local zip = require("zip")

-- Empaqueter un dossier de sources en une archive
zip.compressdir("dist/mypackage", "mypackage-1.0.0.zip", { overwrite = true })

-- Inspecter le contenu d'une archive
local ar = zip.open("mypackage-1.0.0.zip", "r")
for _, e in ipairs(ar:entries()) do
    print(e.name, e.size, e.isdirectory)
end
local manifest = ar:read("package.json")
ar:close()

-- Construire/mettre à jour une archive entrée par entrée
local pkg = zip.open("mypackage-1.0.0.zip", "a")
pkg:replace("package.json", manifest .. "\n-- updated")
pkg:addfile("CHANGELOG.md", "CHANGELOG.md")
pkg:remove("old-file.txt")
pkg:close()

-- "Installer" un paquet : tout extraire dans un dossier
zip.extractall("mypackage-1.0.0.zip", "installed/mypackage", true)

Limites connues (v1)

• Pas de support des mots de passe / chiffrement d'archive.
• :replace n'est pas une opération atomique au niveau du fichier zip (suppression + ajout en interne).
• Pas de contrôle fin du niveau de compression par entrée.
• Pas de préservation de métadonnées spécifiques à une plateforme (permissions Unix, attributs Windows, liens symboliques).