PICKLE Utilities Docs

There are, at the moment, two terribly exciting utilities: piklist,
which lists the contents of a PICKLE file, and pikmake, which puts
together existing files into a PICKLE file.

* Building

To compile the tools, you'll first have to adapt the pickle.h file
to your machine. Uncomment the definition of either BIG_ENDIAN or
LITTLE_ENDIAN, depending on whether integers are stored with the
most significant byte or the least significant byte first.
(Respectively.) Also, if the "long int" type is not 32 bits long,
you'll have to change the typedef of pikLong to whatever signed
integer type is 32 bits.

The library checks these settings at run-time, so you'll get error
messages if you set them wrong. 

Then type "make all", if you have anything resembling UNIX make. 

(Mac note: The Mac version of this archive comes with Pickle-List and
Pickle-Make applications already built. They're not pretty, but they
work. They don't accept dragged files. Double-click the application,
and then fill out the command line in the dialog. Don't delete the
application name; just add more arguments. There are some obvious
controls to redirect the output to a text file, if you want.)

* Use

	* piklist: 

Type "piklist file.pik" to list the contents of "file.pik". The
output will look something like this:

	test.pik:
	pict 1: (text 0) length 28, start 112
	exec 0: (zcod 5) length 1536, start 140
	pict 2: (text 0) length 34, start 1676
	pict 3: (text 0) length 28, start 1710

The format is
	USE NUMBER: (MAJORFORMAT MINORFORMAT) length LEN, start POS

where "length" and "start" are measured in bytes from the beginning
of the PICKLE file. If you've read the PICKLE spec, you'll note that
this is pretty much a direct dump of the descriptors at the
beginning of the file.

You can also use "piklist -m file.pik" to generate a listing in
the directory format used by pikmake. See:

	* pikmake:

Type "pikmake file.dir file.pik" to read in a directory listing from
file.dir, create a PICKLE file, and write it into file.pik. (If
file.pik already exists, it will be replaced.)

A directory listing looks something like this:

	# This is a comment
	pict 1 text 0 test1.pic
	exec 0 zcod 5 test.z5
	pict 2 text 0 test2.pic
	pict 3 text 0 test3.pic

Blank lines and lines beginning with '#' are comments. Each other
line defines a chunk which will go into the PICKLE file. The format
is
	USE NUMBER MAJORFORMAT MINORFORMAT FILENAME
This will create a chunk containing the entire file FILENAME. You can
also use lines like
	USE NUMBER MAJORFORMAT MINORFORMAT FILENAME ORIGSTART ORIGLENGTH
where ORIGSTART and ORIGLENGTH are numbers. This lets you create a
chunk containing just a piece of FILENAME; the piece used will start
at ORIGSTART bytes from the beginning of FILENAME, and be ORIGLENGTH
bytes long.

Recall that the "piklist -m file.pik" option generates listings in
this format, using "file.pik" as the FILENAME and the appropriate
start and length values. If you pour the resulting output back into
pikmake, pikmake will pluck all the chunks from file.pik and create
a new PICKLE file which is, well, exactly the same as file.pik. This
is more useful if you edit the output first, to add or replace a
chunk. With a little shell-script machinery you could even make
"pikaddchunk" or "pikdeletechunk" tools. Go crazy.