Strings

A set of useful methods for working with strings such as align, truncate, wrap, and many more.

Installation

Add this line to your application's Gemfile:

gem 'strings'

And then execute:

$ bundle

Or install it yourself as:

$ gem install strings

Features

• No monkey-patching String class
• Functional API that can be easily wrapped by other objects
• Supports multibyte character encodings such as UTF-8, EUC-JP
• Handles languages without white-spaces between words (like Chinese and Japanese)
• Supports ANSI escape codes
• Flexible by nature, split into components

Contents

• 1. Usage
• 2. API
  • 2.1 align
  • 2.2 ansi?
  • 2.3 fold
  • 2.4 pad
  • 2.5 sanitize
  • 2.6 truncate
  • 2.7 wrap
• 3. Extending String class
• 4. Components

1. Usage

Strings is a module with stateless function calls which can be executed directly or mixed into other classes.

For example, to wrap a text using wrap method, you can call it directly:

text = "Think not, is my eleventh commandment; and sleep when you can, is my twelfth."
Strings.wrap(text, 30)
# =>
#  "Think not, is my eleventh\n"
#  "commandment; and sleep when\n"
#  "you can, is my twelfth."

or using namespaced name:

Strings::Wrap.wrap(text, 30)

2. API

2.1 align

To align a given multiline text within a given width use align, align_left, align_center or align_right.

Given the following multiline text:

text = <<-TEXT
for there is no folly of the beast
of the earth which
is not infinitely
outdone by the madness of men
TEXT

Passing text as first argument, the maximum width and :direction to align to:

Strings.align(text, 40, direction: :center)
# =>
#  "   for there is no folly of the beast   \n"
#  "           of the earth which           \n"
#  "           is not infinitely            \n"
#  "     outdone by the madness of men      "

You can also pass :fill option to replace default space character:

Strings.align(text, 40, direction: :center, fill: '*')
# =>
#  "***for there is no folly of the beast***\n"
#  "***********of the earth which***********\n"
#  "***********is not infinitely************\n"
#  "*****outdone by the madness of men******"

It handles UTF-8 text:

text = "ラドクリフ\n、マラソン五輪\n代表に1万m出\n場にも含み"
Strings.align_left(text, 20)
# =>
#  "ラドクリフ          \n"
#  "、マラソン五輪      \n"
#  "代表に1万m出        \n"
#  "場にも含み          \n"

2.2 ansi?

To check if a string includes ANSI escape codes use ansi? method like so:

Strings.ansi?("\e[33;44mfoo\e[0m")
# => true

Or fully qualified name:

Strings::ANSI.ansi?("\e[33;44mfoo\e[0m")
# => true

2.3 fold

To fold a multiline text into a single line preserving white-space characters use fold:

Strings.fold("\tfoo \r\n\n bar")
# => "foo  bar"

2.4 pad

To pad around a text with a given padding use pad function where the seconds argument is a padding value that needs to be one of the following values corresponding with CSS padding property:

[1,1,1,1]  # => pad text left & right with 1 character and add 1 line above & below
[1,2]      # => pad text left & right with 2 characters and add 1 line above & below
1          # => shorthand for [1,1,1,1]

For example, to pad sentence with a padding of 1 space:

text = "Ignorance is the parent of fear."
Strings.pad(text, 1)
# =>
#  "                                  \n"
#  " Ignorance is the parent of fear. \n"
#  "                                  "

You can also pass :fill option to replace default space character:

text = "Ignorance is the parent of fear."
Strings.pad(text, [1, 2], fill: "*")
# =>
#  "************************************\n"
#  "**Ignorance is the parent of fear.**\n"
#  "************************************"

You can also apply padding to multiline content:

text = <<-TEXT
It is the easiest thing
in the world for a man
to look as if he had
a great secret in him.
TEXT

Strings.pad(text, 1)
# =>
#  "                         \n"
#  " It is the easiest thing \n"
#  " in the world for a man \n"
#  " to look as if he had \n"
#  " a great secret in him. \n"
#  "                         "

The pad handles UTF-8 text as well:

text = "ラドクリフ、マラソン"
Strings.pad(text, 1)
# =>
# "                      \n"
# " ラドクリフ、マラソン \n"
# "                      "

2.5 sanitize

To remove ANSI escape codes from a string use sanitize:

Strings.sanitize("\e[33;44mfoo\e[0m")
# => "foo"

or namespaced:

Strings::ANSI.sanitize("\e[33;44mfoo\e[0m")
# => "foo"

2.6 truncate

Please note this API will change in the next release and will be replaced by the strings-truncation component. See the Components section for more information.

You can truncate a given text after a given length with truncate method.

Given the following text:

text = "for there is no folly of the beast of the earth " +
       "which is not infinitely outdone by the madness of men"

To shorten the text to given length call truncate:

Strings.truncate(text, 20) # => "for there is no fol…"

or directly using the module namesapce:

Strings::Truncate.truncate(text, 20) # => "for there is no fol…"

If you want to split words on their boundaries use :separator option:

Strings.truncate(text, 20, separator: ' ') # => "for there is no…"

Use :trailing option (by default …) to provide omission characters:

Strings.truncate(text, 22, trailing: '... (see more)')
# => "for there...(see more)"

You can also specify UTF-8 text as well:

text = 'ラドクリフ、マラソン五輪代表に1万m出場にも含み'
Strings.truncate(text, 12)   # => "ラドクリフ…"

Strings::Truncate works with ANSI escape codes:

text = "I try \e[34mall things\e[0m, I achieve what I can"
Strings.truncate(text, 18)
# => "I try \e[34mall things\e[0m…"

2.7 wrap

To wrap text into lines no longer than wrap_at argument length, the wrap method will break either on white-space character or in case of east Asian characters on character boundaries.

Given the following text:

text = "Think not, is my eleventh commandment; and sleep when you can, is my twelfth."

Then to wrap the text to given length do:

Strings.wrap(text, 30)
# =>
#  "Think not, is my eleventh\n"
#  "commandment; and sleep when\n"
#  "you can, is my twelfth."

Similarly, to handle UTF-8 text do:

text = "ラドクリフ、マラソン五輪代表に1万m出場にも含み"
Strings.wrap(text, 8)
# =>
#  "ラドクリ\n"
#  "フ、マラ\n"
#  "ソン五輪\n"
#  "代表に1\n"
#  "万m出場\n"
#  "にも含み"

Strings::Wrap knows how to handle ANSI codes:

ansi_text = "\e[32;44mIgnorance is the parent of fear.\e[0m"
Strings.wrap(ansi_text, 14)
# =>
#  "\e[32;44mIgnorance is \e[0m\n"
#  "\e[32;44mthe parent of \e[0m\n"
#  "\e[32;44mfear.\e[0m"

You can also call wrap directly on Strings::Wrap:

Strings::Wrap.wrap(text, wrap_at)

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.

For example, if you wish to only extend strings with wrap method do:

module MyStringExt
  refine String do
    def wrap(*args)
      Strings.wrap(self, *args)
    end
  end
end

Then wrap method will be available for any strings where refinement is applied:

using MyStringExt

string.wrap(30)

However, if you want to include all the Strings methods:

require 'strings/extensions'

using Strings::Extensions

4. Components

Strings aims to be flexible and allow you to choose only the components that you need. Currently you can choose from:

Component	Description	API docs
strings-ansi	Handle ANSI escape codes in strings.	docs
strings-case	Handle case transformations in strings.	docs
strings-inflection	Inflects English nouns and verbs.	docs
strings-numeral	Express numbers as word numerals.	docs
strings-truncation	Truncate strings with fullwidth characters and ANSI codes.	docs

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

1. Fork it ( https://github.com/piotrmurach/strings/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

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

Code of Conduct

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

Copyright

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