Debian Codegraph @

.cargo/vendor/delharc/README.md

raw
1 delharc
2 =======
3
4 [![Crate][Crate img]][Crate Link]
5 [![Docs][Docs img]][Docs Link]
6 [![Build Status][Build img]][Build Link]
7 [![Coverage Status][Coverage img]][Coverage Link]
8 [![Minimum rustc version][rustc version img]][rustc version link]
9
10 A [Rust] library for parsing and extracting content of [LHA/LZH] archives.
11
12 What it does
13 ------------
14
15 This library provides ways to parse the content of **LHA** headers and allows to read files, compressed with some of the methods used by the archive format.
16
17 Files using this format usually have `.lzh` or `.lha` extensions. Some formats, such as the retro chip-tune [YM] format, use **LHA** as its default packaging method. The entire content of the [Aminet] has also been packaged using this format.
18
19
20 What it doesn't do
21 ------------------
22
23 This library does not provide high level methods for creating files or directories from the extracted archives.
24
25
26 Usage
27 -----
28
29 Add to `Cargo.toml`:
30
31 ```toml
32 [dependencies]
33 delharc = "0.6"
34 ```
35
36 For more information, please see the [Documentation][Docs Link].
37
38
39 No std
40 ------
41
42 Since version 0.6 `delharc` can be used without the `std` library. In this instance the `alloc`
43 external crate will be required instead.
44
45 ```toml
46 [dependencies.delharc]
47 version = "0.6"
48 default-features = false
49 features = ["lh1", "lz"] # select desired features
50 ```
51
52 `delharc` API was originally built around the `std::io` types such as `io::Error` and `io::Read`.
53
54 This design choice made it impossible to adapt `delharc` to be used in the absence of the `std::io`
55 library without some significant implementation changes.
56
57 To work around this problem the `stub_io` module and `error` module was added. `stub_io`
58 contains an I/O proxy trait `Read` and a `Take` type which are now used as interfaces for generic
59 types throughout the library. Instead of relying on `io::Error` for fallible results `delharc`
60 defines its own `error::LhaError` which encapsulates an I/O error type.
61
62 With `std` library enabled, `error::LhaError` converts to `io::Error` via the `From` trait and
63 `stub_io::Read` is implemented for all types that implement `io::Read`.
64
65 For `std` users the difference from previous versions is that methods previously returning
66 `io::Result` now return `Result<_, LhaError<io::Error>>`. This might break cases when result
67 `Err(error)` from calls to `delharc` methods is returned as is without the `?` or `From` conversion.
68
69 Now, when using `default-features = false` the `std` feature needs to be added back along with other
70 compression method features.
71
72
73 Rust Version
74 ------------
75
76 `delharc` requires Rustc version 1.63 or greater due to the stabilized [`array::from_fn`](https://doc.rust-lang.org/std/array/fn.from_fn.html) function in this version.
77
78 License
79 -------
80
81 This project is licensed under either of
82
83 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
84 https://opensource.org/licenses/MIT)
85 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
86 https://www.apache.org/licenses/LICENSE-2.0)
87
88 at your option.
89
90 [Rust]: https://www.rust-lang.org/
91 [LHA/LZH]: https://en.wikipedia.org/wiki/LHA_(file_format)
92 [Aminet]: https://aminet.net/
93 [YM]: http://leonard.oxg.free.fr/ymformat.html
94 [Crate Link]: https://crates.io/crates/delharc
95 [Crate img]: https://img.shields.io/crates/v/delharc.svg
96 [Docs Link]: https://docs.rs/delharc
97 [Docs img]: https://docs.rs/delharc/badge.svg
98 [Build Link]: https://github.com/royaltm/rust-delharc/actions/workflows/ci.yml
99 [Build img]: https://github.com/royaltm/rust-delharc/actions/workflows/ci.yml/badge.svg?branch=master
100 [Coverage Link]: https://coveralls.io/github/royaltm/rust-delharc?branch=master
101 [Coverage img]: https://coveralls.io/repos/github/royaltm/rust-delharc/badge.svg?branch=master
102 [rustc version link]: https://github.com/royaltm/rust-delharc#rust-version
103 [rustc version img]: https://img.shields.io/badge/rustc-1.63+-lightgray.svg