class WordMage::GeneratorBuilder

Overview

Fluent API for configuring and building Generator instances.

GeneratorBuilder provides a chainable interface for setting up word generation with all necessary components. This makes it easy to configure complex generation rules without dealing with the underlying object construction.

Example

generator = GeneratorBuilder.create
  .with_phonemes(["p", "t", "k"], ["a", "e", "i"])
  .with_syllable_patterns(["CV", "CVC"])
  .with_syllable_count(SyllableCountSpec.range(2, 4))
  .starting_with(:vowel)
  .with_constraints(["rr", "ss"])
  .random_mode
  .build

Defined in:

generator_builder.cr

Class Method Summary

Instance Method Summary

Class Method Detail

def self.create #

Creates a new GeneratorBuilder instance.

Returns

A new GeneratorBuilder ready for configuration


[View source]

Instance Method Detail

def build : Generator #

Builds the final Generator instance.

Returns

Configured Generator ready for word generation

Raises

Raises if required components (phonemes, syllable patterns, syllable count) are missing Raises if syllable patterns contain undefined custom symbols


[View source]
def disable_gemination #

Disables gemination (0% probability).

Returns

Self for method chaining

Example

.disable_gemination  # No consonant doubling

Note

Convenience method equivalent to #with_gemination_probability(0.0).


[View source]
def disable_vowel_lengthening #

Disables vowel lengthening (0% probability).

Returns

Self for method chaining

Example

.disable_vowel_lengthening  # No vowel lengthening

Note

Convenience method equivalent to #with_vowel_lengthening_probability(0.0).


[View source]
def enable_gemination #

Enables gemination with maximum probability (100%).

Returns

Self for method chaining

Example

.enable_gemination  # 100% chance of consonant doubling

Note

Convenience method equivalent to #with_gemination_probability(1.0).


[View source]
def enable_vowel_lengthening #

Enables vowel lengthening with maximum probability (100%).

Returns

Self for method chaining

Example

.enable_vowel_lengthening  # 100% chance of vowel lengthening

Note

Convenience method equivalent to #with_vowel_lengthening_probability(1.0).


[View source]
def ending_with_sequence(sequence : String) #

Sets an ending sequence constraint forcing words to end with specific phonemes.

Parameters

  • sequence: The romanized sequence that must end all generated words

Returns

Self for method chaining

Example

.ending_with_sequence("ath")  # All words end with "ath"

Note

This creates words like "gorath", "menath" where the exact sequence is preserved at the end, with normal generation before it.


[View source]
def random_mode #

Sets random generation mode.

Returns

Self for method chaining

Note

Random mode generates words using random sampling (default mode)


[View source]
def sequential_mode(max_words : Int32 = 1000) #

Sets sequential generation mode.

Parameters

  • max_words: Maximum number of words to generate (default: 1000)

Returns

Self for method chaining

Note

Sequential mode generates all possible combinations systematically


[View source]
def starting_with(type : Symbol) #

Constrains words to start with a specific phoneme type.

Parameters

  • type: Either :vowel or :consonant

Returns

Self for method chaining


[View source]
def starting_with_sequence(sequence : String) #

Sets a starting sequence constraint forcing words to begin with specific phonemes.

Parameters

  • sequence: The romanized sequence that must start all generated words

Returns

Self for method chaining

Example

.starting_with_sequence("thra")  # All words start with "thra"

Note

This creates words like "thraesy", "thranor" where the exact sequence is preserved at the beginning, then normal generation continues.


[View source]
def with_analysis(analysis : Analysis, vowel_harmony : Bool = true, analysis_weight_factor : Float32 = 20.0_f32) #

Applies an analysis to configure the generator.

Parameters

  • analysis: Analysis instance containing language patterns
  • vowel_harmony: Whether to apply vowel harmony (default: true)

Returns

Self for method chaining

Note

This method applies phoneme weights, syllable patterns, complexity budget, vowel harmony, and other settings derived from the analysis.


[View source]
def with_analysis_of_words(words : Array(String), vowel_harmony : Bool = true, analysis_weight_factor : Float32 = 20.0_f32) #

Convenience method to analyze words and apply the results.

Parameters

  • words: Array of romanized words to analyze
  • vowel_harmony: Whether to auto-detect and apply vowel harmony (default: true)

Returns

Self for method chaining

Note

This method uses the existing romanization map to analyze the words and applies the results to the generator configuration, including automatic vowel harmony detection.

Raises

Raises if no romanization map has been set


[View source]
def with_cluster_cost(cost : Float32) #

Sets the complexity cost for consonant clusters.

Parameters

  • cost: Cost per consonant cluster (default: 3.0)

Returns

Self for method chaining

Example

.with_cluster_cost(5.0_f32)  # Make clusters more expensive

[View source]
def with_complex_coda_cost(cost : Float32) #

Sets the complexity cost for complex codas.

Parameters

  • cost: Cost per complex coda (default: 2.0)

Returns

Self for method chaining

Example

.with_complex_coda_cost(4.0_f32)  # Make complex codas more expensive

[View source]
def with_complexity_budget(budget : Int32) #

Sets the complexity budget for controlling word complexity.

Parameters

  • budget: Complexity budget points (typical range: 3-12)
    • 3-5: Simple, melodic words
    • 6-8: Moderate complexity
    • 9-12: Complex words with clusters and hiatus

Returns

Self for method chaining

Note

Complexity budget controls clusters, hiatus, and vowel diversity. When budget is exhausted, generator creates more melodic patterns.


[View source]
def with_complexity_costs(cluster : Float32 = 3.0_f32, hiatus : Float32 = 2.0_f32, coda : Float32 = 2.0_f32, gemination : Float32 = 3.0_f32, vowel_lengthening : Float32 = 1.0_f32) #

Sets all complexity costs at once.

Parameters

  • cluster: Cost per consonant cluster (default: 3.0)
  • hiatus: Cost per hiatus sequence (default: 2.0)
  • coda: Cost per complex coda (default: 2.0)
  • gemination: Cost per gemination (default: 3.0)
  • vowel_lengthening: Cost per vowel lengthening (default: 1.0)

Returns

Self for method chaining

Example

.with_complexity_costs(
  cluster: 4.0_f32,
  hiatus: 1.5_f32,
  gemination: 2.0_f32
)

[View source]
def with_constraints(patterns : Array(String)) #

Adds word-level constraints to prevent unwanted patterns.

Parameters

  • patterns: Array of regex patterns that words must NOT match

Returns

Self for method chaining

Example

.with_constraints(["rr", "ss", "tt"])  # No double consonants

[View source]
def with_custom_group(symbol : Char, phonemes : Array(String), positions : Array(Symbol) = [] of Symbol) #

Backward compatibility overload for strings only


[View source]
def with_custom_group(symbol : Char, phonemes : Array(String | IPA::Phoneme), positions : Array(Symbol) = [] of Symbol) #

Adds a custom phoneme group for pattern generation.

Parameters

  • symbol: Single character symbol for the group (e.g., 'F' for fricatives)
  • phonemes: Array of phonemes (strings or IPA::Phoneme instances) belonging to this group
  • positions: Optional array of position symbols for positional constraints

Returns

Self for method chaining

Example

generator = GeneratorBuilder.create
  .with_phonemes(["p", "t", "k", "f", "s"], ["a", "e", "i"])
  .with_custom_group('F', ["f", "s"])  # Fricatives
  .with_custom_group('P', ["p", "t", "k"])  # Plosives  
  .with_syllable_patterns(["FVC", "PVF"])  # Use custom groups in patterns
  .build

Note

Must be called after #with_phonemes


[View source]
def with_gemination_cost(cost : Float32) #

Sets the complexity cost for gemination.

Parameters

  • cost: Cost per gemination (default: 3.0)

Returns

Self for method chaining

Example

.with_gemination_cost(2.0_f32)  # Make gemination cheaper

[View source]
def with_gemination_probability(probability : Float32) #

Sets the gemination probability for consonant doubling.

Parameters

  • probability: Probability (0.0-1.0) of consonant gemination

Returns

Self for method chaining

Example

.with_gemination_probability(0.1)  # 10% chance of consonant doubling

Note

Gemination creates words like "tenna", "korro", "silla" where consonants are doubled to create emphasis or length. Common in many natural languages.


[View source]
def with_hiatus_cost(cost : Float32) #

Sets the complexity cost for hiatus sequences.

Parameters

  • cost: Cost per hiatus sequence (default: 2.0)

Returns

Self for method chaining

Example

.with_hiatus_cost(1.0_f32)  # Make hiatus cheaper

[View source]
def with_hiatus_escalation(factor : Float32) #

Sets the hiatus escalation factor for controlling multiple hiatus sequences.

Parameters

  • factor: Escalation multiplier (typical range: 1.0-3.0)
    • 1.0: No escalation, all hiatus cost the same
    • 1.5: Moderate escalation (default)
    • 2.0: Strong escalation, discourages multiple hiatus
    • 3.0: Very strong escalation

Returns

Self for method chaining

Note

Each additional hiatus in a word costs progressively more: 1st hiatus: 2 points, 2nd: 2×factor points, 3rd: 2×factor² points


[View source]
def with_phonemes(consonants : Array(String), vowels : Array(String)) #

Backward compatibility overload for strings only


[View source]
def with_phonemes(consonants : Array(String | IPA::Phoneme), vowels : Array(String | IPA::Phoneme)) #

Sets the consonants and vowels for generation.

Parameters

  • consonants: Array of consonant phonemes (strings or IPA::Phoneme instances)
  • vowels: Array of vowel phonemes (strings or IPA::Phoneme instances)

Returns

Self for method chaining


[View source]
def with_phonemes(grouped_phonemes : Hash(Char, Array(String | IPA::Phoneme))) #

Sets the phonemes by group i:E {'C' => ["b", "p"...], ...}

Returns

Self for method chaining


[View source]
def with_romanization(mappings : Hash(String, String)) #

Sets up romanization mappings for phoneme-to-text conversion.

Parameters

  • mappings: Hash mapping phonemes to their written form

Returns

Self for method chaining


[View source]
def with_syllable_count(spec : SyllableCountSpec) #

Sets the syllable count specification.

Parameters

  • spec: SyllableCountSpec defining how many syllables to generate

Returns

Self for method chaining


[View source]
def with_syllable_pattern_probabilities(patterns_with_probabilities : Hash(String, Float32)) #

Sets syllable patterns with custom probabilities.

Parameters

  • patterns_with_probabilities: Hash mapping pattern strings to their relative probabilities

Returns

Self for method chaining

Example

.with_syllable_pattern_probabilities({
  "CV" => 3.0,   # CV patterns are 3x more likely
  "CVC" => 2.0,  # CVC patterns are 2x more likely
  "CCV" => 1.0   # CCV patterns have baseline probability
})

[View source]
def with_syllable_patterns(patterns : Array(String)) #

Sets syllable patterns using pattern strings.

Parameters

  • patterns: Array of pattern strings (e.g., ["CV", "CVC", "CCV"])

Returns

Self for method chaining


[View source]
def with_syllable_templates(templates : Array(SyllableTemplate)) #

Sets syllable templates directly for advanced configuration.

Parameters

  • templates: Array of configured SyllableTemplate objects

Returns

Self for method chaining

Note

Use this for templates with custom constraints or hiatus probabilities


[View source]
def with_thematic_vowel(vowel : String | IPA::Phoneme) #

Sets a thematic vowel constraint forcing the last vowel to be specific.

Parameters

  • vowel: The phoneme (string or IPA::Phoneme instance) that must be the last vowel in generated words

Returns

Self for method chaining

Example

.with_thematic_vowel("ɑ")  # All words end with /a/ as last vowel
.with_thematic_vowel(IPA::Utils.find_phoneme("a").not_nil!)  # Using IPA::Phoneme

Note

This creates words like "thranas", "kona", "tenask" where 'a' is always the final vowel, regardless of other vowels or consonants that follow.


[View source]
def with_vowel_harmony(harmony : VowelHarmony) #

Sets vowel harmony rules for the generator.

Parameters

  • harmony: VowelHarmony instance defining transition rules and strength

Returns

Self for method chaining

Note

Vowel harmony controls which vowels can follow others, from strict traditional harmony (strength 1.0) to loose statistical preferences (0.1-0.5).


[View source]
def with_vowel_harmony(enabled : Bool) #

Toggles vowel harmony on/off or sets strength.

Parameters

  • enabled: Whether to enable vowel harmony

Returns

Self for method chaining

Note

Requires previous analysis to have been applied. If enabled is false, disables vowel harmony. If true, uses the detected harmony rules.


[View source]
def with_vowel_harmony_strength(strength : Float32) #

Sets the vowel harmony strength/weight.

Parameters

  • strength: Harmony strength (0.0-1.0)

Returns

Self for method chaining

Note

Requires vowel harmony to already be configured. Adjusts the strength of existing harmony rules.


[View source]
def with_vowel_lengthening_cost(cost : Float32) #

Sets the complexity cost for vowel lengthening.

Parameters

  • cost: Cost per vowel lengthening (default: 1.0)

Returns

Self for method chaining

Example

.with_vowel_lengthening_cost(0.5_f32)  # Make vowel lengthening very cheap

[View source]
def with_vowel_lengthening_probability(probability : Float32) #

Sets the vowel lengthening probability for vowel doubling.

Parameters

  • probability: Probability (0.0-1.0) of vowel lengthening

Returns

Self for method chaining

Example

.with_vowel_lengthening_probability(0.15)  # 15% chance of vowel lengthening

Note

Vowel lengthening creates words like "kaara", "niilon", "tuuro" where vowels are doubled to create length or emphasis. Common in languages like Finnish.


[View source]
def with_weights(weights : Hash(String, Float32)) #

Backward compatibility overload for strings only


[View source]
def with_weights(weights : Hash(String | IPA::Phoneme, Float32)) #

Adds weights to phonemes for weighted sampling.

Parameters

  • weights: Hash mapping phonemes (strings or IPA::Phoneme instances) to their relative weights

Returns

Self for method chaining

Note

Must be called after #with_phonemes


[View source]