Strings::Truncation

Truncate strings with fullwidth characters and ANSI codes.

Features

• No monkey-patching String class
• Omit text from the start, middle, end or both ends
• Account for fullwidth characters in encodings such as UTF-8, EUC-JP
• Shorten text without whitespaces between words (Chinese, Japanese, Korean etc)
• Preserve ANSI escape codes

Contents

• 1. Usage
• 2. API
  • 2.1 configure
  • 2.2 truncate
• 3. Extending String class

Installation

Add this line to your application's Gemfile:

gem "strings-truncation"

And then execute:

$ bundle

Or install it yourself as:

$ gem install strings-truncation

1. Usage

Use truncate to shorten string to 30 characters by default:

strings = Strings::Truncation.new
strings.truncate("I try all things, I achieve what I can.")
# => "I try all things, I achieve w…"

As a convenience, you can call truncate method directly on a class:

Strings::Truncation.truncate("I try all things, I achieve what I can.")
# => "I try all things, I achieve w…"

To change the default truncation length, pass an integer as a second argument:

strings.truncate("I try all things, I achieve what I can.", 15)
# => "I try all thin…"

Or if you want to be more explicit and flexible use :length keyword:

strings.truncate("I try all things, I achieve what I can.", length: 15)
# => "I try all thin…"

You can specify custom omission string in place of default …:

strings.truncate("I try all things, I achieve what I can.", omission: "...")
# => "I try all things, I achieve..."

If you wish to truncate preserving words use a string or regexp as a separator:

strings.truncate("I try all things, I achieve what I can.", separator: /\s/)
# => "I try all things, I achieve…"

You can omit text from the start, middle, end or both ends:

strings.truncate("I try all things, I achieve what I can", position: :middle)
# => "I try all thing…ve what I can."

You can truncate text with fullwidth characters (Chinese, Japanese, Korean etc):

strings.truncate("おはようございます", 8)
# => "おはよ…"

As well as truncate text that contains ANSI escape codes:

strings.truncate("\e[34mI try all things, I achieve what I can\e[0m", 18)
# => "\e[34mI try all things,\e[0m…"

2. API

2.1 configure

To change default configuration settings at initialization use keyword arguments.

For example, to omit text from the start and separate on a whitespace character do:

strings = Strings::Truncation.new(position: :start, separator: /\s/)

After initialization, you can use configure to change settings inside a block:

strings.configure do |config|
  config.length 25
  config.omission "[...]"
  config.position :start
  config.separator /\s/
end

Alternatively, you can also use configure with keyword arguments:

strings.configure(position: :start, separator: /\s/)

2.2 truncate

By default a string is truncated from the end to maximum length of 30 display columns.

strings.truncate("I try all things, I achieve what I can.")
# => "I try all things, I achieve w…"

To change the default truncation length, pass an integer as a second argument:

strings.truncate("I try all things, I achieve what I can.", 15)
# => "I try all thin…"

Or use :length keyword to be more explicit:

strings.truncate("I try all things, I achieve what I can.", length: 15)
# => "I try all thin…"

The default … omission character can be replaced using :omission:

strings.truncate("I try all things, I achieve what I can.", omission: "...")
# => "I try all things, I achieve..."

You can omit text from the start, middle, end or both ends by specifying :position:

strings.truncate("I try all things, I achieve what I can", position: :start)
# => "…things, I achieve what I can."

strings.truncate("I try all things, I achieve what I can", position: :middle)
# => "I try all thing…ve what I can."

strings.truncate("I try all things, I achieve what I can", position: :ends)
# => "… all things, I achieve what …"

To truncate based on custom character(s) use :separator that accepts a string or regular expression:

strings.truncate("I try all things, I achieve what I can.", separator: /\s/)
=> "I try all things, I achieve…"

You can combine all settings to achieve desired result:

strings.truncate("I try all things, I achieve what I can.", length: 20,
                 omission: "...", position: :ends, separator: /\s/)
# => "...I achieve what..."

3. Extending String class

Though it is highly discouraged to pollute core Ruby classes, you can add the required methods to String class by using refinements.

To include all the Strings::Truncation methods, you can load extensions like so:

require "strings/truncation/extensions"

using Strings::Truncation::Extensions

And then call truncate directly on any string:

"I try all things, I achieve what I can.".truncate(20, separator: " ")
# => "I try all things, I…"

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/strings-truncation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Strings::Truncation project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Copyright

Copyright (c) 2019 Piotr Murach. See LICENSE for further details.