177 lines
6.2 KiB
Markdown
177 lines
6.2 KiB
Markdown
|
# 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. You can also use Textwrap to wrap text
|
|||
|
|
set in a proportional font—such as text used to generate PDF files, or
|
|||
|
|
drawn on a [HTML5 canvas using WebAssembly][wasm-demo].
|
|||
|
|
|
|||
|
|
## Usage
|
|||
|
|
|
|||
|
|
To use the textwrap crate, add this to your `Cargo.toml` file:
|
|||
|
|
```toml
|
|||
|
|
[dependencies]
|
|||
|
|
textwrap = "0.15"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
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 as well as their impact on the size of
|
|||
|
|
your binary.
|
|||
|
|
|
|||
|
|
## Documentation
|
|||
|
|
|
|||
|
|
**[API documentation][api-docs]**
|
|||
|
|
|
|||
|
|
## Getting Started
|
|||
|
|
|
|||
|
|
Word wrapping is easy using the `wrap` and `fill` functions:
|
|||
|
|
|
|||
|
|
```rust
|
|||
|
|
#[cfg(feature = "smawk")] {
|
|||
|
|
let text = "textwrap: an efficient and powerful library for wrapping text.";
|
|||
|
|
assert_eq!(
|
|||
|
|
textwrap::wrap(text, 28),
|
|||
|
|
vec![
|
|||
|
|
"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.
|
|||
|
|
This is controlled with the `smawk` Cargo feature, which is why the
|
|||
|
|
example is wrapped in the `cfg`-block.
|
|||
|
|
|
|||
|
|
Without look-ahead, the first line would be longer and the text would
|
|||
|
|
look like this:
|
|||
|
|
|
|||
|
|
```rust
|
|||
|
|
#[cfg(not(feature = "smawk"))] {
|
|||
|
|
let text = "textwrap: an efficient and powerful library for wrapping text.";
|
|||
|
|
assert_eq!(
|
|||
|
|
textwrap::wrap(text, 28),
|
|||
|
|
vec![
|
|||
|
|
"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 `Options::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::word_splitter` to use it:
|
|||
|
|
|
|||
|
|
```rust
|
|||
|
|
#[cfg(feature = "hyphenation")] {
|
|||
|
|
use hyphenation::{Language, Load, Standard};
|
|||
|
|
use textwrap::{fill, Options, WordSplitter};
|
|||
|
|
|
|||
|
|
let dictionary = Standard::from_embedded(Language::EnglishUS).unwrap();
|
|||
|
|
let options = textwrap::Options::new(28).word_splitter(WordSplitter::Hyphenation(dictionary));
|
|||
|
|
let text = "textwrap: an efficient and powerful library for wrapping text.";
|
|||
|
|
|
|||
|
|
assert_eq!(
|
|||
|
|
textwrap::wrap(text, &options),
|
|||
|
|
vec![
|
|||
|
|
"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.
|
|||
|
|
|
|||
|
|
If you want to see Textwrap in action right away, then take a look at
|
|||
|
|
[`examples/wasm/`], which shows how to wrap sans-serif, serif, and
|
|||
|
|
monospace text. It uses WebAssembly and is automatically deployed to
|
|||
|
|
https://mgeisler.github.io/textwrap/.
|
|||
|
|
|
|||
|
|
For the command-line examples, you’re invited to clone the repository
|
|||
|
|
and try them out for yourself! Of special note is
|
|||
|
|
[`examples/interactive.rs`]. 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
|
|||
|
|
[wasm-demo]: https://mgeisler.github.io/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
|
|||
|
|
[`examples/wasm/`]: https://github.com/mgeisler/textwrap/tree/master/examples/wasm
|
|||
|
|
[`examples/interactive.rs`]: https://github.com/mgeisler/textwrap/tree/master/examples/interactive.rs
|
|||
|
|
[api-docs]: https://docs.rs/textwrap/
|
|||
|
|
[CHANGELOG file]: https://github.com/mgeisler/textwrap/blob/master/CHANGELOG.md
|
|||
|
|
[mit]: LICENSE
|