# State machines generation using ragel

HarfBuzz uses [ragel](https://github.com/adrian-thurston/ragel) to generate
state machines for some shapers.
The produced C code is rather low-level and relies on `goto` a lot,
therefore converting it to Rust by hand is rather problematic.
And this is the code that updates relatively often.

Can we use `ragel` to generate Rust code directly? Not using the stable `ragel`.
But the latest development branch does have a native Rust support.
Therefore to use `ragel` directly, we have to use the latest devel version and modify
ragel scripts a bit.

## Build ragel

`ragel` is a C++ project that uses the dreadful `autotools`.
Good luck building it on Windows. But on Unix-like OSes it should be relatively easy.

It also requires a 3rdparty dependency of
[colm](https://github.com/adrian-thurston/colm), which we have to build first.

In case of macOS, we would need:

```sh
brew install automake autoconf libtool
```

And now we can build `ragel`:

```sh
# build `colm` first
git clone https://github.com/adrian-thurston/colm
cd colm
./autogen.sh
./configure --prefix=/path/to/colm/install # prefer a custom path to /usr/local
make
make install

cd ..
git clone https://github.com/adrian-thurston/ragel
./autogen.sh
# --with-colm takes the same path we used above
./configure --prefix=/path/to/ragel/install --with-colm=/path/to/colm/install
make
make install
```

## Running ragel

Now we can convert our ragel scripts using:

```sh
/path/to/ragel/install/bin/ragel-rust -e -F1 src/hb/ot_shape_complex_indic_machine.rl # or any other .rl file
```

That's it!

PS: `ragel` will create temporary `*.ri` files. They can be safely removed.

## Code format

`ragel` uses strange code formatting for the Rust output, therefore running `cargo fmt`
is required.

## Comments

`ragel` doesn't preserve any comments, therefore we have to add

```c
// This file is autogenerated. Do not edit it!
//
// See docs/ragel.md for details.
```

Manually to each generated file.

## The Universal state machine

The `universal_machine.rl` is special since we have to modify its output manually
because we cannot express our needs via `ragel` directly.

The change is simple. After the `universal_machine.rs` is generated, Rust will complain about
about some variables set to 0. Like `ts = 0;`.
In all those cases `0` should simply be replaced with `p0`.
There are no better solution for now...