Crystal ICU

A binding & wrapper to the ICU library for the Crystal language.

About

This library provides high-level Crystal APIs to access the core features of the ICU library's lower-level C API.

Installation

Debian/Ubuntu

apt-get install -y libicu-dev

macOS

brew install icu4c
brew link --force icu4c

Usage

Add this to your application's shard.yml:

dependencies:
  icu:
    github: olbat/icu.cr

Then require the lib in your Crystal code:

require "icu"

Wrapped components

• [x] CharsetDetector, Charset detection (ucsdet.h)
• [x] BreakIterator, Text Boundary Analysis (Break Iteration) (ubrk.h)
• [x] Transliterator, Text Transformation (Transliteration) (utrans.h)
• [x] Normalizer, Normalization (unorm2.h)
• [x] Collator, Collation (ucol.h)
• [x] StringSearch, String Searching (usearch.h)
• [x] Locale, Locales (uloc.h, ulocdata.h)
• [x] IDNA, International Domain Names in Applications (uidna.h)
• [x] Currencies, Encapsulates information about a currency (ucurr.h)
• [x] Region, Territory containment and mapping (uregion.h)
• [x] NumberFormatter, Number Formatting/Spellout (unum.h)
• [x] DateTimeFormatter Date and Time Formatting (udat.h, udatpg.h, udateintervalformat.h)
• [x] Calendar, Calendars (ucal.h)
• [x] UniversalTimeScale, Universal Time Scale (utmscale.h)
• [x] PluralRules, Plural rules (upluralrules.h)
• [x] Bidirectional Algorithm, Bidirectional text handling (ubidi.h)
• [x] Regex, Regular Expressions (uregex.h)
• [x] Converter, Codepage Conversion (ucnv.h, ucnvsel.h)
• [x] SpoofChecker, Identifier Spoofing & Confusability (uspoof.h)

Internals

• [x] UChars, UChar conversion routines
• [x] UEnum, String Enumeration (uenum.h)
• [x] USet, Sets of Unicode Code Points and Strings (uset.h)
• ustring, Strings and Character Iteration (ustring.h, uiter.h) — superseded by Crystal's String
• utext, Abstract Unicode Text API (utext.h) — abstract C iterator, no value over Crystal String
• usprep, StringPrep (usprep.h) — niche protocol use (XMPP), out of scope
• ures, Resource Bundles (ures.h) — internal ICU data format, out of scope
• udata, Data loading interface (udata.h) — internal ICU infrastructure, out of scope

Development

ICU version compatibility

This binding is compatible with the ICU library starting from version 4.8. It has been generated using ICU version 74.2 so every additions in the API following this version will not be present in this binding.

The Crystal wrapper's (the ICU class) class and methods are enabled dynamically at compile-time depending on the version of the ICU library that's installed.

Please make sure that the class/feature you want to use is supported by your version ICU by checking the API documentation.

Regenerate the binding

To be sure that the LibICU binding fits with the version of the lib that's installed, it's possible to regenerate the binding by:

1. Installing libgen and it's dependencies (cf. libgen's documentation)
2. Run libgen and the lib_transformer program by running make generate_lib

Note: for some reasons, using LLVM versions >= 16 generate broken bindings. It'll be investigated later. For now, better stick using LLVM versions <= 15 when regenerating the libicu bindings using libgen.

Project's structure

• src/lib_icu: this directory contains the binding to the ICU library, it's generated by libgen & a transformation program
• src/icu: this directory contains the wrapper to the LibICU crystal lib that eases the usage of the binding
• src/icu_info.cr: this small program is used to determine which version of ICU is installed on the system (see #1)
• src/lib_transformer.cr: this small program is used to fix the binding generated by libgen (see #3)

About the binding's generation

For implementation and technical details about the binding's generation, see #1 & #3.