textwrap_macros/lib.rs
1//! *Simple procedural macros to use [`textwrap`] utilities at compile time.*
2//!
3//! [`textwrap`]: https://github.com/mgeisler/textwrap
4//!
5//! [](https://travis-ci.com/althonos/textwrap-macros/branches)
6//! [](https://codecov.io/gh/althonos/textwrap-macros)
7//! [](https://choosealicense.com/licenses/mit/)
8//! [](https://github.com/althonos/textwrap-macros)
9//! [](https://crates.io/crates/textwrap-macros)
10//! [](https://docs.rs/textwrap-macros)
11//! [](https://github.com/althonos/textwrap-macros.rs/blob/master/CHANGELOG.md)
12//!
13//! ## Usage
14//!
15//! Either use the macros using the old-style `#[macro_use]` or import them as
16//! any other crate member:
17//! ```rust
18//! use textwrap_macros::dedent;
19//!
20//! const poem: &str = dedent!(r#"
21//! When we two parted
22//! In silence and tears,
23//! Half broken-hearted
24//! To sever for years,
25//! Pale grew thy cheek and cold,
26//! Colder thy kiss;
27//! Truly that hour foretold
28//! Sorrow to this.
29//! "#);
30//! ```
31//!
32//! Checkout the [documentation of the original library](https://docs.rs/textwrap/0.12.0/textwrap/)
33//! for more information about the behaviour of each of the wrapped functions.
34//!
35//! ## Changelog
36//!
37//! This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html)
38//! and provides a [changelog](https://github.com/althonos/textwrap-macros/blob/master/CHANGELOG.md)
39//! in the [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) format.
40#![cfg_attr(not(feature = "std"), no_std)]
41
42extern crate proc_macro_hack;
43
44#[proc_macro_hack::proc_macro_hack]
45/// Removes common leading whitespace from each line.
46///
47/// This macro will look at each non-empty line and determine the maximum
48/// amount of whitespace that can be removed from all lines, and create a
49/// new string literal in place of the old one.
50///
51/// # Usage
52/// ```rust,ignore
53/// dedent!($text: lit &str) -> lit &str
54/// ```
55///
56/// # Example
57/// ```rust
58/// use textwrap_macros::dedent;
59///
60/// const X: &str = dedent!("
61/// 1st line
62/// 2nd line
63/// 3rd line
64/// ");
65///
66/// assert_eq!(X, "
67/// 1st line
68/// 2nd line
69/// 3rd line
70/// ");
71/// ```
72///
73/// See also [`textwrap::dedent`](https://docs.rs/textwrap/latest/textwrap/fn.dedent.html).
74pub use textwrap_macros_impl::dedent;
75
76#[proc_macro_hack::proc_macro_hack]
77/// Add prefix to each non-empty line.
78///
79/// Empty lines (consisting only of whitespaces, with respect to
80/// [`char.is_whitespace`](https://doc.rust-lang.org/std/primitive.char.html#method.is_whitespace))
81/// are not indented but replaced by a single newline character `\n`. Leading
82/// and trailing whitespace on non-empty lines is kept unchanged.
83///
84/// # Usage
85/// ```rust,ignore
86/// indent!($text: lit &str, $prefix: lit &str) -> lit &str
87/// ```
88///
89/// # Example
90/// ```rust
91/// use textwrap_macros::indent;
92///
93/// const Y: &str = indent!("\
94/// Foo
95/// Bar
96/// ", "-> ");
97///
98/// assert_eq!(Y, "\
99/// -> Foo
100/// -> Bar
101/// ");
102/// ```
103///
104/// See also [textwrap::indent](https://docs.rs/textwrap/latest/textwrap/fn.indent.html).
105pub use textwrap_macros_impl::indent;
106
107#[proc_macro_hack::proc_macro_hack]
108/// Fill a line of text at `width` characters.
109///
110/// Strings are wrapped based on their displayed width, not their size in bytes.
111/// The result is a string with newlines between each line. Use `wrap` if
112/// you need access to the individual lines.
113///
114/// # Usage
115/// ```rust, ignore
116/// fill!($text: lit &str, $width: lit usize) -> lit &str
117/// ```
118///
119/// # Example
120/// ```rust
121/// use textwrap_macros::fill;
122///
123/// const FILLED: &str = fill!("Memory safety without garbage collection.", 15);
124/// assert_eq!(FILLED, "Memory safety\nwithout garbage\ncollection.");
125/// ```
126///
127/// See also [textwrap::fill](https://docs.rs/textwrap/latest/textwrap/fn.fill.html).
128pub use textwrap_macros_impl::fill;
129
130#[proc_macro_hack::proc_macro_hack]
131/// Wrap a line of text at width characters.
132///
133/// Strings are wrapped based on their displayed width, not their size in
134/// bytes.
135///
136/// # Usage
137/// ```rust, ignore
138/// wrap!($text: lit &str, $width: lit usize) -> lit &[ lit &str ]
139/// ```
140///
141/// # Example
142/// ```rust
143/// use textwrap_macros::wrap;
144///
145/// const LINES: &[&str] = wrap!("Concurrency without data races.", 15);
146/// assert_eq!(LINES, ["Concurrency", "without data", "races."]);
147/// ```
148pub use textwrap_macros_impl::wrap;
149
150#[proc_macro_hack::proc_macro_hack]
151/// Unpack a paragraph of already-wrapped text.
152///
153/// This function attempts to recover the original text from a single paragraph
154/// of text. In addition, it will recognize a common prefix and a common line
155/// ending among the lines.
156///
157/// # Usage
158/// ```rust, ignore
159/// unfill!($text: lit &str) -> lit &str
160/// ```
161///
162/// # Example
163/// ```rust
164/// use textwrap_macros::unfill;
165///
166/// const TEXT: &str = unfill!("\
167/// Concurrency
168/// without data
169/// races.
170/// ");
171/// assert_eq!(TEXT, "Concurrency without data races.\n");
172/// ```
173pub use textwrap_macros_impl::unfill;
174
175#[proc_macro_hack::proc_macro_hack]
176/// Refill a paragraph of wrapped text with a new width.
177///
178/// This function will first use the `unfill` function to remove newlines from
179/// the text. Afterwards the text is filled again using the `fill` function.
180///
181/// # Usage
182/// ```rust, ignore
183/// fill!($text: lit &str, $width: lit usize) -> lit &str
184/// ```
185///
186/// # Example
187/// ```rust
188/// use textwrap_macros::refill;
189///
190/// const TEXT: &str = refill!("\
191/// Concurrency
192/// without data
193/// races.
194/// ", 20);
195/// assert_eq!(TEXT, "\
196/// Concurrency without
197/// data races.
198/// ");
199/// ```
200pub use textwrap_macros_impl::refill;