BSD-3-Clause licensed by Rory Tyler Hayford
Maintained by [email protected]
This version can be pinned in stack with:ipa-,1632

Module documentation for

* ipa
** About
~ipa~ is a Haskell library for dealing with International Phonetic Alphabet (IPA) transcriptions. It provides a set of datatypes for working with speech segments and suprasegmentals which can be represented using IPA transcription. Speech sounds can be converted to their IPA representations or parsed from text written in IPA notation. It also supports most of the ASCII-only X-SAMPA transcription scheme.
** Usage
IPA values can be created by constructing ~Segment~ or ~Syllable~ values and applying ~toIPA~.
For instance:
#+begin_src haskell
{-# LANGUAGE PatternSynonyms #-}
{-# LANGUAGE OverloadedStrings #-}

import Language.IPA
import qualified Data.Text.IO as T

main :: IO ()
main = maybe message (T.putStrLn . unIPA) (toIPA b)
b = PulmonicConsonant Voiced Bilabial Plosive
message = T.putStrLn "Invalid or unrepresentable segment!"

A ~QuasiQuoter~ can be used to construct values as well. You can provide text in IPA or X-SAMPA notation, to be transformed at compile time into ~Segment~ or ~Syllable~ values. For example:
#+begin_src haskell
{-# LANGUAGE QuasiQuotes #-}

ezIPA :: Segment
ezIPA = [segment|x|]
-- Consonant (Pulmonic Voiceless Velar (Fricative NonSibilant))

~Segment~ and ~Syllable~ values can be adorned with additional articulatory information as well, and can further be nested to created more complex structures, e.g.:
#+begin_src haskell
someComplexVowel :: Segment
someComplexVowel = WithSegmentalFeature
(Length OverLong)
(Vowel Close Back Unrounded))
-- ɯᵝːː

~IPA~ is an instance of ~Semigroup~, so values can be concatenated with ~<>~:
#+begin_src haskell
someSyllables :: Maybe IPA
someSyllables = (<>) <$> toIPA syllable1 <*> toIPA syllable2
syllable1 =
WithSuprasegmentalFeature Linking
(Syllable [ WithSegmentalFeature
(Length Long)
(Vowel Close Back Rounded)

syllable2 = Syllable [ PulmonicConsonant Voiced Palatal Approximant
, Vowel OpenMid Front Unrounded
, Vowel Mid Central Unrounded
-- uː‿jɛə

~toIPA~ is a method of the ~ReprIPA~ typeclass; I decided a typeclass was best in order to allow users to create their own instances if the library-supplied ones were insufficient. You could create an instance, for example, for a hypothetical ~Mora~ datatype, etc...
** License
This library is distributed under the BSD 3-Clause revised license.
- [ ] Export constant values for common segments
- [X] Convenience functions for wrapping IPA values in different transcription delimiters (phonemic, phonetic, etc...)
- [X] Support for X-SAMPA transcription
- [X] Support for IPA <-> X-SAMPA conversion
- [X] Parsing and validation of user-supplied IPA and XSampa literals
- [X] Quasi quoter for making segment construction somewhat less painful


+ Relax version bounds for ~attoparsec~
* 0.3.1
+ ~Delimiter~ type added along with ~transcribe~ and ~transcribeXSampa~ functions; these wrap values in IPA transcriptions delimiters
+ Various ~QuasiQuoter~ s added to make it easier to construct ~Syllable~ and ~Segment~ values in IPA notation
* 0.3
+ Breaking changes:
- ~parseIPA~ method added to ~ReprIPA~ typeclass to parse values from text in IPA
- X-SAMPA-related methods have been moved from ~ReprIPA~ to the new ~ReprXSampa~ typeclass, which also includes the new ~parseXSampa~ method
- ~toIPA'~ and ~toXSampa'~ have been removed as methods, and are now functions (with the same behavior as the previous default implementation) exported from ~Language.IPA~
- New ~Vowel~ type with three variants: ~Pure~, ~Diphthongized~, and ~Triphthongized~. The ~Vowel~ constructor of ~Segment~ now takes a variant of this type as a parameter. There are also three new pattern synonyms that produce ~Segments~: ~PureVowel~, ~Diphthong~, and ~Triphthong~, corresponding to the ~Vowel~ constructors
- Constraints for the ~ReprIPA~ for ~Syllable~ instance have changed: was previously just ~Traversable~, now also includes ~Monoid~ and ~Applicative~. This is to allow for polymorphism in the syllable parser
- A data constructor has been added to ~Segment~: ~Optional~, which represents speech segments that are conventionally (and unofficially) written inside parentheses
- ~SuperscriptNumeric~ has been removed; it is replaced by a new data constructor for ~SuprasegmentalFeature~: ~ToneNumber~
+ Other changes:
- New utilities for determining literal text validity, membership in different categories of segments, converting between different notations, etc...
- ~ReprIPA~ is now in a separate module (~Language.IPA.Class~, along with ~ReprXSampa~); ~Language.IPA~ still re-exports it
- New ~mkXSampa~ smart constructor validates that the underlying text value only contains ASCII characters
* 0.2
+ Breaking changes:
- ~toXSampa~ and ~toXSampa'~ added to ~ReprIPA~ typeclass. Most (but not all) of the ~Segment~, ~SegmentalFeature~, and ~SuprasegmentalFeature~ values representable in IPA now have an X-SAMPA equivalent
- The partial ~toIPA'~ and ~toXSampa'~ methods now return the new ~IPAException~ in the event of failure, instead of simply calling ~error~
+ Bugfixes:
- There were some issues with voiced/voiceless pairs in v0.1, where the wrong variant had the voiceless diacritic
* 0.1
+ Initial release