skey-engine 0.1.23

Stateless Vietnamese input method engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# skey-engine

Stateless Vietnamese input method engine written in Rust — used by
[skey](https://github.com/collyn/skey), a fcitx5 Vietnamese input method addon.

## Why

skey only needs a stateless `input → output` transform for Vietnamese text
processing. Most existing engines carry unnecessary state-machine complexity.
skey-engine provides the same functionality in ~700 lines of straightforward Rust,
with a simple Letter-based accumulator model.

## Design

- **Stateless** — `input string → output string`, no internal mutable state
- **Unikey-compatible transforms** — `dd→đ`, `aa→â`, `aw→ă`, `ow→ơ`, `uw→ư`,
  `vaya→vây`, `toiws→tới`, tone replacement, and more
- **String-based `is_valid()`** — CVC validation works on the composed string
  directly, not tied to engine state
- **4 input methods** — Telex, VNI, VIQR, and combined Telex+VNI
- **Embedded dictionary** — optional dictionary mode for auto-restore: validates
  the composed output against a ~7.9k-word Vietnamese list compiled into the
  binary (no runtime file loading), extensible with user words
- **Thin FFI** — 10 C functions covering lifecycle, config, transform, and validation

## API

```c
// Lifecycle
SkeyEngine *skey_engine_new(int32_t method);        // 0=Telex, 1=VNI, 2=VIQR, 3=TeipVni
void        skey_engine_free(SkeyEngine *e);

// Configuration
void skey_engine_set_method(SkeyEngine *e, int32_t method);
void skey_engine_set_tone_style(SkeyEngine *e, int32_t modern);    // 0=traditional, 1=modern
void skey_engine_set_short_w(SkeyEngine *e, int32_t enabled);      // standalone w→ư
void skey_engine_set_free_marking(SkeyEngine *e, int32_t free);    // reserved
void skey_engine_set_bracket_uo(SkeyEngine *e, int32_t enabled);   // reserved
void skey_engine_set_dict(SkeyEngine *e, int32_t enabled);         // auto-restore checks real words
void skey_engine_add_word(SkeyEngine *e, const char *word);        // user word override

// Core
char   *skey_engine_transform(SkeyEngine *e, const char *input);
int32_t skey_engine_is_valid(const char *s);
void    skey_free_string(char *s);
```

## Build

```bash
cargo build --release
# → target/release/libskey_engine.a
```

## Release

Bump version and create a tag:

```bash
# 1. Edit version in Cargo.toml
sed -i 's/^version = ".*"/version = "0.2.0"/' Cargo.toml

# 2. Commit & tag
git add Cargo.toml
git commit -m "chore: bump version to 0.2.0"
git tag v0.2.0
git push origin main --tags
```

Pushing a `v*` tag triggers the [release workflow](.github/workflows/release.yml)
which builds `libskey_engine.a`, runs tests, and publishes the artifact to
GitHub Releases.

## License

[GPL-3.0](LICENSE)