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


[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 with_analysis(analysis : Analysis, vowel_harmony : Bool = true) #

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) #

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_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_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_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)) #

Sets the consonants and vowels for generation.

Parameters

  • consonants: Array of consonant phonemes
  • vowels: Array of vowel phonemes

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_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_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_weights(weights : Hash(String, Float32)) #

Adds weights to phonemes for weighted sampling.

Parameters

  • weights: Hash mapping phonemes to their relative weights

Returns

Self for method chaining

Note

Must be called after #with_phonemes


[View source]