admerge/lib.rs
1//! Provides mergers with advanced options.
2//!
3//! The main entities of this crate are [`RsMerger`] and [`FileMerger`]. The former works on any
4//! source that implemnts [`Read`] and [`Seek`] traits; the latter one is mostly identical with the
5//! former, but provides addtional methods to work with [`Path`]s and [`File`]s.
6//!
7//! # Behaviours
8//!
9//! When merging sources, mergers provided by this crate allow you to skip partials of contents
10//! from each source, pad with extra padding between sources. No modifications are done to the
11//! given sources as it violate the semantics of merging.
12//!
13//! The current algorithm to merge sources is described as following:
14//!
15//! 1. If any leading padding is given by [`pad_with`], writes it into the writer.
16//! 2. For each source, if skip range is given by [`skip_head`] and
17//! [`skip_tail`], writes the contents remain into the writer.
18//! 3. For each source, if forcing ending newline option is set by
19//! [`force_ending_newline`], writes a ending newline into the writer if this source
20//! is not ends with a newline.
21//! 4. For each source, if any inner padding is given by [`pad_with`], writes it into the
22//! writer.
23//! 5. If any ending padding is given by [`pad_with`], writes it into the writer.
24//!
25//! When merging three sources, the result should be imagined as following:
26//!
27//! ```bash
28//! ------------------------------
29//! | Padding before | <== `Pad::Before` apprears here.
30//! ------------------------------
31//! ------------------------------
32//! | Source 1 (skipped) | <== `skip_head` ignores partials of contents of source 1.
33//! ------------------------------
34//! ------------------------------
35//! | Source 1 (remaining) | <== The remaining contents of source 1.
36//! ------------------------------
37//! ------------------------------
38//! | Source 1 (skipped) | <== `skip_tail` ignores partials of contents of source 1.
39//! ------------------------------
40//! ------------------------------
41//! | An ending newline | <== `force_ending_newline` appends a newline here.
42//! ------------------------------
43//! ------------------------------
44//! | Padding between | <== `Pad::Between` apprears here.
45//! ------------------------------
46//! ------------------------------
47//! | Source 2 (skipped) | <== `skip_head` ignores partials of contents of source 2.
48//! ------------------------------
49//! ------------------------------
50//! | Source 2 (remaining) | <== The remaining contents of source 2.
51//! ------------------------------
52//! ------------------------------
53//! | Source 2 (skipped) | <== `skip_tail` ignores partials of contents of source 2.
54//! ------------------------------
55//! ------------------------------
56//! | An ending newline | <== `force_ending_newline` appends a newline here.
57//! ------------------------------
58//! ------------------------------
59//! | Padding between | <== `Pad::Between` apprears here.
60//! ------------------------------
61//! ------------------------------
62//! | Source 3 (skipped) | <== `skip_head` ignores partials of contents of source 3.
63//! ------------------------------
64//! ------------------------------
65//! | Source 3 (remaining) | <== The remaining contents of source 3.
66//! ------------------------------
67//! ------------------------------
68//! | Source 3 (skipped) | <== `skip_tail` ignores partials of contents of source 3.
69//! ------------------------------
70//! ------------------------------
71//! | An ending newline | <== `force_ending_newline` appends a newline here.
72//! ------------------------------
73//! ------------------------------
74//! | Padding after | <== `Pad::After` apprears here.
75//! ------------------------------
76//! ```
77//!
78//! [`Read`]: std::io::Read
79//! [`Seek`]: std::io::Seek
80//! [`Path`]: std::path::Path
81//! [`File`]: std::fs::File
82//! [`new`]: RsMerger::new
83//! [`pad_with`]: RsMerger::pad_with
84//! [`skip_head`]: RsMerger::skip_head
85//! [`skip_tail`]: RsMerger::skip_tail
86//! [`force_ending_newline`]: RsMerger::force_ending_newline
87//! [`merge_sources_into`]: RsMerger::merge_sources_into
88mod error;
89mod merge;
90mod util;
91
92pub use error::*;
93pub use merge::*;