Metadata-Version: 2.4
Name: clafrica
Version: 1.0.1
Summary: Clafrica keyboard mapping for Nufi (Fe'éfě'e): converts ASCII shortcut sequences to Unicode characters
License-Expression: MIT
Project-URL: Repository, https://github.com/your-org/clafrica
Keywords: nufi,clafrica,cameroonian,keyboard,input-method,unicode,nlp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# clafrica

Python library for the **Clafrica** keyboard input method — converts ASCII shortcut
sequences into Nufi (Fe'éfě'e) Unicode characters.

## Install

```bash
pip install clafrica
```

---

## Quick start

```python
from clafrica import apply_mapping, finalize_input

apply_mapping("af1 e2 n*")   # → "ɑ̀ é ŋ"
apply_mapping("eu3 af5")     # → "ə̄ ɑ̂"
finalize_input("eu3")        # → "ə̄"
```

---

## API

### `apply_mapping(text)`

Converts all Clafrica shortcuts in *text* to Unicode, preserving whitespace.

```python
from clafrica import apply_mapping

apply_mapping("af1 e2 n*")   # → "ɑ̀ é ŋ"
apply_mapping("uu1 o*2")     # → "ʉ̀ ɔ́"
apply_mapping("N* O*")       # → "Ŋ Ɔ"
apply_mapping("eu3 af5")     # → "ə̄ ɑ̂"
```

**Live-typing mode** — pass `preserve_ambiguous_trailing=True` to leave the last
token untouched while the user may still extend it:

```python
apply_mapping("af", preserve_ambiguous_trailing=True)  # → "af"  (could become af1, af2…)
apply_mapping("af1")                                   # → "ɑ̀"
```

### `finalize_input(text)`

Like `apply_mapping` but also resolves any trailing ambiguous shortcut —
use this when the user confirms input (e.g. presses Enter or Space).

```python
from clafrica import finalize_input

finalize_input("eu3")   # → "ə̄"
finalize_input("af1")   # → "ɑ̀"
finalize_input("n*")    # → "ŋ"
```

### `ClafricaEngine` — advanced use

Instantiate the engine directly for a custom mapping or extra entries.

```python
from clafrica import ClafricaEngine

# Add project-specific shortcuts on top of the default table
engine = ClafricaEngine(extra={"nkap": "ŋkɑ̄p"})
engine.apply_mapping("nkap e2")   # → "ŋkɑ̄p é"
engine.finalize_input("eu3")      # → "ə̄"
engine.lookup("af1")              # → "ɑ̀"
engine.lookup("xyz")              # → None

# Fully custom table (replaces the default)
engine = ClafricaEngine(mapping={"a1": "à", "e1": "è"})
```

---

## Shortcut reference

| Shortcut | Output | Notes |
|----------|--------|-------|
| `af` | `ɑ` | open-a |
| `eu` | `ə` | schwa |
| `ai` | `ε` | epsilon |
| `o*` | `ɔ` | open-o |
| `uu` | `ʉ` | u-bar |
| `u-` | `ʉ` | u-bar (alternative) |
| `n*` | `ŋ` | eng |
| `N*` | `Ŋ` | Eng (uppercase) |
| `b*` | `ɓ` | implosive b |
| `d*` | `ɗ` | implosive d |
| `*n` | `ɲ` | palatal n |
| `a1` `a2` `a3` | `à` `á` `ā` | low / mid / high tone |
| `a5` `a7` | `â` `ǎ` | rising / falling tone |
| `af1` `af2` `af3` | `ɑ̀` `ɑ́` `ɑ̄` | open-a tones |
| `eu1` `eu2` `eu3` | `ə̀` `ə́` `ə̄` | schwa tones |
| `ai1` `ai2` `ai3` | `ɛ̀` `έ` `ɛ̄` | epsilon tones |
| `o*1` `o*2` `o*3` | `ɔ̀` `ɔ́` `ɔ̄` | open-o tones |
| `uu1` `uu2` `uu3` | `ʉ̀` `ʉ́` `ʉ̄` | u-bar tones |

Tone digits: `1` = low, `2` = mid, `3` = high, `5` = rising, `7` = falling.

### Phrase shortcuts (space-terminated)

These require a trailing space to trigger:

| Type | Output |
|------|--------|
| `af ` | `ɑ` |
| `eu ` | `ə` |
| `ai ` | `ε` |
| `uu ` | `ʉ` |

---

## Notes

- ASCII-only shortcuts are matched case-insensitively (`AF1` = `af1`).
- Unicode shortcuts (e.g. `à2`, `ɑ́1`) are case-sensitive.
- The mapping table is the canonical one used by the Nufi Android and Windows keyboards.

---

## License

MIT
