icu

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

# Crystal ICU
A binding & wrapper to the [ICU](https://unicode-org.github.io/icu/userguide/icu/) library for the [Crystal language](https://crystal-lang.org/).

## About
This library provides high-level [Crystal APIs](https://olbat.github.io/icu.cr/index.html#wrapped-components) to access the core features of the ICU library's lower-level [C API](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/).

## Installation
__Debian/Ubuntu__
```bash
apt-get install -y libicu-dev
```

__macOS__
```bash
brew install icu4c
brew link --force icu4c
```


## Usage

Add this to your application's `shard.yml`:
```yaml
dependencies:
  icu:
    github: olbat/icu.cr
```

Then require the lib in your Crystal code:
```crystal
require "icu"
```


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

__Internals__
- [x] [UChars](https://olbat.github.io/icu.cr/ICU/UChars.html), UChar conversion routines
- [x] [UEnum](https://olbat.github.io/icu.cr/ICU/UEnum.html), String Enumeration _(uenum.h)_
- [x] [USet](https://olbat.github.io/icu.cr/ICU/USet.html), 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](lib.yml) 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](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/).

### 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](https://github.com/olbat/libgen#installation))
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](https://crystal-lang.org/docs/syntax_and_semantics/c_bindings/lib.html) to the ICU library, it's generated by [libgen](https://github.com/olbat/libgen) & a [transformation program](src/lib_transformer.cr)
- `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](https://github.com/olbat/icu.cr/issues/1))
- `src/lib_transformer.cr`: this small program is used to fix the binding generated by libgen (see [#3](https://github.com/olbat/icu.cr/issues/3))

### About the binding's generation

For implementation and technical details about the binding's generation, see [#1](https://github.com/olbat/icu.cr/issues/1) & [#3](https://github.com/olbat/icu.cr/issues/3).