Stringex

Some [hopefully] useful extensions to Crystal's String class. It is made up of two libraries: Unidecoder and StringExtensions.

NOTE: This is a Crystal port of the Ruby stringex gem. ActsAsUrl is not available in the Crystal version as it requires ORM support.

Installation

Add this to your application's shard.yml:

dependencies:
  stringex:
    github: crystal-ports/rsl-stringex

Then run:

shards install

Usage

require "stringex"

Unidecoder

This library converts Unicode [and accented ASCII] characters to their plain-text ASCII equivalents. This is a port of Perl's Unidecode and provides eminently superior and more reliable results than relying on other transliterations.

require "stringex"

# Basic ASCII conversion
"simple English".to_ascii # => "simple English"
"kick it en Français".to_ascii # => "kick it en Francais"
"rock it Español style".to_ascii # => "rock it Espanol style"
"tell your readers 你好".to_ascii # => "tell your readers Ni Hao "

For anyone interested, details of the implementation can be read about in the original implementation of Text::Unidecode. Extensive examples can be found in the tests.

StringExtensions

A small collection of extensions on Crystal's String class. Please see the documentation for StringExtensions module for more information. There's not much to explain about them really.

require "stringex"

# URL-friendly strings
"simple English".to_url # => "simple-english"
"it's nothing at all".to_url # => "its-nothing-at-all"
"rock & roll".to_url # => "rock-and-roll"

# Currency conversion
"$12 worth of Crystal power".to_url # => "12-dollars-worth-of-crystal-power"
"10% off if you act now".to_url # => "10-percent-off-if-you-act-now"

# Unicode handling
"kick it en Français".to_url # => "kick-it-en-francais"
"rock it Español style".to_url # => "rock-it-espanol-style"
"tell your readers 你好".to_url # => "tell-your-readers-ni-hao"

# Other string methods
"<p>Hello World</p>".strip_html_tags # => "Hello World"
"hello world".convert_miscellaneous_characters # => "hello world"
"foo & bar".convert_miscellaneous_characters # => "foo and bar"

Localization

Stringex supports localization for string conversions. You can set the locale to change how characters, currencies, and other conversions are handled:

require "stringex"

# Default is English
"foo & bar".convert_miscellaneous_characters # => "foo and bar"

# Switch to German
Stringex::Localization.locale = "de"
"foo & bar".convert_miscellaneous_characters # => "foo und bar"

# Switch to French
Stringex::Localization.locale = "fr"
"foo & bar".convert_miscellaneous_characters # => "foo et bar"

Currently, built-in translations are available for the following languages:

• English (en)
• Danish (da)
• Swedish (sv)
• Dutch (nl)
• French (fr)
• German (de)
• Polish (pl)
• Portuguese Brazilian (pt-BR)
• Russian (ru)

You can easily add your own or customize the built-in translations. If you add a new language, please submit a pull request so we can make it available to other users also.

Stringex::Localization.store_translations("en", "characters", {
  "custom_char" => "replacement"
})

Running Tests

Install dependencies first:

shards install

Run individual test files:

crystal run test/unit/string_extensions_test.cr
crystal run test/unit/unidecoder_test.cr
crystal run test/unit/localization_test.cr
crystal run test/unit/localization/default_test.cr
crystal run test/unit/localization/da_test.cr
crystal run test/unit/localization/de_test.cr
crystal run test/unit/localization/en_test.cr
crystal run test/unit/localization/fr_test.cr
crystal run test/unit/localization/nl_test.cr
crystal run test/unit/localization/pl_test.cr
crystal run test/unit/localization/pt_br_test.cr
crystal run test/unit/localization/ru_test.cr
crystal run test/unit/localization/sv_test.cr
crystal run test/unit/unicode_point_suite/basic_latin_test.cr
crystal run test/unit/unicode_point_suite/basic_greek_test.cr

Thanks & Acknowledgements

This is a Crystal port of the stringex Ruby gem by Russell Norris. Unidecoder is a Ruby port of Sean Burke's Text::Unidecode module for Perl. And, finally, the bulk of strip_html_tags in StringExtensions was stolen from Tobias Lütke's Regex in Typo.

GIANT thanks to the many contributors who have helped make Stringex better and better: http://github.com/rsl/stringex/contributors

Copyright (c) 2008-2018 Lucky Sneaks, released under the MIT license