Debian Codegraph @

.cargo/vendor/delharc/src/lib.rs

raw
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 }