|
|
# Textwrap
|
|
|
|
|
|
[][build-status]
|
|
|
[][codecov]
|
|
|
[][crates-io]
|
|
|
[][api-docs]
|
|
|
|
|
|
Textwrap is a library for wrapping and indenting text. It is most
|
|
|
often used by command-line programs to format dynamic output nicely so
|
|
|
it looks good in a terminal. However, you can use the library to wrap
|
|
|
arbitrary things by implementing the `Fragment` trait — an example
|
|
|
would be wrapping text for PDF files.
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
To use the textwrap crate, add this to your `Cargo.toml` file:
|
|
|
```toml
|
|
|
[dependencies]
|
|
|
textwrap = "0.13"
|
|
|
```
|
|
|
|
|
|
By default, this enables word wrapping with support for Unicode
|
|
|
strings. Extra features can be enabled with Cargo features — and the
|
|
|
Unicode support can be disabled if needed. This allows you slim down
|
|
|
the library and so you will only pay for the features you actually
|
|
|
use. Please see the [_Cargo Features_ in the crate
|
|
|
documentation](https://docs.rs/textwrap/#cargo-features) for a full
|
|
|
list of the available features.
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
**[API documentation][api-docs]**
|
|
|
|
|
|
## Getting Started
|
|
|
|
|
|
Word wrapping is easy using the `fill` function:
|
|
|
|
|
|
```rust
|
|
|
fn main() {
|
|
|
let text = "textwrap: an efficient and powerful library for wrapping text.";
|
|
|
println!("{}", textwrap::fill(text, 28));
|
|
|
}
|
|
|
```
|
|
|
|
|
|
The output is wrapped within 28 columns:
|
|
|
|
|
|
```
|
|
|
textwrap: an efficient
|
|
|
and powerful library for
|
|
|
wrapping text.
|
|
|
```
|
|
|
|
|
|
Sharp-eyed readers will notice that the first line is 22 columns wide.
|
|
|
So why is the word “and” put in the second line when there is space
|
|
|
for it in the first line?
|
|
|
|
|
|
The explanation is that textwrap does not just wrap text one line at a
|
|
|
time. Instead, it uses an optimal-fit algorithm which looks ahead and
|
|
|
chooses line breaks which minimize the gaps left at ends of lines.
|
|
|
|
|
|
Without look-ahead, the first line would be longer and the text would
|
|
|
look like this:
|
|
|
|
|
|
```
|
|
|
textwrap: an efficient and
|
|
|
powerful library for
|
|
|
wrapping text.
|
|
|
```
|
|
|
|
|
|
The second line is now shorter and the text is more ragged. The kind
|
|
|
of wrapping can be configured via `Option::wrap_algorithm`.
|
|
|
|
|
|
If you enable the `hyphenation` Cargo feature, you get support for
|
|
|
automatic hyphenation for [about 70 languages][patterns] via
|
|
|
high-quality TeX hyphenation patterns.
|
|
|
|
|
|
Your program must load the hyphenation pattern and configure
|
|
|
`Options::splitter` to use it:
|
|
|
|
|
|
```rust
|
|
|
use hyphenation::{Language, Load, Standard};
|
|
|
use textwrap::Options;
|
|
|
|
|
|
fn main() {
|
|
|
let hyphenator = Standard::from_embedded(Language::EnglishUS).unwrap();
|
|
|
let options = Options::new(28).splitter(hyphenator);
|
|
|
let text = "textwrap: an efficient and powerful library for wrapping text.";
|
|
|
println!("{}", fill(text, &options);
|
|
|
}
|
|
|
```
|
|
|
|
|
|
The output now looks like this:
|
|
|
```
|
|
|
textwrap: an efficient and
|
|
|
powerful library for wrap-
|
|
|
ping text.
|
|
|
```
|
|
|
|
|
|
The US-English hyphenation patterns are embedded when you enable the
|
|
|
`hyphenation` feature. They are licensed under a [permissive
|
|
|
license][en-us license] and take up about 88 KB in your binary. If you
|
|
|
need hyphenation for other languages, you need to download a
|
|
|
[precompiled `.bincode` file][bincode] and load it yourself. Please
|
|
|
see the [`hyphenation` documentation] for details.
|
|
|
|
|
|
## Wrapping Strings at Compile Time
|
|
|
|
|
|
If your strings are known at compile time, please take a look at the
|
|
|
procedural macros from the [`textwrap-macros` crate].
|
|
|
|
|
|
## Examples
|
|
|
|
|
|
The library comes with [a
|
|
|
collection](https://github.com/mgeisler/textwrap/tree/master/examples)
|
|
|
of small example programs that shows various features. You’re invited
|
|
|
to clone the repository and try them out for yourself!
|
|
|
|
|
|
Of special note is the `interactive` example. This is a demo program
|
|
|
which demonstrates most of the available features: you can enter text
|
|
|
and adjust the width at which it is wrapped interactively. You can
|
|
|
also adjust the `Options` used to see the effect of different
|
|
|
`WordSplitter`s and wrap algorithms.
|
|
|
|
|
|
Run the demo with
|
|
|
|
|
|
```sh
|
|
|
$ cargo run --example interactive
|
|
|
```
|
|
|
|
|
|
The demo needs a Linux terminal to function.
|
|
|
|
|
|
## Release History
|
|
|
|
|
|
Please see the [CHANGELOG file] for details on the changes made in
|
|
|
each release.
|
|
|
|
|
|
## License
|
|
|
|
|
|
Textwrap can be distributed according to the [MIT license][mit].
|
|
|
Contributions will be accepted under the same license.
|
|
|
|
|
|
[crates-io]: https://crates.io/crates/textwrap
|
|
|
[build-status]: https://github.com/mgeisler/textwrap/actions?query=workflow%3Abuild+branch%3Amaster
|
|
|
[codecov]: https://codecov.io/gh/mgeisler/textwrap
|
|
|
[`textwrap-macros` crate]: https://crates.io/crates/textwrap-macros
|
|
|
[`hyphenation` example]: https://github.com/mgeisler/textwrap/blob/master/examples/hyphenation.rs
|
|
|
[`termwidth` example]: https://github.com/mgeisler/textwrap/blob/master/examples/termwidth.rs
|
|
|
[patterns]: https://github.com/tapeinosyne/hyphenation/tree/master/patterns-tex
|
|
|
[en-us license]: https://github.com/hyphenation/tex-hyphen/blob/master/hyph-utf8/tex/generic/hyph-utf8/patterns/tex/hyph-en-us.tex
|
|
|
[bincode]: https://github.com/tapeinosyne/hyphenation/tree/master/dictionaries
|
|
|
[`hyphenation` documentation]: http://docs.rs/hyphenation
|
|
|
[api-docs]: https://docs.rs/textwrap/
|
|
|
[CHANGELOG file]: https://github.com/mgeisler/textwrap/blob/master/CHANGELOG.md
|
|
|
[mit]: LICENSE
|
