Repository files navigation

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

Add this line to your application's Gemfile:

gem'strings'

And then execute:

$ bundle

Or install it yourself as:

$ gem install strings

• 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 intocomponents

• 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

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

For example, to wrap a text usingwrap 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)

To align a given multiline text within a givenwidth usealign,align_left,align_center oralign_right.

Given the following multiline text:

text=<<-TEXTfor there is no folly of the beastof the earth whichis not infinitelyoutdone by the madness of menTEXT

Passingtext 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 handlesUTF-8 text:

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

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

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

Or fully qualified name:

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

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

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

To pad around a text with a given padding usepad 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 & below1# => 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=<<-TEXTIt is the easiest thingin the world for a manto look as if he hada great secret in him.TEXTStrings.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"#  "                         "

Thepad handlesUTF-8 text as well:

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

To remove ANSI escape codes from a string usesanitize:

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

or namespaced:

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

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

You can truncate a given text after a given length withtruncate 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 calltruncate:

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 specifyUTF-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…"

To wrap text into lines no longer thanwrap_at argument length, thewrap 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 handleUTF-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 callwrap directly onStrings::Wrap:

Strings::Wrap.wrap(text,wrap_at)

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

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

moduleMyStringExtrefineStringdodefwrap(*args)Strings.wrap(self, *args)endendend

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

usingMyStringExtstring.wrap(30)

However, if you want to include all theStrings methods:

require'strings/extensions'usingStrings::Extensions

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

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

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

Bug reports and pull requests are welcome on GitHub athttps://github.com/piotrmurach/strings. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to theContributor 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

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

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

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