ZipLib — Plan9Basic Documentation

ZipLib — ZIP Archive Library

Create, read, and manipulate ZIP archives. Multi-file archives with individual compression, widely used for file distribution, backup, and data exchange. 14 functions.

Category	Count	Description
Error Handling	1	ziperror
Open/Close	3	zipcreate#, zipopen#, zipclose
Adding Files	2	zipadd, zipaddstr
Extracting	2	zipextract, zipextractall
Archive Info	4	ziplist$, zipcount, zipexists, zipread$, zipfilesize
Convenience	2	zipquick, unzipquick

Feature	Description
Create archives	`zipcreate#` → add files → `zipclose`
Read archives	`zipopen#` → list/extract/read → `zipclose`
String content	Add strings directly as files with `zipaddstr`
Quick one-liners	`zipquick` / `unzipquick` for single operations
Directory structure	Use forward slashes in archive names (e.g. `docs/readme.txt`)

Error Handling

Code	Constant	Description
0	ERR_NONE	No error
1	ERR_INVALID_HANDLE	Archive not open or invalid handle
2	ERR_FILE_NOT_FOUND	File not found in archive
3	ERR_FILE_ERROR	File system error (read/write)
4	ERR_INVALID_ARGUMENT	Invalid argument
5	ERR_COMPRESSION	Compression error
6	ERR_ARCHIVE_EXISTS	Archive already exists (when creating)
7	ERR_ENTRY_EXISTS	Entry already exists in archive

Function	Signature	Description
`ziperror()`	`ziperror@`	Error code from last ZipLib operation (0–7)

Archive Open/Close

Function	Signature	Description
`zipcreate#(path$)`	`zipcreate#@$`	Create new ZIP for writing (returns handle, 0 on failure)
`zipopen#(path$)`	`zipopen#@$`	Open existing ZIP for reading (returns handle, 0 on failure)
`zipclose(handle#)`	`zipclose@#`	Close archive and release handle (1/0)

╯ plan9basic─◻✕
' Create archive
handle# = zipcreate#("myarchive.zip")
if PntToNum(handle#) <> 0 then
    ' Add files...
    zipclose(handle#)
endif

' Open existing archive
handle# = zipopen#("existing.zip")
if PntToNum(handle#) <> 0 then
    println "Contains "; zipcount(handle#); " files"
    zipclose(handle#)
endif

⚠ Warning: Always close archives with zipclose to ensure data is written properly. Archives opened with zipcreate# can only add; archives opened with zipopen# can only read/extract.

Adding Files

Function	Signature	Description
`zipadd(h#, src$, name$)`	`zipadd@#$$`	Add file to archive (1/0)
`zipaddstr(h#, content$, name$)`	`zipaddstr@#$$`	Add string as file (1/0)

╯ plan9basic─◻✕
handle# = zipcreate#("backup.zip")
if PntToNum(handle#) <> 0 then
    ' Add files with paths inside archive
    zipadd(handle#, "C:\docs\report.docx", "documents/report.docx")
    zipadd(handle#, "C:\data\sales.xlsx", "spreadsheets/sales.xlsx")
    
    ' Add generated content
    config$ = "server=localhost" + chr$(10)
    config$ = config$ + "port=8080" + chr$(10)
    zipaddstr(handle#, config$, "config.txt")
    
    ' Add JSON data
    jsonData$ = "{\"name\":\"Project\",\"version\":\"1.0\"}"
    zipaddstr(handle#, jsonData$, "manifest.json")
    
    zipclose(handle#)
endif

ⓘ Note: Use forward slashes (/) in archive names for cross-platform compatibility. zipaddstr uses UTF-8 encoding.

Extracting Files

Function	Signature	Description
`zipextract(h#, name$, dest$)`	`zipextract@#$$`	Extract single file to directory (1/0)
`zipextractall(h#, dest$)`	`zipextractall@#$`	Extract all files to directory (1/0)

╯ plan9basic─◻✕
handle# = zipopen#("archive.zip")
if PntToNum(handle#) <> 0 then
    ' Extract one file
    if zipextract(handle#, "readme.txt", ".") = 1 then
        println "Extracted readme.txt"
    endif
    
    ' Extract everything
    if zipextractall(handle#, "C:\extracted") = 1 then
        println "All files extracted"
    else
        println "Failed: "; ziperror()
    endif
    zipclose(handle#)
endif

Archive Information

Function	Signature	Description
`ziplist$(h#)`	`ziplist$@#`	Newline-separated list of file names
`zipcount(h#)`	`zipcount@#`	Number of files in archive
`zipexists(h#, name$)`	`zipexists@#$`	File exists in archive? (1/0)
`zipread$(h#, name$)`	`zipread$@#$`	Read file from archive as string
`zipfilesize(h#, name$)`	`zipfilesize@#$`	Uncompressed file size (-1 on error)

╯ plan9basic─◻✕
handle# = zipopen#("archive.zip")
if PntToNum(handle#) <> 0 then
    println "Files: "; zipcount(handle#)
    
    ' Check for a specific file
    if zipexists(handle#, "config.txt") = 1 then
        content$ = zipread$(handle#, "config.txt")
        println "Config:"
        println content$
    endif
    
    ' List all with sizes
    fileList$ = ziplist$(handle#)
    println fileList$
    zipclose(handle#)
endif

Convenience Functions

Function	Signature	Description
`zipquick(src$, zip$)`	`zipquick@$$`	Quick compress: single file → ZIP (1/0)
`unzipquick(zip$, dest$)`	`unzipquick@$$`	Quick extract: ZIP → directory (1/0)

╯ plan9basic─◻✕
' One-liner compress
if zipquick("report.pdf", "report.zip") = 1 then
    println "Compressed!"
endif

' One-liner extract
if unzipquick("package.zip", "C:\extracted") = 1 then
    println "Extracted!"
endif

ⓘ Note: Convenience functions handle open/close automatically. Use the full API for multi-file archives.

Complete Examples

Create Backup Archive

╯ backup.bas─◻✕
println "=== Creating Backup ==="

backupName$ = "backup_" + format$(now(), "yyyymmdd") + ".zip"
handle# = zipcreate#(backupName$)
if PntToNum(handle#) = 0 then
    println "Failed to create archive"
    end
endif

files# = sdim#(4)
files#$[1] = "config.ini"
files#$[2] = "database.db"
files#$[3] = "settings.json"
files#$[4] = "notes.txt"

addedCount = 0
for i = 1 to 4
    filename$ = files#$[i]
    if fileexists(filename$, 0) = 1 then
        if zipadd(handle#, filename$, filename$) = 1 then
            println "Added: "; filename$
            addedCount = addedCount + 1
        endif
    else
        println "Skip: "; filename$
    endif
next

zipclose(handle#)
println "Backup: "; backupName$; " ("; addedCount; " files)"

Archive Browser

╯ browser.bas─◻✕
function onZipPath$(zipPath$) local handle#, count, fileList$
    if zipPath$ = "" then
        println "No path"
        return ""
    endif
    
    handle# = zipopen#(zipPath$)
    if PntToNum(handle#) = 0 then
        println "Cannot open: "; ziperror()
        return ""
    endif
    
    count = zipcount(handle#)
    println "Archive: "; zipPath$
    println "Files: "; count
    println ""
    
    fileList$ = ziplist$(handle#)
    println fileList$
    
    zipclose(handle#)
    return ""
endfunction

println "=== ZIP Browser ==="
input "Open", "ZIP file:", "", onZipPath$

Generate Archive with Content

╯ generate.bas─◻✕
println "=== Generate Archive ==="

handle# = zipcreate#("generated.zip")
if PntToNum(handle#) = 0 then
    println "Failed"
    end
endif

' README
readme$ = "Generated Archive" + chr$(10)
readme$ = readme$ + "Created: " + formatdatetime$("yyyy-mm-dd hh:nn:ss", now()) + chr$(10)
zipaddstr(handle#, readme$, "README.txt")
println "Added: README.txt"

Randomize()
' Data files in subdirectory
for i = 1 to 5
    data$ = "File #" + str$(i) + chr$(10)
    data$ = data$ + "Value: " + str$(rnd() * 1000) + chr$(10)
    zipaddstr(handle#, data$, "data/file" + stri$(i) + ".txt")
    println "Added: data/file"; i; ".txt"
next

' JSON manifest
manifest$ = "{\"name\": \"Generated\", \"files\": 6}"
zipaddstr(handle#, manifest$, "manifest.json")
println "Added: manifest.json"

zipclose(handle#)
println "Done: generated.zip"

Technical Notes

Topic	Details
Handle management	Always close with `zipclose`. Open handles consume system resources.
Read vs Write	`zipcreate#` = write only. `zipopen#` = read only.
Path separators	Use `/` in archive names for cross-platform compatibility.
Text encoding	`zipaddstr` and `zipread$` use UTF-8.
Large files	Use file-based functions (`zipadd`, `zipextract`) instead of string-based to avoid memory issues.
Directory structure	Include path separators in archive names (e.g. `docs/readme.txt`).

Quick Reference

Function	Signature	Description
`ziperror()`	`ziperror@`	Last error code (0–7)
`zipcreate#(path$)`	`zipcreate#@$`	Create new archive (write mode)
`zipopen#(path$)`	`zipopen#@$`	Open existing archive (read mode)
`zipclose(h#)`	`zipclose@#`	Close archive (1/0)
`zipadd(h#, src$, name$)`	`zipadd@#$$`	Add file to archive (1/0)
`zipaddstr(h#, content$, name$)`	`zipaddstr@#$$`	Add string as file (1/0)
`zipextract(h#, name$, dest$)`	`zipextract@#$$`	Extract single file (1/0)
`zipextractall(h#, dest$)`	`zipextractall@#$`	Extract all files (1/0)
`ziplist$(h#)`	`ziplist$@#`	List all files (newline-separated)
`zipcount(h#)`	`zipcount@#`	Number of files
`zipexists(h#, name$)`	`zipexists@#$`	File exists? (1/0)
`zipread$(h#, name$)`	`zipread$@#$`	Read file as string
`zipfilesize(h#, name$)`	`zipfilesize@#$`	Uncompressed size (-1 on error)
`zipquick(src$, zip$)`	`zipquick@$$`	Quick single-file compress (1/0)
`unzipquick(zip$, dest$)`	`unzipquick@$$`	Quick extract all (1/0)

14 functions across 6 categories.