diff options
Diffstat (limited to 'textwrap/README.md')
| -rw-r--r-- | textwrap/README.md | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/textwrap/README.md b/textwrap/README.md deleted file mode 100644 index 23a5439..0000000 --- a/textwrap/README.md +++ /dev/null @@ -1,337 +0,0 @@ -# Textwrap - -[][crates-io] -[][api-docs] -[][travis-ci] -[][appveyor] -[][codecov] - -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][py-textwrap]. - -## Usage - -Add this to your `Cargo.toml`: -```toml -[dependencies] -textwrap = "0.11" -``` - -and this to your crate root: -```rust -extern crate textwrap; -``` - -If you would like to have automatic hyphenation, specify the -dependency as: -```toml -[dependencies] -textwrap = { version = "0.11", features = ["hyphenation"] } -``` - -To conveniently wrap text at the current terminal width, enable the -`term_size` feature: - -```toml -[dependencies] -textwrap = { version = "0.11", features = ["term_size"] } -``` - -## Documentation - -**[API documentation][api-docs]** - -## Getting Started - -Word wrapping single strings is easy using the `fill` function: -```rust -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][patterns]. Your program must load and -configure the hyphenation patterns to use: -```rust -extern crate hyphenation; -extern crate textwrap; - -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 hyphenation uses high-quality TeX hyphenation patterns. - -## 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: - -```shell -$ 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 - -This section lists the largest changes per release. - -### Version 0.11.0 — December 9th, 2018 - -Due to our dependencies bumping their minimum supported version of -Rust, the minimum version of Rust we test against is now 1.22.0. - -* Merged [#141][issue-141]: Fix `dedent` handling of empty lines and - trailing newlines. Thanks @bbqsrc! -* Fixed [#151][issue-151]: Release of version with hyphenation 0.7. - -### Version 0.10.0 — April 28th, 2018 - -Due to our dependencies bumping their minimum supported version of -Rust, the minimum version of Rust we test against is now 1.17.0. - -* Fixed [#99][issue-99]: Word broken even though it would fit on line. -* Fixed [#107][issue-107]: Automatic hyphenation is off by one. -* Fixed [#122][issue-122]: Take newlines into account when wrapping. -* Fixed [#129][issue-129]: Panic on string with em-dash. - -### Version 0.9.0 — October 5th, 2017 - -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! - -* Fixed [#101][issue-101]: Make `term_size` an optional dependency. - -### Version 0.8.0 — September 4th, 2017 - -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. - -* Fixed [#59][issue-59]: `wrap` could return an iterator. Thanks - @hcpl! -* Fixed [#81][issue-81]: Set `html_root_url`. - -### Version 0.7.0 — July 20th, 2017 - -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. - -* Fixed [#58][issue-58]: Add a "fast_wrap" function. -* Fixed [#61][issue-61]: Documentation errors. - -### Version 0.6.0 — May 22nd, 2017 - -Version 0.6.0 adds builder methods to `Wrapper` for easy one-line -initialization and configuration: - -```rust -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. - -* Fixed [#28][issue-28]: Support not squeezing whitespace. - -### Version 0.5.0 — May 15th, 2017 - -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 -```rust -wrapper.corpus = Some(&corpus); -``` -to -```rust -wrapper.splitter = Box::new(corpus); -``` - -Other changes include optimizations, so version 0.5.0 is roughly -10-15% faster than version 0.4.0. - -* Fixed [#19][issue-19]: Add support for finding terminal size. -* Fixed [#25][issue-25]: Handle words longer than `self.width`. -* Fixed [#26][issue-26]: Support custom indentation. -* Fixed [#36][issue-36]: Support building without `hyphenation`. -* Fixed [#39][issue-39]: Respect non-breaking spaces. - -### Version 0.4.0 — January 24th, 2017 - -Documented complexities and tested these via `cargo bench`. - -* Fixed [#13][issue-13]: Immediatedly add word if it fits. -* Fixed [#14][issue-14]: Avoid splitting on initial hyphens. - -### Version 0.3.0 — January 7th, 2017 - -Added support for automatic hyphenation. - -### Version 0.2.0 — December 28th, 2016 - -Introduced `Wrapper` struct. Added support for wrapping on hyphens. - -### Version 0.1.0 — December 17th, 2016 - -First public release with support for wrapping strings on whitespace. - -## 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 -[travis-ci]: https://travis-ci.org/mgeisler/textwrap -[appveyor]: https://ci.appveyor.com/project/mgeisler/textwrap -[codecov]: https://codecov.io/gh/mgeisler/textwrap -[py-textwrap]: https://docs.python.org/library/textwrap -[patterns]: https://github.com/tapeinosyne/hyphenation/tree/master/patterns-tex -[api-docs]: https://docs.rs/textwrap/ -[issue-13]: https://github.com/mgeisler/textwrap/issues/13 -[issue-14]: https://github.com/mgeisler/textwrap/issues/14 -[issue-19]: https://github.com/mgeisler/textwrap/issues/19 -[issue-25]: https://github.com/mgeisler/textwrap/issues/25 -[issue-26]: https://github.com/mgeisler/textwrap/issues/26 -[issue-28]: https://github.com/mgeisler/textwrap/issues/28 -[issue-36]: https://github.com/mgeisler/textwrap/issues/36 -[issue-39]: https://github.com/mgeisler/textwrap/issues/39 -[issue-58]: https://github.com/mgeisler/textwrap/issues/58 -[issue-59]: https://github.com/mgeisler/textwrap/issues/59 -[issue-61]: https://github.com/mgeisler/textwrap/issues/61 -[issue-81]: https://github.com/mgeisler/textwrap/issues/81 -[issue-99]: https://github.com/mgeisler/textwrap/issues/99 -[issue-101]: https://github.com/mgeisler/textwrap/issues/101 -[issue-107]: https://github.com/mgeisler/textwrap/issues/107 -[issue-122]: https://github.com/mgeisler/textwrap/issues/122 -[issue-129]: https://github.com/mgeisler/textwrap/issues/129 -[issue-141]: https://github.com/mgeisler/textwrap/issues/141 -[issue-151]: https://github.com/mgeisler/textwrap/issues/151 -[mit]: LICENSE |