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}