commit	5337c7acd438dea8728464bc20bba71735cda45f	[log] [tgz]
author	Chih-Hung Hsieh <chh@google.com>	Mon Oct 12 09:44:57 2020 +0000
committer	Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>	Mon Oct 12 09:44:57 2020 +0000
tree	16c9f3c1b6152cc3494ba804e5e830f105154e80
parent	fcc4575e4764b90680571db4d7c155d265bd641b [diff]
parent	bbe7aa08dae399d28b40d65f49773033e2c9ed09 [diff]

tree: 16c9f3c1b6152cc3494ba804e5e830f105154e80

README.md

Textwrap

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.

Usage

To use textwrap, add this to your Cargo.toml file:

[dependencies]
textwrap = "0.12"

This gives you the text wrapping without of the optional features listed next.

`hyphenation`

If you would like to have automatic language-sensitive hyphenation, enable the hyphenation feature:

[dependencies]
textwrap = { version = "0.12", features = ["hyphenation"] }

This gives you hyphenation support for US English. Please see the hyphenation example for an executable demo. Read the Getting Started section below to see how to load the hyphenation patterns for other languages.

`terminal_size`

To conveniently wrap text at the current terminal width, enable the terminal_size feature:

[dependencies]
textwrap = { version = "0.12", features = ["terminal_size"] }

Please see the termwidth example for how to use this feature.

Documentation

API documentation

Getting Started

Word wrapping single strings is easy using the fill function:

fn main() {
    let text = "textwrap: a small library for wrapping text.";
    println!("{}", textwrap::fill(text, 18));
}

The output is

textwrap: a small
library for
wrapping text.

If you enable the hyphenation feature, you get support for automatic hyphenation for about 70 languages via high-quality TeX hyphenation patterns.

Your program must load the hyphenation pattern and call Wrapper::with_splitter to use it:

use hyphenation::{Language, Load, Standard};
use textwrap::Wrapper;

fn main() {
    let hyphenator = Standard::from_embedded(Language::EnglishUS).unwrap();
    let wrapper = Wrapper::with_splitter(18, hyphenator);
    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 US-English hyphenation patterns are embedded when you enable the hyphenation feature. They are licensed under a permissive license and take up about 88 KB of space in your application. If you need hyphenation for other languages, you need to download a precompiled .bincode file 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 some small example programs that shows various features.

Layout Example

The layout example shows how a fixed example string is wrapped at different widths. Run the example with:

$ cargo run --features hyphenation --example layout

The 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.

Terminal Width Example

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.
----

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. Contributions will be accepted under the same license.