1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
# seek-bzip
[![Build Status][1]][2] [![dependency status][3]][4] [![dev dependency status][5]][6]
`seek-bzip` is a pure-javascript Node.JS module adapted from [node-bzip](https://github.com/skeggse/node-bzip) and before that [antimatter15's pure-javascript bzip2 decoder](https://github.com/antimatter15/bzip2.js). Like these projects, `seek-bzip` only does decompression (see [compressjs](https://github.com/cscott/compressjs) if you need compression code). Unlike those other projects, `seek-bzip` can seek to and decode single blocks from the bzip2 file.
`seek-bzip` primarily decodes buffers into other buffers, synchronously.
With the help of the [fibers](https://github.com/laverdet/node-fibers)
package, it can operate on node streams; see `test/stream.js` for an
example.
## How to Install
```
npm install seek-bzip
```
This package uses
[Typed Arrays](https://developer.mozilla.org/en-US/docs/JavaScript/Typed_arrays), which are present in node.js >= 0.5.5.
## Usage
After compressing some example data into `example.bz2`, the following will recreate that original data and save it to `example`:
```
var Bunzip = require('seek-bzip');
var fs = require('fs');
var compressedData = fs.readFileSync('example.bz2');
var data = Bunzip.decode(compressedData);
fs.writeFileSync('example', data);
```
See the tests in the `tests/` directory for further usage examples.
For uncompressing single blocks of bzip2-compressed data, you will need
an out-of-band index listing the start of each bzip2 block. (Presumably
you generate this at the same time as you index the start of the information
you wish to seek to inside the compressed file.) The `seek-bzip` module
has been designed to be compatible with the C implementation `seek-bzip2`
available from https://bitbucket.org/james_taylor/seek-bzip2. That codebase
contains a `bzip-table` tool which will generate bzip2 block start indices.
There is also a pure-JavaScript `seek-bzip-table` tool in this package's
`bin` directory.
## Documentation
`require('seek-bzip')` returns a `Bunzip` object. It contains three static
methods. The first is a function accepting one or two parameters:
`Bunzip.decode = function(input, [Number expectedSize] or [output], [boolean multistream])`
The `input` argument can be a "stream" object (which must implement the
`readByte` method), or a `Buffer`.
If `expectedSize` is not present, `decodeBzip` simply decodes `input` and
returns the resulting `Buffer`.
If `expectedSize` is present (and numeric), `decodeBzip` will store
the results in a `Buffer` of length `expectedSize`, and throw an error
in the case that the size of the decoded data does not match
`expectedSize`.
If you pass a non-numeric second parameter, it can either be a `Buffer`
object (which must be of the correct length; an error will be thrown if
the size of the decoded data does not match the buffer length) or
a "stream" object (which must implement a `writeByte` method).
The optional third `multistream` parameter, if true, attempts to continue
reading past the end of the bzip2 file. This supports "multistream"
bzip2 files, which are simply multiple bzip2 files concatenated together.
If this argument is true, the input stream must have an `eof` method
which returns true when the end of the input has been reached.
The second exported method is a function accepting two or three parameters:
`Bunzip.decodeBlock = function(input, Number blockStartBits, [Number expectedSize] or [output])`
The `input` and `expectedSize`/`output` parameters are as above.
The `blockStartBits` parameter gives the start of the desired block, in bits.
If passing a stream as the `input` parameter, it must implement the
`seek` method.
The final exported method is a function accepting two or three parameters:
`Bunzip.table = function(input, Function callback, [boolean multistream])`
The `input` and `multistream` parameters are identical to those for the
`decode` method.
This function will invoke `callback(position, size)` once per bzip2 block,
where `position` gives the starting position of the block (in *bits*), and
`size` gives the uncompressed size of the block (in bytes).
This can be used to construct an index allowing direct access to a particular
block inside a bzip2 file, using the `decodeBlock` method.
## Command-line
There are binaries available in bin. The first generates an index of all
the blocks in a bzip2-compressed file:
```
$ bin/seek-bzip-table test/sample4.bz2
32 99981
320555 99981
606348 99981
847568 99981
1089094 99981
1343625 99981
1596228 99981
1843336 99981
2090919 99981
2342106 39019
$
```
The first field is the starting position of the block, in bits, and the
second field is the length of the block, in bytes.
The second binary decodes an arbitrary block of a bzip2 file:
```
$ bin/seek-bunzip -d -b 2342106 test/sample4.bz2 | tail
élan's
émigré
émigré's
émigrés
épée
épée's
épées
étude
étude's
études
$
```
Use `--help` to see other options.
## Help wanted
Improvements to this module would be generally useful.
Feel free to fork on github and submit pull requests!
## Related projects
* https://github.com/skeggse/node-bzip node-bzip (original upstream source)
* https://github.com/cscott/compressjs
Lots of compression/decompression algorithms from the same author as this
module, including bzip2 compression code.
* https://github.com/cscott/lzjb fast LZJB compression/decompression
## License
#### MIT License
> Copyright © 2013-2015 C. Scott Ananian
>
> Copyright © 2012-2015 Eli Skeggs
>
> Copyright © 2011 Kevin Kwok
>
> Permission is hereby granted, free of charge, to any person obtaining
> a copy of this software and associated documentation files (the
> "Software"), to deal in the Software without restriction, including
> without limitation the rights to use, copy, modify, merge, publish,
> distribute, sublicense, and/or sell copies of the Software, and to
> permit persons to whom the Software is furnished to do so, subject to
> the following conditions:
>
> The above copyright notice and this permission notice shall be
> included in all copies or substantial portions of the Software.
>
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
[1]: https://travis-ci.org/cscott/seek-bzip.png
[2]: https://travis-ci.org/cscott/seek-bzip
[3]: https://david-dm.org/cscott/seek-bzip.png
[4]: https://david-dm.org/cscott/seek-bzip
[5]: https://david-dm.org/cscott/seek-bzip/dev-status.png
[6]: https://david-dm.org/cscott/seek-bzip#info=devDependencies
|
