Rawleenc
02cf48088a
- Introduced MEMORY_TRADEOFFS.md to explain memory vs deduplication trade-offs in anagram generation. - Added PERFORMANCE.md detailing optimizations for handling large volumes of anagram generation efficiently. - Created USAGE.md for comprehensive usage instructions, including installation, basic commands, and advanced generation modes. - Enhanced generator with streaming and batch processing capabilities for improved memory management. - Implemented quick hashing for deduplication to reduce memory footprint. - Updated main.rs to support new command-line arguments for streaming and batch modes. - Added tests to ensure letter removal maintains minimum word length and to verify anagram sorting functionality.
320 lines
10 KiB
Markdown
320 lines
10 KiB
Markdown
# Anagram Generator
|
|
|
|
Un générateur d'anagrammes prononçables haute performance en Rust pour créer des pseudonymes.
|
|
|
|
## Caractéristiques
|
|
|
|
- **Génère des anagrammes** à partir d'un mot donné
|
|
- **Génération aléatoire** : Crée des mots prononçables complètement aléatoires (sans mot source)
|
|
- **Évalue la prononçabilité** de chaque anagramme avec un score de 0 à 100
|
|
- **Filtre les résultats** selon un score minimum de prononçabilité
|
|
- **Retrait de lettres** : Supprime des lettres pour maximiser la prononçabilité
|
|
- **Ajout de lettres** : Ajoute des voyelles ou lettres communes pour améliorer la prononçabilité
|
|
- **Haute performance** : 3 modes de génération optimisés (standard, streaming, batch)
|
|
- **Scalabilité** : Supporte jusqu'à 1 milliard de générations avec empreinte mémoire minimale
|
|
- **Interface CLI** simple et intuitive
|
|
- **46 tests unitaires** complets
|
|
|
|
## Installation
|
|
|
|
Assurez-vous d'avoir Rust installé sur votre système. Si ce n'est pas le cas, installez-le depuis [rustup.rs](https://rustup.rs/).
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
## Utilisation
|
|
|
|
### Syntaxe de base
|
|
|
|
```bash
|
|
cargo run -- --word <MOT> [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
#### Options de base
|
|
- `-w, --word <MOT>` : Le mot à partir duquel générer les anagrammes (optionnel - si absent, génère des mots aléatoires)
|
|
- `-c, --count <NOMBRE>` : Nombre d'anagrammes/mots à générer (défaut: 10)
|
|
- `-l, --length <NOMBRE>` : Longueur des mots aléatoires (défaut: 6, utilisé si --word non spécifié)
|
|
- `-p, --prefix <PRÉFIXE>` : Préfixe pour commencer les mots aléatoires (utilisé uniquement si --word non spécifié)
|
|
- `-s, --min-score <SCORE>` : Score minimum de prononçabilité (0-100, défaut: 50)
|
|
- `-a, --max-attempts <NOMBRE>` : Nombre maximum de tentatives par anagramme (défaut: 1000)
|
|
|
|
#### Options de transformation
|
|
- `-r, --remove-letters <NOMBRE>` : Autoriser le retrait jusqu'à N lettres pour maximiser la prononçabilité
|
|
- `--add-vowels <NOMBRE>` : Ajouter jusqu'à N voyelles pour maximiser la prononçabilité
|
|
- `--add-letters <NOMBRE>` : Ajouter jusqu'à N lettres communes (voyelles + r,s,t,n,l) pour maximiser la prononçabilité
|
|
|
|
#### Options de performance
|
|
- `--streaming` : Mode streaming pour grandes quantités (mémoire constante ~10MB)
|
|
- `--batch-size <NOMBRE>` : Mode batch avec taille de batch spécifiée (mémoire contrôlée)
|
|
- `--progress` : Afficher la progression pour grandes générations
|
|
|
|
### Exemples
|
|
|
|
Générer 10 anagrammes prononçables à partir du mot "exemple":
|
|
|
|
```bash
|
|
cargo run -- --word exemple
|
|
```
|
|
|
|
Générer 20 anagrammes avec un score minimum de 60:
|
|
|
|
```bash
|
|
cargo run -- --word generateur --count 20 --min-score 60
|
|
```
|
|
|
|
Générer 5 anagrammes avec un score minimum faible pour plus de résultats:
|
|
|
|
```bash
|
|
cargo run -- --word pseudo --count 5 --min-score 30
|
|
```
|
|
|
|
Générer des anagrammes d'un mot difficile en autorisant le retrait de lettres:
|
|
|
|
```bash
|
|
cargo run -- --word strength --count 10 --min-score 60 --remove-letters 3
|
|
```
|
|
|
|
Ajouter des voyelles pour améliorer la prononçabilité d'un mot sans voyelles:
|
|
|
|
```bash
|
|
cargo run -- --word bcdfg --count 10 --min-score 60 --add-vowels 3
|
|
# Résultat: cufdubeg, egcedfeb, dficugb, etc.
|
|
```
|
|
|
|
Combiner retrait et ajout de lettres pour une transformation maximale:
|
|
|
|
```bash
|
|
cargo run -- --word xyzqwk --count 10 --min-score 70 --remove-letters 2 --add-vowels 3
|
|
# Résultat: wxiqekyze, qywkezo, kowaxq, etc.
|
|
```
|
|
|
|
**Générer des mots prononçables complètement aléatoires:**
|
|
|
|
```bash
|
|
cargo run -- --count 15 --length 7 --min-score 60
|
|
# Résultat: uzeviex, jadukau, scalodo, vohipoi, etc.
|
|
```
|
|
|
|
Créer des pseudonymes courts et prononçables:
|
|
|
|
```bash
|
|
cargo run -- --count 20 --length 5 --min-score 70
|
|
# Résultat: oimoe, gijiw, oaxiv, itoro, yedoz, etc.
|
|
```
|
|
|
|
**Générer des mots avec un préfixe imposé:**
|
|
|
|
```bash
|
|
cargo run -- --count 10 --length 7 --min-score 60 --prefix "test"
|
|
# Résultat: testoxo, testaan, testaer, testela, testitu, etc.
|
|
```
|
|
|
|
Créer des pseudonymes commençant par "jo":
|
|
|
|
```bash
|
|
cargo run -- --count 10 --length 6 --min-score 70 --prefix "jo"
|
|
# Résultat: jobeuw, jowung, jokeim, jodifn, joverx, etc.
|
|
```
|
|
|
|
## Fonctionnalités de transformation
|
|
|
|
### Génération aléatoire
|
|
|
|
**Nouveau** : Sans spécifier de mot source (`--word`), le générateur crée des mots complètement aléatoires mais prononçables.
|
|
|
|
**Algorithme** :
|
|
- Alterne intelligemment entre voyelles et consonnes
|
|
- 60% de préférence pour commencer par une consonne
|
|
- 70% de chance d'alterner entre voyelle/consonne à chaque lettre
|
|
- Filtre selon le score de prononçabilité
|
|
|
|
**Cas d'usage** :
|
|
- Générer des pseudonymes uniques
|
|
- Créer des noms de marque
|
|
- Inventer des noms de personnages
|
|
- Générer des identifiants mémorables
|
|
|
|
**Exemples** :
|
|
```bash
|
|
# Noms courts (5 lettres)
|
|
cargo run -- --count 10 --length 5 --min-score 70
|
|
|
|
# Noms moyens (7-8 lettres)
|
|
cargo run -- --count 10 --length 7 --min-score 60
|
|
|
|
# Noms longs très prononçables
|
|
cargo run -- --count 10 --length 10 --min-score 80
|
|
|
|
# Avec un préfixe imposé
|
|
cargo run -- --count 10 --length 7 --min-score 60 --prefix "test"
|
|
```
|
|
|
|
**Option de préfixe** :
|
|
L'option `--prefix` permet d'imposer le début des mots générés. Le générateur complète le mot en alternant intelligemment voyelles et consonnes après le préfixe.
|
|
|
|
### Retrait de lettres
|
|
|
|
La nouvelle option `--remove-letters` permet de générer des pseudonymes plus prononçables en retirant stratégiquement des lettres du mot source.
|
|
|
|
Lorsque le retrait est activé, le générateur retire stratégiquement des lettres problématiques.
|
|
|
|
**Exemple** :
|
|
```bash
|
|
cargo run -- --word strength --count 10 --min-score 60 --remove-letters 2
|
|
# Résultat: thsetr, rtethg, trgent, etc.
|
|
```
|
|
|
|
### Ajout de lettres
|
|
|
|
Les options `--add-vowels` et `--add-letters` permettent d'ajouter des lettres pour améliorer la prononçabilité.
|
|
|
|
#### `--add-vowels`
|
|
Ajoute des voyelles (a, e, i, o, u) aléatoires :
|
|
```bash
|
|
cargo run -- --word bcdfg --count 10 --min-score 60 --add-vowels 3
|
|
# Résultat: cufdubeg (8 lettres), egcedfeb (8 lettres), etc.
|
|
```
|
|
|
|
#### `--add-letters`
|
|
Ajoute des lettres communes (voyelles + r, s, t, n, l) :
|
|
```bash
|
|
cargo run -- --word xyz --count 10 --min-score 70 --add-letters 4
|
|
# Résultat: Mots de 7 lettres plus prononçables
|
|
```
|
|
|
|
### Combinaison retrait + ajout
|
|
|
|
Les deux options peuvent être combinées pour une transformation maximale :
|
|
|
|
```bash
|
|
cargo run -- --word xyzqwk --count 10 --min-score 70 --remove-letters 2 --add-vowels 3
|
|
```
|
|
|
|
Le générateur :
|
|
1. Essaie différentes combinaisons de retraits (0 à 2 lettres) et d'ajouts (0 à 3 voyelles)
|
|
2. Sélectionne le meilleur anagramme selon le score de prononçabilité
|
|
3. À score égal, préfère les transformations minimales
|
|
|
|
### Cas d'usage
|
|
|
|
**Retrait** : Mots avec trop de consonnes
|
|
- "strength" → mots plus courts et prononçables
|
|
|
|
**Ajout** : Mots sans voyelles ou très courts
|
|
- "xyz" → mots plus longs avec voyelles
|
|
- "bcdfg" → ajout de voyelles pour prononçabilité
|
|
|
|
**Combinaison** : Mots extrêmement difficiles
|
|
- "xyzqwk" → transformation complète pour maximiser la prononçabilité
|
|
|
|
## Système de prononçabilité
|
|
|
|
Le système de scoring évalue la prononçabilité selon plusieurs critères:
|
|
|
|
1. **Consonnes consécutives** : Pénalité pour 2+ consonnes consécutives (sauf clusters communs comme "th", "st", "br", etc.)
|
|
2. **Voyelles consécutives** : Pénalité modérée pour 3+ voyelles consécutives
|
|
3. **Alternance voyelle-consonne** : Bonus pour une bonne alternance (ratio > 60%)
|
|
4. **Présence de voyelles** : Pénalité forte si aucune voyelle ou que des voyelles
|
|
5. **Début du mot** : Léger bonus si le mot commence par une consonne
|
|
|
|
### Clusters de consonnes courants
|
|
|
|
Le système reconnaît ces clusters comme prononçables:
|
|
bl, br, ch, cl, cr, dr, fl, fr, gl, gr, pl, pr, sc, sh, sk, sl, sm, sn, sp, st, sw, th, tr, tw, wh, wr
|
|
|
|
## Modes de génération haute performance
|
|
|
|
### Mode Standard (par défaut)
|
|
Pour petites quantités (< 10k anagrammes) :
|
|
```bash
|
|
cargo run --release -- --word "programming" --count 1000
|
|
```
|
|
- Mémoire : ~1-10MB
|
|
- Tous les résultats en mémoire et triés
|
|
|
|
### Mode Streaming (recommandé pour 10k-100k)
|
|
Génération à la demande avec faible latence :
|
|
```bash
|
|
cargo run --release -- --word "programming" --count 50000 --streaming --progress
|
|
```
|
|
- Mémoire : O(n) - croît avec le nombre d'anagrammes (~8 bytes par anagramme)
|
|
- Résultats immédiats (latence très faible)
|
|
- Déduplication 100%
|
|
- ⚠️ Pour > 100k anagrammes, **préférer le mode batch** (mémoire contrôlée)
|
|
|
|
### Mode Batch (recommandé pour > 100k)
|
|
Traitement par batches pour très grandes quantités :
|
|
```bash
|
|
cargo run --release -- --word "algorithm" --count 10000000 --batch-size 100000 --progress
|
|
```
|
|
- Mémoire : proportionnelle au batch-size
|
|
- Déduplication globale efficace
|
|
- Idéal pour génération massive
|
|
|
|
**Exemple extrême (1 milliard d'anagrammes)** :
|
|
```bash
|
|
cargo run --release -- --word "word" --count 1000000000 --batch-size 1000000 --progress > output.txt
|
|
```
|
|
|
|
Voir [docs/PERFORMANCE.md](docs/PERFORMANCE.md) pour plus de détails sur les optimisations.
|
|
|
|
## Tests et benchmarks
|
|
|
|
### Tests unitaires
|
|
Exécuter les tests unitaires:
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
Exécuter les tests avec sortie détaillée:
|
|
|
|
```bash
|
|
cargo test -- --nocapture
|
|
```
|
|
|
|
### Benchmarks
|
|
Exécuter les benchmarks de performance:
|
|
|
|
```bash
|
|
cargo bench
|
|
```
|
|
|
|
Les benchmarks comparent les performances des différents modes de génération.
|
|
|
|
## Structure du code
|
|
|
|
Le projet suit les principes SOLID et Clean Code avec une architecture modulaire :
|
|
|
|
- **`src/types.rs`** : Types de domaine (Anagram, PronouncabilityScore)
|
|
- **`src/scorer.rs`** : Traits et configurations pour le scoring
|
|
- **`src/analyzer.rs`** : Implémentation de l'analyse de prononçabilité
|
|
- **`src/generator.rs`** : Générateur d'anagrammes (standard, streaming, batch)
|
|
- **`src/error.rs`** : Gestion des erreurs
|
|
- **`src/main.rs`** : Interface CLI
|
|
- **`benches/`** : Benchmarks de performance
|
|
|
|
Voir [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) pour une analyse détaillée de l'architecture.
|
|
|
|
## Documentation
|
|
|
|
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** : Architecture et principes SOLID
|
|
- **[PERFORMANCE.md](docs/PERFORMANCE.md)** : Optimisations et modes de génération
|
|
- **[USAGE.md](docs/USAGE.md)** : Guide d'utilisation détaillé
|
|
|
|
## Dépendances
|
|
|
|
### Production
|
|
- `clap` (4.5) : Parsing des arguments de ligne de commande
|
|
- `rand` (0.8) : Génération aléatoire pour mélanger les lettres
|
|
|
|
### Développement
|
|
- `criterion` (0.5) : Framework de benchmarking
|
|
|
|
## License
|
|
|
|
MIT
|