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.