| 1 |
/*! A library for parsing and extracting content of [LHA/LZH](https://en.wikipedia.org/wiki/LHA_(file_format)) archives. |
| 2 |
|
| 3 |
This library is for easy parsing of LHA headers and allows to read files compressed with some of the |
| 4 |
methods used by the archive format. |
| 5 |
|
| 6 |
This library does not provide high level methods for creating files or directories from the extracted archives. |
| 7 |
|
| 8 |
There are many extensions to the base LHA headers, used by many different archive programs, in many different |
| 9 |
operating systems. This library only allows for parsing some basic properties of the archived files, such as |
| 10 |
file path names and last modification timestamps. |
| 11 |
|
| 12 |
The [LhaHeader] exposes properties and methods to inspect the raw content of header extensions, as well as |
| 13 |
extended header data and may be explored by the user program in case extra archive properties are needed to be read. |
| 14 |
|
| 15 |
LHA header levels: 0, 1, 2 and 3 are recognized. |
| 16 |
|
| 17 |
|
| 18 |
## Compression methods |
| 19 |
|
| 20 |
You may include or opt out of some of the decoders: |
| 21 |
|
| 22 |
```toml |
| 23 |
[dependencies.delharc] |
| 24 |
version = "0.6" |
| 25 |
default-features = false |
| 26 |
features = ["std", "lh1"] # select desired features |
| 27 |
``` |
| 28 |
|
| 29 |
`lh1` and `lz` features are enabled by **default**. |
| 30 |
|
| 31 |
When using `default-features = false` the `std` feature needs to be added back along with other |
| 32 |
compression method features. Otherwise the library will be compiled in the `no_std` mode. |
| 33 |
|
| 34 |
| identifier | decoder | feature | description |
| 35 |
|------------|--------------------|---------|------------ |
| 36 |
| `-lh0-` | PassthroughDecoder | | no compression |
| 37 |
| `-lh1-` | Lh1Decoder | lh1 | LHarc version 1, 4kB sliding window, dynamic huffman |
| 38 |
| `-lh4-` | Lh5Decoder | | LHarc version 2, 4kB sliding window, static huffman |
| 39 |
| `-lh5-` | Lh5Decoder | | LHarc version 2, 8kB sliding window, static huffman |
| 40 |
| `-lh6-` | Lh7Decoder | | LHarc version 2, 32kB sliding window, static huffman |
| 41 |
| `-lh7-` | Lh7Decoder | | LHarc version 2, 64kB sliding window, static huffman |
| 42 |
| `-lhd-` | unsupported | | an empty directory, data should be empty and should be skipped |
| 43 |
| `-lhx-` | LhxDecoder | lhx | UNLHA32.DLL method, 128-512kb sliding window, static huffman |
| 44 |
| `-lz4-` | PassthroughDecoder | | no compression |
| 45 |
| `-lzs-` | LzsDecoder | lz | LArc, 2kb sliding window |
| 46 |
| `-lz5-` | Lz5Decoder | lz | LArc, 4kb sliding window |
| 47 |
| `-pm0-` | PassthroughDecoder | | no compression |
| 48 |
| `-pm1-` | unsupported | N/A | PMarc, 8 Kb sliding window, static huffman |
| 49 |
| `-pm2-` | unsupported | N/A | PMarc, 4 Kb sliding window, static huffman |
| 50 |
|
| 51 |
*/ |
| 52 |
#![cfg_attr(feature = "std", doc = r##" |
| 53 |
## Example |
| 54 |
|
| 55 |
```no_run |
| 56 |
use std::{io, path::Path}; |
| 57 |
|
| 58 |
fn extract_to_stdout<P: AsRef<Path>>( |
| 59 |
archive_name: P, |
| 60 |
matching_path: P |
| 61 |
) -> io::Result<bool> |
| 62 |
{ |
| 63 |
let mut lha_reader = delharc::parse_file(archive_name.as_ref())?; |
| 64 |
loop { |
| 65 |
let header = lha_reader.header(); |
| 66 |
let filename = header.parse_pathname(); |
| 67 |
|
| 68 |
eprintln!("Path: {:?} modified: {} ", filename, header.parse_last_modified()); |
| 69 |
|
| 70 |
if filename.ends_with(matching_path.as_ref()) { |
| 71 |
if lha_reader.is_decoder_supported() { |
| 72 |
let stdout = io::stdout(); |
| 73 |
let mut handle = stdout.lock(); |
| 74 |
io::copy(&mut lha_reader, &mut handle)?; |
| 75 |
lha_reader.crc_check()?; |
| 76 |
return Ok(true) |
| 77 |
} |
| 78 |
else if header.is_directory() { |
| 79 |
eprintln!("skipping: an empty directory"); |
| 80 |
} |
| 81 |
else { |
| 82 |
eprintln!("skipping: has unsupported compression method"); |
| 83 |
} |
| 84 |
} |
| 85 |
|
| 86 |
if !lha_reader.next_file()? { |
| 87 |
break; |
| 88 |
} |
| 89 |
} |
| 90 |
|
| 91 |
Ok(false) |
| 92 |
} |
| 93 |
``` |
| 94 |
"##)] |
| 95 |
/*! |
| 96 |
## No std |
| 97 |
|
| 98 |
With `std` feature enabled, [`error::LhaError`] converts to [`std::io::Error`] via the [`From`] trait |
| 99 |
and [`stub_io::Read`] is implemented for all types that implement [`std::io::Read`]. |
| 100 |
|
| 101 |
In this instance to read decompressed files, callers should access the [`LhaDecodeReader`] using |
| 102 |
[`std::io::Read`] trait methods. |
| 103 |
|
| 104 |
Without the `std` feature enabled `delharc` is compiled without the `std` library. |
| 105 |
The extern crate `alloc` is still required though. Because [`std::io`] is missing, |
| 106 |
in this instance callers should interface the [`LhaDecodeReader`] using [`stub_io::Read`] |
| 107 |
trait directly. [`stub_io::Read`] is implemented initially for `&[u8]` slices and `Box<R: Read>` |
| 108 |
and can be implemented for other types. |
| 109 |
|
| 110 |
When compiled without `std`: [`stub_io::Read`], [`stub_io::Take`] and `UnexpectedEofError` are |
| 111 |
re-exported directly under the crate root. `UnexpectedEofError` is only available in `no_std`. |
| 112 |
|
| 113 |
```ignore |
| 114 |
use delharc::{LhaDecodeReader, LhaError, LhaResult, Read, UnexpectedEofError}; |
| 115 |
const DATA: &[u8] = include_bytes!("file.lzh"); |
| 116 |
//... |
| 117 |
let lha_reader = LhaDecodeReader::new(DATA).unwrap(); |
| 118 |
``` |
| 119 |
*/ |
| 120 |
// http://archive.gamedev.net/archive/reference/articles/article295.html |
| 121 |
#![cfg_attr(not(feature = "std"), no_std)] |
| 122 |
#[cfg(not(feature = "std"))] |
| 123 |
extern crate alloc; |
| 124 |
pub mod crc; |
| 125 |
mod error; |
| 126 |
pub mod stub_io; |
| 127 |
pub mod decode; |
| 128 |
pub mod header; |
| 129 |
pub(crate) mod ringbuf; |
| 130 |
pub(crate) mod bitstream; |
| 131 |
pub(crate) mod statictree; |
| 132 |
|
| 133 |
pub use decode::LhaDecodeReader; |
| 134 |
pub use header::{ |
| 135 |
LhaHeader, CompressionMethod, OsType, TimestampResult, MsDosAttrs |
| 136 |
}; |
| 137 |
pub use error::{LhaError, LhaResult}; |
| 138 |
#[cfg(not(feature = "std"))] |
| 139 |
pub use stub_io::{Read, Take, UnexpectedEofError}; |
| 140 |
|
| 141 |
#[cfg(feature = "std")] |
| 142 |
use std::path::Path; |
| 143 |
#[cfg(feature = "std")] |
| 144 |
use std::fs::File; |
| 145 |
|
| 146 |
#[cfg(feature = "std")] |
| 147 |
/// Attempt to open a file from a filesystem in read-only mode and on success return an instance of |
| 148 |
/// [LhaDecodeReader] with the first parsed LHA file header, ready to decode the content of the first |
| 149 |
/// archived file. |
| 150 |
/// |
| 151 |
/// # `no_std` |
| 152 |
/// Available only with `std` feature enabled. |
| 153 |
/// |
| 154 |
/// # Errors |
| 155 |
/// This function will return an error if an opened file is not an LHA/LZH file or the header couldn't |
| 156 |
/// be recognized. Other errors may also be returned from [File::open] and from attempts to read the file. |
| 157 |
pub fn parse_file<P: AsRef<Path>>(path: P) -> std::io::Result<LhaDecodeReader<File>> { |
| 158 |
let file = File::open(path)?; |
| 159 |
Ok(LhaDecodeReader::new(file)?) |
| 160 |
} |