Skip to content
Newer
Older
100644 140 lines (75 sloc) 3.4 KB
08627ae add deflate-stream and improve inflate-stream
John Foderaro authored
1
2 deflate module documentation
3
4 [this is temporary until the documentation is property formatted
5 and merged with other documentation]
6
7
8 The deflate module provides a stream interface to the widely
9 available libz compression library. libz is not included and is
10 assumee to be on your machine.
11
12
13
14
15
16 Functions are in the util.zip package.
17 The module exports
18
19 class:
20 deflate-stream
21
22 functions
23 deflate-target-stream
24 deflate-stream-vector
25 deflate-stream-vector-combined
26
27
28
29
30
31
32 This module implements the deflate-stream. A deflate-stream
33 accepts characters and byte and causes them to be compressed
34 and sent to a target.
35
36 The target can either another stream, or it can be a vector.
37 In the case of a vector the deflate-stream will collect the
38 complete deflation of what is written to it in a sequence of
39 vectors, initially using the vector passed in as the target and
40 then allocating new vectors as necessary.
41
42 Usage:
43 (make-instance 'deflate-stream :target target-spec :compression compress-spec)
44
45 The target-spec is a stream or a simple vector element type (unsigned-byte 8).
46
47 The compress-spec is either :gzip or :deflate (where :gzip is the default).
48
49 :gzip is the preferred format as the result can be uncompressed with
50 the inflate-stream (be sure to specify :skip-gzip-header t to the
51 make-instance of inflate-stream). The :gzip format output can
52 also be uncompressed with the gunzip program fount on Unix.
53
54
55
56
57
58 Stream as a target-spec
59
60 If you pass a stream as the target-spec then as you write characters
61 and bytes to the deflate-stream, the bytes resulting from deflation
62 will be written to the given stream. There is a lot of buffering
63 going on in this stream and the compression library. Therefore you
64 may not see the results in your target-spec stream immeidately.
65
66 When you close the deflate-stream the last bytes in all the buffers
67 will be sent through deflation and the end of deflation record will
68 be written to the target-spec stream.
69
70 The target-spec stream will NOT be closed. It is the callers responsibility
71 to close the stream passed in as the target-spec
72
73
74 The function
75 (deflate-target-stream deflate-stream)
76
77 will return that target-spec stream used by the deflate-stream
78
79
80
81 ;
82
83
84 Octet vector as a target-spec
85
86 Passing a simple vector of type (unsigned-byte 8) as the target-spec
87 is telling the deflate-stream that you wish to collect the deflation
88 result in vectors in the lisp heap.
89
90 After you close the deflate-stream you can retrieve the result of
91 deflation in one of two ways:
92
93
94
95 (deflate-stream-vector-combined deflate-stream)
96
97 returns two values
98 1. octet vector
99 2. number of bytes of actual data
100
101 this says that the result of deflation is found in the first N bytes
102 of the vector returned by the first value. The second value returned is N.
103
104
105
106
107
108 (deflate-stream-vector deflate-stream)
109
110 returns three values
111 1. the newest vector
112 2. the number of byte of actual data in the newest vector
113 3. a list of previous vectors holding data in reverse order
114
115 for example if the three returned values were
116
117 v
118 100
119 (c b a)
120
121 then the deflated result is found by combining in this order:
122 all of a
123 all of b
124 all of c
125 the first 100 bytes of v
126
127 The deflate-stream-vector-combined function does the combination
128 described above to produce its results. This results in
129 a new vector allocation and then copying that wouldn't be necessary
130 if you're prepared to work with the raw results from deflate-stream-vector
131
132
133
134
135
136
137
138
139
Something went wrong with that request. Please try again.