
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¶ ↑
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 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 © 2019 Piotr Murach. See LICENSE for further details.