package camomile

Camomile

This is the version 2.0.0 release of Camomile library package. Camomile is a Unicode library for ocaml. Camomile provides Unicode character type, UTF-8, UTF-16, UTF-32 strings, conversion to/from about 200 encodings, collation and locale-sensitive case mappings, and more.

The library is licensed under LGPL-2 with the common linking exception given to OCaml packages. See LICENSE.md

Installation

The recommended way to install Camomile is via the opam package manager. With the opam binary installed and configured, all you should have to do is:

$ opam install camomile

Otherwise, you might want to see if your distribution has a package available for it.

Building

For developers and testers, dune is used to build the library:

$ dune build

This includes a default library configured with paths internals to dune where its shared files are stored.

The Camomile API provides a functor-base configuration interface that allows to define custom libraries with shared files located at a different location.

If you are building for packaging purposes and need to place shared files in a specific location for the default library, you can use environment variables at build-time:

$ CAMOMILE_CONFIG=env CAMOMILE_PREFIX=/usr dune build

in which case, the library will look for those files at /usr/share/camomile

Please note that dune install installs the file under the same local directory regardless of this option. This option is meant to be used when packaging the library for distributions using binary packages such as debian or ubuntu packages, RPM package etc.

Migrating form 1.x.x

The library's API was update and cleaned up in its version 2.0.0 as part of the migration to support OCaml 5.0.0. As a consequence, modules depending on the old library are now incompatible with the new library.

If you were previously using the CamomileLibraryDefault module, all you should have to do is use the new top-level Camomile module.

If you were previously using the configuration functor to define your own library, you should be able to use the new Camomile.Make functor available at top-level as well.

Otherwise, you can check the compat/ directory of this repository. It contains a simple compatibility library that you should be able to re-use in your code. We do, however, recommend simply updating your code to the new API. It really shouldn't be too hard!

Using libraries

Configuration

Camomile requires a runtime configuration to be able to locate its data files.

Camomile's idea of configuration is "configuration by functors". Modules which require configuration become functors parametrized by a module which contains configuration variables. Camomile.Config.Type specifies the module type of configuration parameters. You can pass the configuration module to individual modules' Make (as UCol.Make) or Configure functors (as CharEncoding.Configure), or pass it to the whole-in-one functor Camomile.Make and obtain configured modules.

Camomile provides two top-level modules which contains modules already configured. Therefore it is suitable to use if you are using Camomile locally installed from the source.

Individual modules.

See camomile.ml file.

Development

See https://github.com/savonet/Camomile

Updating the Unicode data

The Unicode Character Database is vendored under src/unidata and test/unidata so that builds stay offline. To refresh it:

CAMOMILE_UPDATE_UNICODE=1 dune build @update-unicode --auto-promote

This downloads the latest published release and rewrites the vendored files in place. Without --auto-promote it only reports which files are out of date. CAMOMILE_UPDATE_UNICODE is what gates the download: with it unset, no build ever reaches the network. There is no way to ask for a specific release — the vendored files are the pin, so downgrading means reverting the commit.

UCharInfo.script_type and UCharInfo.version_type are generated from the data, so new scripts and versions are picked up without touching any source.

The UCA conformance suite does not pass and is excluded from dune runtest; run it with dune build @uca-conformance. See test/tester/test_uCol.ml for what is broken.

Author

Camomile is currently maintained by Romain Beauxis romain.beauxis@gmail.com and was forked over from the original project with permission from @yoriyuki

However, the project is still in need of active contributors. Please file pull requests and more!

Acknowledgment

So many people are contributed to Camomile. See https://github.com/savonet/Camomile/graphs/contributors

Before GitHub becomes into existence...

• Peter Jolly provided CP932 conversion table.
• Kawakami Shigenobu contributed findlib support.
• Pierre Chambart contributed StringPrep module.
• Stanisław T. Findeisen pointed out the balancing bug of AVL-trees.
• Sylvain Le Gall provided dynamic configuration module ConfigDyn.ml.

Many people contributed bug fixes.