Textwrap is a small Rust crate for word wrapping text. You can use it to format strings for display in commandline applications. The crate name and interface is inspired by the Python textwrap module.
Add this to your Cargo.toml:
[dependencies]
textwrap = "0.10"and this to your crate root:
extern crate textwrap;If you would like to have automatic hyphenation, specify the dependency as:
[dependencies]
textwrap = { version = "0.10", features = ["hyphenation"] }To conveniently wrap text at the current terminal width, enable the
term_size feature:
[dependencies]
textwrap = { version = "0.10", features = ["term_size"] }Word wrapping single strings is easy using the fill function:
extern crate textwrap;
use textwrap::fill;
fn main() {
let text = "textwrap: a small library for wrapping text.";
println!("{}", fill(text, 18));
}The output is
textwrap: a small
library for
wrapping text.
With the hyphenation feature, you can get automatic hyphenation
for about 70 languages. Your program must load and
configure the hyphenation patterns to use:
extern crate hyphenation;
extern crate textwrap;
use hyphenation::Language;
use textwrap::Wrapper;
fn main() {
let corpus = hyphenation::load(Language::English_US).unwrap();
let wrapper = Wrapper::with_splitter(18, corpus);
let text = "textwrap: a small library for wrapping text.";
println!("{}", wrapper.fill(text))
}The output now looks like this:
textwrap: a small
library for wrap-
ping text.
The hyphenation uses high-quality TeX hyphenation patterns.
The library comes with some small example programs that shows various features.
The layout example shows how a fixed example string is wrapped at
different widths. Run the example with:
$ cargo run --features hyphenation --example layoutThe program will use the following string:
Memory safety without garbage collection. Concurrency without data races. Zero-cost abstractions.
The string is wrapped at all widths between 15 and 60 columns. With narrow columns the output looks like this:
.--- Width: 15 ---.
| Memory safety |
| without garbage |
| collection. |
| Concurrency |
| without data |
| races. Zero- |
| cost abstrac- |
| tions. |
.--- Width: 16 ----.
| Memory safety |
| without garbage |
| collection. Con- |
| currency without |
| data races. Ze- |
| ro-cost abstrac- |
| tions. |
Later, longer lines are used and the output now looks like this:
.-------------------- Width: 49 --------------------.
| Memory safety without garbage collection. Concur- |
| rency without data races. Zero-cost abstractions. |
.---------------------- Width: 53 ----------------------.
| Memory safety without garbage collection. Concurrency |
| without data races. Zero-cost abstractions. |
.------------------------- Width: 59 -------------------------.
| Memory safety without garbage collection. Concurrency with- |
| out data races. Zero-cost abstractions. |
Notice how words are split at hyphens (such as "zero-cost") but also how words are hyphenated using automatic/machine hyphenation.
The termwidth example simply shows how the width can be set
automatically to the current terminal width. Run it with this command:
$ cargo run --example termwidth
If you run it in a narrow terminal, you'll see output like this:
Formatted in within 60 columns:
----
Memory safety without garbage collection. Concurrency
without data races. Zero-cost abstractions.
----
If stdout is not connected to the terminal, the program will use a
default of 80 columns for the width:
$ cargo run --example termwidth | cat
Formatted in within 80 columns:
----
Memory safety without garbage collection. Concurrency without data races. Zero-
cost abstractions.
----
This section lists the largest changes per release.
Due to our dependencies bumping their minimum supported version of Rust, the minimum version of Rust we test against is now 1.21.0.
- Merged #141: Fix
dedenthandling of empty lines and trailing newlines. Thanks @bbqsrc!
Due to our dependencies bumping their minimum supported version of Rust, the minimum version of Rust we test against is now 1.17.0.
Issues closed:
- Fixed #99: Word broken even though it would fit on line.
- Fixed #107: Automatic hyphenation is off by one.
- Fixed #122: Take newlines into account when wrapping.
- Fixed #129: Panic on string with em-dash.
The dependency on term_size is now optional, and by default this
feature is not enabled. This is a breaking change for users of
Wrapper::with_termwidth. Enable the term_size feature to restore
the old functionality.
Added a regression test for the case where width is set to
usize::MAX, thanks @Fraser999! All public structs now implement
Debug, thanks @hcpl!
Issues closed:
- Fixed #101: Make
term_sizean optional dependency.
The Wrapper stuct is now generic over the type of word splitter
being used. This means less boxing and a nicer API. The
Wrapper::word_splitter method has been removed. This is a breaking
API change if you used the method to change the word splitter.
The Wrapper struct has two new methods that will wrap the input text
lazily: Wrapper::wrap_iter and Wrapper::into_wrap_iter. Use those
if you will be iterating over the wrapped lines one by one.
Issues closed:
Version 0.7.0 changes the return type of Wrapper::wrap from
Vec<String> to Vec<Cow<'a, str>>. This means that the output lines
borrow data from the input string. This is a breaking API change if
you relied on the exact return type of Wrapper::wrap. Callers of the
textwrap::fill convenience function will see no breakage.
The above change and other optimizations makes version 0.7.0 roughly 15-30% faster than version 0.6.0.
The squeeze_whitespace option has been removed since it was
complicating the above optimization. Let us know if this option is
important for you so we can provide a work around.
Issues closed:
Version 0.6.0 adds builder methods to Wrapper for easy one-line
initialization and configuration:
let wrapper = Wrapper::new(60).break_words(false);It also add a new NoHyphenation word splitter that will never split
words, not even at existing hyphens.
Issues closed:
- Fixed #28: Support not squeezing whitespace
Version 0.5.0 has breaking API changes. However, this only affects
code using the hyphenation feature. The feature is now optional, so
you will first need to enable the hyphenation feature as described
above. Afterwards, please change your code from
wrapper.corpus = Some(&corpus);to
wrapper.splitter = Box::new(corpus);Other changes include optimizations, so version 0.5.0 is roughly 10-15% faster than version 0.4.0.
Issues closed:
- Fixed #19: Add support for finding terminal size
- Fixed #25: Handle words longer than
self.width - Fixed #26: Support custom indentation
- Fixed #36: Support building without
hyphenation - Fixed #39: Respect non-breaking spaces
Documented complexities and tested these via cargo bench.
- Fixed #13: Immediatedly add word if it fits
- Fixed #14: Avoid splitting on initial hyphens in
--foo-bar
Added support for automatic hyphenation.
Introduced Wrapper struct. Added support for wrapping on hyphens.
First public release with support for wrapping strings on whitespace.
Textwrap can be distributed according to the MIT license. Contributions will be accepted under the same license.