README.md
1# Textwrap
2
3[][build-status]
4[][codecov]
5[][crates-io]
6[][api-docs]
7
8Textwrap is a library for wrapping and indenting text. It is most
9often used by command-line programs to format dynamic output nicely so
10it looks good in a terminal. However, you can use the library to wrap
11arbitrary things by implementing the `Fragment` trait — an example
12would be wrapping text for PDF files.
13
14## Usage
15
16To use the textwrap crate, add this to your `Cargo.toml` file:
17```toml
18[dependencies]
19textwrap = "0.13"
20```
21
22By default, this enables word wrapping with support for Unicode
23strings. Extra features can be enabled with Cargo features — and the
24Unicode support can be disabled if needed. This allows you slim down
25the library and so you will only pay for the features you actually
26use. Please see the [_Cargo Features_ in the crate
27documentation](https://docs.rs/textwrap/#cargo-features) for a full
28list of the available features.
29
30## Documentation
31
32**[API documentation][api-docs]**
33
34## Getting Started
35
36Word wrapping is easy using the `fill` function:
37
38```rust
39fn main() {
40 let text = "textwrap: an efficient and powerful library for wrapping text.";
41 println!("{}", textwrap::fill(text, 28));
42}
43```
44
45The output is wrapped within 28 columns:
46
47```
48textwrap: an efficient
49and powerful library for
50wrapping text.
51```
52
53Sharp-eyed readers will notice that the first line is 22 columns wide.
54So why is the word “and” put in the second line when there is space
55for it in the first line?
56
57The explanation is that textwrap does not just wrap text one line at a
58time. Instead, it uses an optimal-fit algorithm which looks ahead and
59chooses line breaks which minimize the gaps left at ends of lines.
60
61Without look-ahead, the first line would be longer and the text would
62look like this:
63
64```
65textwrap: an efficient and
66powerful library for
67wrapping text.
68```
69
70The second line is now shorter and the text is more ragged. The kind
71of wrapping can be configured via `Option::wrap_algorithm`.
72
73If you enable the `hyphenation` Cargo feature, you get support for
74automatic hyphenation for [about 70 languages][patterns] via
75high-quality TeX hyphenation patterns.
76
77Your program must load the hyphenation pattern and configure
78`Options::splitter` to use it:
79
80```rust
81use hyphenation::{Language, Load, Standard};
82use textwrap::Options;
83
84fn main() {
85 let hyphenator = Standard::from_embedded(Language::EnglishUS).unwrap();
86 let options = Options::new(28).splitter(hyphenator);
87 let text = "textwrap: an efficient and powerful library for wrapping text.";
88 println!("{}", fill(text, &options);
89}
90```
91
92The output now looks like this:
93```
94textwrap: an efficient and
95powerful library for wrap-
96ping text.
97```
98
99The US-English hyphenation patterns are embedded when you enable the
100`hyphenation` feature. They are licensed under a [permissive
101license][en-us license] and take up about 88 KB in your binary. If you
102need hyphenation for other languages, you need to download a
103[precompiled `.bincode` file][bincode] and load it yourself. Please
104see the [`hyphenation` documentation] for details.
105
106## Wrapping Strings at Compile Time
107
108If your strings are known at compile time, please take a look at the
109procedural macros from the [`textwrap-macros` crate].
110
111## Examples
112
113The library comes with [a
114collection](https://github.com/mgeisler/textwrap/tree/master/examples)
115of small example programs that shows various features. You’re invited
116to clone the repository and try them out for yourself!
117
118Of special note is the `interactive` example. This is a demo program
119which demonstrates most of the available features: you can enter text
120and adjust the width at which it is wrapped interactively. You can
121also adjust the `Options` used to see the effect of different
122`WordSplitter`s and wrap algorithms.
123
124Run the demo with
125
126```sh
127$ cargo run --example interactive
128```
129
130The demo needs a Linux terminal to function.
131
132## Release History
133
134Please see the [CHANGELOG file] for details on the changes made in
135each release.
136
137## License
138
139Textwrap can be distributed according to the [MIT license][mit].
140Contributions will be accepted under the same license.
141
142[crates-io]: https://crates.io/crates/textwrap
143[build-status]: https://github.com/mgeisler/textwrap/actions?query=workflow%3Abuild+branch%3Amaster
144[codecov]: https://codecov.io/gh/mgeisler/textwrap
145[`textwrap-macros` crate]: https://crates.io/crates/textwrap-macros
146[`hyphenation` example]: https://github.com/mgeisler/textwrap/blob/master/examples/hyphenation.rs
147[`termwidth` example]: https://github.com/mgeisler/textwrap/blob/master/examples/termwidth.rs
148[patterns]: https://github.com/tapeinosyne/hyphenation/tree/master/patterns-tex
149[en-us license]: https://github.com/hyphenation/tex-hyphen/blob/master/hyph-utf8/tex/generic/hyph-utf8/patterns/tex/hyph-en-us.tex
150[bincode]: https://github.com/tapeinosyne/hyphenation/tree/master/dictionaries
151[`hyphenation` documentation]: http://docs.rs/hyphenation
152[api-docs]: https://docs.rs/textwrap/
153[CHANGELOG file]: https://github.com/mgeisler/textwrap/blob/master/CHANGELOG.md
154[mit]: LICENSE
155
){kind=link}
){kind=link}
){kind=link}
){kind=link}