Addons/arc/zip

From J Wiki
Jump to navigation Jump to search
User Guide | Installation | Development | Categories | Git | Build Log

arc/zip - zip file utilities

Provides zip file utilities with API similar to the files package.
Based on zlib 1.2.3 and minizip libraries.
Interface API is similar to the files package. Includes Win32, Linux and Mac OS X universal binaries.
Browse source and examples in SVN.


Installation

Use JAL/Package Manager or download the arc_zip archive from JAL:j601/addons and into the addons/arc/zip folder.

Zip Files

Load zip addon with the following line

   load 'arc/zip/zfiles'

To see the sampler of usage, run the test.ijs script with Ctrl+E. Here is a typical output.

Files Information

Check if a zip file exists with regular file utilities

   fexist jpath '~addons/arc/zip/test.zip'
1

Get directory of the zip file

   zdir jpath '~addons/arc/zip/test.zip'
+---------------+-----------------+------+---+------+
|test1.ijs      |2006 2 20 2 10 24|45    |rw-|-----a|
+---------------+-----------------+------+---+------+
|test2.txt      |2006 2 20 2 7 6  |21    |rw-|-----a|
+---------------+-----------------+------+---+------+
|zlib.bmp       |2006 2 20 4 21 4 |226086|rw-|-----a|
+---------------+-----------------+------+---+------+
|other/         |2006 2 20 4 26 56|0     |rw-|----da|
+---------------+-----------------+------+---+------+
|other/test3.txt|2006 2 20 4 27 22|32    |rw-|-----a|
+---------------+-----------------+------+---+------+

Subset of files is obtained with regular file mask

   zdir '*.txt';jpath '~addons/arc/zip/test.zip'
+---------------+-----------------+--+---+------+
|test2.txt      |2006 2 20 2 7 6  |21|rw-|-----a|
+---------------+-----------------+--+---+------+
|other/test3.txt|2006 2 20 4 27 22|32|rw-|-----a|
+---------------+-----------------+--+---+------+

File size can be obtained as for regular files

   zsize 'test2.txt';jpath '~addons/arc/zip/test.zip'
21

Check if internal file exists. Note folder separator is always '/'

   zexist 'other/test3.txt';jpath '~addons/arc/zip/test.zip'
1

Extracting files

Files are extracted with zread one at a time. Full path inside zip must be provided.

   zread 'test2.txt';jpath '~addons/arc/zip/test.zip'
this is a test text

   #zread 'test2.txt';jpath '~addons/arc/zip/test.zip'
21

Appending Files

Files are appended with zwrite one at a time. If zip file does not exist, it is automatically created.

   'one' zwrite 'test1.txt';jpath '~addons/arc/zip/test1.zip'
3
   'two123' zwrite 'test2.txt';jpath '~addons/arc/zip/test1.zip'
6
   zdir jpath '~addons/arc/zip/test1.zip'
+---------+-----------------+-+---+------+
|test1.txt|2006 7 12 9 45 54|3|rw-|-----a|
+---------+-----------------+-+---+------+
|test2.txt|2006 7 12 9 46 4 |6|rw-|-----a|
+---------+-----------------+-+---+------+

The left argument is the contents of the file named on the right by the first element of the right argument. So, to zip a single file, leaving the name the same except for the .zip suffix, you could do something like this:

   (fread 'foo.bar') zwrite 'foo.bar';'foo.zip'

Duplicate file names are permitted. To update or erase an existing file, the zip must be recreated and all the files pumped over.

To append an existing file, it is read into memory first, thus allowing to copy files both from disk and other zips.

   32{. F=. fread jpath '~addons/arc/zip/zfiles.ijs'
NB. zfiles - zip file utilities

   F zwrite 'test1.ijs';jpath '~addons/arc/zip/test1.zip'
6478

   zdir jpath '~addons/arc/zip/test1.zip'
| ...
+---------+------------------+----+---+------+
|test1.ijs|2006 7 14 14 40 50|6478|rw-|-----a|
+---------+------------------+----+---+------+

   32{.zread 'test1.ijs';jpath '~addons/arc/zip/test1.zip'
NB. zfiles - zip file utilities

There are many possible scenarios, such as zipping a folder, possibly recursive, versioning, giving other names to files, etc., details of which are best to be resolved in particular application specific utility, which will use this basic functionality.

Folders

An individual file or folder can be queried with zinfo

   zinfo 'other/';jpath '~addons/arc/zip/test.zip'
+------+-----------------+-+---+------+
|other/|2006 2 20 4 26 56|0|rw-|----da|
+------+-----------------+-+---+------+

Folders always terminate with '/'

   ztype 'other/';jpath '~addons/arc/zip/test.zip'
2

Information.png Press Ctrl-F1 on ztype to see scriptdoc for further information.

To append a folder, simply append a file with empty content whose name is terminated with the '/' symbol.

To append a folder, simply append a file with empty content whose name is terminated with the '/' symbol.

   '' zwrite 'folder/';DIR,'/test1.zip'
0
   'three' zwrite 'folder/test3.txt';DIR,'/test1.zip'
5
   zdir DIR,'/test1.zip'
+----------------+----------------+----+---+------+
|folder/         |2007 8 8 2 29 32|0   |rw-|----da|
+----------------+----------------+----+---+------+
|folder/test3.txt|2007 8 8 2 29 32|5   |rw-|-----a|
+----------------+----------------+----+---+------+

Running Scripts

Zip addon allows scripts to be run directly from zip files. Thus it provides a means for distributing and using code compactly in zip files without unpacking.

   zread 'test1.ijs';jpath '~addons/arc/zip/test.zip'
smoutput 'test script output'
TEST=: i.3 4

   zscript 'test1.ijs';jpath '~addons/arc/zip/test.zip'
test script output

   names''
TEST
   TEST
0 1  2  3
4 5  6  7
8 9 10 11

You can also run the script in a different locale.

   a=. cocreate''
   zscript__a 'test1.ijs';jpath '~addons/arc/zip/test.zip'
test script output
   names__a''
TEST
   codestroy__a''
1

Resources

Zip files can provide medium for resources, which can be stored in a convenient format while saving space.

   load'viewmat'
   bfile=: jpath'~temp/test.bmp'

   bfile fwrite~ zread 'zlib.bmp';jpath '~addons/arc/zip/test.zip'
226086

   viewbmp bfile

Error Handling

Errors are handled similar to files package. To see error details, examine the ZERR_zfiles_ noun. See zfiles.ijs for further details.

Information.png Errors could be related either to either incorrect zip or internal file.

   zinfo 'other';jpath '~addons/arc/zip/test.zip'     NB. empty result

   0=#zinfo 'other';jpath '~addons/arc/zip/test.zip'
1
   ZERR_zfiles_
_100

   zsize 'bogus';jpath '~addons/arc/zip/test.zip'
_1
   zread 'bogus';jpath '~addons/arc/zip/test.zip'
_1
   zscript 'bogus';jpath '~addons/arc/zip/bogus.zip'
|domain error: zscript
|       0!:0 zread y.
   ZERR_zfiles_
_1

In-memory Buffer

The arc/zip/zbuffer addon script implements in-memory buffer compression using zlib. Combined with ascii85 it produces plain text encoding.

  load 'arc/zip/zbuffer'

  zput85 2000$a.
GhQY8A7B.ZARjo]jPo=\jl7-g'G;/n'bcpqP`h>pQ'59G<)Qao<E%MreC)pqe^HH21bpsD2)D_G
['I-F[Bk'rFE2PEF`[<Ho^__Gp%&\"$jmIN%1A5QN/EXPNJgS'9M/&O9hWgRbf\5Qc-%ag/1N8$
/M"$'XK&G&XfHARChdj%D/8V(m-=$'mH^AuERNns;l<?^0ltq43HOB.?a+Lsi[%6a/RPc'e`o#-
f<*r7ERX&%>ISJ,Z#eOb4aZqj5B-,=i?LjR*C"Q7eEJc%c^hgin^?ML=0GoEEV%cK4*U/LJ+2sT
j!RWp4b*"mea#/4hnB'Zn^HYS?b_$hnakB$5C`_3B,L=AW;fBd5O/8Gs,[#+)#,0Q()tW?    ~>

  (-: # zget85 zput85) 10000$a.
1
  (-: # zget  zput  ) 10000$a.
1

ascii85 (used in zput85) emits multi-line LF separated output. So it can be used together with 0 : 0 ... ).

Authors