class WordMage::PhonemeSet

Overview

Manages consonants and vowels with positional constraints and weights for word generation.

The PhonemeSet class provides a unified interface for managing phoneme inventories with support for positional rules (e.g., certain phonemes only at word boundaries) and weighted sampling for more realistic distribution.

Example

phonemes = PhonemeSet.new(Set{"p", "t", "k"}, Set{"a", "e", "i"})
phonemes.add_phoneme("p", :consonant, [:word_initial])
phonemes.add_weight("p", 2.0_f32)  # Make "p" twice as likely
consonant = phonemes.sample_phoneme(:consonant, :word_initial)

Defined in:

phoneme_set.cr
phoneme_set_old.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(consonants : Array(String), vowels : Array(String)) #

Backward compatibility constructor for string arrays


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

Creates a new PhonemeSet with the given consonants and vowels. Accepts arrays of strings or IPA::Phoneme instances.


[View source]
def self.new(consonants : Set(String), vowels : Set(String)) #

Backward compatibility constructor for string sets


[View source]
def self.new(consonants : Set(IPA::Phoneme) | Array(String | IPA::Phoneme), vowels : Set(IPA::Phoneme) | Array(String | IPA::Phoneme)) #

Creates a new PhonemeSet with the given consonants and vowels. Accepts either String symbols or IPA::Phoneme instances.


[View source]
def self.new(groups : Hash(Char, Array(String | IPA::Phoneme))) #

Creates a new PhonemeSet with grouped phonemes. Accepts a hash mapping group symbols to arrays of phonemes.

Parameters

  • groups: Hash mapping group symbols to phoneme arrays
    • 'C': Required consonant group
    • 'V': Required vowel group
    • Any other char: Custom phoneme groups

Example

groups = {
  'C' => ["p", "t", "k", "b", "d", "g"],
  'V' => ["a", "e", "i", "o", "u"],
  'F' => ["f", "s", "θ"],  # Fricatives
  'N' => ["m", "n", "ɲ"]   # Nasals
}
phonemes = PhonemeSet.new(groups)

Raises

ArgumentError if 'C' or 'V' groups are missing


[View source]

Instance Method Detail

def add_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

Example

phonemes.add_custom_group('F', ["f", "v", "s", "z"])  # Fricatives
phonemes.add_custom_group('N', ["m", "n"], [:word_final])  # Nasals only at word end
phonemes.add_custom_group('P', [IPA::Utils.find_phoneme("p").not_nil!])  # Using IPA::Phoneme

Raises

Raises if symbol conflicts with reserved 'C' or 'V' symbols


[View source]
def add_phoneme(phoneme : String, type : Symbol, positions : Array(Symbol) = [] of Symbol) #

Backward compatibility overload for string phonemes


[View source]
def add_phoneme(phoneme : String | IPA::Phoneme, type : Symbol, positions : Array(Symbol) = [] of Symbol) #

Adds a phoneme to the set with optional positional constraints.

Parameters

  • phoneme: The phoneme string or IPA::Phoneme instance to add
  • type: Either :consonant or :vowel
  • positions: Array of position symbols (:word_initial, :word_medial, :word_final, etc.)

Example

phonemes.add_phoneme("ng", :consonant, [:word_final])  # "ng" only at word end
phonemes.add_phoneme(IPA::Utils.find_phoneme("p").not_nil!, :consonant, [:word_initial])

[View source]
def add_weight(phoneme : String | IPA::Phoneme, weight : Float32) #

Assigns a weight to a phoneme for weighted sampling.

Phonemes with higher weights are more likely to be selected. Default weight is 1.0 for all phonemes.

Example

phonemes.add_weight("p", 3.0_f32)  # "p" is 3x more likely than default
phonemes.add_weight(IPA::Utils.find_phoneme("p").not_nil!, 3.0_f32)  # Using IPA::Phoneme

[View source]
def consonant_phonemes : Set(IPA::Phoneme) #

Get consonant phoneme instances directly


[View source]
def consonant_symbols : Set(String) #

Convenience method to get consonant symbols as strings for backward compatibility


[View source]
def consonants : Set(IPA::Phoneme) #

[View source]
def consonants=(consonants : Set(IPA::Phoneme)) #

[View source]
def custom_groups : Hash(Char, Set(IPA::Phoneme)) #

[View source]
def custom_groups=(custom_groups : Hash(Char, Set(IPA::Phoneme))) #

[View source]
def get_consonants(position : Symbol | Nil = nil) : Array(String) #

Returns consonants, optionally filtered by position.

Parameters

  • position: Optional position to filter by (e.g., :word_initial)

Returns

Array of consonant strings that can appear at the given position


[View source]
def get_custom_group(symbol : Char, position : Symbol | Nil = nil) : Array(String) #

Returns phonemes from a custom group, optionally filtered by position.

Parameters

  • symbol: Custom group symbol
  • position: Optional position to filter by

Returns

Array of phonemes from the custom group that can appear at the given position

Raises

Raises if the custom group symbol is not defined


[View source]
def get_phoneme_by_symbol(symbol : String) : IPA::Phoneme | Nil #

Public method to find a phoneme by its symbol


[View source]
def get_vowels(position : Symbol | Nil = nil) : Array(String) #

Returns vowels, optionally filtered by position.

Parameters

  • position: Optional position to filter by (e.g., :word_initial)

Returns

Array of vowel strings that can appear at the given position


[View source]
def has_custom_group?(symbol : Char) : Bool #

Checks if a custom group symbol is defined.

Parameters

  • symbol: Custom group symbol to check

Returns

true if the custom group is defined, false otherwise


[View source]
def is_vowel?(phoneme : String) : Bool #

Checks if a phoneme is a vowel.

Returns

true if the phoneme is in the vowels set or recognized by IPA classification, false otherwise

Note

First checks the local vowels set, then falls back to IPA classification for broader coverage


[View source]
def is_vowel_like_group?(symbol : Char) : Bool #

Checks if a custom group symbol should be treated as vowel-like for hiatus generation.

Parameters

  • symbol: Custom group symbol to check

Returns

true if the custom group contains only vowels, false otherwise

Note

This is used to determine if hiatus (vowel sequences) should be applied to custom groups. Uses the IPA module for accurate vowel detection beyond just the local vowels set.


[View source]
def phoneme_weights : Hash(IPA::Phoneme, Float32) #

Get weights mapped by phoneme instances directly


[View source]
def position_rules : Hash(Symbol, Set(IPA::Phoneme)) #

[View source]
def position_rules=(position_rules : Hash(Symbol, Set(IPA::Phoneme))) #

[View source]
def sample_phoneme(type : Symbol, position : Symbol | Nil, context : String | Nil, transitions : Hash(String, Hash(String, Float32)), transition_weight_factor : Float32, positional_frequencies : Hash(String, Hash(String, Float32))) : String #

Randomly selects a phoneme using positional frequencies for word-initial selection.

Parameters

  • type: Either :consonant or :vowel
  • position: Optional position constraint
  • context: Previous phoneme for transition weighting (nil for word-initial)
  • transitions: Hash mapping phoneme transitions to frequencies
  • transition_weight_factor: Weight factor for transition probabilities
  • positional_frequencies: Hash mapping phonemes to their positional frequency distributions

Returns

A randomly selected phoneme symbol that respects constraints and positional frequencies


[View source]
def sample_phoneme(type : Symbol, position : Symbol | Nil, context : String | Nil, transitions : Hash(String, Hash(String, Float32)), transition_weight_factor : Float32) : String #

Randomly selects a phoneme from the specified type with contextual transition weights.

Parameters

  • type: Either :consonant or :vowel
  • position: Optional position constraint
  • context: Previous phoneme for transition weighting
  • transitions: Hash mapping phoneme transitions to frequencies
  • transition_weight_factor: Weight factor for transition probabilities

Returns

A randomly selected phoneme symbol that respects constraints and transition probabilities


[View source]
def sample_phoneme(type : Symbol, position : Symbol | Nil = nil) : String #

Randomly selects a phoneme of the given type, respecting position and weights.

Parameters

  • type: Either :consonant or :vowel
  • position: Optional position constraint

Returns

A randomly selected phoneme string

Raises

Raises if no candidates are available for the given type and position


[View source]
def sample_phoneme(symbol : Char, position : Symbol | Nil = nil) : String #

Randomly selects a phoneme from a custom group, respecting position and weights.

Parameters

  • symbol: Custom group symbol (e.g., 'F' for fricatives)
  • position: Optional position constraint

Returns

A randomly selected phoneme string from the custom group

Raises

Raises if the custom group is not defined or no candidates are available


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

Get weights mapped by symbol strings for backward compatibility


[View source]
def vowel_phonemes : Set(IPA::Phoneme) #

Get vowel phoneme instances directly


[View source]
def vowel_symbols : Set(String) #

Convenience method to get vowel symbols as strings for backward compatibility


[View source]
def vowels : Set(IPA::Phoneme) #

[View source]
def vowels=(vowels : Set(IPA::Phoneme)) #

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

[View source]
def weights=(weights : Hash(IPA::Phoneme, Float32)) #

[View source]